From cef9a34bead0f40a95f53b47b146982e0507bde6 Mon Sep 17 00:00:00 2001
From: Claude <developers@lethean.io>
Date: Sat, 21 Feb 2026 02:21:36 +0000
Subject: [PATCH] docs: Phase 8 mining complete

Co-Authored-By: Charon <charon@lethean.io>
---
 docs/architecture.md | 30 ++++++++++++++++++++++++++++--
 docs/history.md      | 14 +++++++++++---
 2 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 6f4917f..94d37d3 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -22,6 +22,7 @@ rpc/          Daemon JSON-RPC 2.0 client (12 endpoints)
 chain/        Chain storage, indexing, and sync client (go-store backed)
 consensus/    Three-layer block/transaction validation (structural, economic, crypto)
 wallet/       Wallet core: key management, scanning, signing, TX construction
+mining/      Solo PoW miner (daemon RPC, RandomX nonce grinding)
 ```
 
 ### config/
@@ -122,7 +123,7 @@ The Levin wire format in go-p2p includes:
 ### rpc/
 
 Typed JSON-RPC 2.0 client for querying the Lethean daemon. The `Client` struct
-wraps `net/http` and provides Go methods for 10 core daemon endpoints.
+wraps `net/http` and provides Go methods for 11 core daemon endpoints.
 
 Eight endpoints use JSON-RPC 2.0 via `/json_rpc`. Two endpoints (`GetHeight`,
 `GetTransactions`) use legacy JSON POST to dedicated URI paths (`/getheight`,
@@ -139,7 +140,7 @@ rather than `MAP_JON_RPC`.
 - `blocks.go` -- `GetLastBlockHeader`, `GetBlockHeaderByHeight`,
   `GetBlockHeaderByHash`, `GetBlocksDetails`.
 - `transactions.go` -- `GetTxDetails`, `GetTransactions` (legacy).
-- `mining.go` -- `SubmitBlock`.
+- `mining.go` -- `GetBlockTemplate`, `SubmitBlock`.
 
 **Wallet endpoints:**
 - `wallet.go` -- `GetRandomOutputs` (for ring decoy selection via `/getrandom_outs1`)
@@ -265,6 +266,31 @@ with four core abstractions so v1 (NLSAG) implementations ship now and v2+
 - Build-tagged integration test (`//go:build integration`) syncing from
   C++ testnet daemon and verifying balance/transfers.
 
+### mining/
+
+Solo PoW miner that talks to a C++ daemon via JSON-RPC. Single-threaded
+mining loop: fetches block templates, computes a header mining hash once
+per template, then grinds nonces with RandomX until a solution is found
+or the chain advances.
+
+**Core types:**
+- `Config` -- daemon URL, wallet address, poll interval, callbacks.
+- `Miner` -- mining loop with `Start(ctx)` (blocking) and `Stats()` (lock-free).
+- `TemplateProvider` -- interface satisfied by `rpc.Client` for testability.
+
+**Mining flow:**
+1. `GetBlockTemplate(walletAddr)` -- fetches template from daemon.
+2. `HeaderMiningHash(block)` -- Keccak-256 of `BlockHashingBlob` with nonce=0.
+3. Nonce loop: `RandomXHash("LetheanRandomXv1", headerHash || nonce_LE)`.
+4. `CheckDifficulty(powHash, difficulty)` -- solution found?
+5. `SubmitBlock(hexBlob)` -- submits the solved block.
+
+**Template refresh:** polls `GetInfo()` every `PollInterval` (default 3s) to
+detect new blocks. Re-fetches the template when the chain height advances.
+
+**Testing:** Mock `TemplateProvider` for unit tests. Build-tagged integration
+test against C++ testnet daemon on `localhost:46941`.
+
 ---
 
 ## Key Types
diff --git a/docs/history.md b/docs/history.md
index 4f89ca4..8f333d5 100644
--- a/docs/history.md
+++ b/docs/history.md
@@ -511,10 +511,18 @@ Coverage: 82.1% of statements.
 
 All passing with `-race` and `go vet`.
 
-## Phase 8 -- Mining (Planned)
+## Phase 8 -- Mining
 
-PoW mining support with stratum protocol client. PoS staking with kernel
-hash computation and coinstake transaction construction.
+Solo PoW miner in `mining/` package. Fetches block templates from the C++
+daemon, computes header mining hash (nonce=0 Keccak-256), grinds nonces with
+RandomX, submits solutions. Single-threaded loop with poll-based template
+refresh.
+
+**Commits:** `8735e53..f9ff8ad` on `feat/phase8-mining`
+
+**Known limitations:**
+- Single-threaded (CGo RandomX bridge uses static global cache/VM).
+- Solo mining only (no stratum protocol).
 
 ---