Merge pull request #85 from filecoin-project/aboodman-storage-api-spec

Add Storage API to spec

drafts/vm_abi.md

@@ -1,8 +1,14 @@
-# VM ABI
+# VM
 
-## Data Types
+All changes to the Filecoin blockchain are the result of _messages_ invoked on _actors_.
 
-### Level 0 - Byte Code Level
+Filecoin actors are conceptually similar to _smart contracts_ in other blockchains. Currently, it is not possible to upload a custom actor to Filecoin, but we expect that to be possible in future versions of the protocol.
+
+The _VM_ is the part of Filecoin that is responsible for running actors and dispatching messages.
+
+# Data Types
+
+## Level 0 - Byte Code Level
 
 WebAssembly [defines the following four value types](http://webassembly.org/docs/semantics/#types):
 
@@ -34,19 +40,20 @@ Types on the boundary of the VM and the rest of Filecoin, need therefore be redu
 `i32` (`i32ptr`) or `i64`.
 
 
-### Level 1 - Filecoin Native Types
+## Level 1 - Filecoin Native Types
 
 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.
 
+- `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
 
 > **TODO**: Possibly add the varint family (defined [here](https://github.com/filecoin-project/specs/pull/61/commits/f58a71989b212192e5ea804a7466d48d4b44a83a))
 
 
 
-### Level 2 - Builtin Actors
+## Level 2 - Builtin Actors
 
 The builtin actors which Filecoin will ship with in 1.0, use CBOR to encode any values passed between the VM
 boundaries.
@@ -58,13 +65,55 @@ boundaries.
   - encoded as CBOR fixed size array (this allows us to support multiple return arguments if we need to)
   - passed by calling a builtin function `return(offset: i32ptr, length: i32) -> ()`
 
+# 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.
+
+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`
+
+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`
+
+Writes a new chunk to storage if the chunk is not already present.
+
+_codec_ is the multicodec to use to interpret the data. See:
+https://github.com/multiformats/multicodec/blob/master/table.csv
+
+`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
+
+### `get(cid) bytes`
+
+Reads a chunk from storage.
+
+If the chunk does not exist, the returned bytes array is empty.
+
+### `commit(new cid, old cid) i32`
+
+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.
 
+If the current head for this actor does not equal the old `cid`,
+`commit` exits and returns `1` without changing anything.
 
-> **TODO**: What is the equivalent of [`json-interface`](https://web3js.readthedocs.io/en/1.0/glossary.html#glossary-json-interface)
-> for us? Do we need it? Can we define a generic, high level language agnostic way for it that is always stored on chain?
-> Idea: use the start of `exports` and extend it.
+### `head() cid`
 
+Returns the last cid successfully written by `commit`.
 
-> **TODO**: Tie in with execution model and details of the actual Filecoin ABI interface, once those are defined.
+# TODO
 
-> **TODO**: Tie in with versioning of contracts and possible changes of encodings between versions.
+* Make a call on whether to commit to indefinite storage of block data. My concern is that there be no practical way to avoid this committment unless we implement state pruning in v1, which I do not want to do. ***
+* Document rest of syscalls available from `VMContext` above.
+* What is the equivalent of [`json-interface`](https://web3js.readthedocs.io/en/1.0/glossary.html#glossary-json-interface) for us? Do we need it? Can we define a generic, high level language agnostic way for it that is always stored on chain? Idea: use the start of `exports` and extend it.
+* Tie in with execution model and details of the actual Filecoin ABI interface, once those are defined.
+* Tie in with versioning of contracts and possible changes of encodings between versions.