- | Type | Representation |
|---|
- | Non-empty list | A pair of the head and the tail. |
- | Record | A tuple of the field values. |
- | Data type |
- 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
- datatype zeroOrTwo = Zero | Two(int, int)
- Zero is encoded as a singleton tuple (0) and
- Two(a, b) as the triple (1, a, b).
- |
- | Signature | A pair of two 256-bit words. |
- | Option types | datatype option('a) = None | Some('a). |
- | ttl | datatype ttl = RelativeTTL(int) | FixedTTL(int) |
- | Type representations |
-
- When types need to be encoded as data, they are represented as the following datatype
-
-
- datatype typerep = Word // any unboxed type
- | String
- | List(typerep)
- | Tuple(list(typerep))
- | Datatype(list(list(typerep)))
- | TypeRep
- | Map(typerep, typerep)
- |
-
-
-### 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.