Struct VMHostFunctions 

pub struct VMHostFunctions<'a> { /* private fields */ }

The self-referencing struct.

Implementations

impl VMHostFunctions<'_>

pub fn blob_create(&mut self) -> VMLogicResult<u64>

Creates a new blob for writing.

This initializes a blob upload stream and returns a file descriptor (fd) that can be used with blob_write and blob_close.

Returns

A u64 file descriptor for the new blob write handle.

Errors

• HostError::BlobsNotSupported if the node client is not configured.
• HostError::TooManyBlobHandles if the maximum number of handles is exceeded.
• HostError::IntegerOverflow on u64 overflow.

pub fn blob_write(&mut self, fd: u64, src_data_ptr: u64) -> VMLogicResult<u64>

Writes a chunk of data to a blob.

Arguments

• fd - The file descriptor obtained from blob_create() operation.
• src_data_ptr - A pointer to a source-buffer sys::Buffer in guest memory containing the data chunk to write.

Returns

The number of bytes written as u64, which is equal to the length of the input data buffer.

Errors

• HostError::BlobsNotSupported if the node client is not configured.
• HostError::InvalidBlobHandle if the fd is invalid or not a write handle.
• HostError::BlobWriteTooLarge if the data chunk exceeds max_blob_chunk_size.

pub fn blob_close( &mut self, fd: u64, dest_blob_id_ptr: u64, ) -> VMLogicResult<u32>

Closes a blob handle and gets the resulting blob ID.

For a write handle, this finalizes the upload and writes the resulting BlobId into the guest’s memory buffer. For a read handle, it simply closes it.

Arguments

• fd - The file descriptor to close.
• dest_blob_id_ptr - A pointer to a 32-byte destination buffer sys::BufferMut in guest memory where the final BlobId will be written (for write handles).

Returns

Returns 1 on success.

Errors

• HostError::InvalidMemoryAccess if the blob_id_ptr buffer is not 32 bytes or if memory access fails for a descriptor buffer.
• HostError::InvalidBlobHandle if the fd is invalid.
• HostError::BlobsNotSupported if the node client is not supported or upload operation fails.

pub fn blob_announce_to_context( &mut self, src_blob_id_ptr: u64, src_context_id_ptr: u64, ) -> VMLogicResult<u32>

Announces a blob to a specific context for network discovery.

Arguments

• src_blob_id_ptr - pointer to a 32-byte source-buffer sys::Buffer in guest memory, containing the 32-byte BlobId.
• src_context_id_ptr - pointer to a 32-byte source-buffer sys::Buffer in guest memory, containing the 32-byte ContextId.

Returns

Returns 1 on successful announcement.

Errors

• HostError::BlobsNotSupported if blob functionality is disabled or a network error occurs.
• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

pub fn blob_open(&mut self, src_blob_id_ptr: u64) -> VMLogicResult<u64>

Opens an existing blob for reading.

Arguments

• src_blob_id_ptr - pointer to a 32-byte source-buffer sys::Buffer in guest memory, containing the 32-byte BlobId.

Returns

A u64 file descriptor for the new blob read handle.

Errors

• HostError::BlobsNotSupported if the node client is not configured.
• HostError::TooManyBlobHandles if the maximum number of handles is exceeded.
• HostError::InvalidMemoryAccess if memory access fails for a descriptor buffer.

pub fn blob_read(&mut self, fd: u64, dest_data_ptr: u64) -> VMLogicResult<u64>

Reads a chunk of data from an open blob.

Data is read from the blob and copied into the provided guest memory buffer.

Arguments

• fd - The file descriptor obtained from blob_open.
• dest_data_ptr - A pointer to a destination buffer sys::BufferMut in guest memory where the read data will be stored

Returns

The number of bytes actually read as u64. This can be less than the buffer size if the end of the blob is reached.

Errors

• HostError::BlobsNotSupported if blob functionality is unavailable.
• HostError::InvalidBlobHandle if the fd is invalid or not a read handle.
• HostError::BlobBufferTooLarge if the guest buffer exceeds max_blob_chunk_size.
• HostError::InvalidMemoryAccess if memory access fails for a descriptor buffer.

impl VMHostFunctions<'_>

pub fn send_proposal( &mut self, src_actions_ptr: u64, dest_id_ptr: u64, ) -> VMLogicResult<()>

Creates a new governance proposal.

Call the contract’s send_proposal() function through the bridge.

The proposal actions are obtained as raw data and pushed onto a list of proposals to be sent to the host.

Note that multiple actions are received, and the entire batch is pushed onto the proposal list to represent one proposal.

A unique ID for the proposal is generated by the host and written back into guest memory. The proposal itself is stored in the VMLogic to be included in the Outcome.

Arguments

• src_actions_ptr - pointer to a source-buffer sys::Buffer in guest memory, containing the proposal’s actions.
• dest_id_ptr - A pointer to a 32-byte destination buffer sys::BufferMut in guest memory where the generated proposal ID will be written.

Errors

• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

pub fn approve_proposal(&mut self, src_approval_ptr: u64) -> VMLogicResult<()>

Approves a governance proposal.

Adds the given proposal ID to the list of approvals in the VMLogic.

Arguments

• src_approval_ptr - Pointer to a 32-byte source-buffer sys::Buffer in guest memory containing the ID of the proposal to approve.

Errors

• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

impl VMHostFunctions<'_>

pub fn storage_read( &mut self, src_key_ptr: u64, dest_register_id: u64, ) -> VMLogicResult<u32>

Reads a value from the persistent storage.

If the key exists, the corresponding value is copied into the specified register.

Arguments

• src_key_ptr - A pointer to the key source-buffer in guest memory.
• dest_register_id - The ID of the destination register in host memory where to place the value (if found).

Returns

• Returns 1 if the key was found and the value was recorded into the register.
• Returns 0 if the key was not found.

Errors

• HostError::KeyLengthOverflow if the key size exceeds the configured limit.
• HostError::InvalidMemoryAccess if memory access fails for a descriptor buffer.

pub fn storage_remove( &mut self, src_key_ptr: u64, dest_register_id: u64, ) -> VMLogicResult<u32>

Removes a key-value pair from persistent storage.

If the key exists, the value is copied into the specified host register before removal.

Arguments

• src_key_ptr - A pointer to the key source-buffer in guest memory.
• dest_register_id - The ID of the destination register in host memory where to place the value (if found).

Returns

• Returns 1 if the key was found and removed.
• Returns 0 if the key was not found.

Errors

• HostError::KeyLengthOverflow if the key size exceeds the configured limit.
• HostError::InvalidMemoryAccess if memory access fails for a descriptor buffer.

pub fn storage_write( &mut self, src_key_ptr: u64, src_value_ptr: u64, dest_register_id: u64, ) -> VMLogicResult<u32>

Writes a key-value pair to persistent storage.

If the key already exists, its value is overwritten. The old value is placed into the specified host register.

Arguments

• src_key_ptr - A pointer to the key source-buffer in guest memory.
• src_value_ptr - A pointer to the value source-buffer in guest memory.
• dest_register_id - The ID of the destination register in host memory where to place the old value (if found).

Returns

• Returns 1 if a value was evicted (i.e., the key already existed).
• Returns 0 if a new key was inserted.

Errors

• HostError::KeyLengthOverflow if the key size exceeds the limit.
• HostError::ValueLengthOverflow if the value size exceeds the limit.
• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

impl VMHostFunctions<'_>

pub fn panic(&mut self, src_location_ptr: u64) -> VMLogicResult<()>

Host function to handle a simple panic from the guest.

This function is called when the guest code panics without a message. It captures the source location (file, line, column) of the panic and terminates the execution.

Arguments

• src_location_ptr - A pointer in guest memory to a sys::Location struct, containing file, line, and column information about the panic’s origin.

Returns/Errors

• HostError::Panic if the panic action was successfully executed.
• HostError::InvalidMemoryAccess if memory access fails for a descriptor buffer.

pub fn panic_utf8( &mut self, src_panic_msg_ptr: u64, src_location_ptr: u64, ) -> VMLogicResult<()>

Host function to handle a panic with a UTF-8 message from the guest.

This function is called when guest code panics with a message. It captures the message and source location, then terminates the execution.

Arguments

• src_panic_msg_ptr - A pointer in guest memory to a source-buffer sys::Buffer containing the UTF-8 panic message.
• src_location_ptr - A pointer in guest memory to a sys::Location struct for the panic’s origin.

Returns/Errors

• HostError::Panic if the panic action was successfully executed.
• HostError::BadUTF8 if reading UTF8 string from guest memory fails.
• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

pub fn register_len(&self, register_id: u64) -> VMLogicResult<u64>

Returns the length of the data in a given register.

Arguments

• register_id - The ID of the register to query.

Returns

The length of the data in the specified register. If the register is not found, it returns u64::MAX.

pub fn read_register( &self, register_id: u64, dest_data_ptr: u64, ) -> VMLogicResult<u32>

Reads the data from a register into a guest memory buffer.

Arguments

• register_id - The ID of the register to read from.
• dest_data_ptr - A pointer in guest memory to a destination buffer sys::BufferMut where the data should be copied.

Returns

• Returns 1 if the data was successfully read and copied.
• Returns 0 if the provided guest buffer has a different length than the register’s data.

Errors

• HostError::InvalidRegisterId if the register does not exist.
• HostError::InvalidMemoryAccess if memory access fails for a descriptor buffer.

pub fn context_id(&mut self, dest_register_id: u64) -> VMLogicResult<()>

Copies the current context ID into a register.

Arguments

• dest_register_id - The ID of the destination register.

Errors

• HostError::InvalidMemoryAccess if the register operation fails (e.g., exceeds limits).

pub fn executor_id(&mut self, dest_register_id: u64) -> VMLogicResult<()>

Copies the executor’s public key into a register.

Arguments

• dest_register_id - The ID of the destination register.

Errors

• HostError::InvalidMemoryAccess if the register operation fails (e.g., exceeds limits).

pub fn input(&mut self, dest_register_id: u64) -> VMLogicResult<()>

Copies the input data for the current execution (from context ID) into a register.

Arguments

• dest_register_id - The ID of the destination register.

Errors

• HostError::InvalidMemoryAccess if the register operation fails (e.g., exceeds limits).

pub fn value_return(&mut self, src_value_ptr: u64) -> VMLogicResult<()>

Sets the final return value of the execution.

This function can be called by the guest to specify a successful result (Ok) or a custom execution error (Err). This value will be part of the final Outcome.

Arguments

• src_value_ptr - A pointer in guest memory to a source-sys::ValueReturn, which is an enum indicating success or error, along with the data buffer.

Errors

• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

pub fn log_utf8(&mut self, src_log_ptr: u64) -> VMLogicResult<()>

Adds a new log message (UTF-8 encoded string) to the execution log. The message is being obtained from the guest memory.

Arguments

• src_log_ptr - A pointer in guest memory to a source-sys::Buffer containing the log message.

Errors

• HostError::LogsOverflow if the maximum number of logs has been reached.
• HostError::BadUTF8 if the message is not a valid UTF-8 string.
• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

pub fn emit(&mut self, src_event_ptr: u64) -> VMLogicResult<()>

Emits a structured event that is added to the events log.

Events are recorded and included in the final execution Outcome.

Arguments

• src_event_ptr - A pointer in guest memory to a sys::Event struct, which contains source-buffers for the event kind and data.

Errors

• HostError::EventKindSizeOverflow if the event kind is too long.
• HostError::EventDataSizeOverflow if the event data is too large.
• HostError::EventsOverflow if the maximum number of events has been reached.
• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

pub fn emit_with_handler( &mut self, src_event_ptr: u64, src_handler_ptr: u64, ) -> VMLogicResult<()>

Emits an event with an optional handler name.

This function is similar to emit but includes handler information. The handler name is read from the provided memory pointer.

Arguments

• src_event_ptr - Pointer to the event data in guest memory.
• src_handler_ptr - Pointer to the handler name in guest memory (can be 0 for no handler).

Returns

• Ok(()) if the event was successfully emitted.

Errors

• HostError::EventKindSizeOverflow if the event kind is too long.
• HostError::EventDataSizeOverflow if the event data is too large.
• HostError::EventsOverflow if the maximum number of events has been reached.
• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

pub fn commit( &mut self, src_root_hash_ptr: u64, src_artifact_ptr: u64, ) -> VMLogicResult<()>

Commits the execution state, providing a state root and an artifact.

This function can only be called once per execution.

Arguments

• src_root_hash_ptr - A pointer to a source-buffer in guest memory containing the 32-byte state root hash.
• src_artifact_ptr - A pointer to a source-buffer in guest memory containing a binary artifact.

Errors

• HostError::InvalidMemoryAccess if this function is called more than once or if memory access fails for descriptor buffers.

impl VMHostFunctions<'_>

pub fn fetch( &mut self, src_url_ptr: u64, src_method_ptr: u64, src_headers_ptr: u64, src_body_ptr: u64, dest_register_id: u64, ) -> VMLogicResult<u32>

Fetches data from a URL.

Performs an HTTP request. This is a synchronous, blocking operation. The response body is placed into the specified host register.

Arguments

• src_url_ptr - Pointer to the URL string source-buffer in guest memory.
• src_method_ptr - Pointer to the HTTP method string source-buffer (e.g., “GET”, “POST”) in guest memory.
• src_headers_ptr - Pointer to a borsh-serialized Vec<(String, String)> source-buffer of headers in guest memory.
• src_body_ptr - Pointer to the request body source-buffer in guest memory.
• dest_register_id - The ID of the destination register in host memory where to store the response body.

Returns

• Returns 0 on success (HTTP 2xx)
• Returns 1 on failure. The response body or error message is placed in the host register.

Errors

• HostError::DeserializationError if the headers cannot be deserialized.
• HostError::InvalidMemoryAccess if memory access fails for descriptor buffers.

pub fn random_bytes(&mut self, dest_ptr: u64) -> VMLogicResult<()>

Fills a guest memory buffer with random bytes.

Arguments

• dest_ptr - A destination pointer to a sys::BufferMut in guest memory to be filled.

Errors

• HostError::InvalidMemoryAccess if memory access fails for a descriptor buffer.

pub fn time_now(&mut self, dest_ptr: u64) -> VMLogicResult<()>

Gets the current Unix timestamp in nanoseconds.

This function obtains the current time as a nanosecond timestamp, as SystemTime is not available inside the guest runtime. Therefore the guest needs to request this from the host.

The result is written into a guest buffer as a u64.

Arguments

• dest_ptr - A pointer to an 8-byte destination buffer sys::BufferMut in guest memory where the u64 timestamp will be written.

Errors

• HostError::InvalidMemoryAccess if the provided buffer is not exactly 8 bytes long or if memory access fails for a descriptor buffer.

Trait Implementations

impl<'a> Drop for VMHostFunctions<'a>

fn drop(&mut self)

Executes the destructor for this type.