Storage System#

GenVM’s storage system provides persistent state management for intelligent contracts. It is language-agnostic.

Storage Architecture#

  1. Storage is scoped to an address

  2. Storage is organized into Storage Slots: blocks of 4294967296 octets (4GB)

  3. For given address, each Storage Slot has a unique identifier called SlotID which is a 32-octet value

  4. Reading uninitialized memory returns zeroes

  5. Storage is linear, meaning that each slot provides a contiguous block of memory

Default Derivation Algorithm#

Note

This is a proposed default algorithm, but using it is not mandatory.

Consider following structure:

x: str
y: str

Both x and y may occupy arbitrary amount of space. For that reason variable-length content is stored at an indirection: separate Storage Slot which SlotID is computed based on previous location, using following algorithm: sha3_256(slot_id, offset_in_slot_as_4_bytes_little_endian).

This means that that it is: sha3_256(slot_id, [0, 0, 0, 0]) for x and sha3_256(slot_id, [0, 0, 0, 4]) for y. 4 is because maximum length of string is bound by 4GB and there is no point in storing it at indirection. Note that any data that uses an indirection must occupy at least one byte in it’s residing slot

Root Slot#

Storage Slot with SlotID of all zeroes is called Root Slot. It uses Default Derivation Algorithm to store the following data:

  • contract_instance: (offset 0) Reference to the contract instance data.

  • code: (offset 1) The contract’s code. Slot contains 4 bytes little-endian length followed by data

  • locked_slots: (offset 2) A list of storage SlotIDs that cannot be modified by non-upgraders.

    Slot contains 4 bytes little-endian length followed length arrays of 32 byte SlotIDs

  • upgraders: (offset 3) A list of addresses that are authorized to modify the contract code and locked slots.

    Slot contains 4 bytes little-endian length followed length arrays of 20 byte addresses

Upgrade permissions and slot locking is described in Contract Upgradability