GenLayer WASI SDK WASI Interface#

Overview#

The GenLayer WASI SDK WASI interface provides blockchain-specific functionality to WebAssembly contracts through a custom WASI extension. This interface enables contracts to interact with blockchain state, execute non-deterministic operations, and participate in consensus mechanisms while maintaining security and isolation.

Interface Design#

Throughput-heavy operations are exposed as regular wasm functions. Others functions are hidden behind gl_call function, which accepts Calldata Encoded message and returns an error code.

Interface Definition#

#include <stdint.h>

static const uint32_t error_success = 0

static const uint32_t error_overflow = 1
static const uint32_t error_inval = 2
static const uint32_t error_fault = 3
static const uint32_t error_ilseq = 4

static const uint32_t error_io = 5

static const uint32_t error_forbidden = 6
static const uint32_t error_inbalance = 7

__attribute__((import_module("genlayer_sdk"))) uint32_t
storage_read(char const* slot, uint32_t index, char* buf, uint32_t buf_len);
__attribute__((import_module("genlayer_sdk"))) uint32_t
storage_write(
   char const* slot,
   int32_t index,
   char const* buf,
   uint32_t buf_len
);
__attribute__((import_module("genlayer_sdk"))) uint32_t
get_balance(char const* address, char* result);
__attribute__((import_module("genlayer_sdk"))) uint32_t
get_self_balance(char* result);
__attribute__((import_module("genlayer_sdk"))) uint32_t
gl_call(char const* request, uint32_t request_len, uint32_t* result_fd);

Backwards Compatibility#

Passing invalid request to gl_call results in error_inval. Passing data that turned out to be compatible with future version is filtered out by version limitation. And will result in error_inval if method wasn’t available at given version

Functions#

storage_read#

Reads data from contract storage at the specified slot and index.

Requirements#

  1. Sub-VM must be in deterministic mode

  2. Sub-VM must have read storage permission

  3. index + buf_len must not overflow

storage_write#

Writes data to contract storage at the specified slot and index.

Requirements#

  1. Sub-VM must be in deterministic mode

  2. Sub-VM must have write storage permission

  3. index + buf_len must not overflow

  4. Sub-VM Storage slot must not be locked, unless the sender is in upgraders

get_balance#

Queries the balance of a specified contract address.

Result value is a 32 octets long little-endian unsigned integer

get_self_balance#

Gets the current contract’s balance, adjusted for the current transaction context. It is following: balance_before_transaction + message.value - value_consumed_by_current_tx

Result value is a 32 octets long little-endian unsigned integer

Requirements#

  • Contract must be in deterministic mode

gl_call#

Primary GenLayer WASI SDK function handling most intelligent contract operations. Takes serialized Calldata Encoded message buffer and dispatches to various blockchain operations based on message type.

Parameters: request (calldata buffer), request_len (buffer length), result_fd (output file descriptor)

Returns

  • error_success on success

  • error_inval for invalid requests

  • error_forbidden for permission violations

  • error_inbalance for insufficient balance

gl_call Functions#

EthSend Message#

Sends transaction to Ethereum address with optional value transfer.

Requirements#

  1. Deterministic Mode execution

  2. can_send_messages permission

  3. Sufficient contract balance for value transfer

EthCall Message#

Calls Ethereum contract method (read-only operation).

Requirements#

  1. Deterministic Mode execution

  2. can_call_others permission

CallContract Message#

Calls another GenLayer Intelligent Contract.

Requirements#

  1. Deterministic Mode execution

  2. can_call_others permission

Creates new sub-VM instance for contract execution. Inherits sender permissions but disables write_storage.

PostMessage Message#

Posts message to GenLayer contract for later execution.

Requirements#

  1. Deterministic Mode execution

  2. can_send_messages permission

  3. Sufficient contract balance for value transfer

DeployContract Message#

Deploys new intelligent contract to blockchain.

Requirements#

  1. Deterministic Mode execution

  2. can_send_messages permission

  3. Sufficient contract balance for value transfer

Supports CREATE2-style deployment with salt nonce for deterministic addressing.

RunNondet Message#

Executes non-deterministic code with leader/validator consensus. Creates Non-Deterministic Mode VM instance with restricted permissions. See Switching To gvm-def-non-det-mode for more details.

Requirements#

  1. can_spawn_nondet permission

Sandbox Message#

Executes code in sandboxed environment with restricted permissions.

Creates isolated VM instance. Inherits Deterministic Mode from parent. Disables storage read access and spawn_nondet/call_others permissions.

WebRender Message#

Renders web content using GenVM web module.

Requirements#

  1. Non-Deterministic Mode execution

  2. Web module availability

WebRequest Message#

Makes HTTP requests using GenVM web module.

Requirements#

  1. Non-Deterministic Mode execution

  2. Web module availability

ExecPrompt Message#

Executes LLM prompts using GenVM LLM module.

Requirements#

  1. Non-Deterministic Mode execution

  2. LLM module availability

Supports up to 2 images per prompt. Consumes fuel based on LLM usage.

ExecPromptTemplate Message#

Executes structured LLM prompt templates with type-specific validation.

Requirements#

  1. Non-Deterministic Mode execution

  2. LLM module availability

Comparative templates expect boolean responses. Non-comparative templates expect text responses.

EmitEvent Message#

Emits blockchain events with topics and data.

Requirements#

  1. Deterministic Mode execution

  2. GenVM version 0.1.5 or higher

Topics must be exactly 32 bytes each.

Rollback Message#

Triggers contract rollback with custom error message.

Causes VM to exit with UserError. Terminates contract execution immediately.

Return Message#

Returns value from contract execution and terminates.

Causes VM to exit with ContractReturn. Encodes return value using Calldata Encoded format.

Trace.Message Message#

Logs a debug message with timing information including:

  • Custom message text

  • Total elapsed time since VM start

  • Time elapsed since last trace call

Note

Implementations may choose to ignore this message and return an error.

Requirements#

  1. GenVM version 0.1.10 or higher

  2. GenVM implementation is allowed ignore this message

Trace.RuntimeMicroSec Sub-Message#

In Non-Deterministic Mode returns the elapsed execution time in microseconds since VM start. In Deterministic Mode, it always returns 0.

Note

Implementations may choose to ignore this message and return an error.

Requirements#

  1. GenVM version 0.1.10 or higher

  2. GenVM implementation is allowed ignore this message