Struct VmContext 

pub struct VmContext {
    pub instructions_executed: u64,
    pub cache_hits: u64,
    pub pda_cache_hits: u64,
    pub pda_cache_misses: u64,
    pub pending_queue_size: u64,
    /* private fields */
}

Fields

instructions_executed: u64

cache_hits: u64

pda_cache_hits: u64

pda_cache_misses: u64

pending_queue_size: u64

Implementations

impl VmContext

pub fn new() -> Self

pub fn new_with_config(state_config: StateTableConfig) -> Self

pub fn get_state_table_mut(&mut self, state_id: u32) -> Option<&mut StateTable>

Get a mutable reference to a state table by ID Returns None if the state ID doesn’t exist

pub fn registers_mut(&mut self) -> &mut Vec<RegisterValue>

Get public access to registers (for metrics context)

pub fn path_cache(&self) -> &HashMap<String, CompiledPath>

Get public access to path cache (for metrics context)

pub fn current_context(&self) -> Option<&UpdateContext>

Get the current update context

pub fn update_state_from_register( &mut self, state_id: u32, key: Value, register: Register, ) -> Result<()>

pub fn extract_partial_state( &self, state_reg: Register, dirty_fields: &HashSet<String>, ) -> Result<Value>

Extract only the dirty fields from state (public for use by instruction hooks)

pub fn process_event_with_context( &mut self, bytecode: &MultiEntityBytecode, event_value: Value, event_type: &str, context: Option<&UpdateContext>, ) -> Result<Vec<Mutation>>

Process an event with optional context metadata

pub fn process_event( &mut self, bytecode: &MultiEntityBytecode, event_value: Value, event_type: &str, ) -> Result<Vec<Mutation>>

Process an event without context (backward compatibility)

pub fn process_any( &mut self, bytecode: &MultiEntityBytecode, any: Any, ) -> Result<Vec<Mutation>>

pub fn update_pda_reverse_lookup( &mut self, state_id: u32, lookup_name: &str, pda_address: String, seed_value: String, ) -> Result<Vec<PendingAccountUpdate>>

Update a PDA reverse lookup and return pending updates for reprocessing

After registering the PDA reverse lookup, this returns any pending account updates that were queued for this PDA. The caller should reprocess these through the VM by calling process_event() for each update.

Example

let pending = vm.update_pda_reverse_lookup(state_id, lookup_name, pda_addr, seed)?;
for update in pending {
    vm.process_event(&bytecode, update.account_data, &update.account_type)?;
}

pub fn cleanup_expired_pending_updates(&mut self, state_id: u32) -> usize

Clean up expired pending updates that are older than the TTL

Returns the number of updates that were removed. This should be called periodically to prevent memory leaks from orphaned updates.

pub fn queue_account_update( &mut self, state_id: u32, update: QueuedAccountUpdate, ) -> Result<()>

Queue an account update for later processing when PDA reverse lookup is not yet available

Workflow

This implements a deferred processing pattern for account updates when the PDA reverse lookup needed to resolve the primary key is not yet available:

1. Initial Account Update: When an account update arrives but the PDA reverse lookup is not available, call queue_account_update() to queue it for later.

2. Register PDA Mapping: When the instruction that establishes the PDA mapping is processed, call update_pda_reverse_lookup() which returns pending updates.

3. Reprocess Pending Updates: Process the returned pending updates through the VM:

   let pending = vm.update_pda_reverse_lookup(state_id, lookup_name, pda_addr, seed)?;
   for update in pending {
       let mutations = vm.process_event(
           &bytecode,
           update.account_data,
           &update.account_type
       )?;
       // Handle mutations...
   }

Arguments

• state_id - The state table ID
• pda_address - The PDA address that needs reverse lookup
• account_type - The event type name for reprocessing
• account_data - The account data (event value) for reprocessing
• slot - The slot number when this update occurred
• signature - The transaction signature

pub fn get_pending_queue_stats( &self, state_id: u32, ) -> Option<PendingQueueStats>

Get statistics about the pending queue for monitoring

pub fn get_memory_stats(&self, state_id: u32) -> VmMemoryStats

pub fn cleanup_all_expired(&mut self, state_id: u32) -> CleanupResult

pub fn check_state_table_capacity( &self, state_id: u32, ) -> Option<CapacityWarning>

pub fn try_pda_reverse_lookup( &mut self, state_id: u32, lookup_name: &str, pda_address: &str, ) -> Option<String>

Try to resolve a primary key via PDA reverse lookup

pub fn evaluate_computed_expr( &self, expr: &ComputedExpr, state: &Value, ) -> Result<Value>

Evaluate a computed expression AST against the current state This is the core runtime evaluator for computed fields from the AST

pub fn evaluate_computed_fields_from_ast( &self, state: &mut Value, computed_field_specs: &[ComputedFieldSpec], ) -> Result<Vec<String>>

Evaluate all computed fields for an entity and update the state This takes a list of ComputedFieldSpec from the AST and applies them

pub fn create_evaluator_from_specs( specs: Vec<ComputedFieldSpec>, ) -> impl Fn(&mut Value) -> Result<()> + Send + Sync + 'static

Create a computed fields evaluator closure from AST specs This returns a function that can be passed to the bytecode builder

Trait Implementations

impl Default for VmContext

fn default() -> Self

Returns the “default value” for a type.

impl ReverseLookupUpdater for VmContext

fn update( &mut self, pda_address: String, seed_value: String, ) -> Vec<PendingAccountUpdate>

fn flush_pending(&mut self, pda_address: &str) -> Vec<PendingAccountUpdate>