docs/aevm_01_abi.md

@@ -0,0 +1,229 @@
+## The Sophia\_AEVM\_01 ABI
+
+### Byte code
+
+The byte code contains meta data about the original sophia source
+code.
+
+#### Meta data
+The byte code contains meta data for the contract.
+- source_code_hash - a Blake2b hash of the source code string of the contract
+- type_info - see Type information below
+- byte_code - the actual byte code
+
+The layout of the encoding can be found
+[here](https://github.com/aeternity/protocol/blob/master/serializations.md#sophia-byte-code). 
+The encoding is tagged with the compiler version.
+
+#### Type information
+The type information of each function is encoded in the meta data. The function
+hash depends both on the function name and the type signature of the function.
+The function hash is also the identifier of a function when calling a contract.
+In this way, the function prototype in the calling function gets some level of
+type verification.
+
+The type information contains:
+- fun_hash - A Blake2b hash of the function name and the function types
+- fun_name - The function name as a string
+- arg_type - The vm encoded typerep of the argument (as a tuple) of the function
+- out_type - The vm encoded typerep of the return type of the function
+
+### Memory layout
+
+Sophia values are 256-bit words. In case of unboxed types (`int`,
+`address`, and `bool`) this is simply the value. For boxed types
+such as tuples and (non-empty) lists, the word is a pointer into the heap
+(memory).
+
+More precisely
+
+- Unboxed types are represented as a single big endian 256-bit (32 bytes) word.
+  Booleans are represented as 0 for `false` and 1 for `true`. The empty list is
+  represented as an unboxed -1. In memory maps are represented by an unboxed
+  unique identifier. The contents of the map is stored separately in the VM
+  state.
+
+- Boxed types are represented as a 256-bit pointer to a contiguous sequence of
+  words, called a *heap object*, on the heap.
+
+  | Value/Type | Heap object
+  | --- | ---
+  | Tuple | The value of each component in left-to-right order.
+  | String | The length (number of bytes), followed by as many words as required to store the character data, padded on the right with 0.
+
+  The following types are represented in terms of other types:
+
+  <table>
+  <tr><th>Type</th><th>Representation</th></tr>
+  <tr><td>Non-empty list</td><td>A pair of the head and the tail.</td></tr>
+  <tr><td>Record</td><td>A tuple of the field values.</td></tr>
+  <tr><td>Data type</td>
+      <td>A tuple where the first component is a constructor
+          tag (starting with 0 for the first constructor), and the following
+          components are the constructor arguments. For instance, for<br/><br/>
+          <tt>datatype zeroOrTwo = Zero | Two(int, int)</tt><br/><br/>
+          <tt>Zero</tt> is encoded as a singleton tuple <tt>(0)</tt> and
+          <tt>Two(a, b)</tt> as the triple <tt>(1, a, b)</tt>.
+      </td></tr>
+  <tr><td>Signature</td><td>A pair of two 256-bit words.</td></tr>
+  <tr><td>Option types</td><td><tt>datatype option('a) = None | Some('a)</tt>.</td></tr>
+  <tr><td><tt>ttl</tt></td><td><tt>datatype ttl = RelativeTTL(int) | FixedTTL(int)</tt></td></tr>
+  <tr><td>Type representations</td>
+      <td>
+      When types need to be encoded as data, they are represented as the following datatype<br/><br/>
+      <div>
+      <pre>
+        datatype typerep = Word  // any unboxed type
+                         | String
+                         | List(typerep)
+                         | Tuple(list(typerep))
+                         | Datatype(list(list(typerep)))
+                         | TypeRep
+                         | Map(typerep, typerep)
+      </pre></div>
+      The argument to the <tt>Datatype</tt> constructor is the list of type
+      representations of the constructor arguments.
+      </td></tr>
+  </table>
+
+### Encoding Sophia values as binaries
+
+When communicating Sophia values between a contract and the outside world they
+are encoded as a binary containing a heap whose first word is the encoded value
+(except in the case of maps, see below). For example, the value `("main", (1, 2, 3))`
+can be encoded as
+```
+Word       0       1       2       3       4       5       6       7
+Addr    0x00    0x20    0x40    0x60    0x80    0xA0    0xC0    0xE0
+Value   0x20    0x60    0xA0       4   "main"      1       2       3
+```
+where `"main"` is the 32 byte word obtained by right padding the string
+`"main"` with zeroes.
+
+Note that the order of the heap objects on the heap is unspecified. Another
+valid encoding of the same value is
+```
+Word       0       1       2       3       4       5       6       7
+Addr    0x00    0x20    0x40    0x60    0x80    0xA0    0xC0    0xE0
+Value   0x60       4   "main"   0x20    0xA0       1       2       3
+```
+
+A canonical binary representation is obtained by storing heap objects in
+depth-first left-to-right order (as in the first example). This is the
+representation used in map keys.
+
+#### Binary encoding of Sophia maps
+
+In memory, maps are represented by their unique identifier, but in binary
+encodings the identifier is replaced by a boxed representation with a heap
+object of the shape
+```
+    MapSize (N)
+    KeySize1
+  +----------+
+  |   Key1   |
+  +----------+
+    ValSize1
+  +----------+
+  |   Val1   |
+  +----------+
+      ...
+    KeySizeN
+  +----------+
+  |   KeyN   |
+  +----------+
+    ValSizeN
+  +----------+
+  |   ValN   |
+  +----------+
+```
+The keys and values are encoded as standalone binaries, so the addresses in
+`KeyI` (say) are relative only to the `KeyI` binary.
+
+### Initialization
+
+When a Sophia contract is called the calldata should be a pair of a function
+hash and a tuple of arguments, encoded as a binary as described above
+The value should be a pair of a function hash and a tuple of arguments
+For instance, to call the function `foo` (assuming the function
+hash 12345) with arguments `1` and `"bar"`, the calldata should be
+(the binary encoding of)
+```
+  (12345, (1, "bar"))
+```
+Before the contract starts executing the first word of the encoded calldata
+(i.e. the calldata value) is pushed on the stack and the rest of the calldata
+heap is written to memory. The result is that the Sophia contract starts with
+the value of the calldata on top of the stack.
+
+If the contract state has been initialized it is stored on the heap and a
+pointer to it is written to address 0. If the contract state has not been
+initialized, for instance, when running the `init` function, 0 is written to
+address 0. Note that address 0 contains a *pointer* to the value of the state,
+not the value itself.
+
+The compiler is responsible for generating the appropriate dispatch code,
+looking at the calldata and calling the correct function.
+
+### Return
+
+When returning from a contract call (using the `RETURN` instruction) the
+type information from the meta data is used to encode the return value.
+The VM reads the return value from the heap and returns it to the caller,
+and reads the updated contract state using the state pointer at address 0.
+A contract can write 0 to the state pointer to indicate that the state
+did not change.
+
+### Storing the contract state
+
+The contract state is stored in the *store* as a binary heap whose first word
+is the value (with maps stored as their identifiers) under key `0x00`.
+The type of the state is stored as an encoded type representation under key
+`0x01` (***subject to change: contract state type to be stored in contract
+metadata***). The list of maps in the contract state is stored under key `0x02`
+as a sequence of 256-bit map identifiers. For each map there are mappings
+(where `[X]` denotes a single 256-bit word):
+```
+  [MapId]      => [RealId] [RefCount] [Size] Types
+  [RealId] Key => Val
+```
+`Types` is the binary encoding of the tuple `(KeyType, ValType)` of type
+representations for the key and value types of the map. `Key` and `Val` are
+stand-alone heap encodings with map identifiers for maps (although for keys
+there are no maps). The `RealId` field is an indirection to allow in-place
+updates of maps and the `RefCount` field is used to track the number of
+occurrences of a map in other maps for the purpose of garbage collection.
+
+The `init` function of a contract should return a pair of the state type
+representation and the initial state, which are written to the store by the VM.
+Note that the Sophia code for `init` only returns the initial state value--the
+compiler is responsible for adding the type representation.
+
+### Remote contract calls
+
+The `CALL` instruction for calling another contract works differently for
+Sophia contracts than in the EVM. It expects on the stack (top to bottom):
+- `Gas` - the amount of gas to allocate to the call
+- `Address` - the address of the contract to call (or 0 for primops)
+- `Amount` - the amount of tokens to transfer with the call
+- `Calldata` - the calldata value (pair of function hash and arguments)
+- `TypeHash` - the function hash of primops that have dynamic types
+               (e.g., oracles). Otherwise unused.
+- `_` - unused (offset to write return value in the EVM)
+- `_` - unused (return value size in the EVM)
+
+The calldata is read from the heap guided by the calldata type and passed to
+the called contract. Before the call is made gas is charged for the size of the
+expanded calldata (e.g. maps have to be made explicit when passed between
+contracts). When the call returns the return value is pushed on top of the
+stack, and potential heap objects for the return value written to the top of
+the heap. The return type from the contracts meta data is used when writing it
+ to the heap. Since maps are handled outside the heap, the caller explicitly
+pays gas for handling maps in the return value.
+
+### Delegation signature
+Some chain operations (`Oracle.<operation>` and `AENS.<operation>`) has an optional
+delegation signature. This is typically used when a user/accounts would like to
+allow a contract to act on it's behalf. The exact data to be signed varies for the
+different operations, but in *all* cases you should prepend the signature data with
+the `network_id` (`ae_mainnet` for the Aeternity mainnet, etc.).