State Model

Lyquid offers a powerful and ergonomic state model that eliminates manual serialization while giving you direct, byte-addressable access to persistent memory, via a unified architecture called Direct Memory Architecture (DMA).

Both network state and instance state are backed by DMA and accessible through WASM memory during runtime. The only difference between them is:

• Network state is versioned, as it's modified by consensus-driven transactions.
• Instance state is not versioned, but otherwise identical in behavior: persistent, portable, and zero-overhead to access.

🔹 Network State (Global, Shared)

• Synchronized across all nodes running the same Lyquid at a given version
• Modified via network functions
• Ideal for shared, traditional contract state like balances, permissions, or role assignments
• Versioned by LyquidNumber and tracked with standard "on-chain" guarantees.

lyquid::state! {
    network total_supply: U256 = U256::ZERO;
    network balances: network::HashMap<Address, U256> = network::new_hashmap();
    network allowances: network::HashMap<(Address, Address), U256> = network::new_hashmap();
}

🔸 Instance State (Local, Node-Specific)

• The state data are private to each node (not part of consensus). Only the node operator can possibly obtain it.
• Read and written by instance functions.
• Ideal for computationally intensive states, caches, private secret to nodes, or other node-local data.
• Not versioned like network state, one can treat this like a local database that is directly mirrored in memory.

lyquid::state! {
    instance multi_sig_key: Option<PrivateKey> = None;
    instance tx_history: Vec<Transaction> = Vec::new();
    instance users: HashMap<Address, UserCache> = instance::HashMap::new();
}

💡 In most cases, you can use standard Rust containers like Vec or HashMap via the network::* and instance::* type aliases. They're already configured with the correct allocator for our DMA storage.

For a complete specification, see lyquid::state!.