Primea API brain dump as of March 2018

[axic]

These are all the random notes after 2 hours of data extraction from @wanderer's head:

// reference array for each moduel instance, indexde from 0 (i32), "anyref" goes into it
//
// data.externalize : (offset : addr, length : int) -> (databuf)
// data.internalize : (offset : addr, length : int, src : databuf, src_offset: addr) -> ()
// data.length : (databuf) -> (int)

/*
slot = index in the function table

(table (export "table") 1 1 anyfunc)
// index0 + function id
(elem (i32.const 0) $callback)

funcref properties:
- actor id
- function index in the "table"
- gas budget
- type information

func.externalize    : (slot : int) -> (funcref)
func.internalize    : (slot : int, func : funcref) -> ()
func.set_gas_budget : (func : funcref, cost : int) -> (funcref)
func.get_gas_budget : (funcref) -> (int)
*/


/*
module properties:
- exports
- id

module.new    : (binary : databuf) -> (modref)
module.self   : (modref)
module.id     : (module : modref) -> (id)
module.export : (module : modref, name : string) -> (anyref)

module export: take name of exported function and create a funcref (could be more in the future)

*/

/*
- key/value db

key: variable length bytes (>=1)
value: variable length bytes (>=0)

- tree.get(id).left      -> id/0
- tree.get(id).right     -> id/1
- tree.get(id).value     -> meta information (type + nonce)
- tree.get(id).extension

top level merkle tree key is the actor id and the value is a CBOR encoded array of 2 items,
can't be more than 2 items:
- the first is a number, representing the containerType (0 for wasm)
- the second is a number, starting at 0, representing the nonce, incremented everytime an actor creates another actor

key: id/0 stores the code
key: id/1 stores the storage

storage is a CBOR encoded anyref table:
[ databuf, id, module ]

CBOR tags:
- link: 42
- id: 43
- func: 44
- mod: 45

databuf CBOR encoding: CBOR(buffer)
id CBOR encoding (tagged: id): CBOR(id) (id == 20 byte buffer)
module CBOR encoding (tagged: mod): CBOR([exports, id])
funcref CBOR encoding (tagged: func):
- CBOR([bool, ...]) where bool is true if it is "private" and refers to the anyfunc table
- CBOR([bool(0), string(exported name), id, array(functionsig)]
- CBOR([bool(1), anyfunc index, id, array(functionsig)]

functionsig: array of numbers where:
- link: 0
- id: 1
- fun: 2
- mod: 3
- i32: 0x7f
- i64: 0x7e
- f32: 0x7d
- f64: 0x7c

id:
- actor created: id of parent actor + nonce of parent CBOR([ id, nonce ])
- first actor ever created: id = 0 nonce = 0 sha256(CBOR([ 0x00...00, 0 ])):truncate(0, 20)

--
0. runtimeObjects ("ref") vs. persistedObjects ("storage")
1. before the first run after deployment persistedObjects is empty, so their values cannot be assigned to the globals defined in the bytecode
2. on the first run, the globals have their default values set (clarify)
3. objects are created at runtime and they have na index assigned and stored in runtimeObjects
4. at the end of execution these objects are persisted:
- the value of each global is retrieved and the appropriate runtimeObjects are persisted into persistedObjects

e.g. there are 3 globals (indexed 0, 1, 2) which contain runtimeObject references as 42, 33, 10 the persistedObjects will
be the objects retrieved via references 42, 33, 10

*/

/*
external execution: id + string name (function name) + functionsig + arguments

getactor(id) -> actor
    actor.code
    actor.storage
    actor.meta

createfuncref(id, name) -> funcref

load(code).execute(name)

*/