:term:`Module`\s
================

Overview
--------

:term:`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**: :term:`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 :ref:`gvm-def-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 :term:`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