# blocklessnetwork/sdk-rust architecture

> Architecture diagram of the GitHub repository blocklessnetwork/sdk-rust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blocklessnetwork/sdk-rust
- Repository: https://github.com/blocklessnetwork/sdk-rust

## Overview

##### Project type and purpose
- This is a Rust SDK crate (`blockless-sdk-rust`) designed for building WebAssembly modules that run on the Blockless network (native or browser runtimes).
- It provides abstractions over host-provided services (HTTP, socket/CGI, memory, LLM) so that example applications (under `examples/`) can be compiled to `wasm32-wasip1` and executed in the Blockless runtime environment.

##### File structure
- Top‐level files:
- `Cargo.toml`, `rust-toolchain.toml` – project metadata and toolchain lock
- `Makefile` – build helper
- `.github/workflows/*` – CI for build/test/publish
- `src/` contains the library source, split into modules:
- `lib.rs` – crate root, exposes public API
- `http.rs` – HTTP client abstraction
- `socket.rs` & `cgi.rs` – socket/CGI interfaces
- `memory.rs` – persistent storage interface
- `llm.rs` – LLM / Model Control Protocol interface
- `error.rs` – error types
- `examples/` – sample applications that use the SDK modules and demonstrate runtime integration.

##### README for additional insights
- Usage examples build to WASM and invoke:
- Blockless runtime → loads WASM → grants permissions (HTTP, SSE, etc.)
- SDK APIs → call host functions → return data to the module.
- Demonstrates multiple host services (Coingecko HTTP, HTTPBin, LLM/MCP).

##### Main components
A. Developer Code & Examples
- Your application code (e.g., `examples/httpbin.rs`)
- Links against `blockless-sdk` crate
B. blockless-sdk Library
- Modules: HTTP, Socket/CGI, Memory, LLM, Error
- Compiled into a single WASM binary
C. Blockless Runtime (Host Environment)
- Provides low-level host functions (imports) to:
- Perform HTTP requests
- Open sockets / CGI streams
- Read/write to persistent memory
- To LLM endpoints via SSE
- Enforces permissions (via CLI flags)
D. External Services
- HTTP endpoints (e.g., `https://api.coingecko.com/`, `httpbin.org`)
- LLM tool servers (port 3001/3002 for MCP)
E. Crate Publishing & CI/CD
- GitHub Actions workflows: CI (build/test), publish to crates.io
- Developer → pushes tag → `publish.yaml` → crates.io

##### Relationships & interactions
1. Developer writes Rust code (examples) → imports SDK
2. `cargo build --target wasm32-wasip1` → WASM module
3. Blockless runtime CLI (`bls-runtime` or browser plugin) loads WASM
4. WASM → calls imported host functions (HTTP, socket, memory, LLM)
5. Host functions → forward to external services → return data
6. WASM module processes data & returns results to the runtime → console or caller.

##### Architectural patterns & design principles
- Modular crate: each service has its own Rust module
- WASM host-guest boundary: clear separation between SDK (guest) and runtime (host)
- Permission model: runtime enforces fine-grained access
- Example‐driven: showcases extensibility and how the SDK integrates new host services.

##### Final recommendations
- WASM target artifact in your build pipeline.
- Core architectural boundary: SDK crate vs. Blockless runtime vs. external world.

## Diagram (Mermaid)

```mermaid
graph TD
  %% Source Code
  subgraph "Source Code"
    direction TB
    ExamplesDir["Developer Code & Examples (examples/)"]:::dev
    CG["Coingecko Oracle Example"]:::dev
    HB["HTTPBin Example"]:::dev
    LMCP["LLM-MCP Example"]:::dev
    LM["LLM Example"]:::dev
    ExamplesDir --> CG
    ExamplesDir --> HB
    ExamplesDir --> LMCP
    ExamplesDir --> LM

    CrateRoot["blockless-sdk Crate Root (lib.rs)"]:::lib
    HTTPMod["HTTP Client Abstraction (http.rs)"]:::lib
    SocketMod["Socket Interface (socket.rs)"]:::lib
    CGIMod["CGI Interface (cgi.rs)"]:::lib
    MemoryMod["Memory Interface (memory.rs)"]:::lib
    LLMMod["LLM/MCP Interface (llm.rs)"]:::lib
    ErrorMod["Error Types (error.rs)"]:::lib
  end

  %% Build & CI/CD
  subgraph "Build & CI/CD"
    direction TB
    Metadata["Project Metadata & Toolchain"]:::ci
    Makefile["Build Helper (Makefile)"]:::ci
    CI["GitHub Actions CI (ci.yaml)"]:::ci
    Publish["GitHub Actions Publish (publish.yaml)"]:::ci
    CratesIO["crates.io"]:::external
    Metadata --> CI
    Makefile --> CI
    CI --> Publish
    Publish --> CratesIO
  end

  %% Build relationship
  CG -->|imports SDK| CrateRoot
  HB -->|imports SDK| CrateRoot
  LMCP -->|imports SDK| CrateRoot
  LM -->|imports SDK| CrateRoot

  CrateRoot --> HTTPMod
  CrateRoot --> SocketMod
  CrateRoot --> CGIMod
  CrateRoot --> MemoryMod
  CrateRoot --> LLMMod
  CrateRoot --> ErrorMod

  CrateRoot -->|cargo build --target wasm32-wasip1| WASM
  HTTPMod --> WASM
  SocketMod --> WASM
  CGIMod --> WASM
  MemoryMod --> WASM
  LLMMod --> WASM
  ErrorMod --> WASM

  %% WASM Module (Guest)
  subgraph "WASM Module (Guest)"
    direction TB
    WASM["Compiled WASM Binary"]:::wasm
  end

  %% Runtime Host Environment
  subgraph "Blockless Runtime (Host)"
    direction TB
    Permissions["Permission Layer"]:::runtime
    HostFuncs["Host Functions"]:::runtime
    WASM -->|calls imports| HostFuncs
    HostFuncs --> Permissions
  end

  %% External Services
  subgraph "External Services"
    direction TB
    HTTPServices["HTTP Endpoints"]:::external
    LLMServices["LLM Tool Servers"]:::external
    HostFuncs -->|HTTP requests| HTTPServices
    HostFuncs -->|LLM SSE| LLMServices
    HTTPServices -->|responses| HostFuncs
    LLMServices -->|streams| HostFuncs
    HostFuncs -->|returns data| WASM
  end

  %% Build from source
  ExamplesDir -->|push/publish tag| CI

  %% Style classes
  classDef dev fill:#D6EAF8,stroke:#21618C,color:#1B4F72
  classDef lib fill:#AED6F1,stroke:#1A5276,color:#154360
  classDef ci fill:#D5DBDB,stroke:#566573,color:#1C2833
  classDef wasm fill:#A9DFBF,stroke:#196F3D,color:#145A32
  classDef runtime fill:#ABEBC6,stroke:#196F3D,color:#145A32
  classDef external fill:#F9E79F,stroke:#B9770E,color:#7D6608

  %% Click events
  click ExamplesDir "https://github.com/blocklessnetwork/sdk-rust/tree/main/examples/"
  click CG "https://github.com/blocklessnetwork/sdk-rust/blob/main/examples/coingecko_oracle.rs"
  click HB "https://github.com/blocklessnetwork/sdk-rust/blob/main/examples/httpbin.rs"
  click LMCP "https://github.com/blocklessnetwork/sdk-rust/blob/main/examples/llm-mcp.rs"
  click LM "https://github.com/blocklessnetwork/sdk-rust/blob/main/examples/llm.rs"
  click CrateRoot "https://github.com/blocklessnetwork/sdk-rust/blob/main/src/lib.rs"
  click HTTPMod "https://github.com/blocklessnetwork/sdk-rust/blob/main/src/http.rs"
  click SocketMod "https://github.com/blocklessnetwork/sdk-rust/blob/main/src/socket.rs"
  click CGIMod "https://github.com/blocklessnetwork/sdk-rust/blob/main/src/cgi.rs"
  click MemoryMod "https://github.com/blocklessnetwork/sdk-rust/blob/main/src/memory.rs"
  click LLMMod "https://github.com/blocklessnetwork/sdk-rust/blob/main/src/llm.rs"
  click ErrorMod "https://github.com/blocklessnetwork/sdk-rust/blob/main/src/error.rs"
  click Metadata "https://github.com/blocklessnetwork/sdk-rust/blob/main/Cargo.toml"
  click Metadata "https://github.com/blocklessnetwork/sdk-rust/blob/main/rust-toolchain.toml"
  click Makefile "https://github.com/blocklessnetwork/sdk-rust/tree/main/Makefile"
  click CI "https://github.com/blocklessnetwork/sdk-rust/blob/main/.github/workflows/ci.yaml"
  click Publish "https://github.com/blocklessnetwork/sdk-rust/blob/main/.github/workflows/publish.yaml"
```
