Modules#

Overview#

Modules 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: Modules 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

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

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