Struct VM

pub struct VM(/* private fields */);

The Virtual Machine (VM) for executing smart contracts in the Dusk Network.

The VM struct serves as the core for managing the network’s state, executing smart contracts, and interfacing with host functions. It supports both persistent and ephemeral sessions for handling transactions, contract queries and contract deployments.

Implementations

impl VM

pub fn new(root_dir: impl AsRef<Path> + Into<PathBuf>) -> Result<Self, Error>

Creates a new instance of the virtual machine.

This method initializes the VM with a given root directory and registers the necessary host-queries for contract execution.

Arguments

• root_dir - The path to the root directory for the VM’s state storage. This directory will be used to save any future session commits made by this VM instance.

Returns

A new VM instance.

Errors

If the directory contains unparseable or inconsistent data.

Examples

use dusk_vm::VM;

let vm = VM::new("/path/to/root_dir");

pub fn ephemeral() -> Result<VM, Error>

Creates an ephemeral VM instance.

This method initializes a VM that operates in memory without persisting state. It is useful for testing or temporary computations.

Returns

A new ephemeral VM instance.

Errors

If creating a temporary directory fails.

Examples

use dusk_vm::VM;

let vm = VM::ephemeral();

pub fn session( &self, base: [u8; 32], chain_id: u8, block_height: u64, ) -> Result<Session, Error>

Creates a new session for transaction execution.

This method initializes a session with a specific base state commit, chain identifier, and block height. Sessions allow for isolated transaction execution without directly affecting the persistent VM state until finalized.

Arguments

• base - A 32-byte array representing the base state from which the session begins.
• chain_id - The identifier of the network.
• block_height - The current block height at which the session is created.

Returns

A Result containing a Session instance for executing transactions, or an error if the session cannot be initialized.

Errors

If base commit is provided but does not exist.

Examples

use dusk_vm::VM;

const CHAIN_ID: u8 = 42;

// create a genesis session
let vm = VM::ephemeral().unwrap();
let session = vm.genesis_session(CHAIN_ID);

// [...] apply changes to the network through the running session

// commit the changes
let base = session.commit().unwrap();

// spawn a new session on top of the base-commit
let block_height = 21;
let session = vm.session(base, CHAIN_ID, block_height).unwrap();

pub fn genesis_session(&self, chain_id: u8) -> Session

Initializes a session for setting up the genesis block.

This method creates a session specifically for defining the genesis block, which serves as the starting state of the network. The genesis session uses the specified chain ID.

Arguments

• chain_id - The identifier of the blockchain chain for which the genesis state is initialized.

Returns

A Session instance for defining the genesis block.

Examples

use dusk_vm::VM;

const CHAIN_ID: u8 = 42;

let vm = VM::ephemeral().unwrap();
let genesis_session = vm.genesis_session(CHAIN_ID);

pub fn commits(&self) -> Vec<[u8; 32]>

Retrieves all pending commits in the VM.

This method fetches unfinalized state changes for inspection or processing.

Returns

A vector of commits.

pub fn delete_commit(&self, root: [u8; 32]) -> Result<(), Error>

Deletes a specified commit from the VM.

Arguments

• commit - The commit to be deleted.

pub fn finalize_commit(&self, root: [u8; 32]) -> Result<(), Error>

Finalizes a specified commit, applying its state changes permanently.

Arguments

• commit - The commit to be finalized.

pub fn root_dir(&self) -> &Path

Returns the root directory of the VM.

This is either the directory passed in by using [new], or the temporary directory created using [ephemeral].

pub fn sync_thread(&self) -> &Thread

Returns a reference to the synchronization thread.

Trait Implementations

impl Debug for VM

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<VM> for VM

fn from(piecrust_vm: PiecrustVM) -> Self

Converts to this type from the input type.