# opentensor/subtensor architecture

> Architecture diagram of the GitHub repository opentensor/subtensor, 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/opentensor/subtensor
- Repository: https://github.com/opentensor/subtensor

## Overview

Based on your file tree and README, this project is a Substrate-based blockchain node called “Subtensor” that implements Bittensor’s trusted consensus, neuron information advertisement, and value transfer (using TAO). It is essentially a full blockchain node built on FRAME with custom runtime logic and a host of modular “pallets” (each implementing parts of the blockchain logic) plus supporting tooling (Docker, CI workflows, EVM integration tests, etc).

##### Main System Components
- Node & Client Interface:
– The “node” folder (and its associated files like service.rs, cli.rs, and chain_spec.rs) represents the core blockchain client that launches the node.
– This node accepts external connections via RPC/Websocket and communicates with peers over the p2p layer (ports 9944, 9933, and 30333).
- Runtime & FRAME:
– The “runtime” directory contains the core state transition logic. This is where the blockchain’s state is managed and where the FRAME “construct_runtime!” macro assembles all the pallets.
- Pallets:
– Multiple pallets are defined within the “pallets” directory (such as subtensor, admin-utils, collective, commitments, drand, proxy, registry, utility, etc.). These modules implement storage, dispatchables (extrinsics), events, and more.
- Supporting Libraries & Modules:
– “common”, “precompiles” and “primitives” bring in shared logic for smart contract precompiles (like EVM utilities) and safe math operations.
– “support” directory includes macros, linting, and procedural fork tools that assist in constructing the runtime.
- Auxiliary Tools:
– The “evm-tests” folder, along with “scripts” and GitHub Actions workflows, represents the testing, deployment, and CI/CD tooling needed for continuous development.

##### Relationships and Interactions
- The Node acts as the “host” that initializes the chain by reading chain specifications (from node/src/chain_spec, chainspecs) and launching the runtime.
- The pallets interact with each other through defined interfaces in the runtime. For example, things like consensus (via the consensus pallets inside runtime) and staking (within subtensor) work together.
- Communication flows occur between the node’s external interfaces (RPC, WS, and p2p) and the underlying runtime logic.
- Testing and development utilities (evm-tests, Dockerfiles, CI workflows) support the main components but are more peripheral. They can be represented as external tools integrated for development and deployment.

##### Important Architectural Patterns and Design Principles
- Modularity: The heavy use of pallets and support libraries shows a modular and composable design – each module (e.g., subtensor, drand, proxy) is self-contained.
- FRAME and Macro-based Composition: The runtime uses the construct_runtime! macro to aggregate pallets, an important architectural detail.
- Separation of Concerns: There is a clear distinction between the node’s infrastructure (networking, service management, CLI) and the runtime’s state management, which is implemented through pallets.
- DevOps & Testing Infrastructure: The inclusion of Docker, GitHub workflows, shell scripts, and CI tooling indicates a mature development lifecycle and automated testing/deployment ecosystem.

##### Technologies and Frameworks
- Rust and Cargo (used throughout – Cargo.toml, Cargo.lock, rust-toolchain.toml)
- Substrate/FRAME (runtime, chain_spec, service, construct_runtime!)
- Libp2p (for p2p networking as referenced in the README)
- Docker (Dockerfile, docker-compose.yml)
- CI/CD workflows in GitHub Actions (under .github/workflows)
- EVM Testing using TypeScript (evm-tests folder)

##### Final Recommendations
- Be detailed: Include as many components as possible. The granularity might include the primary directories (node, runtime, pallets, precompiles, support) since these indicate key architectural segments.
- Including small callouts for architectural notes (like “Constructed using FRAME”, “Uses Libp2p for networking”, “Chain Spec defines genesis state”) that offer context for each major component.
- You include the testing and deployment layers as “external tools/components” even if they are not part of the runtime code. This is important for understanding the complete development and operational flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global External Interface
    Ext["External RPC/WS Clients"]:::external

    %% Node & Client Interface
    subgraph "Node & Client Interface"
        NodeService["Node Service"]:::node
        NodeCLI["Node CLI"]:::node
        ChainSpec["Chain Spec"]:::node
    end

    %% Runtime & FRAME Layer
    subgraph "Runtime & FRAME"
        RuntimeLogic["Runtime Logic"]:::runtime
        %% Pallet Modules Subgraph
        subgraph "Pallet Modules"
            Subtensor["Subtensor"]:::pallet
            AdminUtils["Admin Utils"]:::pallet
            Collective["Collective"]:::pallet
            Commitments["Commitments"]:::pallet
            Drand["Drand"]:::pallet
            Proxy["Proxy"]:::pallet
            Registry["Registry"]:::pallet
            Utility["Utility"]:::pallet
        end
    end

    %% Supporting Libraries & Modules
    subgraph "Supporting Libraries & Modules"
        CommonLib["Common Library"]:::support
        Precompiles["Precompiles"]:::support
        PrimitivesSafe["Primitives: SafeMath"]:::support
        PrimitivesShare["Primitives: SharePool"]:::support
        SupportLinting["Support: Linting"]:::support
        SupportMacros["Support: Macros"]:::support
        SupportFork["Support: Procedural Fork"]:::support
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        EvmTests["EVM Tests"]:::tools
        DeploymentScripts["Deployment Scripts"]:::tools
        CIWorkflows["CI Workflows"]:::tools
    end

    %% Connections
    Ext -->|"connects"| NodeService
    NodeService -->|"initiates"| RuntimeLogic
    ChainSpec -->|"configures"| RuntimeLogic
    NodeCLI -->|"commands"| NodeService

    %% Runtime to Pallets
    RuntimeLogic -->|"assembles"| Subtensor
    RuntimeLogic -->|"assembles"| AdminUtils
    RuntimeLogic -->|"assembles"| Collective
    RuntimeLogic -->|"assembles"| Commitments
    RuntimeLogic -->|"assembles"| Drand
    RuntimeLogic -->|"assembles"| Proxy
    RuntimeLogic -->|"assembles"| Registry
    RuntimeLogic -->|"assembles"| Utility

    %% Runtime using Supporting Libraries
    RuntimeLogic -->|"uses"| CommonLib
    RuntimeLogic -->|"uses"| Precompiles
    RuntimeLogic -->|"uses"| PrimitivesSafe
    RuntimeLogic -->|"uses"| PrimitivesShare
    RuntimeLogic -->|"uses"| SupportLinting
    RuntimeLogic -->|"uses"| SupportMacros
    RuntimeLogic -->|"uses"| SupportFork

    %% Auxiliary Tools support the system
    CIWorkflows ---|"deploys"| NodeService
    DeploymentScripts ---|"scripts"| NodeService
    EvmTests ---|"tests"| NodeService

    %% Styles
    classDef external fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef node fill:#f4cccc,stroke:#333,stroke-width:2px;
    classDef runtime fill:#c9daf8,stroke:#333,stroke-width:2px;
    classDef pallet fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef support fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef tools fill:#d9d2e9,stroke:#333,stroke-width:2px;

    %% Click Events for Node & Client Interface
    click NodeService "https://github.com/opentensor/subtensor/blob/main/node/src/service.rs"
    click NodeCLI "https://github.com/opentensor/subtensor/blob/main/node/src/cli.rs"
    click ChainSpec "https://github.com/opentensor/subtensor/tree/main/node/src/chain_spec"

    %% Click Events for Runtime & FRAME
    click RuntimeLogic "https://github.com/opentensor/subtensor/blob/main/runtime/src/lib.rs"

    %% Click Events for Pallets
    click Subtensor "https://github.com/opentensor/subtensor/tree/main/pallets/subtensor"
    click AdminUtils "https://github.com/opentensor/subtensor/tree/main/pallets/admin-utils"
    click Collective "https://github.com/opentensor/subtensor/tree/main/pallets/collective"
    click Commitments "https://github.com/opentensor/subtensor/tree/main/pallets/commitments"
    click Drand "https://github.com/opentensor/subtensor/tree/main/pallets/drand"
    click Proxy "https://github.com/opentensor/subtensor/tree/main/pallets/proxy"
    click Registry "https://github.com/opentensor/subtensor/tree/main/pallets/registry"
    click Utility "https://github.com/opentensor/subtensor/tree/main/pallets/utility"

    %% Click Events for Supporting Libraries & Modules
    click CommonLib "https://github.com/opentensor/subtensor/blob/main/common/src/lib.rs"
    click Precompiles "https://github.com/opentensor/subtensor/tree/main/precompiles/src"
    click PrimitivesSafe "https://github.com/opentensor/subtensor/tree/main/primitives/safe-math"
    click PrimitivesShare "https://github.com/opentensor/subtensor/tree/main/primitives/share-pool"
    click SupportLinting "https://github.com/opentensor/subtensor/tree/main/support/linting"
    click SupportMacros "https://github.com/opentensor/subtensor/tree/main/support/macros"
    click SupportFork "https://github.com/opentensor/subtensor/tree/main/support/procedural-fork"

    %% Click Events for Auxiliary Tools
    click EvmTests "https://github.com/opentensor/subtensor/tree/main/evm-tests"
    click DeploymentScripts "https://github.com/opentensor/subtensor/tree/main/scripts/"
    click CIWorkflows "https://github.com/opentensor/subtensor/tree/main/.github/workflows"
```
