# Project History

## Origin

go-blockchain implements the Lethean blockchain protocol in pure Go, following
ADR-001 (Go Shell + C++ Crypto Library). The chain lineage is CryptoNote (2014)
to IntenseCoin (2017) to Lethean to a Zano rebase. All consensus parameters are
derived from the canonical C++ source files `currency_config.h.in` and
`default.cmake`.

The package was created as part of the broader effort to rewrite the Lethean
node tooling in Go, keeping protocol logic in Go while deferring only the
mathematically complex cryptographic primitives (ring signatures, bulletproofs,
Zarcanum proofs) to a cleaned C++ library via CGo in later phases.

---

## Phase 0 -- Scaffold

Commit: `4c0b7f2` -- `feat: Phase 0 scaffold -- config, types, wire, difficulty`

Phase 0 established the foundational four packages with complete test suites
and full coverage of the consensus-critical configuration surface.

### Packages implemented

- **config/** -- All chain constants from `currency_config.h.in` and
  `default.cmake`: tokenomics (Coin, BlockReward, fees, premine), address
  prefixes (standard, integrated, auditable, auditable integrated), network
  ports (mainnet 36940-36942, testnet 46940-46942), difficulty parameters
  (window 720, lag 15, cut 60, targets 120s), block and transaction limits,
  version constants, PoS parameters, P2P constants, network identity, currency
  identity, and alias rules. `ChainConfig` struct with pre-populated `Mainnet`
  and `Testnet` globals. Hardfork schedule (HF0-HF6) with `VersionAtHeight()`
  and `IsHardForkActive()` lookup functions.

- **types/** -- Fixed-size cryptographic types: `Hash` (32 bytes), `PublicKey`
  (32 bytes), `SecretKey` (32 bytes), `KeyImage` (32 bytes), `Signature`
  (64 bytes). Hex encode/decode for `Hash` and `PublicKey`. CryptoNote base58
  address encoding with Keccak-256 checksums. `Address` struct with
  `Encode()`/`DecodeAddress()` round-trip. `BlockHeader`, `Block`,
  `Transaction` structs. Input types (`TxInputGenesis`, `TxInputToKey`) and
  output types (`TxOutputBare`, `TxOutputZarcanum`) with wire type tags.
  `TxInput` and `TxOutput` interfaces.

- **wire/** -- CryptoNote varint encoding (7-bit LEB128 with MSB continuation).
  `EncodeVarint()` and `DecodeVarint()` with sentinel errors for overflow and
  empty input. Maximum 10 bytes per uint64.

- **difficulty/** -- LWMA difficulty adjustment algorithm. `NextDifficulty()`
  examines a window of timestamps and cumulative difficulties to compute the
  next target. Handles insufficient data (returns `StarterDifficulty`), zero
  time spans, and negative difficulty deltas.

### Tests added

75 test cases across 5 test files, all passing with the race detector:

- `config/config_test.go` -- 7 test functions validating every constant group
  against C++ source values: tokenomics, address prefixes, ports (mainnet and
  testnet), difficulty parameters, network identity, `ChainConfig` struct fields,
  transaction limits, and transaction version constants.

- `config/hardfork_test.go` -- 7 test functions covering `VersionAtHeight()`
  on both mainnet and testnet fork schedules, `IsHardForkActive()` for boundary
  conditions, unknown version queries, empty fork lists, single-element fork
  lists, and full fork schedule validation for both networks.

- `types/address_test.go` -- 8 test functions covering encode/decode round-trips
  for all four address types, deterministic encoding, auditable flag detection,
  integrated prefix detection, invalid input rejection (empty, invalid base58
  characters, too short), checksum corruption detection, base58 round-trip, and
  base58 edge cases (empty encode/decode).

- `difficulty/difficulty_test.go` -- 7 test functions covering stable difficulty
  with constant intervals, empty input, single entry, fast blocks (difficulty
  increases), slow blocks (difficulty decreases), zero time span handling, and
  algorithm constants.

- `wire/varint_test.go` -- 5 test functions covering encoding known values,
  decoding known values, round-trip across all bit boundaries (0 through
  `MaxUint64`), empty input errors, and overflow detection.

### Coverage

| Package | Coverage |
|---------|----------|
| config | 100.0% |
| difficulty | 81.0% |
| types | 73.4% |
| wire | 95.2% |

`go test -race ./...` passed clean. `go vet ./...` produced no warnings.

---

## Phase 1 -- Wire Serialisation

Phase 1 added consensus-critical binary serialisation for blocks and transactions,
verified to be bit-identical to the C++ daemon output. The definitive proof is
the genesis block hash test: serialising the testnet genesis block and computing
its Keccak-256 hash produces the exact value returned by the C++ daemon
(`cb9d5455ccb79451931003672c405f5e2ac51bff54021aa30bc4499b1ffc4963`).

### Type corrections from Phase 0

Phase 0 types had several mismatches with the C++ wire format, corrected here:

- `BlockHeader.MinorVersion` changed from `uint8` to `uint64` (varint on wire)
- `BlockHeader.Flags` added (`uint8`, 1 byte fixed)
- `Transaction.Version` changed from `uint8` to `uint64` (varint on wire)
- `Transaction.UnlockTime` removed (lives in extra variants, not top-level)
- All variant tags corrected to match `SET_VARIANT_TAGS` from `currency_basic.h`:
  `InputTypeGenesis=0`, `InputTypeToKey=1`, `OutputTypeBare=36`, `OutputTypeZarcanum=38`
- `TxOutToKey` struct added (public key + mix_attr, 33 bytes packed)
- `TxOutRef` variant type added (global index or ref_by_id)
- `Transaction.Signatures`, `Transaction.Attachment`, `Transaction.Proofs` fields added

### Files added

| File | Purpose |
|------|---------|
| `wire/encoder.go` | Sticky-error streaming encoder |
| `wire/decoder.go` | Sticky-error streaming decoder |
| `wire/block.go` | Block/BlockHeader encode/decode |
| `wire/transaction.go` | Transaction encode/decode (v0/v1 + v2+ stubs) |
| `wire/treehash.go` | Keccak-256 + CryptoNote Merkle tree hash |
| `wire/hash.go` | BlockHash, TransactionPrefixHash, TransactionHash |
| `wire/encoder_test.go` | Encoder round-trip tests |
| `wire/decoder_test.go` | Decoder round-trip tests |
| `wire/block_test.go` | Block header + full block round-trip tests |
| `wire/transaction_test.go` | Coinbase, ToKey, signatures, variant tag tests |
| `wire/treehash_test.go` | Tree hash for 0-8 hashes |
| `wire/hash_test.go` | Genesis block hash verification |

### Key findings

- **Block hash length prefix**: The C++ `get_object_hash(blobdata)` serialises
  the string through `binary_archive` before hashing, prepending `varint(length)`.
  The actual block hash input is `varint(len) || block_hashing_blob`, not just
  the blob itself.

- **Genesis data sources**: The `_genesis_tn.cpp.gen` uint64 array is the
  canonical genesis transaction data, not the `.genesis_tn.txt` hex dump (which
  was stale from a different wallet generation).

- **Extra as raw bytes**: Transaction extra, attachment, and proofs are stored
  as opaque raw wire bytes with tag-level boundary detection. This enables
  bit-identical round-tripping without implementing all 20+ extra variant types.

### Coverage

| Package | Coverage |
|---------|----------|
| config | 100.0% |
| difficulty | 81.0% |
| types | 73.4% |
| wire | 76.8% |

Wire coverage is reduced by v2+ code paths (0% -- Phase 2 scope). Excluding
v2+ stubs, the v0/v1 serialisation code exceeds 85% coverage.

## Phase 2 -- Crypto Bridge

Phase 2 created the `crypto/` package with a CGo bridge to the vendored C++
CryptoNote crypto library. The upstream code (37 files from Zano commit
`fa1608cf`) is built as a static library via CMake, with a thin C API
(`bridge.h`) separating Go from C++ types.

### Files added

| File | Purpose |
|------|---------|
| `crypto/upstream/` | 37 vendored C++ files (unmodified copies) |
| `crypto/compat/` | 11 compatibility stubs replacing epee/Boost |
| `crypto/build/` | CMake build output (libcryptonote.a, ~680KB) |
| `crypto/CMakeLists.txt` | C11/C++17 static library build |
| `crypto/bridge.h` | Stable C API contract (29 functions) |
| `crypto/bridge.cpp` | C→C++ wrappers with memcpy marshalling |
| `crypto/doc.go` | Package documentation + build instructions |
| `crypto/crypto.go` | CGo flags + FastHash binding |
| `crypto/keygen.go` | Key generation, derivation, DerivePublicKey/SecretKey |
| `crypto/keyimage.go` | Key image generation and validation |
| `crypto/signature.go` | Standard + NLSAG ring signatures |
| `crypto/clsag.go` | CLSAG (GG/GGX/GGXXG) + cofactor helpers |
| `crypto/proof.go` | BPP, BPPE, BGE, Zarcanum verification wrappers |
| `crypto/PROVENANCE.md` | Upstream origin mapping + update workflow |
| `crypto/crypto_test.go` | 30 tests (all passing) |

### Key findings

- **CMake build required 5 iterations** to resolve all include paths. The
  upstream files use relative includes (`../currency_core/`, `crypto/crypto-ops.h`)
  that assume the full Zano source tree. Solved with symlinks, additional include
  paths, and compat stubs.

- **eth_signature.cpp excluded** from build -- requires Bitcoin's secp256k1
  library which is not needed for CryptoNote consensus crypto.

- **cn_fast_hash name collision** between bridge.h and hash-ops.h. Resolved by
  renaming the bridge wrapper to `bridge_fast_hash`.

- **Zero key is valid on Ed25519** -- it represents the identity element. Tests
  use `0xFF...FF` for invalid key checks instead.

- **1/8 premultiplication** is critical for CLSAG correctness. On-chain
  commitments are stored as `(1/8)*P`. Generate takes full points; verify takes
  premultiplied values. `PointMul8`/`PointDiv8` helpers convert between forms.

- **Proof verification stubs** return "not implemented" -- the serialisation
  format for BPPE/BGE/Zarcanum proofs requires matching the exact on-chain binary
  layout, which needs real chain data via RPC (Phase 4).

### Tests added

22 test cases in `crypto/crypto_test.go`:

- **Hashing (2):** Known Keccak-256 vector (empty input), non-zero hash
- **Key ops (3):** GenerateKeys round-trip, CheckKey negative, uniqueness
- **Key derivation (2):** ECDH commutativity, output scanning round-trip
  (send → receive → derive ephemeral secret → verify public key match)
- **Key images (3):** Generation, determinism, invalid input rejection
- **Standard sigs (3):** Round-trip, wrong key, wrong message
- **Ring sigs NLSAG (2):** 4-member ring round-trip, wrong message
- **CLSAG GG (2):** Generate+verify round-trip with cofactor handling, wrong message
- **CLSAG size (2):** GGX and GGXXG signature size calculations
- **Proof stubs (3):** Skipped -- pending Phase 4 chain data

All passing with `-race` and `go vet`.

## Phase 3 -- P2P Levin Protocol

Phase 3 implemented the CryptoNote Levin binary protocol for peer-to-peer
communication across two repositories. The go-p2p package gained a `node/levin/`
sub-package with the wire format (header, portable storage, framed TCP
connection). The go-blockchain package gained a `p2p/` package with command
handlers for handshake, timed sync, ping, and block/transaction relay.

### Files added (go-p2p)

| File | Purpose |
|------|---------|
| `node/levin/header.go` | 33-byte Levin header encode/decode |
| `node/levin/header_test.go` | Header tests (9 tests) |
| `node/levin/varint.go` | Portable storage varint (2-bit size mark) |
| `node/levin/varint_test.go` | Varint tests (14 tests) |
| `node/levin/storage.go` | Portable storage section encode/decode |
| `node/levin/storage_test.go` | Storage tests (14 tests) |
| `node/levin/connection.go` | Framed TCP connection |
| `node/levin/connection_test.go` | Connection tests (7 tests) |

### Files added/modified (go-blockchain)

| File | Purpose |
|------|---------|
| `config/config.go` | Added NetworkID constants and ClientVersion |
| `config/config_test.go` | NetworkID validation test |
| `p2p/commands.go` | Command ID re-exports |
| `p2p/sync.go` | CoreSyncData type |
| `p2p/sync_test.go` | CoreSyncData roundtrip test |
| `p2p/ping.go` | Ping encode/decode |
| `p2p/ping_test.go` | Ping tests (2 tests) |
| `p2p/handshake.go` | Handshake command + NodeData + peerlist decoding |
| `p2p/handshake_test.go` | Handshake tests (4 tests) |
| `p2p/timedsync.go` | Timed sync request/response |
| `p2p/relay.go` | Block/tx relay + chain request/response |
| `p2p/relay_test.go` | Relay tests (6 tests) |
| `p2p/integration_test.go` | C++ testnet integration test |

### Key findings

- **Portable storage varint differs from CryptoNote varint.** CryptoNote uses
  7-bit LEB128 (implemented in wire/varint.go). Portable storage uses a 2-bit
  size mark in the low bits of the first byte (1/2/4/8 byte encoding). Both
  implementations exist in separate packages.

- **POD-as-blob serialisation.** Hashes, network IDs, and other fixed-size types
  are encoded as STRING values containing raw bytes, not as typed fields. The
  peerlist is a single STRING blob containing packed 24-byte entries
  (ip:4 + port:4 + id:8 + last_seen:8).

- **Network ID bytes from net_node.inl.** Mainnet: byte 10 = 0x00 (not testnet),
  byte 15 = 0x54 (84 = formation version). Testnet: byte 10 = 0x01, byte 15 =
  0x64 (100). These are validated during handshake.

- **P2P port is 46942, not 46941.** The testnet ports are: 46940 (stratum),
  46941 (RPC), 46942 (P2P).

- **No Transport interface extraction.** The existing go-p2p WebSocket transport
  is tightly coupled to WebSocket semantics. The Levin code lives in
  `node/levin/` as a standalone sub-package rather than sharing an interface.

### Tests added

44 go-p2p tests + 13 go-blockchain p2p tests + 1 integration test = 58 total.
All passing with `-race` and `go vet`.

## Phase 4 -- RPC Client

Phase 4 implemented a typed JSON-RPC 2.0 client for querying the Lethean C++
daemon. The `rpc/` package provides Go methods for 10 core daemon endpoints
covering chain info, block headers, block details, transactions, and mining.

### Files added

| File | Purpose |
|------|---------|
| `rpc/client.go` | Client struct, JSON-RPC 2.0 `call()` + legacy `legacyCall()` |
| `rpc/client_test.go` | Client transport tests (7 tests) |
| `rpc/types.go` | BlockHeader, DaemonInfo, BlockDetails, TxInfo types |
| `rpc/info.go` | GetInfo, GetHeight (legacy), GetBlockCount |
| `rpc/info_test.go` | Info endpoint tests (3 tests) |
| `rpc/blocks.go` | GetLastBlockHeader, GetBlockHeaderByHeight/ByHash, GetBlocksDetails |
| `rpc/blocks_test.go` | Block endpoint tests (5 tests) |
| `rpc/transactions.go` | GetTxDetails, GetTransactions (legacy) |
| `rpc/transactions_test.go` | Transaction endpoint tests (4 tests) |
| `rpc/mining.go` | SubmitBlock |
| `rpc/mining_test.go` | Mining endpoint tests (2 tests) |
| `rpc/integration_test.go` | Build-tagged integration test against C++ testnet |

### Tests added

21 mock tests + 1 integration test = 22 total.

Mock tests use `httptest.Server` with canned JSON responses to verify all
10 endpoints and their error paths. The integration test (`//go:build integration`)
connects to the C++ testnet daemon on `localhost:46941` and verifies the genesis
block hash matches the Phase 1 result (`cb9d5455...`).

All passing with `-race` and `go vet`.

### Key findings

- **Legacy vs JSON-RPC.** Two endpoints (`GetHeight`, `GetTransactions`) use
  plain JSON POST to dedicated URI paths rather than JSON-RPC 2.0. The C++
  daemon registers these with `MAP_URI_AUTO_JON2` (not `MAP_JON_RPC`), so
  they are not accessible via `/json_rpc`. The client provides `legacyCall()`
  for these paths alongside `call()` for standard JSON-RPC.

- **SubmitBlock array params.** The `submitblock` method takes a JSON array
  `["hexblob"]` as its params, not a named object. This is one of the few
  JSON-RPC 2.0 endpoints in the daemon that uses positional parameters.

- **Status field convention.** All daemon responses include a `"status": "OK"`
  field outside the JSON-RPC result envelope. The client checks this after
  successful JSON-RPC decode and returns an error for non-OK status values.

## Phase 5 -- Chain Storage and Sync Client

Commit range: `8cb5cb4`..`23d337e`

Added `chain/` package implementing blockchain storage and RPC sync client.
Uses go-store (pure-Go SQLite) as the persistence backend with five storage
groups mapping to the C++ daemon's core containers.

**Files added:**
- `chain/meta.go` -- `BlockMeta`, `TxMeta`, `outputEntry` types
- `chain/chain.go` -- `Chain` struct, `New()`, `Height()`, `TopBlock()`
- `chain/store.go` -- Block and transaction storage/retrieval
- `chain/index.go` -- Key image and output index operations
- `chain/validate.go` -- Header validation (linkage, height, size)
- `chain/sync.go` -- RPC sync loop with block processing and indexing
- `chain/chain_test.go` -- Storage round-trip tests (6 tests)
- `chain/validate_test.go` -- Validation tests (5 tests)
- `chain/sync_test.go` -- Sync loop tests with mock RPC (2 tests)
- `chain/integration_test.go` -- C++ testnet integration test

**Storage schema:**
- `blocks` -- by height (zero-padded), JSON meta + hex blob
- `block_index` -- hash to height
- `transactions` -- tx hash to meta + blob
- `spent_keys` -- key image to height
- `outputs:{amount}` -- per-amount global output index

**Dependencies added:** `forge.lthn.ai/core/go-store` (local replace).

## Phase 6 -- Wallet Core

Commit range: `5b677d1`..`11b50d0`

Added `wallet/` package implementing full send+receive wallet functionality
with interface-driven design for v1/v2+ extensibility.

### Files added

| File | Purpose |
|------|---------|
| `wallet/wordlist.go` | 1626-word Electrum mnemonic dictionary |
| `wallet/mnemonic.go` | 25-word seed phrase encode/decode with CRC32 checksum |
| `wallet/mnemonic_test.go` | Mnemonic tests (9 tests) |
| `wallet/extra.go` | TX extra parser for tags 22/14/11 |
| `wallet/extra_test.go` | Extra parsing tests (10 tests) |
| `wallet/account.go` | Account key management with Argon2id+AES-256-GCM encryption |
| `wallet/account_test.go` | Account tests (6 tests) |
| `wallet/transfer.go` | Transfer type and go-store persistence |
| `wallet/transfer_test.go` | Transfer tests (15 tests) |
| `wallet/scanner.go` | Scanner interface + V1Scanner (ECDH output detection) |
| `wallet/scanner_test.go` | Scanner tests (7 tests) |
| `wallet/signer.go` | Signer interface + NLSAGSigner (CGo ring signatures) |
| `wallet/signer_test.go` | Signer tests (4 tests) |
| `wallet/ring.go` | RingSelector interface + RPCRingSelector |
| `wallet/ring_test.go` | Ring selection tests (3 tests) |
| `wallet/builder.go` | Builder interface + V1Builder (TX construction) |
| `wallet/builder_test.go` | Builder tests (3 tests) |
| `wallet/wallet.go` | Wallet orchestrator (sync, balance, send) |
| `wallet/wallet_test.go` | Wallet orchestrator tests (2 tests) |
| `wallet/integration_test.go` | C++ testnet integration test |
| `rpc/wallet.go` | GetRandomOutputs + SendRawTransaction RPC endpoints |
| `rpc/wallet_test.go` | RPC wallet endpoint tests (4 tests) |

### Files modified

| File | Change |
|------|--------|
| `types/types.go` | Added `PublicKey.IsZero()` method |
| `crypto/bridge.h` | Added `cn_sc_reduce32()` declaration |
| `crypto/bridge.cpp` | Added `cn_sc_reduce32()` implementation |
| `crypto/crypto.go` | Added `ScReduce32()` Go wrapper |

### Key findings

- **View key derivation requires sc_reduce32.** The raw Keccak-256 of the
  spend secret key must be reduced modulo the Ed25519 group order before it is
  a valid scalar. Added `cn_sc_reduce32` to the CGo bridge.

- **Interface-driven design.** Four core interfaces (Scanner, Signer, Builder,
  RingSelector) decouple v1 implementations from the orchestrator. Future v2+
  (Zarcanum/CLSAG) implementations slot in by implementing the same interfaces.

- **go-store GetAll.** Transfer listing uses `store.GetAll(group)` which returns
  all key-value pairs in a group, rather than iterating with individual Gets.

- **CryptoNote mnemonic encoding.** The 1626-word Electrum dictionary encodes
  4 bytes into 3 words using modular arithmetic: `val = w1 + n*((n-w1+w2)%n) +
  n*n*((n-w2+w3)%n)` where n=1626. The 25th word is a CRC32 checksum.

### Tests added

63 unit tests + 1 integration test = 64 total across wallet/ and rpc/wallet.
All passing with `-race` and `go vet`.

## Phase 7 -- Consensus Rules

Commit range: `fa1c127`..`112da0e` (12 commits)

Added standalone `consensus/` package implementing three-layer validation
(structural, economic, cryptographic) for blocks and transactions. Vendored
RandomX PoW hash function into the CGo crypto bridge. Integrated consensus
validation into the chain sync pipeline.

### Files added

| File | Purpose |
|------|---------|
| `consensus/doc.go` | Package documentation |
| `consensus/errors.go` | 21 sentinel error variables |
| `consensus/errors_test.go` | Error uniqueness tests |
| `consensus/reward.go` | Block reward with 128-bit size penalty |
| `consensus/reward_test.go` | Reward calculation tests |
| `consensus/fee.go` | Fee extraction with overflow detection |
| `consensus/fee_test.go` | Fee tests |
| `consensus/tx.go` | Transaction semantic validation (8 checks) |
| `consensus/tx_test.go` | TX validation tests |
| `consensus/block.go` | Block validation (timestamp, miner tx, reward) |
| `consensus/block_test.go` | Block validation tests |
| `consensus/pow.go` | PoW difficulty check (256-bit comparison) |
| `consensus/pow_test.go` | PoW tests |
| `consensus/verify.go` | Signature verification scaffold |
| `consensus/verify_test.go` | Signature verification tests |
| `consensus/integration_test.go` | Build-tagged integration test |
| `crypto/randomx/` | Vendored RandomX source (26 files) |
| `crypto/pow.go` | CGo RandomX hash wrapper |
| `crypto/pow_test.go` | RandomX hash test |

### Files modified

| File | Change |
|------|--------|
| `crypto/CMakeLists.txt` | Added RandomX static library build |
| `crypto/bridge.h` | Added `bridge_randomx_hash()` declaration |
| `crypto/bridge.cpp` | Added `bridge_randomx_hash()` implementation |
| `crypto/crypto.go` | Added RandomX CGo flags |
| `config/config.go` | Added `MaxTransactionBlobSize` constant |
| `chain/sync.go` | Added `SyncOptions`, consensus validation calls |
| `chain/sync_test.go` | Updated for new `Sync()` signature |

### Key findings

- **RandomX integration.** Vendored the full RandomX source (26 files including
  x86_64 JIT compiler) into `crypto/randomx/`. Built as a separate static
  library (`librandomx.a`) linked into the CGo bridge. Cache key is
  `"LetheanRandomXv1"`, input is `header_hash(32B) || nonce(8B LE)`.

- **128-bit arithmetic for size penalty.** The block reward penalty formula
  uses `math/bits.Mul64` and `bits.Div64` for 128-bit intermediate products,
  matching the C++ 128-bit unsigned arithmetic exactly.

- **Standalone package.** `consensus/` has zero dependencies on `chain/` or
  any storage layer. All functions are pure: take types + config + height,
  return errors. The `RingOutputsFn` callback type decouples signature
  verification from chain storage.

- **Hardfork-aware validation.** Every validation function accepts the fork
  schedule as a parameter. Pre-HF4 and post-HF4 code paths are implemented
  throughout (input types, fee treatment, output requirements).

### Tests added

37 unit tests + 1 integration test = 38 total in consensus/.
Coverage: 82.1% of statements.

All passing with `-race` and `go vet`.

## Phase 8 -- Mining

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).

---

## V2+ Transaction Serialisation

Completed and verified v2+ (Zarcanum/HF4+) transaction serialisation. The code
is tested against a real post-HF4 coinbase transaction from testnet block 101
(tx hash `543bc3c29e9f4c5d1fc566be03fb4da1f2ce2d70d4312fdcc3e4eed7ca3b61e0`,
1323 bytes). Round-trip encoding produces byte-identical output and the
prefix hash matches the known tx hash.

### Bugs fixed

- **V2 suffix field order** — was `attachment + proofs`, corrected to
  `attachment + signatures + proofs` (matching C++ serialisation order).
- **`TransactionHash`** — was hashing the full transaction blob; corrected to
  delegate to `TransactionPrefixHash` for all versions (matching C++
  `get_transaction_hash`).
- **`tagSignedParts` (17)** — was reading 4 fixed bytes (uint32 LE); corrected
  to read two varints (`n_outs` + `n_extras`), matching C++ `VARINT_FIELD`.

### New features

- **`TxInputZC`** — Zarcanum confidential input (tag 0x25). Wire format:
  `key_offsets + k_image + etc_details` (no amount field).
- **`SignaturesRaw`** — new Transaction field for v2+ raw signature bytes.
- **`tagZarcanumTxDataV1` (39)** — extra variant handler (varint fee).
- **Proof tag handlers (46-48)** — `zc_asset_surjection_proof` (vector of
  BGE_proof_s), `zc_outs_range_proof` (BPP + aggregation proof),
  `zc_balance_proof` (double Schnorr, 96 bytes).
- **Signature tag handlers (42-45)** — `NLSAG_sig`, `ZC_sig`, `void_sig`,
  `zarcanum_sig` with full crypto blob readers for CLSAG GGX/GGXXG, BPP/BPPE.

### Files

| File | Action |
|------|--------|
| `types/transaction.go` | Added `TxInputZC`, `SignaturesRaw` field |
| `wire/transaction.go` | Fixed suffix, added InputTypeZC, 10 tag handlers |
| `wire/transaction_v2_test.go` | New -- v2 round-trip, hash, fields, prefix tests |
| `wire/hash.go` | Fixed `TransactionHash` to delegate to prefix hash |

---

## Block Sync (Phase 3 addendum)

Commit range: `ca3d8e0`..`a74ac2e` (17 commits)

Wired real NLSAG ring signature verification into the consensus path and
implemented full P2P block synchronisation via the Levin protocol. The chain
can now sync to tip from either a JSON-RPC daemon or a raw P2P peer, with all
blocks validated through the same shared code path.

### Highlights

- NLSAG ring signature verification wired into consensus path
- Full testnet chain synced via RPC with all blocks validated
- Ring signature verification passes on all spending transactions
- P2P block sync via REQUEST_CHAIN / REQUEST_GET_OBJECTS protocol
- Sparse chain history builder for P2P sync requests
- Shared `processBlockBlobs()` for RPC and P2P paths
- Context cancellation and progress logging for long syncs
- `TxInputZC` key image tracking for v2+ transactions
- Block blob reconstruction from daemon JSON response

### Files added

| File | Purpose |
|------|---------|
| `chain/p2p.go` | `P2PConnection` interface + `LevinP2PConn` adapter |
| `chain/p2p_sync.go` | `P2PSync()` state machine (REQUEST_CHAIN / REQUEST_GET_OBJECTS loop) |
| `chain/sparse.go` | `SparseChainHistory()` exponentially-spaced block hash list |
| `chain/integration_p2p_test.go` | P2P sync integration test against C++ testnet |
| `p2p/getobjects.go` | `RequestGetObjects` (2003) and `ResponseGetObjects` (2004) types |
| `p2p/getobjects_test.go` | GetObjects round-trip tests |
| `p2p/integration_chain_test.go` | Chain request + block fetch integration test |

### Files modified

| File | Change |
|------|--------|
| `chain/sync.go` | Extracted `processBlockBlobs()`, added `resolveBlockBlobs()`, context support, progress logging |
| `chain/index.go` | `TxInputZC` key image tracking |
| `consensus/verify.go` | `verifyV1Signatures()` now performs real NLSAG ring signature verification via CGo |
| `p2p/relay.go` | `BlockCompleteEntry`, `BlockContextInfo` types for chain entry responses |

### Key findings

- **Shared validation path.** `processBlockBlobs()` decodes, validates, and
  indexes blocks identically for both RPC and P2P sync. This ensures consensus
  rules are applied regardless of the transport used to fetch blocks.

- **Sparse chain history.** `SparseChainHistory()` builds an exponentially-spaced
  list of block hashes (every 1, 2, 4, 8, ... blocks back from tip), matching
  the C++ `get_short_chain_history()` algorithm. This minimises the data
  exchanged during the REQUEST_CHAIN handshake.

- **P2PSync state machine.** The sync loop issues REQUEST_CHAIN to get a list
  of chain entry hashes, then fetches blocks in batches via REQUEST_GET_OBJECTS,
  repeating until the peer has no more blocks.

- **Overlap block skipping.** The first block in a REQUEST_GET_OBJECTS response
  overlaps with the last known block (to confirm chain continuity). This
  duplicate is detected and skipped during processing.

- **Network ID and serialisation fixes.** The C++ daemon is strict about
  portable storage field ordering and network ID bytes. Several round-trips
  were needed to match the exact byte layout expected by the C++ peer.

---

## Known Limitations

**V2+ spending transactions untested.** The v2 coinbase serialisation is
verified, but `TxInputZC` and signature tags 42-45 remain untested with real
spending transaction data (no spending txs on testnet yet).

**BPP range proof verification tested with real data.** The `cn_bpp_verify`
bridge function (Bulletproofs++, 1 delta, `bpp_crypto_trait_ZC_out`) is verified
against a real testnet coinbase transaction from block 101 (post-HF4). The
`cn_bppe_verify` function (Bulletproofs++ Enhanced, 2 deltas,
`bpp_crypto_trait_Zarcanum`) is wired but untested with real data -- it is used
for Zarcanum PoS range proofs, not regular transaction output proofs. BGE
(one-out-of-many) proofs are wired but untested (coinbase transactions have
empty BGE proof vectors). CLSAG GGX/GGXXG verify functions are similarly wired
but untested without real ring data. Zarcanum proof verification remains
stubbed -- the bridge API needs extending to pass kernel_hash, ring,
last_pow_block_id, stake_ki, and pos_difficulty.

**CGo toolchain required.** The `crypto/` package requires CMake, GCC/Clang,
OpenSSL, and Boost headers to build `libcryptonote.a`. Pure Go packages
(`config/`, `types/`, `wire/`, `difficulty/`) remain buildable without a C
toolchain.

**Base58 uses math/big.** The CryptoNote base58 implementation converts each
8-byte block via `big.Int` arithmetic. This is correct but not optimised for
high-throughput scenarios. A future phase may replace this with a lookup-table
approach if profiling identifies it as a bottleneck.

**Difficulty coverage at 81%.** The window-capping branch in `NextDifficulty()`
that limits the window to `BlocksCount` (735) entries is not fully exercised by
the current test suite. Adding test vectors with 1,000+ block entries would
cover this path.

**Types coverage at 73.4%.** Unexported base58 helper functions have branches
that are exercised indirectly through the public API but are not fully reached
by the current test vectors. Additional edge-case address strings would improve
coverage.

**Future forks are placeholders.** HF3 through HF6 are defined with activation
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)

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)