# blessnetwork/bls-runtime architecture

> Architecture diagram of the GitHub repository blessnetwork/bls-runtime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blessnetwork/bls-runtime
- Repository: https://github.com/blessnetwork/bls-runtime

## Overview

##### Core Runtime Components
- "blockless" crate: This is the primary library that provides the underlying execution, context management, error handling, and module linking.
- "bls-runtime" crate: Implements the command-line interface and configuration loading. It parses the configuration file (manifest) and initiates the runtime, using environment variables and standard input as further inputs.

##### Driver Infrastructure and Extendibility
- "crates/blockless-drivers" directory: Contains sub-modules for various drivers. These drivers (e.g., cdylib, HTTP, CGI, IPFS, LLM, memory, S3, TCP, and WASI variants) abstract external interactions. They enable the runtime to communicate with external systems and provide extended functionalities.
- The “witx” files serve as interface definitions that detail how the external calls are structured and enforced between the runtime and driver modules.

##### Auxiliary Libraries and WASI Components
- "crates/blockless-env", "crates/blockless-multiaddr", and "crates/wasi-common": Offer system level utilities, networking/multiaddress parsing and proper integration with WASI (WebAssembly System Interface). These are critical for ensuring efficient resource access, safe environment interaction, and portability.

##### Configuration & Logging
- The runtime is highly configurable – driven by an external JSON configuration file example described in the README. This configuration sets paths, fuel limits, memory limits, logging, permissions, and module details to control the environment in which the Wasm code executes.
- Logging is centralized and configured (via the "runtime_logger" parameter) to monitor fuel consumption and runtime errors (such as "Permission Deny" or "wasm unreachable" errors).

##### Supported Languages

- Core Runtime Engine: Represent the "blockless" library as the heart of the system. Show its interaction with module management, code generation, and runtime execution.
- CLI/Configuration Loader: Represent the "bls-runtime" which handles command-line interactions, configuration parsing, and acts as the system entry point.
- Driver Modules: Enumerate the individual driver components (HTTP, CGI, IPFS, LLM, Memory, S3, TCP, WASI) located under “crates/blockless-drivers”. Group them or list them separately according to their functions.
- Supported Language Modules: Create a distinct section or label indicating modules compiled from Rust, Go, and AssemblyScript – showing that the runtime receives “Wasm modules” as input irrespective of their language origin.

- That the core runtime instantiates and links the Wasm modules (provided by users and compiled from the supported languages) to the various driver modules.
- A feedback loop or logging channel connecting the runtime engine to the logging component (configured by runtime_logger) which records events like fuel consumption, errors, or permission violations.
- External communication flows (e.g., network calls via HTTP or file system access) abstracted by the respective drivers.

C. Architectural Patterns and Design Principles:
- Modular Design: The entire system is designed as a collection of self-contained crates/modules (runtime core, drivers, supporting environment modules).
- Configurable & Extensible: The use of external JSON configuration files and clearly defined interface files (witx) support extensibility and customization.
- Isolation & Safety: Note the constraints like fuel and memory limits and permission lists which implement safety and sandboxing principles.
- Multi-language Support Integration: Clearly denote that the system is designed to interoperate with modules from Rust, Go, and AssemblyScript.

- You include every major driver and sub-component from the "blockless-drivers" crate.
- You incorporate all critical pieces including WASI support libraries and the multiaddress parsing component, so that no supported feature is left out.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Configuration Layer"
        CLI["bls-runtime (CLI/Config Loader)"]
        LOGGING["Logging (runtime_logger)"]
    end

    subgraph "Core Engine"
        CORE["blockless (Core Runtime Engine)"]
    end

    subgraph "Driver Modules"
        DRIVER_ROOT["blockless-drivers"]
        CDYLIB["cdylib Driver"]
        CGI["CGI Driver"]
        HTTP["HTTP Driver"]
        IPFS["IPFS Driver"]
        LLM["LLM Driver"]
        MEMORY["Memory Driver"]
        S3["S3 Driver"]
        TCP["TCP Driver"]
        WASI["WASI Support Files"]
        WITX["Interface Definitions (Witx)"]
    end

    subgraph "Auxiliary Libraries"
        ENV["blockless-env"]
        MULTI["blockless-multiaddr"]
        WASI_COMMON["wasi-common"]
    end

    subgraph "Supported Languages"
        RUST["Rust Modules"]
        GO["Go Modules"]
        AS["AssemblyScript Modules"]
    end

    CLI -->|"loadsConfig"| CORE
    CORE -->|"passesModules"| DRIVER_ROOT
    CORE -->|"uses"| ENV
    CORE -->|"uses"| MULTI
    CORE -->|"uses"| WASI_COMMON
    CORE -->|"logsTo"| LOGGING
    RUST -->|"WasmCompiled"| CORE
    GO -->|"WasmCompiled"| CORE
    AS -->|"WasmCompiled"| CORE

    DRIVER_ROOT -->|"contains"| CDYLIB
    DRIVER_ROOT -->|"contains"| CGI
    DRIVER_ROOT -->|"contains"| HTTP
    DRIVER_ROOT -->|"contains"| IPFS
    DRIVER_ROOT -->|"contains"| LLM
    DRIVER_ROOT -->|"contains"| MEMORY
    DRIVER_ROOT -->|"contains"| S3
    DRIVER_ROOT -->|"contains"| TCP
    DRIVER_ROOT -->|"contains"| WASI
    DRIVER_ROOT -->|"contains"| WITX

    class CLI,CORE,LOGGING core
    class DRIVER_ROOT,CDYLIB,CGI,HTTP,IPFS,LLM,MEMORY,S3,TCP,WASI,WITX driver
    class ENV,MULTI,WASI_COMMON aux
    class RUST,GO,AS language

    click CORE "https://github.com/blessnetwork/bls-runtime/tree/main/blockless/"
    click CLI "https://github.com/blessnetwork/bls-runtime/tree/main/bls-runtime/"
    click DRIVER_ROOT "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/"
    click CDYLIB "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/src/cdylib_driver/"
    click CGI "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/src/cgi_driver/"
    click HTTP "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/src/http_driver/"
    click IPFS "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/src/ipfs_driver/"
    click LLM "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/src/llm_driver/"
    click MEMORY "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/src/memory_driver/"
    click S3 "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/src/s3_driver/"
    click TCP "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/src/tcp_driver/"
    click WASI "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/src/wasi/"
    click WITX "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-drivers/witx/"
    click ENV "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-env/"
    click MULTI "https://github.com/blessnetwork/bls-runtime/tree/main/crates/blockless-multiaddr/"
    click WASI_COMMON "https://github.com/blessnetwork/bls-runtime/tree/main/crates/wasi-common/"
    click GO "https://github.com/blessnetwork/bls-runtime/tree/main/examples/golang/"

    classDef core fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef driver fill:#F4A460,stroke:#000,stroke-width:2px;
    classDef aux fill:#DA70D6,stroke:#000,stroke-width:2px;
    classDef language fill:#98FB98,stroke:#000,stroke-width:2px;
```
