System Architecture

Mycelium features a layered structural system designed to bridge off-chain AI model capabilities with on-chain cryptographic safety. This is achieved by dividing operations between deterministic on-chain logic (written in Python DSL and compiled to WASM) and dynamic off-chain agent reasoning loops (built using the Mycelium SDK and standard LLM connectors).

Detailed System Topography

The following flowchart represents the boundaries, data exchange paths, and protocols shared between local developer instances, the off-chain agent runner environment, and the Stellar ledger layers:

  [ Developer Workspace ]
           │  (mycelium check / compile)
           ▼
  [ Compiler Pipeline ] ──► (Transpiles to Rust) ──► [ Optimized WASM Binary ]
                                                               │
                                                       (deploy to ledger)
                                                               ▼
  [ Off-Chain SDK Runtime ] <───── (JSON-RPC Protocol) ─────► [ Soroban RPC Node ]
   - AgentContext Signer                                       │
   - Hive Registry Client                                      │
   - Escrow Payment Router                             (commits state changes)
   - Agent Loop (LLM Tools)                                    ▼
           │                                        [ Stellar Soroban Ledger ]
    (A2A HTTP Call)                                  - Hive Registry Contract
           ▼                                         - Active Escrow Accounts
  [ Peer Agent Endpoint ]                            - Instance Storage Keys

Sandbox Compiler Environment

For security, resource isolation, and consistency, all web compilation requests are executed inside a sandboxed Docker container on the IDE host server. This ensures that untrusted contract code cannot execute malicious commands on the host system.

Isolation Model: The compiler runs in a container built from `mycelium-compiler:latest`.
Network Constraint: Network access is completely disabled via --network none to prevent data exfiltration.
Resource Quotas: Memory allocation is capped at 512 MB and CPU usage is capped at 1.0 cores.
Execution Timeout: A strict 30-second timeout is enforced. If compilation exceeds this threshold, the sandbox process is forcefully terminated.
Offline Caching: Cargo build caching is pre-warmed within the image. Compilation is run in cargo offline mode (CARGO_NET_OFFLINE=true) to prevent network fetching lag.

Web IDE Architecture

The Mycelium Web IDE consists of an optimized Next.js frontend coupled with a FastAPI backend acting as the API Gateway. Key design features include:

Authentication: Users authenticate via GitHub OAuth. The API Gateway issues a secure, signed JWT session token to the frontend.
Credentials Security: User credentials and GitHub access tokens are encrypted using AES-256-GCM before being stored in Firebase Realtime Database. They are decrypted in-memory only when communicating with GitHub on behalf of the user.
Git-Backed Workspaces: Rather than using a local database, user workspaces are directly mapped to GitHub repositories. Changes are committed and retrieved dynamically via GitHub contents APIs.

Compiler Transpilation Pipeline

The Mycelium transpiler converts Python contract sources to WebAssembly through a strict four-stage pipeline designed to guarantee safety, type alignment, and performance:

Stage 1 — Parsing & Lexing (parser.py)

Reads standard Python files, parses the AST structure, and validates variables annotated as contract state along with external methods marked by @external and @view decorators. It also evaluates module-level static constants.

Stage 2 — AST Safety Validation (validator.py)

Filters code to ensure determinism. It rejects dynamic statements (like eval(), exec()), imports of unpinned libraries, loop lengths that cannot be verified statically, and unbounded storage allocations. It also verifies that all type annotations map to supported Soroban primitives.

Stage 3 — Type Inference Mapping (codegen/inferrer.py)

Maps standard Python types to exact-width Rust equivalents targeting the soroban-sdk crate. For example: 'uint256' maps to 'U256', 'Mapping[K, V]' maps to 'Map<K, V>', and 'address' maps to 'Address'. It additionally infers types for storage keys (propagating prefixes like 'reg:' or 'addr:').

Stage 4 — Transpilation & WASM Packaging (codegen/transpiler.py)

Generates Rust source files matching the inferred type bindings. It then calls 'stellar-cli' and 'rustc' targets to produce optimized WASM binaries ready for network deployment.

Compiler Benchmark Specs

To maintain system accuracy, Mycelium validates compilation against 300 test fixtures. These cover 100 core contracts (storage tests, basic math, type boundaries) and 200 advanced contracts (escrow rules, registry details, multi-signature conditions). Currently, 132 out of the 300 templates compile cleanly and are fully available for testing in the Playground.

Pinned Toolchain Specs

To ensure compilation consistency across various platforms, Mycelium locks all compiler actions to specific dependency versions:

stellar-cli

27.0.0

soroban-sdk

26.1.0

Rust Target

wasm32v1-none

Docker Image

rust:1.95-slim-bookworm

Previous CLI Reference

Mycelium v0.1.0-alpha · Stellar Testnet

Playground Agents Home