Webassembly API

[axic]

We had several iterations of what kind of API should be exposed to Wasm, the most comprehensive one was: https://hackmd.io/CYVghsxgpgTAtNAzAY2PALARlugHBgOyHxIBmAnAAyRZkBs9SeQA

This is slightly different to what the hypervisor has in terms of instantiation and messaging.

There are two basic options:
a) expose the hypervisor's API as-is
b) take the above API from hackmd

Option a) makes the wasm-container operate 100% like the other containers, with all the ups and downs, including being very specific to this Javascript implementation of Primea.

Option b) makes the wasm-container operate on an API set which should be fairly easy to support in other implementations.

The downside of option b) is that a new layer must be introduced which translates between code storageRef and container type and actual code path.

[wanderer]

option b) is nice, but I would like to have still have somethings in the API be object oriented.

[wanderer]

updated ideas

createChannel(memloc i32)

creates a channel and writes to port referances to memory. Ideal if wasm had multiple return values we would use createChannel() -> i32, i32

bindPort(index: i32, portRef: i32)

assigns a index to a port and starts to listen for incoming messages on it

unbindPort(index: i32)

stops listening to a port and removes its index

getPortRef(index: i32) -> i32

given a port index return the portRef. If there is no port at the index return -1. This maybe need to be async, and the resulting index return to a callback. The port array will be merklized and we can expect light clients to load the proof on demand.

createMessage(offset: i32, len: i32, numOfRefs: i32) -> msgRef: i32

Messages can contain data which is read from memory starting at the offset and going for len bytes. Messages can also contain port referances. The number of port refs that the message can contain is numOfRefs

addRefToMessage(msgRef:i32, index: i32, portRef: i32)

Add a port ref to a message at the given index. If index is larger then numOfRefs then the vm traps

getMessageDataLen() -> i32

get the number of bytes contain in the message's data payload

loadMessageData(writeOffset: i32, offset: i32, len: i32)

loads the message's data into memory

getMessageRefLen() -> i32

get the number of referances contained in the message

loadMessagePortRef(index: i32) -> i32

loads a port ref from the message

sendMessage(portRef: i32, msgRef: i32)

sends a message on a given port

createInstance(msgRef: i32)

creates a new instance of a wasm contract (program). The data in the message is assumed to be the new contract's code

isvalidRef(ref: i32) -> i32

test is an i32 is a valid ref or not

deleteRef(ref: i32)

deletes port or message refs

[axic]

creates a new instance of a wasm contract (program). The data in the message is assumed to be the new contract's code

That is not the direct API since it can only instantiate wasm containers. The API allows to instantiate anything.

[wanderer]

Rigth, maybe a more extensible api would be something like createInstance(type: i32, msgRef: i32)

[wanderer]

Option 2 for createMessage

int msgRef = createMessage(offset: i32, length: i32);
pushRefToMessage(msgRef: i32, portRef2: i32);

[axic]

Sample "Unicornscript" implementation: https://hackmd.io/BwMxBMFMAZkhaAbAdgMYCZ4BZwENjzDgBGI86WyiWAnCMuMMsEA=?edit

[wanderer]

And a more implicit version of createChannel would be
createChannel(memloc: i32 ,memloc: i32)

[wanderer]

clarification is needed on bindPort. should it throw if index already has a port bound to it?