Overview
Core Lane uses a two-tier state management system:
- StateManager: Persistent state storage
- BundleStateManager: Temporary state changes for transaction bundles
This architecture allows for atomic bundle execution with rollback support.
StateManager
Manages the persistent state of accounts, blobs, intents, and transactions.
Location: src/state.rs:86
Structure
pub struct StateManager {
accounts: BTreeMap<Address, CoreLaneAccount>,
stored_blobs: BTreeMap<B256, Vec<u8>>,
kv_storage: BTreeMap<String, Vec<u8>>,
intents: BTreeMap<B256, Intent>,
transactions: Vec<StoredTransaction>,
transaction_receipts: BTreeMap<String, TransactionReceipt>,
}
Account Management
Creates a new empty state manager.
get_account
fn(&self, address: Address) -> Option<&CoreLaneAccount>
Retrieves an account by address.Parameters:
address: Address to look up
Returns: Reference to the account, or None if not found set_account
fn(&mut self, address: Address, account: CoreLaneAccount)
Sets or updates an account.Parameters:
address: Address of the accountaccount: Account data to store
get_balance
fn(&self, address: Address) -> U256
Gets the balance of an account. Returns zero if account doesn’t exist.Parameters:
address: Address to query
get_nonce
fn(&self, address: Address) -> U256
Gets the nonce of an account. Returns zero if account doesn’t exist.Parameters:
address: Address to query
Returns the total number of accounts in state.
Blob Storage
contains_blob
fn(&self, blob_hash: &B256) -> bool
Checks if a blob is stored.Parameters:
blob_hash: Hash of the blob to check
get_blob
fn(&self, blob_hash: &B256) -> Option<&Vec<u8>>
Retrieves a stored blob.Parameters:
blob_hash: Hash of the blob
insert_blob
fn(&mut self, blob_hash: B256, data: Vec<u8>)
Stores a blob.Parameters:
blob_hash: Hash of the blobdata: Blob data
Key-Value Storage
get_kv
fn(&self, key: &str) -> Option<&Vec<u8>>
Retrieves a value from key-value storage.
insert_kv
fn(&mut self, key: String, value: Vec<u8>)
Inserts or updates a key-value pair.
remove_kv
fn(&mut self, key: &str) -> Option<Vec<u8>>
Removes a key-value pair and returns the previous value.
Intent Management
get_intent
fn(&self, intent_id: &B256) -> Option<&Intent>
Retrieves an intent by ID.
insert_intent
fn(&mut self, intent_id: B256, intent: Intent)
Stores or updates an intent.
Transaction Management
add_transaction
fn(&mut self, transaction: StoredTransaction)
Adds a transaction to the state.
get_transactions
fn(&self) -> &Vec<StoredTransaction>
Returns all stored transactions.
add_receipt
fn(&mut self, tx_hash: String, receipt: TransactionReceipt)
Stores a transaction receipt.
get_receipt
fn(&self, tx_hash: &str) -> Option<&TransactionReceipt>
Retrieves a transaction receipt by hash.
State Application
apply_changes
fn(&mut self, bundle_state_manager: BundleStateManager)
Applies changes from a bundle state manager to the persistent state.Parameters:
bundle_state_manager: Bundle state with changes to apply
This method merges all changes from the bundle into the main state:
- Updates accounts
- Adds blob storage
- Updates intents
- Applies key-value changes
- Stores transactions and receipts
Serialization
borsh_serialize
fn(&self) -> Result<Vec<u8>>
Serializes the state to bytes using Borsh encoding.
borsh_deserialize
fn(bytes: &[u8]) -> Result<Self>
Deserializes state from bytes using Borsh encoding.Parameters:
bytes: Serialized state data
Example
use core_lane::{StateManager, Address, U256};
let mut state = StateManager::new();
let addr = Address::from([1u8; 20]);
// Check initial balance
assert_eq!(state.get_balance(addr), U256::ZERO);
// Serialize and deserialize
let serialized = state.borsh_serialize()?;
let restored = StateManager::borsh_deserialize(&serialized)?;
BundleStateManager
Manages temporary state changes during bundle execution.
Location: src/state.rs:97
Structure
pub struct BundleStateManager {
pub accounts: BTreeMap<Address, CoreLaneAccount>,
pub stored_blobs: BTreeMap<B256, Vec<u8>>,
pub kv_storage: BTreeMap<String, Vec<u8>>,
pub removed_keys: Vec<String>,
pub intents: BTreeMap<B256, Intent>,
pub transactions: Vec<StoredTransaction>,
pub transaction_receipts: BTreeMap<String, TransactionReceipt>,
}
Core Methods
Creates a new empty bundle state manager.
Account Operations
fn get_account<'a>(
&'a self,
original: &'a StateManager,
address: Address,
) -> Option<&'a CoreLaneAccount>
fn get_account_mut(
&mut self,
original: &StateManager,
address: Address,
) -> Option<&mut CoreLaneAccount>
fn get_balance(&self, original: &StateManager, address: Address) -> U256
fn get_nonce(&self, original: &StateManager, address: Address) -> U256
fn add_balance(
&mut self,
original: &StateManager,
address: Address,
amount: U256,
) -> Result<()>
fn sub_balance(
&mut self,
original: &StateManager,
address: Address,
amount: U256,
) -> Result<()>
fn increment_nonce(
&mut self,
original: &StateManager,
address: Address,
) -> Result<()>
Blob Operations
fn contains_blob(&self, original: &StateManager, blob_hash: &B256) -> bool
insert_blob
fn(&mut self, blob_hash: B256, data: Vec<u8>)
Inserts a blob into the bundle state.
Key-Value Operations
get_kv
fn(&self, key: &str) -> Option<&Vec<u8>>
Gets a value from bundle state key-value storage.
insert_kv
fn(&mut self, key: String, value: Vec<u8>)
Inserts a key-value pair into bundle state.
remove_kv
fn(&mut self, key: &str) -> Option<Vec<u8>>
Removes a key-value pair from bundle state.
Intent Operations
fn get_intent<'a>(
&'a self,
original: &'a StateManager,
intent_id: &B256,
) -> Option<&'a Intent>
fn get_intent_mut(
&mut self,
original: &StateManager,
intent_id: &B256,
) -> Option<&mut Intent>
insert_intent
fn(&mut self, intent_id: B256, intent: Intent)
Inserts an intent into the bundle state.
Transaction Operations
add_transaction
fn(&mut self, transaction: StoredTransaction)
Adds a transaction to the bundle state.
add_receipt
fn(&mut self, tx_hash: String, receipt: TransactionReceipt)
Adds a transaction receipt to the bundle state.
Serialization
borsh_serialize
fn(&self) -> Result<Vec<u8>>
Serializes the bundle state to bytes using Borsh encoding.
borsh_deserialize
fn(bytes: &[u8]) -> Result<Self>
Deserializes bundle state from bytes.
Example Usage
use core_lane::{StateManager, BundleStateManager, Address, U256};
let state = StateManager::new();
let mut bundle = BundleStateManager::new();
let addr = Address::from([1u8; 20]);
let amount = U256::from(1000);
// Add balance in bundle
bundle.add_balance(&state, addr, amount)?;
// Check balance in bundle
assert_eq!(bundle.get_balance(&state, addr), amount);
// Original state unchanged
assert_eq!(state.get_balance(addr), U256::ZERO);
// Apply changes to state
let mut new_state = state;
new_state.apply_changes(bundle);
assert_eq!(new_state.get_balance(addr), amount);