Merge pull request #86 from filecoin-project/aboodman-patch-1

Update vm_abi.md

drafts/vm_abi.md

@@ -45,6 +45,8 @@ Types on the boundary of the VM and the rest of Filecoin, need therefore be redu
 This defines a minimum base layer of types, that can be shared between all actors, independent of their implementation.
 This includes all types from Level 0.
 
+- `err` - an i32 containing an error code (see each function for what error codes it can return)
+- `bool` - and i32 containing either `1` or `0`
 - `cid` - binary v1 Cid (see https://github.com/ipld/cid#cidv1)
 - `bytes` - arbitrary sized byte array
 - `address` - 160bit number, represented as 20 bytes little endian unsigned integer
@@ -67,48 +69,61 @@ boundaries.
 
 # Syscalls
 
-Conceptually, actors are isolated programs, without access to the outside world. This isolation isn't currently enforced, but will be in a subsequent version of the protocol. Therefore, actors SHOULD access the outside world only via explicit _syscalls_ provided by Filecoin.
+Conceptually, actors are isolated programs, without access to the outside world. This isolation isn't currently enforced, but will be in a subsequent version of the protocol. Therefore, actors MUST access the outside world only via explicit _syscalls_ provided by Filecoin.
 
 Because it is thought that actors will eventually run inside the [eWASM VM](https://github.com/ewasm), Filecoin follows the WASM system of organizing syscalls using a [two-level namespace](https://github.com/WebAssembly/design/blob/master/Modules.md#imports) composed of a _module name_ and an _import name_. 
 
 The currently available modules are:
 
 ## `storage`
 
+### Constants
+
+| Name | Value |
+| ---- | ----- |
+| `OK` | `0`  |
+| `ERR_DECODE` | `33` |
+| `ERR_DANGLING_POINTER` | `34` |
+| `ERR_OPTIMISIC_CONCURRENCY` | `35` |
+
 The storage module provides a low-level content-addressed storage API to actors. Data stored using this API becomes part of the Filecoin blockchain.
 
-### `put(codec ui32, data bytes) cid`
+### `put(chunk bytes) cid`
+
+Stages a chunk to be put into storage and returns its cid. If the chunk is already in storage, then does nothing and returns its cid.
+
+When a chunk is _staged_ with `put()`, it is retrievable with `get()` to from all other messages in the block.
 
-Writes a new chunk to storage if the chunk is not already present.
+When a block is processed successfully, all newly added chunks reachable from the final commit for each actor are written to local node storage and made available to the network. These chunks become part of the blockchain.
 
-_codec_ is the multicodec to use to interpret the data. See:
-https://github.com/multiformats/multicodec/blob/master/table.csv
+If the cid from a put call is not explicitly reachable through the graph referenced by the final commit of any actor, it will not be included in the blockchain, and future invocations will not be able to access it.
 
-`put` will fail and return an empty cid if:
- * data cannot be decoded with codec
- * data is incomplete: refers to other chunks which do not exist in storage
+The chunk data MUST be encoded with [`dag-cbor`](https://github.com/multiformats/multicodec/blob/master/table.csv#L408). The returned `cid` will reflect this.
 
-### `get(cid) bytes`
+### `get(cid) (bytes, ok bool)`
 
-Reads a chunk from storage.
+Gets a chunk from storage. This can be either a chunk that was already in the blockchain prior to processing this block, or a chunk that was staged with `put()` by some actor earlier in the block.
 
-If the chunk does not exist, the returned bytes array is empty.
+If the chunk does not exist, the returned bytes array is empty and ok is `false`.
 
-### `commit(new cid, old cid) i32`
+### `commit(new cid, old cid) err`
 
 Executes an atomic compare-and-swap of the old and new head CIDs provided.
 
-If the current head for this actor equals old cid, `commit`
-atomically replaces it with the new cid and returns `0`. The new head,
-along with all chunks that head refers to become instantaneous visible to
-all actors.
+The dag rooted at `new` must be _complete_: all reachable chunks referred to via IPLD link attributes must also be present in the store.
 
 If the current head for this actor does not equal the old `cid`,
-`commit` exits and returns `1` without changing anything.
+`commit` exits and returns `ERR_OPTIMISTIC_CONCURRENCY` without changing anything.
+
+If any chunk cannot be decoded using `dag-cbor`, `commit` exits and returns `ERR_DECODE` without changing anything.
+
+If the new `cid` is not complete, `commit` exits and returns `ERR_DANGLING_POINTER` without changing anything.
+
+Otherwise, the commit succeeds and returns `OK`. When the block is completed processing, the final commit value is written into the block for this actor and all chunks reachable from it are flushed to persistent storage and made available to the network.
 
 ### `head() cid`
 
-Returns the last cid successfully written by `commit`.
+Returns the last cid successfully written by `commit()`.
 
 # TODO