Struct soroban_sdk::storage::Storage

pub struct Storage { /* private fields */ }

Storage stores and retrieves data for the currently executing contract.

All data stored can only be queried and modified by the contract that stores it. Contracts cannot query or modify data stored by other contracts.

There are two types of storage - Persistent and Temporary.

Temporary entries are the cheaper storage option and are never in the Expired State Stack (ESS). Whenever a TemporaryEntry expires, the entry is permanently deleted and cannot be recovered. This storage type is best for entries that are only relevant for short periods of time or for entries that can be arbitrarily recreated.

Recreateable entries are in between temporary and persistent entries when it comes to fees. Whenever a recreateable entry expires, it is deleted from the ledger, but sent to an ESS. The entry can then be recovered later through an operation in Stellar Core issued for the expired entry.

Persistent entries are the more expensive storage type. Whenever a persistent entry expires, it is deleted from the ledger, sent to the ESS and can be recovered via an operation in Stellar Core. only a single version of a persistent entry can exist at a time.

Examples

use soroban_sdk::{Env, Symbol};

let storage = env.storage();
let key = symbol_short!("key");
storage.persistent().set(&key, &1, None);
assert_eq!(storage.persistent().has(&key), true);
assert_eq!(storage.persistent().get::<_, i32>(&key), Some(1));

Implementations

impl Storage

pub fn persistent(&self) -> Persistent

Storage for data that can stay in the ledger forever until deleted.

Persistent entries might expire and be removed from the ledger if they run out of the rent balance. However, expired entries can be restored and they cannot be recreated. This means these entries behave ‘as if’ they were stored in the ledger forever.

This should be used for data that requires persistency, such as token balances, user properties etc.

pub fn temporary(&self) -> Temporary

Storage for data that may stay in ledger only for a limited amount of time.

Temporary storage is cheaper than Persistent storage.

Temporary entries will be removed from the ledger after their lifetime ends. Removed entries can be created again, potentially with different values.

This should be used for data that needs to only exist for a limited period of time, such as oracle data, claimable balances, offer, etc.

pub fn instance(&self) -> Instance

Storage for a small amount of persistent data associated with the current contract’s instance.

Storing a small amount of frequently used data in instance storage is likely cheaper than storing it separately in Persistent storage.

Instance storage is tightly coupled with the contract instance: it will be loaded from the ledger every time the contract instance itself is loaded. It also won’t appear in the ledger footprint. All the data stored in the instance storage is read from ledger every time the contract is used and it doesn’t matter whether contract uses the storage or not.

This has the same lifetime properties as Persistent storage, i.e. the data semantically stays in the ledger forever and can be expired/restored.

The amount of data that can be stored in the instance storage is limited by the ledger entry size (a network-defined parameter). It is in the order of 100 KB serialized.

This should be used for small data directly associated with the current contract, such as its admin, configuration settings, tokens the contract operates on etc. Do not use this with any data that can scale in unbounded fashion (such as user balances).

pub fn get<K, V>(&self, key: &K, storage_type: StorageType) -> Option<V>where K: IntoVal<Env, Val>, V: TryFromVal<Env, Val>,

Returns the value stored for the given key in the currently executing contract’s storage, when present.

Returns None when the value is missing.

If the value is present, then the returned value will be a result of converting the internal value representation to V, or will panic if the conversion to V fails.

Trait Implementations

impl Clone for Storage

fn clone(&self) -> Storage

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Storage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.