Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/provablehq/snarkvm/llms.txt

Use this file to discover all available pages before exploring further.

Overview

The VM type is the highest-level interface in the synthesizer, managing program execution, deployment, verification, and blockchain state. It integrates the process, storage, and consensus logic.

Type Definition

pub struct VM<N: Network, C: ConsensusStorage<N>> {
    /// The process for program execution
    process: Arc<RwLock<Process<N>>>,
    /// The puzzle for proof-of-work
    puzzle: Puzzle<N>,
    /// The consensus storage backend
    store: ConsensusStore<N, C>,
    /// Cache of partially-verified transactions
    partially_verified_transactions: Arc<RwLock<LruCache<TransactionCacheKey<N>, N::TransmissionChecksum>>>,
    /// Program restrictions (e.g., banned programs)
    restrictions: Restrictions<N>,
    /// Channel for sequential operations
    sequential_ops_tx: Arc<RwLock<Option<mpsc::Sender<SequentialOperationRequest<N>>>>>,
    /// Thread handle for sequential operations
    sequential_ops_thread: Arc<Mutex<Option<thread::JoinHandle<()>>>>,
}

Initialization

VM::from

Initializes a VM from consensus storage.
pub fn from(store: ConsensusStore<N, C>) -> Result<Self>
store
ConsensusStore<N, C>
required
Consensus storage backend containing blocks, transactions, and finalize state
return
Result<VM<N, C>>
Returns a new VM instance with all deployed programs loaded from storage

Example

use snarkvm_synthesizer::VM;
use snarkvm_ledger_store::{ConsensusStore, helpers::memory::ConsensusMemory};
use aleo_std::StorageMode;

type CurrentNetwork = snarkvm_console::network::MainnetV0;

let store = ConsensusStore::<CurrentNetwork, ConsensusMemory<_>>::open(
    StorageMode::Production
)?;
let vm = VM::from(store)?;

Loading Process

During initialization, the VM:
  1. Loads the credits.aleo program and initializes its mappings
  2. Retrieves all deployment transactions from storage
  3. Loads deployments in order of block height to respect dependencies
  4. Creates the universal SRS and puzzle
  5. Spawns a background thread for sequential operations

Program Deployment

VM::deploy

Creates a deployment transaction for a new program.
pub fn deploy<R: Rng + CryptoRng>(
    &self,
    private_key: &PrivateKey<N>,
    program: &Program<N>,
    fee_record: Option<Record<N, Plaintext<N>>>,
    priority_fee_in_microcredits: u64,
    query: Option<&dyn QueryTrait<N>>,
    rng: &mut R,
) -> Result<Transaction<N>, VmDeployError>
private_key
&PrivateKey<N>
required
Private key of the program owner
program
&Program<N>
required
The program to deploy
fee_record
Option<Record<N, Plaintext<N>>>
Record to pay private fee. If None, uses public fee from on-chain balance
priority_fee_in_microcredits
u64
Additional fee on top of the base deployment cost (in microcredits)
query
Option<&dyn QueryTrait<N>>
Query interface for blockchain state. Defaults to VM’s block store
rng
&mut R
Cryptographically secure random number generator
return
Result<Transaction<N>, VmDeployError>
Returns a deployment transaction ready to broadcast

Example

use snarkvm_console::program::Program;

let program_source = r"
program token.aleo;

record token:
    owner as address.private;
    amount as u64.private;

function mint:
    input r0 as address.private;
    input r1 as u64.private;
    cast r0 r1 into r2 as token.record;
    output r2 as token.record;
";

let program = Program::from_str(program_source)?;
let deployment = vm.deploy(
    &private_key,
    &program,
    Some(fee_record),
    10_000_000, // 10 credit priority fee
    None,
    &mut rng,
)?;

Deployment Cost Calculation

The deployment cost is computed based on:
  • Program size (bytes)
  • Number of functions
  • Complexity of each function
  • Storage cost for program state
Source: synthesizer/src/vm/deploy.rs:62

Program Execution

VM::execute

Executes a program function and returns a transaction.
pub fn execute<R: Rng + CryptoRng>(
    &self,
    private_key: &PrivateKey<N>,
    (program_id, function_name): (impl TryInto<ProgramID<N>>, impl TryInto<Identifier<N>>),
    inputs: impl ExactSizeIterator<Item = impl TryInto<Value<N>>>,
    fee_record: Option<Record<N, Plaintext<N>>>,
    priority_fee_in_microcredits: u64,
    query: Option<&dyn QueryTrait<N>>,
    rng: &mut R,
) -> Result<Transaction<N>, VmExecError>
private_key
&PrivateKey<N>
required
Private key to authorize the execution
program_id
impl TryInto<ProgramID<N>>
required
Program identifier (e.g., “token.aleo”)
function_name
impl TryInto<Identifier<N>>
required
Function name to execute (e.g., “transfer_private”)
inputs
impl ExactSizeIterator<Item = impl TryInto<Value<N>>>
required
Function input values (records, plaintext values, etc.)
fee_record
Option<Record<N, Plaintext<N>>>
Record for private fee. If None, uses public fee
priority_fee_in_microcredits
u64
Additional fee on top of execution cost (in microcredits)
query
Option<&dyn QueryTrait<N>>
Query interface for blockchain state
rng
&mut R
Cryptographically secure random number generator
return
Result<Transaction<N>, VmExecError>
Returns an execution transaction with proof

Example

use snarkvm_console::program::Value;

let inputs = [
    Value::from_str("aleo1...")?,  // recipient address
    Value::from_str("1000u64")?,   // amount
];

let transaction = vm.execute(
    &private_key,
    ("credits.aleo", "transfer_public"),
    inputs.iter(),
    None,              // public fee
    0,                 // no priority fee
    None,
    &mut rng,
)?;
Source: synthesizer/src/vm/execute.rs:29-49

VM::execute_with_response

Executes a function and returns both the transaction and the response.
pub fn execute_with_response<R: Rng + CryptoRng>(
    &self,
    private_key: &PrivateKey<N>,
    (program_id, function_name): (impl TryInto<ProgramID<N>>, impl TryInto<Identifier<N>>),
    inputs: impl ExactSizeIterator<Item = impl TryInto<Value<N>>>,
    fee_record: Option<Record<N, Plaintext<N>>>,
    priority_fee_in_microcredits: u64,
    query: Option<&dyn QueryTrait<N>>,
    rng: &mut R,
) -> Result<(Transaction<N>, Response<N>), VmExecError>
Parameters are identical to execute, but returns a tuple:
return
Result<(Transaction<N>, Response<N>), VmExecError>
Returns both the transaction and the function’s response containing output values
Source: synthesizer/src/vm/execute.rs:57-66

Authorization

Authorization is the first step of execution, creating a signed request without generating proofs.

VM::authorize

Authorizes a function call without executing it.
pub fn authorize<R: Rng + CryptoRng>(
    &self,
    private_key: &PrivateKey<N>,
    program_id: impl TryInto<ProgramID<N>>,
    function_name: impl TryInto<Identifier<N>>,
    inputs: impl IntoIterator<IntoIter = impl ExactSizeIterator<Item = impl TryInto<Value<N>>>>,
    rng: &mut R,
) -> Result<Authorization<N>, VmAuthError>
private_key
&PrivateKey<N>
required
Private key to sign the authorization
program_id
impl TryInto<ProgramID<N>>
required
Program to execute
function_name
impl TryInto<Identifier<N>>
required
Function to authorize
inputs
impl IntoIterator
required
Function inputs
rng
&mut R
required
Random number generator
return
Result<Authorization<N>, VmAuthError>
Returns an authorization that can be executed later
Source: synthesizer/src/vm/authorize.rs:23-30

VM::execute_authorization

Executes a pre-authorized call.
pub fn execute_authorization<R: Rng + CryptoRng>(
    &self,
    execute_authorization: Authorization<N>,
    fee_authorization: Option<Authorization<N>>,
    query: Option<&dyn QueryTrait<N>>,
    rng: &mut R,
) -> Result<Transaction<N>>
This allows separating authorization from execution, useful for:
  • Offline signing
  • Multi-party computation
  • Deferred execution
Source: synthesizer/src/vm/execute.rs:120-130

Fee Management

VM::authorize_fee_private

Authorizes a private fee using a credits record.
pub fn authorize_fee_private<R: Rng + CryptoRng>(
    &self,
    private_key: &PrivateKey<N>,
    credits: Record<N, Plaintext<N>>,
    base_fee_in_microcredits: u64,
    priority_fee_in_microcredits: u64,
    deployment_or_execution_id: Field<N>,
    rng: &mut R,
) -> Result<Authorization<N>>
credits
Record<N, Plaintext<N>>
required
Credits record to spend for the fee
base_fee_in_microcredits
u64
required
Minimum fee required for the operation
priority_fee_in_microcredits
u64
Additional fee for priority execution
deployment_or_execution_id
Field<N>
required
The deployment or execution ID this fee is for
Source: synthesizer/src/vm/authorize.rs:58-66

VM::authorize_fee_public

Authorizes a public fee using on-chain balance.
pub fn authorize_fee_public<R: Rng + CryptoRng>(
    &self,
    private_key: &PrivateKey<N>,
    base_fee_in_microcredits: u64,
    priority_fee_in_microcredits: u64,
    deployment_or_execution_id: Field<N>,
    rng: &mut R,
) -> Result<Authorization<N>>
Source: synthesizer/src/vm/authorize.rs:92-99

Block Management

VM::add_next_block

Adds a new block to the VM and updates state.
pub fn add_next_block(&self, block: &Block<N>) -> Result<()>
block
&Block<N>
required
The block to add (must be the next sequential block)
return
Result<()>
Returns Ok(()) if the block was successfully added and finalized

Process

  1. Constructs finalize state from block metadata
  2. Inserts block into storage (atomic operation)
  3. Finalizes all transactions in the block
  4. Updates verifying keys if consensus version changes
  5. Rolls back on finalization failure
Source: synthesizer/src/vm/mod.rs:472-479

VM::finalize

Finalizes transactions and updates on-chain state.
pub fn finalize(
    &self,
    state: FinalizeGlobalState,
    ratifications: &[Ratify<N>],
    solutions: &Solutions<N>,
    transactions: impl Iterator<Item = &Transaction<N>>,
) -> Result<Vec<FinalizeOperation<N>>>
state
FinalizeGlobalState
required
Global finalize state (block height, timestamp, etc.)
ratifications
&[Ratify<N>]
required
Block ratifications (genesis committee, block rewards, etc.)
solutions
&Solutions<N>
required
Proof-of-work solutions
transactions
impl Iterator<Item = &Transaction<N>>
required
Transactions to finalize
return
Result<Vec<FinalizeOperation<N>>>
Returns the list of state operations performed

State Access

VM::finalize_store

Returns the finalize storage for reading/writing mappings.
pub fn finalize_store(&self) -> &FinalizeStore<N, C::FinalizeStorage>

VM::block_store

Returns the block storage.
pub fn block_store(&self) -> &BlockStore<N, C::BlockStorage>

VM::transaction_store

Returns the transaction storage.
pub fn transaction_store(&self) -> &TransactionStore<N, C::TransactionStorage>

VM::transition_store

Returns the transition storage.
pub fn transition_store(&self) -> &TransitionStore<N, C::TransitionStorage>
Source: synthesizer/src/vm/mod.rs:285-308

Genesis Blocks

VM::genesis_beacon

Creates a genesis block for a new beacon chain.
pub fn genesis_beacon<R: Rng + CryptoRng>(
    &self,
    private_key: &PrivateKey<N>,
    rng: &mut R,
) -> Result<Block<N>>
Creates a genesis block with 4 validators (default). Source: synthesizer/src/vm/mod.rs:328-330

VM::genesis_quorum

Creates a genesis block with custom committee and balances.
pub fn genesis_quorum<R: Rng + CryptoRng>(
    &self,
    private_key: &PrivateKey<N>,
    committee: Committee<N>,
    public_balances: IndexMap<Address<N>, u64>,
    bonded_balances: IndexMap<Address<N>, (Address<N>, Address<N>, u64)>,
    rng: &mut R,
) -> Result<Block<N>>
committee
Committee<N>
required
Initial committee of validators
public_balances
IndexMap<Address<N>, u64>
required
Initial public credit balances
bonded_balances
IndexMap<Address<N>, (Address<N>, Address<N>, u64)>
required
Initial bonded balances for staking
Source: synthesizer/src/vm/mod.rs:383-390

Program Management

VM::contains_program

Checks if a program exists in the VM.
pub fn contains_program(&self, program_id: &ProgramID<N>) -> bool

VM::process

Returns the underlying process.
pub fn process(&self) -> Arc<RwLock<Process<N>>>

Performance Features

Sequential Operations

The VM uses a background thread for operations that must be sequential:
  • Block additions
  • State finalization
  • Storage writes
This allows the main thread to continue processing while state updates occur atomically.

Transaction Caching

The VM caches partially-verified transactions to avoid redundant verification:
partially_verified_transactions: Arc<RwLock<LruCache<TransactionCacheKey<N>, N::TransmissionChecksum>>>
Cache key includes transaction ID and program checksums, invalidating when programs upgrade. Source: synthesizer/src/vm/mod.rs:121-132

Thread Safety

The VM is Clone and uses Arc<RwLock<_>> for shared state, making it safe to use across threads:
#[derive(Clone)]
pub struct VM<N: Network, C: ConsensusStorage<N>> { ... }
This allows concurrent read access while ensuring exclusive write access for state modifications.

Build docs developers (and LLMs) love