How stratum-mining/stratum works
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.