### 01-core-architecture/01-components.txt *GenVM* Components Overview *************************** Introduction ============ *GenVM* is a WebAssembly-based virtual machine that enables "Intelligent Contracts" - smart contracts capable of performing non- deterministic operations (AI inference, web scraping, real-world data access) while maintaining blockchain consensus. This document provides an architectural overview of *GenVM*'s major components and how they work together. High-Level Architecture ======================= [graph] *GenVM* Executor ================ The *GenVM* Executor is the heart of the system, providing a modified WebAssembly runtime with blockchain-specific capabilities. Executor itself is a supervisor of *sub-VM*s. **Key Responsibilities:** * Contract execution in deterministic and non-deterministic modes * RAM management (memory) * State management and storage operations * Communication with *Module*s and the *host* **Major Subcomponents:** * **VM Core**: Dual-mode WebAssembly execution engine * **WASI Implementation**: Standard and GenLayer-specific system interfaces * **:term:`Host` Functions**: Bridge between contracts and the *host* environment * **Caching System**: Module compilation and execution optimization *Sub-VM* -------- *GenVM*'s unique dual execution model is implemented by using multiple wasm *sub-VM*s. **Deterministic Mode:** - Executes blockchain consensus logic - Provides reproducible results across all validators - Handles storage operations, message passing, and standard computation **Non-Deterministic Mode:** - Executes AI inference, web scraping, and external data access - Results are validated through consensus mechanisms - Isolated from deterministic state to prevent contamination WASI Interfaces --------------- *GenVM* exposes two WebAssembly System Interfaces: **WASI Preview 1 (``wasip1``)** - Standard WASI interface with deterministic modifications - File system operations, environment access, time functions - Modified to ensure reproducible behavior across validators **:term:`GenLayer WASI SDK` (``genlayer_sdk``)** - Blockchain-specific operations and primitives - Storage access, message passing, contract deployment - Non-deterministic operation triggers and validation Runners (libraries) ------------------- Language runtimes provide the execution environment for different programming languages: **Python Runtime** - Custom CPython build compiled to WebAssembly with software floating point implementation for deterministic mode * GenLayer Python SDK for blockchain primitives * Curated standard library for deterministic execution * Support for some necessary libraries (NumPy, PIL) GenVM requires some built-in runners to be accessible by contracts. They are identified by hashes of their "tar" contents *Host* Interface ---------------- The *Host* Interface manages communication between *GenVM* and the blockchain node. Host is responsible for providing blockchain state to *GenVM* and updating it. *Module*s ========= *Module*s provide non-deterministic capabilities through isolated services: **LLM :term:`Module`** - Large Language Model inference capabilities - Supports multiple AI providers and models - Configurable prompts and response processing - Support for *greyboxing* **Web :term:`Module`** - Web scraping and HTTP request capabilities - Webpage rendering and content extraction - Domain filtering and security controls They are separated from executor for following reasons: * replace-ability * privileges containment *Manager* ========= The *Manager* oversees *Module*s and is responsible for correct GenVM Executor version selection ### 01-core-architecture/02-host-interface.txt *Host* Interface Protocol ************************* Overview ======== The *Host* Interface defines the communication protocol between GenVM and the blockchain node. GenVM launches with "--host" (socket address) and "--message" (JSON data) parameters and communicates via a binary protocol over TCP or Unix domain sockets. Process Management ================== GenVM Execution --------------- **Launch Parameters**: * "--host": TCP address or "unix://" prefixed Unix domain socket * "--message": Message data as JSON following message schema **Process Control**: * **Graceful Shutdown**: Send "SIGTERM" signal * **Force Termination**: Send "SIGKILL" if not responding * **Crash Detection**: Process exit before sending result indicates crash (should be reported as bug) **Node Responsibilities**: Node decides how to receive code and messages from users. GenVM only knows about calldata and message data. Communication Protocol ====================== Pseudocode is available in Host Loop Pseudocode Binary Protocol Design ---------------------- Data Types and Results ====================== VM Result Codes --------------- **Result Types**: * "Return": Successful execution * "VMError": VM-produced error that usually can't be handled * "UserError": User-produced error Result Encoding --------------- **Non-deterministic Blocks and Sandbox Encoding**: * 1 byte of result code * Result data: calldata for "Return", string for "VMError" or "UserError" **Parent VM Result Encoding**: * 1 byte of result code * Data format: * "Return": calldata * "VMError" / "UserError": "{ "message": "string", "fingerprint": ... }" **Host Responsibility**: Calculating storage updates, hashes, and state management (similar to Ethereum's dirty storage override pattern). Method ID Reference =================== Method IDs are available as JSON in the build system for code generation. Error Handling ============== * **Protocol Errors**: Most methods return error codes, with "json/errors/ok" indicating success * **Communication Failures**: Socket communication errors indicate protocol violations * **Process Termination**: Unexpected process exit indicates GenVM crash and should be reported ### 01-core-architecture/03-modules/01-web.txt Web *Module* ************ Web Scraping Capabilities ========================= * HTML parsing and data extraction * JavaScript execution and dynamic content handling via webdriver HTTP Request Handling ===================== * **Protocol Support**: * HTTP/HTTPS request execution * Custom header specification and management * Authentication mechanism support via RFC9421 * Proxy and routing configuration * **Error Handling**: * Network timeout and retry mechanisms * HTTP error code interpretation * Connection failure recovery Security and Compliance ======================= * Whitelist top-level domain filtering * Whitelist port filtering * URL pattern matching and validation * Execution time limits and timeouts ### 01-core-architecture/03-modules/02-llm.txt Large Language Model (LLM) Module ********************************* Capabilities ============ * **AI Inference**: * Text generation * Image recognition * **Multi-Provider Support**: * Integration with various AI service providers * Load balancing across multiple endpoints * Failover mechanisms for service availability * Cost optimization through provider selection * **:term:`Greyboxing` Support**: * Exposing temperature * Using different providers * Providing built-in functions for text and image manipulation Configuration ============= * **Model Parameters**: * Model selection and version specification * Temperature and sampling parameter control * Maximum token limits and constraints * Custom prompt templates and formatting * **Provider Settings**: * API endpoint configuration and authentication * Timeout and retry policy specification * Cost tracking and budget controls * **Security Controls**: * Content filtering and safety measures * Input validation and sanitization * Output monitoring and compliance checking * Privacy protection and data handling ### 01-core-architecture/03-modules/index.txt *Module*s ********* Overview of GenVM's core architectural components and design patterns. * Web *Module* * Web Scraping Capabilities * HTTP Request Handling * Security and Compliance * Large Language Model (LLM) Module * Capabilities * Configuration Overview ======== *Module*s provide GenVM with non-deterministic capabilities that extend beyond traditional blockchain operations. These modules enable intelligent contracts to interact with AI services, access web content, and process real-world data while maintaining consensus through specialized validation mechanisms. Module Architecture =================== Design Principles ----------------- * **Isolation**: *Module*s run in separate processes to prevent contamination of deterministic execution * **Extensibility**: Lua scripting support * **Security**: Controlled access Communication Protocol ---------------------- * **WebSocket Interface**: * Asynchronous communication between GenVM and modules * Message serialization using Calldata Encoding * Request-response pattern with timeout handling * Connection lifecycle management and reconnection * **Message Structure**: * Standardized request/response envelope * Type-safe parameter encoding * Error handling and status reporting Module Lifecycle ---------------- * **Initialization**: * Module process startup * Configuration loading and validation * Initial health check * Binding listening address * **Operation**: * Accepting GenVM connections * Request processing and external service interaction * Result validation and transformation * Resource monitoring and usage tracking * Error handling and recovery procedures * **Termination**: * Graceful shutdown and resource cleanup ### 01-core-architecture/index.txt Core Architecture ***************** Overview of GenVM's core architectural components and design patterns. * *GenVM* Components Overview * Introduction * High-Level Architecture * *GenVM* Executor * *Module*s * *Manager* * *Host* Interface Protocol * Overview * Process Management * Communication Protocol * Data Types and Results * Method ID Reference * Error Handling * *Module*s * Web *Module* * Large Language Model (LLM) Module * Overview * Module Architecture ### 02-vm/01-wasm-runtime.txt Modified *Wasmtime* Runtime *************************** GenVM is based on Wasmtime, the reference WebAssembly runtime, with specific modifications for blockchain use: * **Deterministic Execution**: Modified for reproducible results across validators * **Resource Limits**: Integrated memory constraints * **Error fingerprinting**: Capturing VM state on errors * **Floating Point Handling**: Floating point operations ban in deterministic mode ### 02-vm/index.txt VM and Supervisor Architecture ****************************** * Modified *Wasmtime* Runtime ### 03-greyboxing/01-lua-api.txt Lua API docs ************ Format ====== ====================================================================== LLM === exec_prompt_in_provider ----------------------- fun(ctx: any, data: { prompt: Prompt, format: "bool"|"json"|"text", model: string, provider: string }):any providers --------- table templates --------- { eq_comparative: any, eq_non_comparative_leader: any, eq_non_comparative_validator: any } ====================================================================== LLMExecPromptPayload ==================== images ------ userdata[] prompt ------ string response_format --------------- "json"|"text" ====================================================================== LLMExecPromptTemplatePayload ============================ [string] -------- string template -------- "EqComparative"|"EqNonComparativeLeader"|"EqNonComparativeValidator" ====================================================================== MappedPrompt ============ format ------ "bool"|"json"|"text" prompt ------ Prompt ====================================================================== MergeStrategy ============= ====================================================================== ModelConfig =========== enabled ------- boolean meta ---- any supports_image -------------- boolean supports_json ------------- boolean use_max_completion_tokens ------------------------- boolean ====================================================================== ModuleError =========== causes ------ string[] ctx --- table fatal ----- boolean ====================================================================== Prompt ====== extra ----- table|nil extra_merge_strategy -------------------- "merge_left"|"merge_right"|"none"|"replace"|table>...(+1) images ------ userdata[] max_tokens ---------- integer seed ---- integer|nil system_message -------------- string|nil temperature ----------- number use_max_completion_tokens ------------------------- boolean user_message ------------ string ====================================================================== ProviderEntry ============= models ------ table ====================================================================== ProvidersDB =========== ====================================================================== RS == as_user_error ------------- fun(val: any):ModuleError|nil base64_decode ------------- fun(val: string):string base64_encode ------------- fun(val: string):string filter_image ------------ fun(image: string, filters: any[]):string filter_text ----------- fun(text: string, filters: string[]):string json_parse ---------- fun(val: string):any json_stringify -------------- fun(val: any):string log_json -------- fun(val: any):nil random_bytes ------------ fun(length: integer):string random_float ------------ fun():number request ------- fun(ctx: any, req: { body: string|nil, url: string, headers: table, method: string, error_on_status: boolean|nil, json: false|nil, response_body_max_size: integer|n...(too long)... string> } sleep_seconds ------------- fun(duration: number):nil split_url --------- fun(url: string):{ schema: string, port: number|nil, host: string }|nil url_encode ---------- fun(url: string):string user_error ---------- fun(val: ModuleError):nil ====================================================================== WEB === allowed_tld ----------- { [string]: boolean } config ------ table get_webdriver_session --------------------- fun(ctx: any):string ====================================================================== WebRenderPayload ================ mode ---- "html"|"screenshot"|"text" size_limit ---------- integer? url --- string wait_after_loaded ----------------- number ====================================================================== WebRequestPayload ================= body ---- string? headers ------- table method ------ "DELETE"|"GET"|"HEAD"|"OPTIONS"|"PATCH"...(+1) sign ---- boolean? size_limit ---------- integer? url --- string ====================================================================== my_data ======= table table ### 03-greyboxing/index.txt Greyboxing Documentation ************************ * Lua API docs * Format * LLM * LLMExecPromptPayload * LLMExecPromptTemplatePayload * MappedPrompt * MergeStrategy * ModelConfig * ModuleError * Prompt * ProviderEntry * ProvidersDB * RS * WEB * WebRenderPayload * WebRequestPayload * my_data It refers to the technique of preventing attacks on LLMs. Implementing it is a responsibility of every node, as bundled presets can be attacked. Greyboxing can be achieved by a few methods: 1. Using different llms, potentially selected based on the request itself 2. Randomizing llm calling parameters 3. Modifying prompts The LLM *Module* provides greyboxing capabilities via lua scripting. Retrieving Data from *Host* =========================== Host can provide additional data to the *Module* to help it make decisions, only transaction id and node address are required, as they are required for signing requests. Current Built-in Filters ======================== To simplify implementation, we provide a set of built-in filters that can be used from the script Text ---- * Zero width character removal * Whitespace normalization * Unicode normalization Image ----- * Unsharpen * GuassianNoise * JPEG reconversion Example Usage ============= args.prompt = lib.rs.filter_text(args.prompt, { 'NFKC', 'RmZeroWidth', 'NormalizeWS' }) args.images[0] = lib.rs.filter_image(args.images[0], { { Unsharpen = { 2.0, 4.0 } }, { GaussianNoise = 0.05 }, { JpegRecompress = 0.8 } }) ### appendix/available-runners.txt Available Runners ***************** Contract runners ================ py-genlayer ----------- Standard runner for single-file Python intelligent contracts. Includes CPython, the genlayer standard library, and all core dependencies. Current hash: "1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" * "132536jbnxkd1axfxg5rpfr5b60cr11adm2y4r90hgn0l59qsp9w" — v0.1.8 -runner-hash___ * "1j12s63yfjpva9ik2xgnffgrs6v44y1f52jvj9w7xvdn7qckd379" — v0.1.3 * "15qfivjvy80800rh998pcxmd2m8va1wq2qzqhz850n8ggcr4i9q0" — v0.1.0 py-genlayer-multi ----------------- Runner for multi-file Python contract packages. Same dependencies as py-genlayer. Current hash: "06zyvrlivjga0d5jlpdbprksc0pa6jmllxvp8s20hq1l512vh5yk" * "0iddpsb7hsrqv10xf4sjdiknba0m3fkm2x9xldy7ci3gj1fpkpjy" — v0.1.8 -runner-hash___ * "0xn02qjjqlpxadhs124cwrr5ddqs7dxcc6m5a7c6801hv54l66p0" — v0.1.3 * "0cwifyzi3956f9yxdpq5kk3ihazv2llsxfj626zbadrg4cizwhq5" — v0.1.0 Optional runners ================ py-lib-genlayer-embeddings -------------------------- Adds semantic search and vector embedding support. Must be specified before py-genlayer in a Seq block. Current hash: "0bmbm3cyfwxsyh454z53vxqjf47wz2q7smcqp1q4g4a6k2kidnyk" * "09h0i209wrzh4xzq86f79c60x0ifs7xcjwl53ysrnw06i54ddxyi" — v0.1.0 through v0.1.8-runner-hash___ Internal dependencies ===================== cpython ------- CPython 3.13 interpreter compiled to WebAssembly. Current hash: "1bk9g3zgym0rrpd9lk584cxfaa4rg0cz36w6xhzkqdj1m2p4xa9n" * "1s66bd44b80habdw2ayf4hyncvpkmmjwva0h6nkk738flsd5nis0" — v0.1.0 through v0.1.8-runner-hash___ softfloat --------- Software floating-point implementation for deterministic arithmetic. Current hash: "08g85lmbfjngvvjyx1gr1pyk61nqba0y42gba8wrb1qd3zkv2gmd" * "17b5yad9r9jzcflawqi12r5llhgklfr6lp75r915r99l4wg8ni4n" — v0.1.0 through v0.1.8-runner-hash___ py-lib-cloudpickle ------------------ Object serialization library. Current hash: "1dlk6mnfabi0z7r39635amyfzw8xb6rm8bv4pmgv6ji1bfx9hghd" * "1pqxan7lxsjrvs66b4a7k81w7rrgbsqi3hxhp7b4bn4gks1b64rb" — v0.1.0 through v0.1.8-runner-hash___ py-lib-genlayer-std ------------------- GenLayer standard library providing the gl.* API. Current hash: "11rhn002yfajawsz7fai6mykznbxkxs6l91iskj5cm82c92qhy3v" * "0mmsw09shx3613jzkhbmqyqw60h6b27hy7bjdbb1msfp40g2idi6" — v0.1.8 -runner-hash___ * "1mds1jiy7phn7b7irqviwbl8lp026dsxfkzv88gj0lkmvcqk5aak" — v0.1.3 * "0asq35p8mzlzwgxcrx5v51srnsqyj72cq7993way1vqddwxcvkq4" — v0.1.0 py-lib-protobuf --------------- Protocol Buffers serialization. Current hash: "0riri6vk1ma3cnmlwls3d4771y0cf3c44afsl6gwfmnl2cpcbdl1" py-lib-word_piece_tokenizer --------------------------- Tokenizer for embedding models. Current hash: "0vjc9x1qqv7bgkf9aldqsi708892vzh2w7mwzhq6w1174qan4bas" * "0m4yvkrbqnyygs4g3mmp11kprylks23q9m0pxnkpm1fg4kpck3qq" — v0.1.0 through v0.1.8-runner-hash___ models-all-MiniLM-L6-v2 ----------------------- Pre-trained sentence embedding model (ONNX). Current hash: "0d1skbkxl1ij1sfm0jvnh18ih5a9mxfiny0myqnyf0wa5jc50mis" * "1sfhqijjsnsf6ik1zvdv4vxjidrjhsbnk1vgs1c5ksgv193flyqb" — v0.1.0 through v0.1.8-runner-hash___ ### appendix/host-loop.txt Host Loop Pseudocode ******************** **Constants**: ACCOUNT_ADDR_SIZE = 20 SLOT_ID_SIZE = 32 **Data Encoding Functions**: write_byte_slice(arr): write_u32_le len(arr) write_bytes arr read_slice(): len := read_u32_le data := read_bytes(len) return data Multi-Host ========== GenVM supports multiple host connections. Each host method is routed to a specific host connection based on a "method_hosts" mapping in "ExecutionData". The mapping is a byte array where each index corresponds to a method ID and the value is the host connection index. When the index is out of bounds or the array is empty, host 0 is used as the default. The executor accepts multiple "--host" arguments. Each host connection independently runs the protocol described below. In the manager deployment, host 0 is the node's host loop and host 1 is a socketpair to the manager. The manager routes "consume_result" to itself (host 1) while all other methods go to host 0. Protocol Loop ============= The *host* processes requests in a loop. Each host connection runs independently, handling only the methods routed to it: loop: method_id := read_byte match method_id json/methods/storage_read: read_type := read_byte as json/storage_type address := read_bytes(ACCOUNT_ADDR_SIZE) slot := read_bytes(SLOT_ID_SIZE) index := read_u32_le len := read_u32_le data, err := host_storage_read(read_type, address, slot, index, len) if err != json/errors/ok: write_byte err else: write_byte json/errors/ok write_bytes data # must be exactly len in size json/methods/consume_result: host_result := read_slice() # this is needed to ensure that genvm doesn't close socket before all data is read write_byte 0x00 json/methods/consume_fuel: gas := read_u64_le host_consume_fuel(gas) # note: this method doesn't send any response json/methods/eth_call: address := read_bytes(ACCOUNT_ADDR_SIZE) calldata := read_slice() result, err := host_eth_call(address, calldata) if err != json/errors/ok: write_byte err else: write_byte json/errors/ok write_byte_slice result json/methods/get_balance: address := read_bytes(ACCOUNT_ADDR_SIZE) balance, err := host_get_balance(address) if err != json/errors/ok: write_byte err else: write_byte json/errors/ok write_bytes balance.to_le_bytes(32) # 256-bit integer json/methods/remaining_fuel_as_gen: fuel, err := host_remaining_fuel_as_gen() if err != json/errors/ok: write_byte err else: write_byte json/errors/ok write_bytes fuel.to_le_bytes(8) # 64-bit integer, must be safe integer (fits in double) json/methods/notify_nondet_disagreement: call_no := read_u32_le host_notify_nondet_disagreement(call_no) # note: this method doesn't send any response json/methods/notify_finished: # signals that all execution is complete write_byte 0x00 ### appendix/index.txt Appendix ******** * Host Loop Pseudocode * Multi-Host * Protocol Loop * Manager API * Available Runners * Contract runners * Optional runners * Internal dependencies ### appendix/manager-api.txt Manager API *********** The GenVM Manager is an HTTP server that provides an API for managing GenVM instances, modules, and related operations. GET /status **Get manager status** Returns the current status of the manager, its modules, permits, and running executions. Status Codes: * 200 OK -- Manager status POST /module/start **Start a module** Start a module with the specified configuration. Status Codes: * 200 OK -- Module started successfully * 500 Internal Server Error -- Error response POST /module/stop **Stop a module** Stop a running module. Status Codes: * 200 OK -- Module stop result * 500 Internal Server Error -- Error response POST /module/restart **Restart a module** Atomically restart a module. Stops the currently running module (if any) and starts a new one with the specified configuration, all under a single lock to prevent concurrent access during the transition. Status Codes: * 200 OK -- Module restarted successfully * 500 Internal Server Error -- Error response POST /genvm/run **Start a GenVM execution** Start a new GenVM instance for contract execution. The request body uses calldata binary encoding (not JSON). The schema below shows the logical structure that must be encoded using the calldata format. Status Codes: * 200 OK -- GenVM instance started * 500 Internal Server Error -- Error response GET /genvm/{genvm_id} **Get GenVM status** Get the status of a specific GenVM instance. Parameters: * **genvm_id** (*integer*) -- Unique identifier of the GenVM instance Status Codes: * 200 OK -- GenVM status * 500 Internal Server Error -- Error response DELETE /genvm/{genvm_id} **Shutdown GenVM instance** Gracefully shutdown a GenVM instance. Parameters: * **genvm_id** (*integer*) -- Unique identifier of the GenVM instance Status Codes: * 200 OK -- Shutdown result POST /contract/detect-version **Detect contract version** Detect the major version specification from contract bytecode. Status Codes: * 200 OK -- Detected version * 500 Internal Server Error -- Error response Request Headers: * **Deployment-Timestamp** -- Contract deployment timestamp in RFC3339 format (Required) POST /log/level **Set log level** Set the logging level for the manager. Status Codes: * 200 OK -- Log level set * 500 Internal Server Error -- Error response POST /manifest/reload **Reload manifest** Reload the executor version manifest. Status Codes: * 200 OK -- Manifest reloaded * 500 Internal Server Error -- Error response POST /env **Set environment variable** Set an environment variable in the manager process. Status Codes: * 200 OK -- Environment variable set * 500 Internal Server Error -- Error response GET /permits **Get permits** Get the current number of execution permits available. Status Codes: * 200 OK -- Current permits POST /permits **Set permits** Set the number of execution permits. Status Codes: * 200 OK -- Permits set * 500 Internal Server Error -- Error response POST /llm/check **Check LLM availability** Test availability and functionality of LLM provider configurations. Status Codes: * 200 OK -- LLM availability results * 500 Internal Server Error -- Error response GET /vm-error/describe **Describe VM error** Get a human-readable description for a VM error code. Query Parameters: * **error** (*string*) -- The VM error code to describe (Required) Status Codes: * 200 OK -- Error description * 500 Internal Server Error -- Error response openapi: 3.0.3 info: title: GenVM Manager API description: HTTP API for managing GenVM instances, modules, and related operations. version: 1.0.0 servers: - url: http://localhost:3999 description: Default local development server paths: /status: get: summary: Get manager status description: Returns the current status of the manager, its modules, permits, and running executions. operationId: getStatus responses: '200': description: Manager status content: application/json: schema: type: object properties: llm_module: type: string description: Status of the LLM module example: running web_module: type: string description: Status of the web module example: stopped permits: type: object properties: current: type: integer description: Current number of available permits max: type: integer description: Maximum number of permits executions: type: object description: Status of running executions /module/start: post: summary: Start a module description: Start a module with the specified configuration. operationId: startModule requestBody: required: true content: application/json: schema: type: object required: - module_type properties: module_type: type: string enum: [llm, web] description: Type of module to start config: type: object description: Module-specific configuration example: module_type: llm config: host: localhost port: 8080 responses: '200': description: Module started successfully content: application/json: schema: type: object properties: result: type: string example: module_started '500': $ref: '#/components/responses/ErrorResponse' /module/stop: post: summary: Stop a module description: Stop a running module. operationId: stopModule requestBody: required: true content: application/json: schema: type: object required: - module_type properties: module_type: type: string enum: [llm, web] description: Type of module to stop example: module_type: llm responses: '200': description: Module stop result content: application/json: schema: type: object properties: result: type: string enum: [module_stopped, module_not_running] '500': $ref: '#/components/responses/ErrorResponse' /module/restart: post: summary: Restart a module description: | Atomically restart a module. Stops the currently running module (if any) and starts a new one with the specified configuration, all under a single lock to prevent concurrent access during the transition. operationId: restartModule requestBody: required: true content: application/json: schema: type: object required: - module_type properties: module_type: type: string enum: [llm, web] description: Type of module to restart config: type: object description: Module-specific configuration (null to use default config file) example: module_type: llm config: host: localhost port: 8080 responses: '200': description: Module restarted successfully content: application/json: schema: type: object properties: result: type: string example: module_restarted '500': $ref: '#/components/responses/ErrorResponse' /genvm/run: post: summary: Start a GenVM execution description: | Start a new GenVM instance for contract execution. The request body uses calldata binary encoding (not JSON). The schema below shows the logical structure that must be encoded using the calldata format. operationId: runGenvm requestBody: required: true content: application/octet-stream: schema: $ref: '#/components/schemas/GenvmRunRequest' responses: '200': description: GenVM instance started content: application/json: schema: type: object properties: result: type: string example: started id: type: integer description: Unique identifier for the GenVM instance example: 12345 '500': $ref: '#/components/responses/ErrorResponse' /genvm/{genvm_id}: get: summary: Get GenVM status description: Get the status of a specific GenVM instance. operationId: getGenvmStatus parameters: - name: genvm_id in: path required: true schema: type: integer description: Unique identifier of the GenVM instance responses: '200': description: GenVM status content: application/json: schema: type: object properties: genvm_id: type: integer status: type: object description: Current status of the GenVM instance '500': $ref: '#/components/responses/ErrorResponse' delete: summary: Shutdown GenVM instance description: Gracefully shutdown a GenVM instance. operationId: shutdownGenvm parameters: - name: genvm_id in: path required: true schema: type: integer description: Unique identifier of the GenVM instance responses: '200': description: Shutdown result content: application/json: schema: oneOf: - type: object properties: result: type: string example: shutdown_completed genvm_id: type: integer - type: object properties: error: type: string example: timeout during shutdown genvm_id: type: integer /contract/detect-version: post: summary: Detect contract version description: Detect the major version specification from contract bytecode. operationId: detectContractVersion parameters: - name: Deployment-Timestamp in: header required: true schema: type: string format: date-time description: Contract deployment timestamp in RFC3339 format requestBody: required: true content: application/octet-stream: schema: type: string format: binary description: Contract bytecode responses: '200': description: Detected version content: application/json: schema: type: object properties: specified_major: type: integer description: Detected major version '500': $ref: '#/components/responses/ErrorResponse' /log/level: post: summary: Set log level description: Set the logging level for the manager. operationId: setLogLevel requestBody: required: true content: application/json: schema: type: object required: - level properties: level: type: string enum: [trace, debug, info, warn, error] description: Log level to set example: level: debug responses: '200': description: Log level set content: application/json: schema: type: object properties: result: type: string example: log_level_set level: type: string '500': $ref: '#/components/responses/ErrorResponse' /manifest/reload: post: summary: Reload manifest description: Reload the executor version manifest. operationId: reloadManifest responses: '200': description: Manifest reloaded content: application/json: schema: type: object properties: result: type: string example: manifest_reloaded '500': $ref: '#/components/responses/ErrorResponse' /env: post: summary: Set environment variable description: Set an environment variable in the manager process. operationId: setEnv requestBody: required: true content: application/json: schema: type: object required: - key - value properties: key: type: string description: Environment variable name value: type: string description: Environment variable value example: key: DEBUG_MODE value: "true" responses: '200': description: Environment variable set content: application/json: schema: type: object properties: result: type: string example: env_var_set key: type: string '500': $ref: '#/components/responses/ErrorResponse' /permits: get: summary: Get permits description: Get the current number of execution permits available. operationId: getPermits responses: '200': description: Current permits content: application/json: schema: type: object properties: permits: type: integer description: Number of available permits post: summary: Set permits description: Set the number of execution permits. operationId: setPermits requestBody: required: true content: application/json: schema: type: object required: - permits properties: permits: type: integer description: New number of permits to allocate example: permits: 10 responses: '200': description: Permits set content: application/json: schema: type: object properties: result: type: string example: permits_set permits: type: integer '500': $ref: '#/components/responses/ErrorResponse' /llm/check: post: summary: Check LLM availability description: Test availability and functionality of LLM provider configurations. operationId: checkLlm requestBody: required: true content: application/json: schema: type: object required: - configs - test_prompts properties: configs: type: array items: type: object required: - host - provider - model - key properties: host: type: string description: LLM provider host URL example: https://api.openai.com provider: type: string description: Provider type example: openai-compatible model: type: string description: Model name example: gpt-4o key: type: string description: API key (supports ${ENV[VAR]} syntax) example: ${ENV[OPENAIKEY]} test_prompts: type: array items: type: object properties: system_message: type: string nullable: true user_message: type: string temperature: type: number images: type: array items: type: string max_tokens: type: integer use_max_completion_tokens: type: boolean example: configs: - host: https://api.openai.com provider: openai-compatible model: gpt-4o key: ${ENV[OPENAIKEY]} test_prompts: - system_message: null user_message: | I am testing that your API works and you are capable for understanding the simplest request. For it I need you to respond with two letters "ok" (without quotes) and nothing else. Lowercase, no repetition or punctuation temperature: 0.2 images: [] max_tokens: 200 use_max_completion_tokens: true responses: '200': description: LLM availability results content: application/json: schema: type: array items: type: object properties: config_index: type: integer prompt_index: type: integer available: type: boolean error: type: string nullable: true response: type: string nullable: true '500': $ref: '#/components/responses/ErrorResponse' /vm-error/describe: get: summary: Describe VM error description: Get a human-readable description for a VM error code. operationId: describeVmError parameters: - name: error in: query required: true schema: type: string description: The VM error code to describe responses: '200': description: Error description content: application/json: schema: type: object properties: description: type: string nullable: true description: Human-readable error description, or null if unknown '500': $ref: '#/components/responses/ErrorResponse' components: schemas: Address: type: string format: hex description: 20-byte Ethereum-style address as hex string example: "0x1234567890abcdef1234567890abcdef12345678" MessageData: type: object description: Contract execution message data required: - contract_address - sender_address - origin_address - chain_id - is_init properties: contract_address: $ref: '#/components/schemas/Address' sender_address: $ref: '#/components/schemas/Address' origin_address: $ref: '#/components/schemas/Address' stack: type: array items: $ref: '#/components/schemas/Address' default: [] description: View methods call chain (empty for entrypoint) chain_id: type: string description: Chain ID as big integer string example: "1" value: type: string description: Transaction value as big integer string default: "0" is_init: type: boolean description: Whether this is a contract initialization call datetime: type: string format: date-time description: Transaction timestamp GenvmRunRequest: type: object description: | GenVM execution request. This structure must be encoded using the calldata binary format before sending. required: - major - message - is_sync - capture_output - storage_pages - host_data - timestamp - host - calldata properties: major: type: integer format: uint32 description: Major version specification message: $ref: '#/components/schemas/MessageData' is_sync: type: boolean description: Whether execution is synchronous capture_output: type: boolean description: Whether to capture execution output max_execution_minutes: type: integer format: uint64 default: 20 description: Maximum execution time in minutes storage_pages: type: integer format: uint64 description: Number of storage pages allocated host_data: type: string description: Host-specific data as JSON string timestamp: type: string format: date-time description: Execution timestamp in RFC3339 format host: type: string description: Host identifier extra_args: type: array items: type: string default: [] description: Additional arguments for execution calldata: type: string format: binary description: Contract calldata (method name and arguments) code: type: string format: binary nullable: true description: Optional contract bytecode (for deployment) responses: ErrorResponse: description: Error response content: application/json: schema: type: object properties: error: type: string description: Error message ### glossary.txt Glossary ******** Greyboxing A set of techniques to prevent forcing LLMs to do unintended by contract creator actions. Host The blockchain node that runs GenVM and communicates with it. Module External service providing non-deterministic capabilities. Manager The GenVM component responsible for managing modules and GenVM versions. ### index.txt GenVM Internals *************** Note: Single text file docs for AI This is a specification of this implementation of GenVM. The specification has been split into multiple sections for better organization and maintainability. Contents: ^^^^^^^^^ * Glossary * Core Architecture * *GenVM* Components Overview * Introduction * High-Level Architecture * *GenVM* Executor * *Module*s * *Manager* * *Host* Interface Protocol * Overview * Process Management * Communication Protocol * Data Types and Results * Method ID Reference * Error Handling * *Module*s * Web *Module* * Large Language Model (LLM) Module * Overview * Module Architecture * VM and Supervisor Architecture * Modified *Wasmtime* Runtime * Greyboxing Documentation * Lua API docs * Format * LLM * LLMExecPromptPayload * LLMExecPromptTemplatePayload * MappedPrompt * MergeStrategy * ModelConfig * ModuleError * Prompt * ProviderEntry * ProvidersDB * RS * WEB * WebRenderPayload * WebRequestPayload * my_data * Retrieving Data from *Host* * Current Built-in Filters * Text * Image * Example Usage * Appendix * Host Loop Pseudocode * Multi-Host * Protocol Loop * Manager API * Available Runners * Contract runners * Optional runners * Internal dependencies