Struct soroban_env_host::vm::Vm

pub struct Vm { /* private fields */ }

A Vm is a thin wrapper around an instance of wasmi::Module. Multiple Vms may be held in a single Host, and each contains a single WASM module instantiation.

Vm rejects modules with either floating point or start functions.

Vm is configured to use its Host as a source of WASM imports. Specifically Host implements [wasmi::ImportResolver] by resolving all and only the functions declared in Env as imports, if requested by the WASM module. Any other lookups on any tables other than import functions will fail.

Implementations

impl Vm

pub fn new(
    host: &Host,
    contract_id: Hash,
    module_wasm_code: &[u8]
) -> Result<Rc<Self>, HostError>

Constructs a new instance of a Vm within the provided Host, establishing a new execution context for a contract identified by contract_id with WASM bytecode provided in module_wasm_code.

This function performs several steps:

• Parses and performs WASM validation on the module.
• Checks that the module contains an meta::INTERFACE_VERSION that matches the host.
• Checks that the module has no floating point code or start function, or post-MVP wasm extensions.
• Instantiates the module, leaving it ready to accept function invocations.
• Looks up and caches its linear memory export named memory if it exists.

This method is called automatically as part of Host::invoke_function and does not usually need to be called from outside the crate.

pub fn invoke_function(
    self: &Rc<Self>,
    host: &Host,
    func: &str,
    args: &ScVec
) -> Result<ScVal, HostError>

Invokes a function in the VM’s module, converting externally stable XDR ScVal arguments into Host-specific RawVals and converting the RawVal returned from the invocation back to an ScVal.

This function, like Vm::new, is called as part of Host::invoke_function, and does not usually need to be called manually from outside the crate.

pub fn functions(&self) -> Vec<VmFunction>

Returns a list of functions in the WASM module loaded into the Vm.

pub fn custom_section(&self, name: impl AsRef<str>) -> Option<&[u8]>

Returns the raw bytes content of a named custom section from the WASM module loaded into the Vm, or None if no such custom section exists.

pub fn with_vmcaller<F, T>(&self, f: F) -> Twhere
    F: FnOnce(&mut VmCaller<'_, Host>) -> T,

Utility function that synthesizes a VmCaller<Host> configured to point to this VM’s Store and Instance, and calls the provided function back with it. Mainly used for testing.