Storage Patterns - Kontor Protocol Documentation

Sigil uses a hierarchical path-based storage model, similar to a filesystem. The storage system provides type-safe accessors through Rust derives that generate methods for reading and writing state.

Storage Derives

StorageRoot - Top-Level Contract Storage

Every contract has exactly one StorageRoot:

#[derive(Clone, Default, StorageRoot)]
struct TokenStorage {
    pub ledger: Map<String, Integer>,
}

What it generates:

.init(ctx) method to initialize storage
Accessible via ctx.model()

Usage:

fn init(ctx: &ProcContext) {
    TokenStorage::default().init(ctx);
}

fn mint(ctx: &ProcContext, n: Integer) {
    let ledger = ctx.model().ledger();  // Access via model()
    // ...
}

Storage - Nested Structures

For structures nested within your storage root:

#[derive(Clone, Default, Storage)]
struct Account {
    pub balance: Integer,
    pub owner: String,
    pub permissions: Map<String, bool>,
}

What it generates:

Same accessors as StorageRoot but without .init()
Used for nested data structures

Store and Model

#[derive(Store)] - Generates only persistence methods (__set()) #[derive(Model)] - Generates only read/write accessor types (*Model, *WriteModel) Most contracts only need StorageRoot and Storage.

Type Constraints

Supported Storage Types

Primitive types:

u64, s64, bool, String

Built-in types:

Integer - Arbitrary precision (256-bit)
Decimal - Arbitrary precision with decimals
ContractAddress - References to other contracts

Structured types:

Enums and structs with #[derive(Storage)] or #[derive(Wavey)]
Option<T> where T is a supported type
Map<K, V> where K: ToString + FromString, V is a supported type

Not Directly Supported

Vec - Use Map<u64, T> as workaround:

// Instead of
pub items: Vec<String>,

// Use
pub items: Map<u64, String>,

// Access
fn add_item(ctx: &ProcContext, item: String) {
    let items = ctx.model().items();
    let len = items.keys().count() as u64;
    items.set(len, item);
}

Unsupported primitives - Use alternatives:

No u32, u16, u8 → Use u64
No f64, f32 → Use Decimal

Working with Basic Fields

#[derive(Clone, Default, StorageRoot)]
struct CounterStorage {
    pub count: u64,
    pub owner: String,
    pub active: bool,
}

impl Guest for Counter {
    fn init(ctx: &ProcContext) {
        CounterStorage {
            count: 0,
            owner: ctx.signer().to_string(),
            active: true,
        }.init(ctx);
    }

    fn increment(ctx: &ProcContext) {
        let current = ctx.model().count();      // Read
        ctx.model().set_count(current + 1);     // Write
    }

    fn get_owner(ctx: &ViewContext) -> String {
        ctx.model().owner()                     // Read
    }
}

Working with Options

#[derive(Clone, Default, StorageRoot)]
struct ProxyStorage {
    contract_address: Option<ContractAddress>,
}

impl Guest for Proxy {
    fn get_address(ctx: &ViewContext) -> Option<ContractAddress> {
        ctx.model().contract_address()  // Returns Option<ContractAddress>
    }

    fn set_address(ctx: &ProcContext, addr: ContractAddress) {
        ctx.model().set_contract_address(Some(addr));
    }

    fn clear_address(ctx: &ProcContext) {
        ctx.model().set_contract_address(None);
    }
}

Working with Maps

Maps provide key-value storage:

#[derive(Clone, Default, StorageRoot)]
struct TokenStorage {
    pub ledger: Map<String, Integer>,
}

impl Guest for Token {
    fn mint(ctx: &ProcContext, n: Integer) {
        let ledger = ctx.model().ledger();
        let account = ctx.signer().to_string();

        // Get (returns Option<V>)
        let balance = ledger.get(&account).unwrap_or_default();

        // Set
        ledger.set(account, balance + n);
    }

    fn all_holders(ctx: &ViewContext) -> Vec<String> {
        // Iterate keys
        ctx.model().ledger().keys().collect()
    }
}

Map API

For read-only access (ViewContext):

pub trait MapModel<K, V> {
    fn get(&self, key: K) -> Option<V>;
    fn keys(&self) -> impl Iterator<Item = K>;
}

For read-write access (ProcContext):

pub trait MapWriteModel<K, V> {
    fn get(&self, key: K) -> Option<V>;
    fn set(&self, key: K, value: V);
    fn keys(&self) -> impl Iterator<Item = K>;
}

Map Initialization with Data

fn init(ctx: &ProcContext) {
    FibStorage {
        cache: Map::new(&[(0, FibValue { value: 0 })]),
    }.init(ctx);
}

Nested Structures

Storage structures can be nested arbitrarily deep:

#[derive(Clone, Default, Storage)]
struct Account {
    pub balance: Integer,
    pub owner: String,
    pub other_tenants: Map<String, bool>,
}

#[derive(Clone, Default, StorageRoot)]
struct SharedAccountStorage {
    pub accounts: Map<String, Account>,
}

impl Guest for SharedAccount {
    fn deposit(ctx: &ProcContext, account_id: String, n: Integer) -> Result<(), Error> {
        let accounts = ctx.model().accounts();
        let account = accounts.get(&account_id).ok_or(unknown_error())?;

        // Access nested fields
        let current_balance = account.balance();

        // Update nested field
        account.set_balance(current_balance + n);

        Ok(())
    }

    fn check_permission(ctx: &ViewContext, account_id: String, user: String) -> bool {
        ctx.model()
            .accounts()
            .get(account_id)
            .map(|account| {
                // Access nested Map
                account.other_tenants().get(user).unwrap_or(false)
            })
            .unwrap_or(false)
    }
}

Updating Nested Fields with Closures

fn deposit(ctx: &ProcContext, account_id: String, n: Integer) -> Result<(), Error> {
    let account = ctx.model().accounts().get(account_id).ok_or(unknown_error())?;

    // Update a field using a closure
    account.update_balance(|b| b + n);

    Ok(())
}

Storage Key Scoping

Keys are scoped by path, preventing collisions:

struct Storage {
    pub map_a: Map<String, u64>,  // path: "map_a.*"
    pub map_b: Map<String, u64>,  // path: "map_b.*"
}

Keys in map_a and map_b are independent—they can have the same key without collision.

Gas Considerations

Storage operations consume gas: General guidance:

Storage writes are more expensive than reads
Minimize storage writes
Cache reads when accessing multiple times
Use lazy evaluation (models load only what you access)
Map iterations over many keys can be expensive

Documentation Index

​Storage Derives

​StorageRoot - Top-Level Contract Storage

​Storage - Nested Structures

​Store and Model

​Type Constraints

​Supported Storage Types

​Not Directly Supported

​Working with Basic Fields

​Working with Options

​Working with Maps

​Map API

​Map Initialization with Data

​Nested Structures

​Updating Nested Fields with Closures

​Storage Key Scoping

​Gas Considerations