Struct Host

pub struct Host<DB: ZephyrDatabase, L: LedgerStateRead>(/* private fields */);

Zephyr Host State.

Implementations

impl<DB: ZephyrDatabase + Clone + 'static, L: LedgerStateRead + 'static> Host<DB, L>

pub fn get_memory(caller: &Caller<'_, Self>) -> Memory

Returns wasmi’s VM memory handler.

impl<DB: ZephyrDatabase + Clone + 'static, L: LedgerStateRead + 'static> Host<DB, L>

pub fn soroban_host(caller: &Caller<'_, Self>) -> Host

Returns the Soroban host object associated to the Zephyr host.

impl<DB: ZephyrDatabase + ZephyrStandard, L: LedgerStateRead + ZephyrStandard> Host<DB, L>

pub fn from_id(id: i64, network_id: [u8; 32]) -> Result<Self>

Creates a standard Host object starting from a given host ID. The host ID is the only relation between the VM and the entity it is bound to. For instance, in Mercury the host id is the id of a Mercury user. This is needed to implement role constraints in Zephyr.

impl<DB: ZephyrDatabase + Clone + 'static, L: LedgerStateRead + 'static> Host<DB, L>

pub fn add_ledger_close_meta( &mut self, ledger_close_meta: Vec<u8>, ) -> Result<()>

Loads the ledger close meta bytes of the ledger the Zephyr VM will have access to.

The ledger close meta is stored as a slice and currenty no type checks occur. The functions returns a HostError::LedgerCloseMetaOverridden error when a ledger close meta is already present in the host object. This is because VMs are not re-usable between ledgers and need to be created and instantiated for each new invocation to prevent memory issues.

pub fn add_transmitter(&mut self, transmitter: UnboundedSender<Vec<u8>>)

Adds a transmitter that will be used to send message to the associated receiver once every time the Self::send_message host is called.

Current behaviour replaces any existing transmitter.

pub fn as_budget(&self) -> Ref<'_, Budget>

Returns a reference to the host’s budget implementation.

pub fn as_stack_mut(&self) -> RefMut<'_, Stack>

Returns a reference to the host’s stack implementation.

pub fn get_host_id(&self) -> i64

Returns the id assigned to the host.

pub fn get_entry_point_info(&self) -> Ref<'_, InvokedFunctionInfo>

Returns a reference to the host’s entry point information.

pub fn load_context(&self, vm: Weak<Vm<DB, L>>) -> Result<()>

Loads VM context in the host if needed.

pub fn send_message( caller: Caller<'_, Self>, offset: i64, size: i64, ) -> Result<()>

Sends a message to any receiver whose sender has been provided to the host object.

pub fn read_result(&self) -> String

Read a result string potentially written from the guest environment.

pub fn host_functions( &self, store: &mut Store<Host<DB, L>>, ) -> Vec<FunctionInfo>

Returns all the host functions that must be defined in the linker. This should be the only public function related to foreign functions provided by the VM, the specific host functions should remain private.

Current host functions

The functions are currently:

• Database write: retrieves instructions and data to be written specified by the module and calls the [DB::write_raw()] function. Writing to the database is streamlined to the [DB] implementation.
• Database read: retrieves instructions for the data to be read by the module and calls the [DB::read_raw()] function. Reading from the database is streamlined to the [DB] implementation.
• Database update: Retrieves and structures instructions and data used by the [DB] implementation to update a table.
• Log function: takes an integer from the module and logs it in the host.
• Stack push function: pushes an integer from the module to the host’s pseudo stack. This is currently the means of communication for unbound intructions between the guest and the host environment.
• Read ledger close meta: Reads the host’s latest ledger meta (if present) and writes it to the module’s memory. Returns the offset and the size of the bytes written in the binary’s memory.

Trait Implementations

impl<DB: Clone + ZephyrDatabase, L: Clone + LedgerStateRead> Clone for Host<DB, L>

fn clone(&self) -> Host<DB, L>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<DB: ZephyrDatabase + ZephyrMock, L: LedgerStateRead + ZephyrMock> ZephyrMock for Host<DB, L>

fn mocked() -> Result<Self>

Creates a Host object designed to be used in tests with potentially mocked data such as host id, databases and context.