# chia-network/pool2-reference architecture

> Architecture diagram of the GitHub repository chia-network/pool2-reference, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chia-network/pool2-reference
- Repository: https://github.com/chia-network/pool2-reference

## Overview

Pool2 Reference is a reference Chia pool server. Farmers register and authenticate over the v2 HTTP API, submit partials, and receive difficulty-weighted payouts after background work validates partials and processes pooled rewards. The service coordinates full-node, wallet, and persistence operations; scheduled loops invoke its distinct tasks. The README documents the major runtime layers, while some wiring is supported only by the SOURCE INDEX; unsampled details and uncertain links are omitted.

Main entry points: [`chia_pool/service/service.py`](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/service/service.py) (Pool Service), [`chia_pool/reference.py`](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/reference.py) (CLI Entrypoint), [`chia_pool/farmer_rpc/v2.py`](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/farmer_rpc/v2.py) (V2 Handlers), [`chia_pool/server/farmer_rpc.py`](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/server/farmer_rpc.py) (HTTP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["Farmer API"]
  node_http_server["HTTP Server<br/>[farmer_rpc.py]"]
  node_handlers["V2 Handlers<br/>[v2.py]"]
  node_authentication["JWT Authentication<br/>[authentication.py]"]
end

subgraph group_core["Pool Operations"]
  node_service["Pool Service<br/>[service.py]"]
end

subgraph group_clients["Chia Integrations"]
  node_node_client["Full Node Client<br/>[rpc_wrapper.py]"]
  node_wallet_client["Wallet Client<br/>[rpc_wrapper.py]"]
end

subgraph group_data["Persistence and Contracts"]
  node_node_rpc["Node RPC Contract<br/>[node_rpc.py]"]
  node_wallet_rpc["Wallet RPC Contract<br/>[wallet_rpc.py]"]
  node_store_contract["Store Contract<br/>[store.py]"]
  node_sqlite[("SQLite Store<br/>[sqlite.py]")]
  node_service_contract["Service Contract<br/>[service.py]"]
  node_server_contract["Server Contract<br/>[server.py]"]
end

subgraph group_runtime["Server Runtime"]
  node_tasks["Scheduled Tasks<br/>[pooling_tasks.py]"]
  node_config["Config Loading<br/>[config_loading.py]"]
  node_cli["CLI Entrypoint<br/>[reference.py]"]
end

node_farmer(("Farmer"))
node_full_node["Chia Full Node"]
node_wallet["Chia Wallet"]

node_farmer -->|"sends requests"| node_http_server
node_http_server -->|"routes requests"| node_handlers
node_handlers -->|"verifies tokens"| node_authentication
node_handlers -->|"uses service"| node_service
node_handlers -->|"reads and writes"| node_store_contract
node_handlers -->|"checks chain state"| node_node_rpc
node_tasks -->|"runs service tasks"| node_service
node_service -->|"reads and writes"| node_store_contract
node_service -->|"checks chain data"| node_node_rpc
node_service -->|"submits transactions"| node_wallet_rpc
node_cli -->|"starts server"| node_http_server
node_cli -->|"starts loops"| node_tasks
node_cli -->|"creates service"| node_service
node_cli -->|"creates store"| node_sqlite
node_cli -->|"creates client"| node_node_client
node_cli -->|"creates client"| node_wallet_client
node_node_client -->|"implements contract"| node_node_rpc
node_wallet_client -->|"implements contract"| node_wallet_rpc
node_sqlite -->|"implements contract"| node_store_contract
node_service -->|"implements contract"| node_service_contract
node_http_server -->|"implements contract"| node_server_contract
node_node_client -->|"calls RPC"| node_full_node
node_wallet_client -->|"calls RPC"| node_wallet
node_http_server -->|"loads configuration"| node_config
node_tasks -->|"loads configuration"| node_config

click node_http_server "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/server/farmer_rpc.py"
click node_handlers "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/farmer_rpc/v2.py"
click node_authentication "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/farmer_rpc/authentication.py"
click node_service "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/service/service.py"
click node_tasks "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/server/pooling_tasks.py"
click node_node_client "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/node/rpc_wrapper.py"
click node_wallet_client "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/wallet/rpc_wrapper.py"
click node_node_rpc "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/node_rpc.py"
click node_wallet_rpc "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/wallet_rpc.py"
click node_store_contract "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/store.py"
click node_sqlite "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/store/sqlite.py"
click node_service_contract "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/service.py"
click node_server_contract "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/server.py"
click node_config "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/config_loading.py"
click node_cli "https://github.com/chia-network/pool2-reference/blob/main/chia_pool/reference.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_http_server,node_handlers,node_authentication toneBlue
class node_service toneAmber
class node_node_client,node_wallet_client toneMint
class node_node_rpc,node_wallet_rpc,node_store_contract,node_sqlite,node_service_contract,node_server_contract toneRose
class node_tasks,node_config,node_cli,node_farmer,node_full_node,node_wallet toneIndigo
```

## Components

### Farmer API

- [HTTP Server](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/server/farmer_rpc.py): `chia_pool/server/farmer_rpc.py`
- [V2 Handlers](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/farmer_rpc/v2.py): `chia_pool/farmer_rpc/v2.py`
- [JWT Authentication](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/farmer_rpc/authentication.py): `chia_pool/farmer_rpc/authentication.py`

### Pool Operations

- [Pool Service](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/service/service.py): `chia_pool/service/service.py`

### Chia Integrations

- [Full Node Client](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/node/rpc_wrapper.py): `chia_pool/node/rpc_wrapper.py`
- [Wallet Client](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/wallet/rpc_wrapper.py): `chia_pool/wallet/rpc_wrapper.py`

### Persistence and Contracts

- [Node RPC Contract](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/node_rpc.py): `chia_pool/api/node_rpc.py`
- [Wallet RPC Contract](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/wallet_rpc.py): `chia_pool/api/wallet_rpc.py`
- [Store Contract](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/store.py): `chia_pool/api/store.py`
- [SQLite Store](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/store/sqlite.py): `chia_pool/store/sqlite.py`
- [Service Contract](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/service.py): `chia_pool/api/service.py`
- [Server Contract](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/api/server.py): `chia_pool/api/server.py`

### Server Runtime

- [Scheduled Tasks](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/server/pooling_tasks.py): `chia_pool/server/pooling_tasks.py`
- [Config Loading](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/config_loading.py): `chia_pool/config_loading.py`
- [CLI Entrypoint](https://github.com/chia-network/pool2-reference/blob/main/chia_pool/reference.py): `chia_pool/reference.py`

### Other components

- **Farmer**
- **Chia Full Node**
- **Chia Wallet**

## Connections

- Farmer → HTTP Server: sends requests
- HTTP Server → V2 Handlers: routes requests
- V2 Handlers → JWT Authentication: verifies tokens (evidence: `chia_pool/farmer_rpc/v2.py`)
- V2 Handlers → Pool Service: uses service (evidence: `chia_pool/farmer_rpc/v2.py`)
- V2 Handlers → Store Contract: reads and writes (evidence: `chia_pool/farmer_rpc/v2.py`)
- V2 Handlers → Node RPC Contract: checks chain state (evidence: `chia_pool/farmer_rpc/v2.py`)
- Scheduled Tasks → Pool Service: runs service tasks (evidence: `chia_pool/server/pooling_tasks.py`)
- Pool Service → Store Contract: reads and writes (evidence: `chia_pool/service/service.py`)
- Pool Service → Node RPC Contract: checks chain data (evidence: `chia_pool/service/service.py`)
- Pool Service → Wallet RPC Contract: submits transactions (evidence: `chia_pool/service/service.py`)
- CLI Entrypoint → HTTP Server: starts server (evidence: `chia_pool/reference.py`)
- CLI Entrypoint → Scheduled Tasks: starts loops (evidence: `chia_pool/reference.py`)
- CLI Entrypoint → Pool Service: creates service (evidence: `chia_pool/reference.py`)
- CLI Entrypoint → SQLite Store: creates store (evidence: `chia_pool/reference.py`)
- CLI Entrypoint → Full Node Client: creates client (evidence: `chia_pool/reference.py`)
- CLI Entrypoint → Wallet Client: creates client (evidence: `chia_pool/reference.py`)
- Full Node Client → Node RPC Contract: implements contract (evidence: `chia_pool/node/rpc_wrapper.py`)
- Wallet Client → Wallet RPC Contract: implements contract (evidence: `chia_pool/wallet/rpc_wrapper.py`)
- SQLite Store → Store Contract: implements contract (evidence: `chia_pool/store/sqlite.py`)
- Pool Service → Service Contract: implements contract (evidence: `chia_pool/service/service.py`)
- HTTP Server → Server Contract: implements contract (evidence: `chia_pool/server/farmer_rpc.py`)
- Full Node Client → Chia Full Node: calls RPC (evidence: `chia_pool/node/rpc_wrapper.py`)
- Wallet Client → Chia Wallet: calls RPC (evidence: `chia_pool/wallet/rpc_wrapper.py`)
- HTTP Server → Config Loading: loads configuration (evidence: `chia_pool/server/farmer_rpc.py`)
- Scheduled Tasks → Config Loading: loads configuration (evidence: `chia_pool/server/pooling_tasks.py`)
