# stratum-mining/stratum architecture

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

## Overview

##### Project Type & Purpose
- SRI is a reference implementation of the Stratum V2 protocol – a next‐generation mining protocol used to improve efficiency, security, and decentralization in Bitcoin mining.
- The codebase is written in Rust and is structured as a multi-crate workspace. It provides low-level primitives (in the "protocols" folder) and higher-level, role-specific implementations (in the "roles" folder), alongside utilities, examples, benchmarks, and tests.

##### File Structure and Architectural Layers
- Core Protocol Layer ("protocols" directory):
– Contains detailed implementations of both SV1 (legacy) and SV2 components.
– Subdirectories for SV2 include modules such as binary encoding (binary-sv2), codec, constants, framing, noise security, roles-logic, and various subprotocols (e.g., job-declaration, mining, template-distribution).
– This layer defines the communication, encoding/decoding, and message handling logic of the protocol.
- Role-Specific Implementations ("roles" directory):
– Implements actual applications such as:
- jd-client and jd-server: Intended for job delegation.
- mining-proxy: Acts as a bridge for mining messages.
- pool: Implements pool-specific logic.
- translator: Provides a bridge between SV1 and SV2.
- Others like roles-utils and test-utils to support the roles.
– Each of these uses the core protocol libraries and include additional configuration and network modules.
- Common & Utility Libraries ("common" and "utils" directories):
– "common" contains shared functionality like URL handling.
– "utils" contains support crates for key-derivation (bip32), error handling, buffering, and more.
- Examples, Benchmarks, and Tests:
– The "examples" directory shows integration examples (including interoperability with C/C++ and ping-pong message flows).
– "benches" holds benchmark tests for performance comparisons.
– "test" includes integration tests and sniffer utilities.
- CI/CD Workflows and Scripts:
– The .github/workflows and scripts directories automate tests, linting, formatting, and release procedures, which helps ensure architectural stability.

##### Main Components & Their Relationships
– Client/External Interfaces/Examples: Represented in the "examples" folder.
– Protocol Engine: The “protocols” crates act as the backbone for encoding/decoding, security (noise-sv2) and framing.
– Role Implementations: The “roles” directory illustrates how different operational roles (miners, pool operators, translators) consume the protocol engine.
– Common/Utility Services: Shared libraries from "common" and "utils".
– Testing and Benchmarking: Integration tests and benchmark routines that touch multiple layers to ensure end-to-end compatibility.
– Indicate that the common utilities are consumed by both protocols and roles.

##### Architectural Patterns and Design Principles
- Modularity: The project is designed as separate, independent crates—for cleaner separation of concerns and easier maintainability.
- Layered Architecture: Clear separation exists between low-level protocol primitives and high-level role implementations.
- Extensibility: The design supports different client scenarios (e.g., SV1-to-SV2 translation and native SV2 roles), emphasizing a plug-and-play modular approach.
- Dependency Management: Each role or protocol component has its own Cargo.toml, ensuring clear boundaries and versioned dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Protocol Engine Layer
    subgraph "Protocol Engine Layer"
        A1["SV1 Primitives"]:::protocol
        A2["SV2 Primitives"]:::protocol
        subgraph "SV2 Components"
            B1["SV2 Binary Encoding"]:::protocol
            B2["SV2 Codec"]:::protocol
            B3["SV2 Framing"]:::protocol
            B4["SV2 Noise Security"]:::protocol
            B5["SV2 Roles-Logic"]:::protocol
            subgraph "SV2 Subprotocols"
                C1["SV2 Job Declaration"]:::protocol
                C2["SV2 Mining"]:::protocol
                C3["SV2 Template Distribution"]:::protocol
            end
        end
    end

    %% Role Implementations Layer
    subgraph "Role Implementations"
        D1["JD Client"]:::role
        D2["JD Server"]:::role
        D3["Mining Proxy"]:::role
        D4["Pool"]:::role
        D5["Translator"]:::role
        D6["Roles Support Utilities"]:::role
    end

    %% Common & Shared Libraries
    subgraph "Shared Libraries"
        E1["Common Libraries"]:::utility
        E2["Utils Library"]:::utility
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        F1["Examples"]:::infrastructure
        F2["Benchmarks"]:::infrastructure
        F3["Integration Tests"]:::infrastructure
        F4["CI/CD Pipelines"]:::infrastructure
    end

    %% Relationships from Role Implementations to Protocol Engine
    D1 -->|"uses"| B5
    D2 -->|"uses"| B5
    D3 -->|"uses"| B5
    D4 -->|"uses"| B5
    D5 <-->|"bridges"| B5

    %% Relationships from Protocol Engine internal dependencies
    A2 --> B1
    A2 --> B2
    A2 --> B3
    A2 --> B4
    A2 --> B5
    B5 --> C1
    B5 --> C2
    B5 --> C3

    %% Shared Libraries used by Protocol Engine and Roles (grouped arrows)
    E1 ---|"shared"| A1
    E1 ---|"shared"| A2
    E1 ---|"shared"| D1
    E1 ---|"shared"| D2
    E2 ---|"support"| A1
    E2 ---|"support"| A2
    E2 ---|"support"| D1
    E2 ---|"support"| D2

    %% Supporting Infrastructure connections to roles and protocols
    F1 -->|"demonstrates"| D5
    F2 -->|"evaluates"| D4
    F3 -->|"tests"| D3
    F4 -->|"validates"| A1

    %% Click Events for Protocol Engine Layer
    click A1 "https://github.com/stratum-mining/stratum/tree/main/protocols/v1"
    click A2 "https://github.com/stratum-mining/stratum/tree/main/protocols/v2"
    click B1 "https://github.com/stratum-mining/stratum/tree/main/protocols/v2/binary-sv2"
    click B2 "https://github.com/stratum-mining/stratum/tree/main/protocols/v2/codec-sv2"
    click B3 "https://github.com/stratum-mining/stratum/tree/main/protocols/v2/framing-sv2"
    click B4 "https://github.com/stratum-mining/stratum/tree/main/protocols/v2/noise-sv2"
    click B5 "https://github.com/stratum-mining/stratum/tree/main/protocols/v2/roles-logic-sv2"
    click C1 "https://github.com/stratum-mining/stratum/tree/main/protocols/v2/subprotocols/job-declaration"
    click C2 "https://github.com/stratum-mining/stratum/tree/main/protocols/v2/subprotocols/mining"
    click C3 "https://github.com/stratum-mining/stratum/tree/main/protocols/v2/subprotocols/template-distribution"

    %% Click Events for Role Implementations
    click D1 "https://github.com/stratum-mining/stratum/tree/main/roles/jd-client"
    click D2 "https://github.com/stratum-mining/stratum/tree/main/roles/jd-server"
    click D3 "https://github.com/stratum-mining/stratum/tree/main/roles/mining-proxy"
    click D4 "https://github.com/stratum-mining/stratum/tree/main/roles/pool"
    click D5 "https://github.com/stratum-mining/stratum/tree/main/roles/translator"
    click D6 "https://github.com/stratum-mining/stratum/tree/main/roles/roles-utils"

    %% Click Events for Shared Libraries
    click E1 "https://github.com/stratum-mining/stratum/tree/main/common"
    click E2 "https://github.com/stratum-mining/stratum/tree/main/utils"

    %% Click Events for Supporting Infrastructure
    click F1 "https://github.com/stratum-mining/stratum/tree/main/examples"
    click F2 "https://github.com/stratum-mining/stratum/tree/main/benches"
    click F3 "https://github.com/stratum-mining/stratum/tree/main/test/integration-tests"
    click F4 "https://github.com/stratum-mining/stratum/tree/main/.github/workflows"

    %% Styles
    classDef protocol fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef role fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef utility fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef infrastructure fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
