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:
| Type | Usage |
|---|---|
| u128 | Most common - token amounts, counts, etc. |
| u64 | Timestamps, heights |
| u32 | Smaller counters, block timestamps |
| u8 | Flags, small enums |
| bool | Via 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:
| Path | Description |
|---|---|
| /initialized | Contract initialization flag |
| /name | Token/contract name |
| /symbol | Token symbol |
| /totalsupply | Total supply for tokens |
| /auth | Auth token AlkaneId for authenticated contracts |
| /owner | Owner 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(())
}