From d8eb6c5478b8a8e1e0555f3b9c4d39015e7ec7e4 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 24 Feb 2026 13:47:35 +0000 Subject: [PATCH] docs: archive completed plans, expand history for TUI and difficulty MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move all 21 plan files to docs/plans/completed/ — every phase (0-9) is implemented. Expand history.md with full writeups for the Difficulty Computation, V2+ Zarcanum Consensus, and TUI Dashboard sections that were previously just bullet points. Co-Authored-By: Claude Opus 4.6 --- docs/history.md | 131 +++++++++++++++++- .../2026-02-20-chain-storage-design.md | 0 .../2026-02-20-chain-storage-plan.md | 0 .../2026-02-20-crypto-bridge-design.md | 0 .../2026-02-20-crypto-bridge-plan.md | 0 .../2026-02-20-p2p-levin-design.md | 0 .../2026-02-20-p2p-levin-plan.md | 0 .../2026-02-20-rpc-client-design.md | 0 .../2026-02-20-rpc-client-plan.md | 0 .../2026-02-20-wallet-core-design.md | 0 .../2026-02-20-wallet-core-plan.md | 0 .../2026-02-21-block-sync-design.md | 0 .../2026-02-21-block-sync-plan.md | 0 .../2026-02-21-consensus-rules-design.md | 0 .../2026-02-21-consensus-rules-plan.md | 0 ...026-02-21-difficulty-computation-design.md | 0 .../2026-02-21-difficulty-computation-plan.md | 0 .../2026-02-21-mining-design.md | 0 .../{ => completed}/2026-02-21-mining-plan.md | 0 .../2026-02-21-v2-tx-serialisation-design.md | 0 .../2026-02-21-v2-tx-serialisation-plan.md | 0 .../2026-02-22-blockchain-tui-design.md | 0 22 files changed, 127 insertions(+), 4 deletions(-) rename docs/plans/{ => completed}/2026-02-20-chain-storage-design.md (100%) rename docs/plans/{ => completed}/2026-02-20-chain-storage-plan.md (100%) rename docs/plans/{ => completed}/2026-02-20-crypto-bridge-design.md (100%) rename docs/plans/{ => completed}/2026-02-20-crypto-bridge-plan.md (100%) rename docs/plans/{ => completed}/2026-02-20-p2p-levin-design.md (100%) rename docs/plans/{ => completed}/2026-02-20-p2p-levin-plan.md (100%) rename docs/plans/{ => completed}/2026-02-20-rpc-client-design.md (100%) rename docs/plans/{ => completed}/2026-02-20-rpc-client-plan.md (100%) rename docs/plans/{ => completed}/2026-02-20-wallet-core-design.md (100%) rename docs/plans/{ => completed}/2026-02-20-wallet-core-plan.md (100%) rename docs/plans/{ => completed}/2026-02-21-block-sync-design.md (100%) rename docs/plans/{ => completed}/2026-02-21-block-sync-plan.md (100%) rename docs/plans/{ => completed}/2026-02-21-consensus-rules-design.md (100%) rename docs/plans/{ => completed}/2026-02-21-consensus-rules-plan.md (100%) rename docs/plans/{ => completed}/2026-02-21-difficulty-computation-design.md (100%) rename docs/plans/{ => completed}/2026-02-21-difficulty-computation-plan.md (100%) rename docs/plans/{ => completed}/2026-02-21-mining-design.md (100%) rename docs/plans/{ => completed}/2026-02-21-mining-plan.md (100%) rename docs/plans/{ => completed}/2026-02-21-v2-tx-serialisation-design.md (100%) rename docs/plans/{ => completed}/2026-02-21-v2-tx-serialisation-plan.md (100%) rename docs/plans/{ => completed}/2026-02-22-blockchain-tui-design.md (100%) diff --git a/docs/history.md b/docs/history.md index 6afd637..aa71f8e 100644 --- a/docs/history.md +++ b/docs/history.md @@ -676,9 +676,132 @@ coverage. height 999,999,999 on mainnet. These heights will be updated when each fork is scheduled for activation on the live network. +## Difficulty Computation + +Added local LWMA difficulty computation to the P2P sync pipeline. Previously, +blocks fetched via P2P had `difficulty=0` hardcoded, causing +`consensus.CheckDifficulty()` to skip validation and cumulative difficulty +tracking to remain zero. + +### Changes + +| File | Change | +|------|--------| +| `config/config.go` | Added `BlockTarget = 120` constant (seconds) | +| `chain/difficulty.go` | `Chain.NextDifficulty(height)` — reads up to 735 blocks of history, feeds `difficulty.NextDifficulty()` | +| `chain/p2p_sync.go` | Replaced `difficulty=0` with `c.NextDifficulty(blockHeight)` | +| `difficulty/difficulty.go` | Fixed LWMA algorithm to be hardfork-aware (target parameter) | + +### Key findings + +- **Lookback window.** The LWMA algorithm examines up to `BlocksCount` (735) + previous blocks for timestamps and cumulative difficulties. At chain heights + below 735, the full available history is used. + +- **Genesis case.** Height 0 returns difficulty 1 (no history to compute from). + +- **Validated against C++ daemon.** P2P-computed difficulties match + RPC-provided values for every block on testnet. + +--- + +## V2+ Zarcanum Consensus + +Commits: `2026-02-22` + +Extended the consensus engine to handle v2+ (Zarcanum/HF4+) signature and +proof verification. This covers the post-HF4 coinbase transactions with +Bulletproofs++ range proofs. + +### Changes + +| File | Change | +|------|--------| +| `consensus/verify.go` | Added `verifyV2Signatures()` with CLSAG and proof dispatch | +| `consensus/integration_test.go` | V2 coinbase verification against testnet block 101 | + +### Key findings + +- **BPP verified with real data.** `cn_bpp_verify` (Bulletproofs++, 1 delta, + `bpp_crypto_trait_ZC_out`) passes against a real testnet coinbase from + block 101 (post-HF4). + +- **BPPE, BGE, Zarcanum remain wired but untested.** These require spending + transaction data (not just coinbase) which does not yet exist on testnet. + +--- + ## TUI Dashboard (Phase 9) -- `tui/` model library: Node wrapper, StatusModel, ExplorerModel, KeyHintsModel -- `cmd/chain/` standalone binary with P2P sync -- Uses core/cli Frame (bubbletea + lipgloss) -- Block explorer with three views: block list, block detail, tx detail +Commits: `2026-02-22`..`2026-02-23` + +Added a terminal dashboard for the Lethean Go node, rendered through the +core/cli Frame (bubbletea + lipgloss) layout system. Runs as a standalone +binary in `cmd/chain/`. + +### Architecture + +Model library (`tui/`) with a thin `cmd/chain/main.go` wiring layer (~175 +lines). The binary starts P2P sync in a background goroutine and runs the +Frame TUI in the main goroutine. + +**Layout:** `"HCF"` — header (StatusModel), content (ExplorerModel), footer +(KeyHintsModel). + +``` +┌─────────────────────────────────────────────────┐ +│ Header: StatusModel │ +│ ⛓ height 6,312 │ sync 100% │ diff 1.2M │ peers │ +├─────────────────────────────────────────────────┤ +│ Content: ExplorerModel │ +│ Block list / block detail / tx detail views │ +├─────────────────────────────────────────────────┤ +│ Footer: KeyHintsModel │ +│ ↑/↓ select │ enter view │ esc back │ q quit │ +└─────────────────────────────────────────────────┘ +``` + +### Files added + +| File | Purpose | +|------|---------| +| `tui/messages.go` | Custom bubbletea message types (`NodeStatusMsg`) | +| `tui/node.go` | Node wrapper — polls chain state every 2s via bubbletea commands | +| `tui/node_test.go` | Node wrapper tests | +| `tui/status_model.go` | `StatusModel` — chain sync header (height, difficulty, peers) | +| `tui/status_model_test.go` | Status model tests | +| `tui/explorer_model.go` | `ExplorerModel` — block list, block detail, tx detail views | +| `tui/explorer_model_test.go` | Explorer model navigation and view tests | +| `tui/keyhints_model.go` | `KeyHintsModel` — context-sensitive footer key hints | +| `tui/keyhints_model_test.go` | Key hints tests | +| `cmd/chain/main.go` | Binary wiring: P2P sync goroutine + Frame TUI | + +### Data flow + +1. `cmd/chain/main.go` opens SQLite store, creates `chain.Chain`, starts P2P + sync loop in a goroutine (Levin handshake + block fetch, retry on failure). +2. `Node` wrapper reads chain height, tip hash, difficulty, and timestamp via + bubbletea `Tick` commands every 2 seconds. +3. `StatusModel` renders the header from `NodeStatusMsg` snapshots. +4. `ExplorerModel` queries `chain.Chain` directly for block lists and detail + views (read-only SQLite). +5. `KeyHintsModel` renders per-view navigation hints. + +### Navigation + +| View | Key | Action | +|------|-----|--------| +| Block list | `↑/↓` | Move cursor | +| Block list | `PgUp/PgDn` | Scroll by page | +| Block list | `Home` | Jump to chain tip | +| Block list | `Enter` | Open block detail | +| Block detail | `↑/↓` | Select transaction | +| Block detail | `Enter` | Open tx detail | +| Block detail | `Esc` | Back to block list | +| Tx detail | `Esc` | Back to block detail | + +### Dependencies added + +- `forge.lthn.ai/core/cli` — Frame, FrameModel interface +- `github.com/charmbracelet/bubbletea` (transitive via core/cli) +- `github.com/charmbracelet/lipgloss` (transitive via core/cli) diff --git a/docs/plans/2026-02-20-chain-storage-design.md b/docs/plans/completed/2026-02-20-chain-storage-design.md similarity index 100% rename from docs/plans/2026-02-20-chain-storage-design.md rename to docs/plans/completed/2026-02-20-chain-storage-design.md diff --git a/docs/plans/2026-02-20-chain-storage-plan.md b/docs/plans/completed/2026-02-20-chain-storage-plan.md similarity index 100% rename from docs/plans/2026-02-20-chain-storage-plan.md rename to docs/plans/completed/2026-02-20-chain-storage-plan.md diff --git a/docs/plans/2026-02-20-crypto-bridge-design.md b/docs/plans/completed/2026-02-20-crypto-bridge-design.md similarity index 100% rename from docs/plans/2026-02-20-crypto-bridge-design.md rename to docs/plans/completed/2026-02-20-crypto-bridge-design.md diff --git a/docs/plans/2026-02-20-crypto-bridge-plan.md b/docs/plans/completed/2026-02-20-crypto-bridge-plan.md similarity index 100% rename from docs/plans/2026-02-20-crypto-bridge-plan.md rename to docs/plans/completed/2026-02-20-crypto-bridge-plan.md diff --git a/docs/plans/2026-02-20-p2p-levin-design.md b/docs/plans/completed/2026-02-20-p2p-levin-design.md similarity index 100% rename from docs/plans/2026-02-20-p2p-levin-design.md rename to docs/plans/completed/2026-02-20-p2p-levin-design.md diff --git a/docs/plans/2026-02-20-p2p-levin-plan.md b/docs/plans/completed/2026-02-20-p2p-levin-plan.md similarity index 100% rename from docs/plans/2026-02-20-p2p-levin-plan.md rename to docs/plans/completed/2026-02-20-p2p-levin-plan.md diff --git a/docs/plans/2026-02-20-rpc-client-design.md b/docs/plans/completed/2026-02-20-rpc-client-design.md similarity index 100% rename from docs/plans/2026-02-20-rpc-client-design.md rename to docs/plans/completed/2026-02-20-rpc-client-design.md diff --git a/docs/plans/2026-02-20-rpc-client-plan.md b/docs/plans/completed/2026-02-20-rpc-client-plan.md similarity index 100% rename from docs/plans/2026-02-20-rpc-client-plan.md rename to docs/plans/completed/2026-02-20-rpc-client-plan.md diff --git a/docs/plans/2026-02-20-wallet-core-design.md b/docs/plans/completed/2026-02-20-wallet-core-design.md similarity index 100% rename from docs/plans/2026-02-20-wallet-core-design.md rename to docs/plans/completed/2026-02-20-wallet-core-design.md diff --git a/docs/plans/2026-02-20-wallet-core-plan.md b/docs/plans/completed/2026-02-20-wallet-core-plan.md similarity index 100% rename from docs/plans/2026-02-20-wallet-core-plan.md rename to docs/plans/completed/2026-02-20-wallet-core-plan.md diff --git a/docs/plans/2026-02-21-block-sync-design.md b/docs/plans/completed/2026-02-21-block-sync-design.md similarity index 100% rename from docs/plans/2026-02-21-block-sync-design.md rename to docs/plans/completed/2026-02-21-block-sync-design.md diff --git a/docs/plans/2026-02-21-block-sync-plan.md b/docs/plans/completed/2026-02-21-block-sync-plan.md similarity index 100% rename from docs/plans/2026-02-21-block-sync-plan.md rename to docs/plans/completed/2026-02-21-block-sync-plan.md diff --git a/docs/plans/2026-02-21-consensus-rules-design.md b/docs/plans/completed/2026-02-21-consensus-rules-design.md similarity index 100% rename from docs/plans/2026-02-21-consensus-rules-design.md rename to docs/plans/completed/2026-02-21-consensus-rules-design.md diff --git a/docs/plans/2026-02-21-consensus-rules-plan.md b/docs/plans/completed/2026-02-21-consensus-rules-plan.md similarity index 100% rename from docs/plans/2026-02-21-consensus-rules-plan.md rename to docs/plans/completed/2026-02-21-consensus-rules-plan.md diff --git a/docs/plans/2026-02-21-difficulty-computation-design.md b/docs/plans/completed/2026-02-21-difficulty-computation-design.md similarity index 100% rename from docs/plans/2026-02-21-difficulty-computation-design.md rename to docs/plans/completed/2026-02-21-difficulty-computation-design.md diff --git a/docs/plans/2026-02-21-difficulty-computation-plan.md b/docs/plans/completed/2026-02-21-difficulty-computation-plan.md similarity index 100% rename from docs/plans/2026-02-21-difficulty-computation-plan.md rename to docs/plans/completed/2026-02-21-difficulty-computation-plan.md diff --git a/docs/plans/2026-02-21-mining-design.md b/docs/plans/completed/2026-02-21-mining-design.md similarity index 100% rename from docs/plans/2026-02-21-mining-design.md rename to docs/plans/completed/2026-02-21-mining-design.md diff --git a/docs/plans/2026-02-21-mining-plan.md b/docs/plans/completed/2026-02-21-mining-plan.md similarity index 100% rename from docs/plans/2026-02-21-mining-plan.md rename to docs/plans/completed/2026-02-21-mining-plan.md diff --git a/docs/plans/2026-02-21-v2-tx-serialisation-design.md b/docs/plans/completed/2026-02-21-v2-tx-serialisation-design.md similarity index 100% rename from docs/plans/2026-02-21-v2-tx-serialisation-design.md rename to docs/plans/completed/2026-02-21-v2-tx-serialisation-design.md diff --git a/docs/plans/2026-02-21-v2-tx-serialisation-plan.md b/docs/plans/completed/2026-02-21-v2-tx-serialisation-plan.md similarity index 100% rename from docs/plans/2026-02-21-v2-tx-serialisation-plan.md rename to docs/plans/completed/2026-02-21-v2-tx-serialisation-plan.md diff --git a/docs/plans/2026-02-22-blockchain-tui-design.md b/docs/plans/completed/2026-02-22-blockchain-tui-design.md similarity index 100% rename from docs/plans/2026-02-22-blockchain-tui-design.md rename to docs/plans/completed/2026-02-22-blockchain-tui-design.md