Skip to content

Commit d09533e

Browse files
frstrtrfrstrtr
committed
Update changelog v0.9.2 and add REST API docs to CLAUDE.md
1 parent 8699490 commit d09533e

2 files changed

Lines changed: 143 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,26 @@
11
# Changelog
22

3+
## [0.9.2] - 2026-03-20
4+
5+
### Security
6+
- **fix: Share target validation** — Reject shares where `target > max_target` (matching p2pool-merged-v36 v0.14-alpha fix). Closes latent vulnerability present since p2pool inception.
7+
- **fix: Bootstrap share target** — Use hardest chain bits during bootstrap instead of MAX_TARGET. Prevents easy-share flooding when joining existing networks.
8+
9+
### Bug Fixes
10+
- **fix: PPLNS desired_weight cap** — V36 exponential decay now uses unlimited desired_weight (`2^288 - 1`). The cap truncated the PPLNS window to ~2 shares on testnet, causing single-miner payouts.
11+
- **fix: merged_payout_hash consensus** — Walk VERIFIED chain only (not raw chain) to exclude c2pool's own unverified shares. Defer check until verified depth >= CHAIN_LENGTH. Fixes consensus divergence with p2pool peers.
12+
- **fix: Share difficulty (desired_target)** — Pass MAX_TARGET (clipped to pool share difficulty) instead of block difficulty. Block difficulty made shares 2634x too hard, causing c2pool's miner to contribute negligible PPLNS weight.
13+
- **fix: PPLNS race condition** — Recompute PPLNS from frozen prev_share in `build_connection_coinbase`. Prevents stale coinbase when chain advances between template creation and share submission.
14+
- **fix: Log rotation** — Add target directory for log rotation, increase default to 100MB.
15+
16+
### Added
17+
- **`/miner_thresholds` API endpoint** — Returns minimum viable hashrate (normal and with 30x DUST range), minimum payout per share, pool hashrate, PPLNS window duration. Enables dashboard display of miner feasibility.
18+
- **`MinerThresholds` struct** — Pool-level computation of minimum viable hashrate from chain state.
19+
- **SHAREREQ diagnostic** — Log first 5 SHAREREQ misses with chain size for debugging share sync issues.
20+
21+
### Documentation
22+
- Analysis documents in frstrtr/the: DESIRED_WEIGHT_CAP_BUG.md, SHARE_TARGET_VALIDATION.md, SHARE_PERIOD_AND_TINY_MINERS.md, TINY_MINER_ECONOMICS.md
23+
324
## [0.9.1] - 2026-03-19
425

526
### Added (untested — implemented, needs live validation)

‎CLAUDE.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## What is C2Pool
6+
7+
C2Pool is a modern C++ reimplementation of the decentralized mining pool P2Pool, targeting the V36 share format with support for Litecoin and merged mining (Dogecoin, etc.). It implements a full P2P mining pool with Stratum protocol, PPLNS payouts, VARDIFF, and a web dashboard.
8+
9+
## Build System
10+
11+
**Requirements:** CMake 3.22+, GCC 13, Conan 2.x, C++20
12+
13+
**System packages (Ubuntu 24.04):**
14+
```bash
15+
sudo apt-get install -y g++ cmake make libleveldb-dev libsecp256k1-dev python3-pip
16+
pip install "conan>=2.0,<3.0" --break-system-packages
17+
conan profile detect --force
18+
```
19+
20+
**Build the main binary:**
21+
```bash
22+
mkdir build && cd build
23+
conan install .. --build=missing --settings=build_type=Debug
24+
cmake .. --preset conan-debug
25+
cmake --build . --target c2pool -j$(nproc)
26+
# Binary: build/src/c2pool/c2pool
27+
```
28+
29+
There is also `build-debug.sh` at the repo root as a convenience script.
30+
31+
**Build and run all tests:**
32+
```bash
33+
cd build
34+
cmake --build . --target test_hardening test_share_messages test_coin_broadcaster \
35+
test_redistribute_address core_test sharechain_test share_test -j$(nproc)
36+
ctest --output-on-failure -j$(nproc)
37+
# Expected: 265 tests passing
38+
```
39+
40+
**Run a single test binary:**
41+
```bash
42+
cd build && ./test/test_hardening
43+
cd build && ./src/core/test/core_test
44+
```
45+
46+
**Python integration tests** (require a running pool):
47+
```bash
48+
cd test && python3 smoke_test.py
49+
cd test && python3 integration_test.py
50+
```
51+
52+
## Architecture
53+
54+
The codebase is split into layered modules under `src/`:
55+
56+
```
57+
btclibs/ Bitcoin/crypto primitives (uint256, SHA256, ECDSA, base58, Script)
58+
core/ Infrastructure: networking (Boost.ASIO), HTTP/Stratum server,
59+
logging, YAML config, LevelDB wrapper, binary serialization
60+
pool/ Generic P2P pool protocol (peer connections, message dispatch)
61+
sharechain/ V36 share format, share chain data structure, LevelDB storage
62+
impl/ltc/ Litecoin-specific: share validation, V36 authority messages,
63+
litecoind RPC/P2P client, payout redistribution modes
64+
c2pool/ Enhanced features + main entry point:
65+
node/ Enhanced node orchestration (ties all modules together)
66+
hashrate/ Real-time hashrate tracking
67+
difficulty/ Per-miner VARDIFF adjustment engine
68+
storage/ LevelDB sharechain persistence manager
69+
payout/ PPLNS payout calculation
70+
merged/ Merged mining support (DOGE, DGB)
71+
```
72+
73+
**Dependency direction:** `c2pool` → `impl/ltc` → `pool` + `sharechain` + `core` → `btclibs`
74+
75+
The main entry point is `src/c2pool/c2pool_refactored.cpp`, which parses 100+ CLI arguments, selects an operating mode, and instantiates `EnhancedNode` from `c2pool/node/`.
76+
77+
**Operating modes** (selected by CLI flags):
78+
- `--integrated` — Full pool: HTTP API + Stratum + P2P sharechain + payouts + web dashboard
79+
- `--sharechain` — P2P node only (no mining)
80+
- default — Solo mining (lightweight, no P2P)
81+
82+
## Key Files
83+
84+
| File | Purpose |
85+
|------|---------|
86+
| `src/c2pool/c2pool_refactored.cpp` | Main entry point, all CLI argument handling |
87+
| `src/core/web_server.cpp` | HTTP/JSON-RPC/Stratum server (~2500 LOC) |
88+
| `src/impl/ltc/share_check.hpp` | Share validation — the most complex file in the repo |
89+
| `src/impl/ltc/share_messages.hpp` | V36 authority message encryption/decryption |
90+
| `src/impl/ltc/node.cpp` | LTC pool node orchestration |
91+
| `src/c2pool/payout/payout_manager.cpp` | PPLNS distribution logic |
92+
| `src/c2pool/merged/merged_mining.cpp` | Merged mining adapter |
93+
| `src/core/pack.hpp` | Binary serialization framework used throughout |
94+
95+
## REST API Endpoints
96+
97+
| Endpoint | Description |
98+
|----------|-------------|
99+
| `/current_payouts` | Current PPLNS payout distribution by address |
100+
| `/local_stats` | Local node statistics (peers, hashrates, shares) |
101+
| `/global_stats` | Pool-wide statistics (pool hashrate, difficulty) |
102+
| `/miner_thresholds` | Minimum viable hashrate, min payout per share, DUST range |
103+
| `/recent_blocks` | Recently found blocks |
104+
| `/connected_miners` | Currently connected stratum workers |
105+
| `/stratum_stats` | Stratum server statistics |
106+
| `/sharechain_stats` | Share chain state (height, verified count) |
107+
108+
## Configuration
109+
110+
Configuration priority: CLI args > YAML file (`--config config.yaml`) > env vars > defaults.
111+
112+
See `config/c2pool_testnet.yaml` for a full example. Key defaults: P2P port 9338, Stratum port 9327, HTTP port 8080.
113+
114+
## Dependencies
115+
116+
- **LevelDB** and **libsecp256k1** must be installed system-wide
117+
- **Boost 1.78** (ASIO, log, thread, filesystem), **nlohmann/json 3.11.3**, **yaml-cpp 0.8.0**, **GTest 1.14.0** are managed via Conan
118+
- `btclibs/` contains vendored/stripped Bitcoin Core utilities
119+
120+
## CI/CD
121+
122+
GitHub Actions (`.github/workflows/build.yml`) runs on Ubuntu 24.04 with GCC 13. The pipeline installs system deps, runs Conan, builds all targets, and runs `ctest`. Conan package cache is keyed by compiler/build_type.

0 commit comments

Comments
 (0)