# autonomys/subspace architecture

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

- Interactive diagram: https://gitdiagram.com/autonomys/subspace
- Repository: https://github.com/autonomys/subspace

## Overview

##### Main subsystems
- Node/Client: Represented by the “subspace-node” crate (in crates/subspace-node) along with runtime components (subspace-runtime, subspace-runtime-primitives, etc.). This is the primary blockchain node that ties together chain specs, transaction execution, and consensus mechanisms.
- Farmer: Found in “subspace-farmer” (crates/subspace-farmer). This CLI application interacts with the node and implements the farming logic (proof-of-space aspects, plotting, etc.).
- Gateway: The “subspace-gateway” (crates/subspace-gateway) is a client for distributed storage network connectivity and serves as an interface for external RPC/HTTP communication.
- Domain Components: The “domains” directory contains execution and client code for decoupled execution (“domain-operator”, “block-preprocessor”, etc.), as well as pallets (located under domains/pallets) and runtime parts that extend the Substrate framework with domain-specific logic.
- Networking & Consensus Modules: The crates related to “subspace-networking”, “sc-consensus-subspace”, “sp-consensus-subspace”, and related libraries are responsible for peer-to-peer communication, slot-based consensus, and block relay.
- Archiving & Storage: There are specialized crates like “subspace-archiving” that handle piece reconstruction and storage, and “subspace-proof-of-space” and “subspace-proof-of-time” for consensus proofs.
- Shared Libraries: The “shared” folder holds common components (e.g., subspace-core-primitives, subspace-metrics, subspace-kzg, logging, etc.) used by the other parts.

##### Relationships and interactions
- The Node/Client is the central hub that houses the runtime logic, chain specifications, and handles blockchain state. It communicates with the Farmer (for block production and farming rewards) via RPC and direct network interactions.
- The Domain components (both runtime and client) plug in as separate execution environments or “sandboxes” that run on top of the core node. Link them to the Node with annotations to highlight the decoupled execution and custom pallet logic.

##### Architectural patterns and design principles
- The project leverages Substrate’s modular framework, evident in the separation between pallets (on-chain logic) and off-chain components (like the farmer and gateway).
- There is a clear separation of concerns with dedicated crates for consensus, networking, archiving, domains, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entity
    E("External Clients"):::external

    %% Interface Layer
    subgraph "Interface Layer"
        F("Subspace Farmer"):::interface
        F2("Farmer Components"):::interface
        G("Subspace Gateway"):::interface
        G2("Gateway RPC"):::interface
    end

    %% Core Blockchain
    subgraph "Core Blockchain"
        subgraph "Node & Runtime"
            N("Subspace Node"):::core
            R1("Runtime: subspace-runtime"):::core
            R2("Runtime: subspace-runtime-primitives"):::core
        end
        subgraph "Domain Components"
            D1("Domains"):::domain
            D2("Domains Client"):::domain
            D3("Domains Pallets"):::domain
            D4("sp-domains"):::domain
            D5("sc-domains"):::domain
        end
        subgraph "Networking & Consensus"
            Nw("Networking Module"):::network
            C1("sc-consensus-subspace"):::network
            C2("sc-consensus-subspace-rpc"):::network
            C3("sp-consensus-subspace"):::network
        end
        subgraph "Archiving & Storage"
            A("Archiving Module"):::archive
            P1("Proof of Space"):::archive
            P2("Proof of Time"):::archive
        end
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        S("Shared Libraries"):::shared
        K("subspace-kzg"):::shared
        L("subspace-logging"):::shared
        M("subspace-metrics"):::shared
    end

    %% Connections between Layers
    F -->|"submitProofs"| N
    G -->|"handleRPC"| N
    N -->|"calls"| R1
    N -->|"calls"| R2
    N -->|"integrates"| D1
    N <-->|"communicates"| Nw
    N -->|"archivesData"| A
    G2 -->|"serves"| E

    %% Internal Domain Components connections
    D1 -->|"contains"| D2
    D1 -->|"contains"| D3
    D1 -->|"contains"| D4
    D1 -->|"contains"| D5

    %% Networking & Consensus internal connections
    Nw -->|"includes"| C1
    Nw -->|"includes"| C2
    Nw -->|"includes"| C3

    %% Archiving internal connections
    A -->|"provides"| P1
    A -->|"provides"| P2

    %% Shared Libraries as foundational dependency (dashed lines)
    S --- N
    S --- F
    S --- G
    S --- D1
    S --- Nw
    S --- A

    %% Click Events for Interface Layer
    click F "https://github.com/autonomys/subspace/tree/main/crates/subspace-farmer"
    click F2 "https://github.com/autonomys/subspace/tree/main/crates/subspace-farmer-components"
    click G "https://github.com/autonomys/subspace/tree/main/crates/subspace-gateway"
    click G2 "https://github.com/autonomys/subspace/tree/main/crates/subspace-gateway-rpc"

    %% Click Events for Core Node & Runtime
    click N "https://github.com/autonomys/subspace/tree/main/crates/subspace-node"
    click R1 "https://github.com/autonomys/subspace/tree/main/crates/subspace-runtime"
    click R2 "https://github.com/autonomys/subspace/tree/main/crates/subspace-runtime-primitives"

    %% Click Events for Domain Components
    click D1 "https://github.com/autonomys/subspace/tree/main/domains"
    click D2 "https://github.com/autonomys/subspace/tree/main/domains/client"
    click D3 "https://github.com/autonomys/subspace/tree/main/domains/pallets"
    click D4 "https://github.com/autonomys/subspace/tree/main/crates/sp-domains"
    click D5 "https://github.com/autonomys/subspace/tree/main/crates/sc-domains"

    %% Click Events for Networking & Consensus
    click Nw "https://github.com/autonomys/subspace/tree/main/crates/subspace-networking"
    click C1 "https://github.com/autonomys/subspace/tree/main/crates/sc-consensus-subspace"
    click C2 "https://github.com/autonomys/subspace/tree/main/crates/sc-consensus-subspace-rpc"
    click C3 "https://github.com/autonomys/subspace/tree/main/crates/sp-consensus-subspace"

    %% Click Events for Archiving & Storage
    click A "https://github.com/autonomys/subspace/tree/main/crates/subspace-archiving"
    click P1 "https://github.com/autonomys/subspace/tree/main/crates/subspace-proof-of-space"
    click P2 "https://github.com/autonomys/subspace/tree/main/crates/subspace-proof-of-time"

    %% Click Events for Shared Libraries
    click S "https://github.com/autonomys/subspace/tree/main/shared"
    click K "https://github.com/autonomys/subspace/tree/main/shared/subspace-kzg"
    click L "https://github.com/autonomys/subspace/tree/main/shared/subspace-logging"
    click M "https://github.com/autonomys/subspace/tree/main/shared/subspace-metrics"

    %% Styles
    classDef interface fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef domain fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef network fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef archive fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef shared fill:#e2e3e5,stroke:#383d41,stroke-width:2px;
    classDef external fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
```
