Storage & State Management

Patterns for persisting data in Alkanes smart contracts

Alkanes contracts store state using key-value storage accessed through StoragePointer. This guide covers storage patterns from simple values to complex data structures.

Storage Basics

All contract state is stored in a key-value store. The StoragePointer type provides a convenient API for reading and writing values.

use alkanes_runtime::storage::StoragePointer;
use metashrew_support::index_pointer::KeyValuePointer;
use std::sync::Arc;

// Create a storage pointer from a path
let pointer = StoragePointer::from_keyword("/my-value");

// Read raw bytes
let data: Arc<Vec<u8>> = pointer.get();

// Write raw bytes
pointer.set(Arc::new(vec![1, 2, 3, 4]));

// Check if value exists
if pointer.get().len() == 0 {
    println!("Value not set");
}

StoragePointer API

StoragePointer wraps a key path and provides methods for reading/writing values:

use alkanes_runtime::storage::StoragePointer;
use metashrew_support::index_pointer::KeyValuePointer;
use std::sync::Arc;

// ===== Creating Pointers =====

// From a keyword/path
let ptr = StoragePointer::from_keyword("/totalsupply");

// Hierarchical selection (creates: /balances/{user_bytes})
let balance_ptr = StoragePointer::from_keyword("/balances/")
    .select(&user_address_bytes);

// ===== Reading Values =====

// Raw bytes
let raw: Arc<Vec<u8>> = ptr.get();

// Typed value (for types implementing byte conversion)
let supply: u128 = ptr.get_value::<u128>();

// ===== Writing Values =====

// Raw bytes (requires Arc)
ptr.set(Arc::new(b"hello".to_vec()));

// Typed value
ptr.set_value::<u128>(1000000);

// ===== Existence Check =====
if ptr.get().len() == 0 {
    // Value doesn't exist or is empty
}

Storing Primitive Types

Use get_value/set_value for types that implement byte serialization:

TypeUsage
u128Most common - token amounts, counts, etc.
u64Timestamps, heights
u32Smaller counters, block timestamps
u8Flags, small enums
boolVia u8 (0 = false, 1 = true)
// u128 - Most common for token amounts
fn total_supply_pointer(&self) -> StoragePointer {
    StoragePointer::from_keyword("/totalsupply")
}

fn total_supply(&self) -> u128 {
    self.total_supply_pointer().get_value::<u128>()
}

fn set_total_supply(&self, v: u128) {
    self.total_supply_pointer().set_value::<u128>(v);
}

// u64 - Timestamps, heights
fn last_update_pointer(&self) -> StoragePointer {
    StoragePointer::from_keyword("/lastupdated")
}

fn last_update(&self) -> u64 {
    self.last_update_pointer().get_value::<u64>()
}

// u32 - Smaller values
fn block_timestamp_last(&self) -> u32 {
    StoragePointer::from_keyword("/blockTimestampLast").get_value::<u32>()
}

// u8 - Flags
fn is_paused(&self) -> bool {
    StoragePointer::from_keyword("/paused").get_value::<u8>() == 1
}

fn set_paused(&self, paused: bool) {
    StoragePointer::from_keyword("/paused")
        .set_value::<u8>(if paused { 1 } else { 0 });
}

Storing Strings

Store strings as raw bytes using Arc<Vec<u8>>:

use std::sync::Arc;

fn name_pointer(&self) -> StoragePointer {
    StoragePointer::from_keyword("/name")
}

fn name(&self) -> String {
    let bytes = self.name_pointer().get();
    String::from_utf8(bytes.as_ref().clone())
        .expect("name not valid utf-8")
}

fn set_name(&self, name: String) {
    self.name_pointer().set(Arc::new(name.into_bytes()));
}

// More robust version with fallback
fn name_or_default(&self) -> String {
    let bytes = self.name_pointer().get();
    if bytes.len() == 0 {
        String::from("Unknown")
    } else {
        String::from_utf8(bytes.as_ref().clone())
            .unwrap_or_else(|_| String::from("Invalid"))
    }
}

Storing AlkaneId

AlkaneId can be converted to/from Vec<u8>:

use alkanes_support::id::AlkaneId;
use std::sync::Arc;

fn factory_pointer(&self) -> StoragePointer {
    StoragePointer::from_keyword("/factory_id")
}

fn factory(&self) -> Result<AlkaneId> {
    let bytes = self.factory_pointer().get();
    if bytes.len() == 0 {
        return Err(anyhow!("factory not set"));
    }
    // Convert bytes to AlkaneId
    bytes.as_ref().clone().try_into()
        .map_err(|_| anyhow!("invalid factory id"))
}

fn set_factory(&self, factory_id: AlkaneId) {
    let bytes: Vec<u8> = factory_id.into();
    self.factory_pointer().set(Arc::new(bytes));
}

// Store two AlkaneIds (e.g., token pair)
fn alkane_pair_pointer(&self) -> StoragePointer {
    StoragePointer::from_keyword("/alkane/pair")
}

fn set_alkane_pair(&self, a: AlkaneId, b: AlkaneId) {
    StoragePointer::from_keyword("/alkane/0")
        .set(Arc::new(a.into()));
    StoragePointer::from_keyword("/alkane/1")
        .set(Arc::new(b.into()));
}

fn get_alkane_pair(&self) -> Result<(AlkaneId, AlkaneId)> {
    let a_bytes = StoragePointer::from_keyword("/alkane/0").get();
    let b_bytes = StoragePointer::from_keyword("/alkane/1").get();
    Ok((
        a_bytes.as_ref().clone().try_into()?,
        b_bytes.as_ref().clone().try_into()?,
    ))
}

Hierarchical Storage

Use .select() to create nested storage namespaces:

// Base pointer
let base = StoragePointer::from_keyword("/users/");

// Select by user address (appends bytes to path)
let user_key = user_address.as_bytes();
let user_ptr = base.select(user_key);

// Further nesting
let balance_ptr = user_ptr.select(b"/balance");
let stake_ptr = user_ptr.select(b"/stake");

// Practical example: User balances per token
fn balance_of(&self, user: &[u8], token: &AlkaneId) -> u128 {
    let token_bytes: Vec<u8> = token.clone().into();
    StoragePointer::from_keyword("/balances/")
        .select(user)
        .select(&token_bytes)
        .get_value::<u128>()
}

// Multi-level nesting for allowances
fn allowance(&self, owner: &[u8], spender: &[u8]) -> u128 {
    StoragePointer::from_keyword("/allowances/")
        .select(owner)
        .select(spender)
        .get_value::<u128>()
}

fn set_allowance(&self, owner: &[u8], spender: &[u8], amount: u128) {
    StoragePointer::from_keyword("/allowances/")
        .select(owner)
        .select(spender)
        .set_value::<u128>(amount);
}

Mapping Pattern

Create key-value mappings by combining base paths with keys:

// Simple mapping: hash -> bool (for tracking seen values)
pub fn seen_pointer(&self, hash: &[u8]) -> StoragePointer {
    StoragePointer::from_keyword("/seen/").select(hash)
}

pub fn is_seen(&self, hash: &[u8]) -> bool {
    self.seen_pointer(hash).get().len() > 0
}

pub fn mark_seen(&self, hash: &[u8]) {
    self.seen_pointer(hash).set_value::<u8>(1);
}

// Counter with unique key
pub fn nonce_pointer(&self, address: &[u8]) -> StoragePointer {
    StoragePointer::from_keyword("/nonces/").select(address)
}

pub fn get_and_increment_nonce(&self, address: &[u8]) -> u128 {
    let mut ptr = self.nonce_pointer(address);
    let current = ptr.get_value::<u128>();
    ptr.set_value::<u128>(current + 1);
    current
}

// Indexed list pattern
fn item_count(&self) -> u128 {
    StoragePointer::from_keyword("/items/count").get_value::<u128>()
}

fn item_at(&self, index: u128) -> Option<Vec<u8>> {
    let ptr = StoragePointer::from_keyword("/items/")
        .select(&index.to_le_bytes());
    let data = ptr.get();
    if data.len() > 0 {
        Some(data.as_ref().clone())
    } else {
        None
    }
}

fn push_item(&self, data: Vec<u8>) {
    let index = self.item_count();
    StoragePointer::from_keyword("/items/")
        .select(&index.to_le_bytes())
        .set(Arc::new(data));
    StoragePointer::from_keyword("/items/count")
        .set_value::<u128>(index + 1);
}

Initialization Pattern

Use observe_initialization() to ensure a contract is only initialized once:

// Built-in initialization check (from AlkaneResponder trait)
fn observe_initialization(&self) -> Result<()> {
    let mut pointer = StoragePointer::from_keyword("/initialized");
    if pointer.get().len() == 0 {
        pointer.set_value::<u8>(0x01);
        Ok(())
    } else {
        Err(anyhow!("already initialized"))
    }
}

// Usage in your contract
impl MyContract {
    fn initialize(&self, name: String, symbol: String) -> Result<CallResponse> {
        // This will fail if called twice
        self.observe_initialization()?;

        // Safe to initialize state
        self.set_name(name);
        self.set_symbol(symbol);

        let context = self.context()?;
        Ok(CallResponse::forward(&context.incoming_alkanes))
    }
}

// Custom initialization flags for features
fn observe_feature_enabled(&self, feature: &str) -> Result<()> {
    let key = format!("/feature/{}/enabled", feature);
    let mut pointer = StoragePointer::from_keyword(&key);
    if pointer.get().len() == 0 {
        pointer.set_value::<u8>(0x01);
        Ok(())
    } else {
        Err(anyhow!("feature {} already enabled", feature))
    }
}

Real-World Example: AMM Pool

Here's how an AMM pool manages multiple storage values:

// Real-world AMM pool storage layout
pub trait AMMPoolBase: MintableToken + AlkaneResponder {
    // Token pair
    fn alkanes_for_self(&self) -> Result<(AlkaneId, AlkaneId)> {
        Ok((
            StoragePointer::from_keyword("/alkane/0")
                .get().as_ref().clone().try_into()?,
            StoragePointer::from_keyword("/alkane/1")
                .get().as_ref().clone().try_into()?,
        ))
    }

    // Factory reference
    fn factory(&self) -> Result<AlkaneId> {
        let ptr = StoragePointer::from_keyword("/factory_id").get();
        ptr.as_ref().clone().try_into()
    }

    fn set_factory(&self, factory_id: AlkaneId) {
        StoragePointer::from_keyword("/factory_id")
            .set(Arc::new(factory_id.into()));
    }

    // Fee configuration
    fn total_fee_pointer(&self) -> StoragePointer {
        StoragePointer::from_keyword("/totalfeeper1000")
    }

    fn total_fee_per_1000(&self) -> u128 {
        let ptr = self.total_fee_pointer();
        if ptr.get().len() == 0 {
            3 // Default: 0.3% fee
        } else {
            ptr.get_value::<u128>()
        }
    }

    // Claimable protocol fees
    fn claimable_fees_pointer(&self) -> StoragePointer {
        StoragePointer::from_keyword("/claimablefees")
    }

    fn claimable_fees(&self) -> u128 {
        self.claimable_fees_pointer().get_value::<u128>()
    }

    // Time-weighted average price (TWAP) tracking
    fn price_cumulative_pointers(&self) -> (StoragePointer, StoragePointer) {
        (
            StoragePointer::from_keyword("/price0CumLast"),
            StoragePointer::from_keyword("/price1CumLast"),
        )
    }

    fn block_timestamp_last(&self) -> u32 {
        StoragePointer::from_keyword("/blockTimestampLast").get_value::<u32>()
    }

    // K-value for invariant tracking
    fn k_last_pointer(&self) -> StoragePointer {
        StoragePointer::from_keyword("/klast")
    }

    fn k_last(&self) -> U256 {
        self.k_last_pointer().get_value::<StorableU256>().into()
    }

    // Initialize all storage in one transaction
    fn init_pool(
        &self,
        alkane_a: AlkaneId,
        alkane_b: AlkaneId,
        factory: AlkaneId,
    ) -> Result<CallResponse> {
        self.observe_initialization()?;

        // Store token pair
        StoragePointer::from_keyword("/alkane/0")
            .set(Arc::new(alkane_a.into()));
        StoragePointer::from_keyword("/alkane/1")
            .set(Arc::new(alkane_b.into()));

        // Store factory
        self.set_factory(factory);

        // Initialize K to 0
        self.set_k_last(U256::from(0));

        // Add initial liquidity
        self.add_liquidity()
    }
}

Custom Storable Types

For complex types, implement byte serialization manually:

use std::io::{Cursor, Read, Write};

// Custom type that can be stored
#[derive(Clone)]
pub struct UserInfo {
    pub balance: u128,
    pub last_claim: u64,
    pub multiplier: u32,
}

impl UserInfo {
    pub fn to_bytes(&self) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(28); // 16 + 8 + 4
        bytes.extend_from_slice(&self.balance.to_le_bytes());
        bytes.extend_from_slice(&self.last_claim.to_le_bytes());
        bytes.extend_from_slice(&self.multiplier.to_le_bytes());
        bytes
    }

    pub fn from_bytes(bytes: &[u8]) -> Result<Self> {
        if bytes.len() < 28 {
            return Err(anyhow!("insufficient bytes for UserInfo"));
        }
        Ok(Self {
            balance: u128::from_le_bytes(bytes[0..16].try_into()?),
            last_claim: u64::from_le_bytes(bytes[16..24].try_into()?),
            multiplier: u32::from_le_bytes(bytes[24..28].try_into()?),
        })
    }
}

// Storage functions for custom type
fn user_info_pointer(&self, user: &[u8]) -> StoragePointer {
    StoragePointer::from_keyword("/userinfo/").select(user)
}

fn get_user_info(&self, user: &[u8]) -> Option<UserInfo> {
    let bytes = self.user_info_pointer(user).get();
    if bytes.len() == 0 {
        None
    } else {
        UserInfo::from_bytes(bytes.as_ref()).ok()
    }
}

fn set_user_info(&self, user: &[u8], info: &UserInfo) {
    self.user_info_pointer(user)
        .set(Arc::new(info.to_bytes()));
}

// Update a single field efficiently
fn update_user_balance(&self, user: &[u8], new_balance: u128) -> Result<()> {
    let mut info = self.get_user_info(user)
        .ok_or(anyhow!("user not found"))?;
    info.balance = new_balance;
    self.set_user_info(user, &info);
    Ok(())
}

Storage Path Conventions

Follow these conventions for consistent storage layout:

PathDescription
/initializedContract initialization flag
/nameToken/contract name
/symbolToken symbol
/totalsupplyTotal supply for tokens
/authAuth token AlkaneId for authenticated contracts
/ownerOwner address or AlkaneId
/balances/{addr}User balances (mapping pattern)
/allowances/{owner}/{spender}Token allowances
/seen/{hash}Prevent replay attacks

Best Practices

Use descriptive paths

Path names should be self-documenting: /reserves/token0 not /r/0

Prefix with slash

Always start paths with / for consistency

Group related data

Use hierarchical paths: /pool/reserves, /pool/fees

Consider key size

Short paths save storage but be descriptive enough

Handle missing values

get() returns empty Vec for missing keys - check length

Use checked arithmetic

Always use checked_add/checked_sub for amounts

Read-Modify-Write Pattern

When modifying values, always read first then write the new value:

use alkanes_support::utils::overflow_error;

// CORRECT: Read, modify, write with overflow check
fn increase_balance(&self, user: &[u8], amount: u128) -> Result<()> {
    let current = self.balance_pointer(user).get_value::<u128>();
    let new_balance = overflow_error(current.checked_add(amount))?;
    self.balance_pointer(user).set_value::<u128>(new_balance);
    Ok(())
}

fn decrease_balance(&self, user: &[u8], amount: u128) -> Result<()> {
    let current = self.balance_pointer(user).get_value::<u128>();
    let new_balance = overflow_error(current.checked_sub(amount))?;
    self.balance_pointer(user).set_value::<u128>(new_balance);
    Ok(())
}

// Transfer pattern: decrease from one, increase to another
fn transfer(&self, from: &[u8], to: &[u8], amount: u128) -> Result<()> {
    // Read both balances first
    let from_balance = self.balance_pointer(from).get_value::<u128>();
    let to_balance = self.balance_pointer(to).get_value::<u128>();

    // Check and calculate new values
    let new_from = overflow_error(from_balance.checked_sub(amount))?;
    let new_to = overflow_error(to_balance.checked_add(amount))?;

    // Write both values
    self.balance_pointer(from).set_value::<u128>(new_from);
    self.balance_pointer(to).set_value::<u128>(new_to);

    Ok(())
}