# btccom/bccpool architecture

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

## Overview

This project is the legacy branch of BTCPool for Bitcoin Cash – a backend system for managing a cryptocurrency mining pool. The pool backend is designed to handle mining work for Bitcoin Cash (and by extension Bitcoin and similar SHA256 coins in the newer version), and it integrates closely with external systems like Bitcoind (via ZMQ), Zookeeper, Kafka, and MySQL. Given its purpose as a high-performance and scalable pool backend, the system is composed of numerous specialized components that interact through message queues and network communication.

##### Main Components
- External Dependencies:
- Bitcoind: A Bitcoin Cash (and related coin) node that provides blockchain data through its ZMQ interface.
- Zookeeper: For coordination and configuration management.
- Kafka: Used as the messaging backbone for transmitting mining tasks and results.
- MySQL: Likely used for storing state, statistics, and pool-related information.
- Docker Containers: Various Docker configurations (found in the “docker” directory) indicate the deployment environment of different Bitcoind versions and pool configurations.
- Core Backend Services (located under the “src” directory):
- BlockMaker (src/blkmaker): Responsible for constructing valid blocks.
- GbtMaker (src/gbtmaker): Produces “getblocktemplate” messages for miners.
- JobMaker (src/jobmaker): Creates mining jobs based on incoming data.
- NMCAuxMaker (src/nmcauxmaker): Likely handles auxiliary proof-of-work for merged mining.
- Stratum Server and Stratum-related modules (src/sserver, src/Stratum*): Handle miner connections through the stratum protocol.
- PoolWatcher (src/poolwatcher): Monitors pool performance, health, or operational data.
- ShareLogger (src/sharelogger): Logs miner shares.
- Simulator (src/simulator): As described in the README for testing; simulates numerous miners.
- Additional utilities and modules (e.g., Statistics, Zookeeper integration (src/Zookeeper.cc), Kafka integration (src/Kafka.cc), and others).

##### Relationships and Interactions
- Data Flow:
- Bitcoind streams block and transaction data via ZMQ.
- Incoming blockchain data is processed by components such as BlockMaker and GbtMaker, which then formulate mining tasks.
- JobMaker distributes these tasks through Kafka, ensuring decoupling between services.
- The Stratum Server communicates mining job information to connected miners (including through BtcAgent – the pool’s custom stratum proxy referenced in the README).
- Results (shares) from the miners are captured by the ShareLogger and fed back into the system (possibly stored in MySQL and monitored by PoolWatcher).
- Control Flow:
- Zookeeper is used for service coordination and possibly for dynamic configuration, ensuring services are synchronized in a distributed environment.
- Each backend service (indicated by separate executables/config files in the src directory) is responsible for a single aspect of the mining pool workflow.

##### Architectural Patterns and Design Principles
- Modular and Microservices-Like Design:
- The separation into distinct executables (block maker, job maker, etc.) suggests modularization where each component handles a dedicated function.
- Message-driven Communication:
- The integration with Kafka implies that many interactions between modules occur through asynchronous message passing.
- External Dependency Integration:
- Usage of Zookeeper for configuration/coordination and Bitcoind for blockchain information exemplify how the system interacts with other critical components.
- Deployment and Configuration:
- The presence of numerous Dockerfiles indicates containerized deployment, which is useful for scalability and reproducibility.

##### Final Recommendations
- Incorporate annotations where necessary to explain the use of external systems like Kafka and Zookeeper.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    ED1["Bitcoind (ZMQ)"]:::external
    ED2["Zookeeper Cluster"]:::external
    ED3["Kafka Broker"]:::external
    ED4["MySQL Database"]:::external

    %% Deployment Environment
    DE1["Docker Deployment"]:::deployment

    %% Backend Services
    subgraph "Backend Services"
        BS1["BlockMaker – Creates Blocks"]:::service
        BS2["GbtMaker – Creates GetBlockTemplate"]:::service
        BS3["NMCAuxMaker – Handles Auxiliary Work"]:::service
        BS4["JobMaker – Distributes Mining Jobs"]:::service
        BS5["Stratum Server – Handles Miner Connections"]:::service
        BS6["Stratum Modules – Additional Stratum Components"]:::service
        BS7["ShareLogger – Logs Miner Shares"]:::service
        BS8["Simulator – Miner Simulator"]:::service
        BS9["PoolWatcher – Monitors Pool Health"]:::service
    end

    %% Integration Components
    IC1["Zookeeper Integration"]:::integration
    IC2["Kafka Integration"]:::integration
    IC3["Kafka CMake Dependency"]:::integration
    IC4["MySQL Integration"]:::integration

    %% Data Flow Connections
    DE1 -->|"hosts"| ED1

    ED1 -->|"blockstream"| BS1
    ED1 -->|"template stream"| BS2
    ED1 -->|"auxiliary data"| BS3

    BS1 -->|"sends blocks"| ED3
    BS2 -->|"sends templates"| ED3

    ED3 -->|"job queue"| BS4
    IC2 -->|"assists"| ED3
    IC3 --> ED3

    BS4 -->|"distributes jobs"| BS5
    BS8 -->|"simulated jobs"| BS5

    BS5 -->|"share submission"| BS7
    BS7 -->|"stores shares"| ED4

    BS9 -->|"monitors"| ED4

    %% Integration connections to services
    IC1 ---|"config/coordination"| BS1
    IC1 --- BS2
    IC1 --- BS3
    IC1 --- BS4
    IC1 --- BS5
    IC1 --- BS7
    IC1 --- BS9

    IC4 ---|"database access"| ED4

    %% Link Stratum Additional Modules
    BS5 -->|"uses"| BS6

    %% Click Events for External Dependencies and Deployments
    click ED1 "https://github.com/btccom/bccpool/tree/master/docker/bitcoind"
    click ED2 "https://github.com/btccom/bccpool/blob/master/src/Zookeeper.cc"
    click ED3 "https://github.com/btccom/bccpool/blob/master/src/Kafka.cc"
    click ED4 "https://github.com/btccom/bccpool/blob/master/src/MySQLConnection.cc"
    click DE1 "https://github.com/btccom/bccpool/tree/master/docker"

    %% Click Events for Backend Services
    click BS1 "https://github.com/btccom/bccpool/blob/master/src/blkmaker/BlkMakerMain.cc"
    click BS2 "https://github.com/btccom/bccpool/blob/master/src/gbtmaker/GbtMakerMain.cc"
    click BS3 "https://github.com/btccom/bccpool/blob/master/src/nmcauxmaker/NMCAuxBlockMakerMain.cc"
    click BS4 "https://github.com/btccom/bccpool/blob/master/src/jobmaker/JobMakerMain.cc"
    click BS5 "https://github.com/btccom/bccpool/blob/master/src/sserver/StratumServerMain.cc"
    click BS6 "https://github.com/btccom/bccpool/blob/master/src/Stratum.cc"
    click BS7 "https://github.com/btccom/bccpool/blob/master/src/sharelogger/ShareLoggerMain.cc"
    click BS8 "https://github.com/btccom/bccpool/blob/master/src/simulator/SimulatorMain.cc"
    click BS9 "https://github.com/btccom/bccpool/blob/master/src/poolwatcher/PoolWatcherMain.cc"

    %% Click Events for Integration Components
    click IC1 "https://github.com/btccom/bccpool/blob/master/src/Zookeeper.cc"
    click IC2 "https://github.com/btccom/bccpool/blob/master/src/Kafka.cc"
    click IC3 "https://github.com/btccom/bccpool/blob/master/cmake/Modules/FindKafkaC.cmake"
    click IC4 "https://github.com/btccom/bccpool/blob/master/src/MySQLConnection.cc"

    %% Styles
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px,color:#721c24;
    classDef service fill:#d1ecf1,stroke:#0c5460,stroke-width:2px,color:#0c5460;
    classDef integration fill:#d4edda,stroke:#155724,stroke-width:2px,color:#155724;
    classDef deployment fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#856404;
```
