Module collections 

High-level storage collections built on 32-byte slots.

This module provides three storage collection types that abstract over raw slot operations:

• StorageMap<V>: Key-value map (like HashMap)
• StorageVec<V>: Dynamic array (like Vec)
• StorageBlob: Variable-length byte storage

All collections use namespace isolation to prevent slot collisions and support both production (HostStorage) and testing (MemoryStorage) backends.

Namespace Isolation

Each collection requires a unique namespace (32-byte identifier) to isolate its storage slots from other collections:

const NS_BALANCES: Namespace = Namespace([1u8; 32]);
const NS_ALLOWANCES: Namespace = Namespace([2u8; 32]);

let balances = StorageMap::<u64>::new(NS_BALANCES);
let allowances = StorageMap::<u64>::new(NS_ALLOWANCES);

Dual API Pattern

Each collection provides two API surfaces:

• _in() methods: Accept explicit backend parameter (for testing)
• Regular methods: Use HostStorage implicitly (for production)

// Production: uses HostStorage
map.insert(b"key", &value)?;

// Testing: explicit backend
let mut storage = MemoryStorage::new();
map.insert_in(&mut storage, b"key", &value)?;

Example: Token Balances

use truthlinked_sdk::collections::{Namespace, StorageMap};

const NS_BALANCES: Namespace = Namespace([1u8; 32]);

fn transfer(from: [u8; 32], to: [u8; 32], amount: u64) -> Result<()> {
    let balances = StorageMap::<u64>::new(NS_BALANCES);
     
    let from_balance = balances.get_typed_key(&from)?.unwrap_or(0);
    let to_balance = balances.get_typed_key(&to)?.unwrap_or(0);
     
    if from_balance < amount {
        return Err(Error::new(ERR_INSUFFICIENT_BALANCE));
    }
     
    balances.insert_typed_key(&from, &(from_balance - amount))?;
    balances.insert_typed_key(&to, &(to_balance + amount))?;
     
    Ok(())
}

Structs

Namespace

A 32-byte namespace identifier for storage isolation.

StorageBlob

A persistent variable-length byte storage.

StorageMap

A persistent key-value map stored in contract storage.

StorageVec

A persistent dynamic array stored in contract storage.