Skip to main content

Persisting Data

Ledger entries​

Contracts can access ledger entries of type CONTRACT_DATA. Host functions are provided to probe, read, write, and delete CONTRACT_DATA ledger entries.

Each CONTRACT_DATA ledger entry is keyed in the ledger by the contract ID that owns it, as well as a single user-chosen value, of the standard value type. This means that the user-chosen key may be a simple value such as a symbol, number or binary blob, or it may be a more complex structured value like a vector or map with multiple sub-values.

Each CONTRACT_DATA ledger entry also holds (in addition to its key) a single value associated with the key. Again, this value may be simple like a symbol or number, or may be complex like a vector or map with many sub-values.

No serialization or deserialization is required in contract code when accessing CONTRACT_DATA ledger entries: the host automatically serializes and deserializes any ledger entries accessed, exchanging them with the contract as deserialized values. If a contract wishes to use a custom serialization format, it can store a binary-valued CONTRACT_DATA ledger entry and provide its own code to serialize and deserialize, but Soroban has been designed with the intent to minimize the need for contracts to ever do this.

Access Control​

Contracts are only allowed to read and write CONTRACT_DATA ledger entries owned by the contract: those keyed by the same contract ID as the contract performing the read or write. Attempting to access other CONTRACT_DATA ledger entries will cause a transaction to fail.

Granularity​

A CONTRACT_DATA ledger entry is read or written from the ledger in its entirety; there is no way to read or write "only a part" of a CONTRACT_DATA ledger entry. There is also a fixed overhead cost to accessing any CONTRACT_DATA ledger entry. Contracts are therefore responsible for dividing logically "large" data structures into "pieces" with an appropriate size granularity, to use for reading and writing. If pieces are too large there may be unnecessary costs paid for reading and writing unused data, as well as unnecessary contention in parallel execution; but if pieces are too small there may be unnecessary costs paid for the fixed overhead of each entry.

Footprints and parallel contention​

Contracts are only allowed to access ledger entries specified in the footprint of their transaction. Transactions with overlapping footprints are said to contend, and will only execute sequentially with respect to one another, on a single thread. Transactions with non-overlapping footprints may execute in parallel. This means that a finer granularity of CONTRACT_DATA ledger entries may reduce artificial contention among transactions using a contract, and thereby increase parallelism.