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
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:
- Loads the
credits.aleo program and initializes its mappings
- Retrieves all deployment transactions from storage
- Loads deployments in order of block height to respect dependencies
- Creates the universal SRS and puzzle
- 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 of the program owner
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
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
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 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
Additional fee on top of execution cost (in microcredits)
query
Option<&dyn QueryTrait<N>>
Query interface for blockchain state
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 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
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
Minimum fee required for the operation
priority_fee_in_microcredits
Additional fee for priority execution
deployment_or_execution_id
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<()>
The block to add (must be the next sequential block)
Returns Ok(()) if the block was successfully added and finalized
Process
- Constructs finalize state from block metadata
- Inserts block into storage (atomic operation)
- Finalizes all transactions in the block
- Updates verifying keys if consensus version changes
- 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.)
Block ratifications (genesis committee, block rewards, etc.)
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>>
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>>>
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.