# pool2win/p2pool-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/pool2win/p2pool-v2
- Repository: https://github.com/pool2win/p2pool-v2

## Overview

##### Main Components
- P2Pool Node (Core Application):
– Represented by the Rust binary (main.rs in src/).
– Includes submodules for configuration (src/config.rs), RPC handling with bitcoind (src/bitcoind_rpc), peer-to-peer messaging (src/node/ and its nested p2p_message_handlers), and share handling (src/shares).
- Bitcoin Node (bitcoind):
– Managed via Docker (docker/Dockerfile.bitcoind and related config files in the docker folder).
– Responsible for maintaining blockchain data and providing RPC interfaces.
- CKPool-Solo and CPUMiner Services:
– CKPool-Solo (docker/Dockerfile.ckpool-solo) helps manage miner connections pointing to the P2Pool node.
– CPUMiner (docker/Dockerfile.cpuminer) produces mining shares and submits them.
- Docker Orchestration:
– Shown through the docker-compose.yml file which brings up all these containers together.
- Test & Development Infrastructure:
– Development containers (.devcontainer) and test suites (tests folder) for integration and unit testing.
- Additional Supporting Modules:
– Configuration files (various config.toml files) to customize behavior.
– Documentation (docs folder with architecture sketches and additional markdown guides).

##### Mapping Relationships and Interactions
- The P2Pool node (core service) communicates with the Bitcoin node via RPC (see src/bitcoind_rpc).
- It handles incoming mining requests and share submissions from external miners running cpuminer or CKPool-Solo.
- The node processes, validates, and records mining shares in its share chain (modules in src/shares).
- There is internal communication within the node between its P2P message handlers (in src/node/p2p_message_handlers) and the main actor modules (src/node/actor.rs), ensuring proper message routing and request/response handling.
- Docker orchestrates the startup of these services (each container representing one of these components), and the docker-compose file defines their interactions and network configuration.

##### Important Architectural Patterns / Design Principles
- Modularity – The project cleanly separates concerns: RPC, node communication, share handling, and configuration are organized in their own modules and directories.
- Message-Driven Architecture – Extensive use of message handlers and request/response patterns (defined under src/node/p2p_message_handlers and similar modules) to manage peer-to-peer communications.
- Containerization – Utilizing Docker to encapsulate the Bitcoin node, mining services, and the p2pool node simplifies deployment and development.
- Extensibility – With multiple configuration files and a modular design, it is set up to easily integrate additional services or adjust mining parameters.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "P2Pool V2 System"
        %% P2Pool Node Container
        subgraph "P2Pool Node Container"
            direction TB
            A1("Main Application"):::module
            A2("Configuration Module"):::module
            A3("RPC Handler"):::module
            subgraph "P2P Communication"
                direction TB
                A4("Message Handlers"):::module
                A5("Actor"):::module
                A6("Gossip Handler"):::module
            end
            A7("Share Handling"):::module
        end

        %% Bitcoin Node Container
        subgraph "Bitcoin Node Container"
            direction TB
            B1("Bitcoin Node"):::external
        end

        %% CKPool-Solo Container
        subgraph "CKPool-Solo Container"
            direction TB
            C1("CKPool-Solo Service"):::external
        end

        %% CPUMiner Container
        subgraph "CPUMiner Container"
            direction TB
            D1("CPUMiner Service"):::external
        end

        %% Docker Orchestration Layer
        subgraph "Docker Orchestration Layer"
            direction TB
            E1("Docker Compose"):::orchestration
        end

        %% Test & Development Infrastructure
        subgraph "Test & Development Infrastructure"
            direction TB
            F1("Dev Container"):::test
            F2("Test Suites"):::test
        end

        %% Documentation
        subgraph "Documentation"
            direction TB
            G1("Documentation & Guides"):::doc
        end
    end

    %% Internal arrows in P2Pool Node Container
    A1 -->|"init-config"| A2
    A1 -->|"init-RPC"| A3
    A1 -->|"start-P2P"| A4
    A4 -->|"msg-forward"| A5
    A4 -->|"validate-share"| A7
    A1 -->|"process-share"| A7

    %% External interactions
    A3 <-->|"RPC-calls"| B1
    D1 -->|"share-submit"| A7
    C1 -->|"share-submit"| A7

    %% Docker Orchestration interactions
    E1 -->|"orchestrates"| A1
    E1 -->|"orchestrates"| B1
    E1 -->|"orchestrates"| C1
    E1 -->|"orchestrates"| D1

    %% Click Events
    click A1 "https://github.com/pool2win/p2pool-v2/blob/main/src/main.rs"
    click A2 "https://github.com/pool2win/p2pool-v2/blob/main/src/config.rs"
    click A3 "https://github.com/pool2win/p2pool-v2/tree/main/src/bitcoind_rpc"
    click A4 "https://github.com/pool2win/p2pool-v2/tree/main/src/node/p2p_message_handlers"
    click A5 "https://github.com/pool2win/p2pool-v2/blob/main/src/node/actor.rs"
    click A6 "https://github.com/pool2win/p2pool-v2/blob/main/src/node/gossip_handler.rs"
    click A7 "https://github.com/pool2win/p2pool-v2/tree/main/src/shares"
    click B1 "https://github.com/pool2win/p2pool-v2/blob/main/docker/Dockerfile.bitcoind"
    click C1 "https://github.com/pool2win/p2pool-v2/blob/main/docker/Dockerfile.ckpool-solo"
    click D1 "https://github.com/pool2win/p2pool-v2/blob/main/docker/Dockerfile.cpuminer"
    click E1 "https://github.com/pool2win/p2pool-v2/blob/main/docker/docker-compose.yml"
    click F1 "https://github.com/pool2win/p2pool-v2/blob/main/.devcontainer"
    click F2 "https://github.com/pool2win/p2pool-v2/tree/main/tests"
    click G1 "https://github.com/pool2win/p2pool-v2/tree/main/docs"

    %% Styles
    classDef module fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef orchestration fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef test fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef doc fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
