diff --git a/docs/architecture.md b/docs/architecture.md index 45c5057..faec0e2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -19,6 +19,7 @@ difficulty/ PoW + PoS difficulty adjustment (LWMA variant) crypto/ CGo bridge to vendored C++ libcryptonote (keys, signatures, proofs) p2p/ CryptoNote P2P command types (handshake, sync, relay) rpc/ Daemon JSON-RPC 2.0 client (10 endpoints) +chain/ Chain storage, indexing, and sync client (go-store backed) ``` ### config/ @@ -144,6 +145,36 @@ rather than `MAP_JON_RPC`. daemon on `localhost:46941`. Verifies genesis block hash matches Phase 1 result (`cb9d5455...`). +### chain/ + +Stores and indexes the Lethean blockchain by syncing from a C++ daemon via RPC. +Uses go-store (pure-Go SQLite) for persistence with five storage groups mapping +to the C++ daemon's core containers. + +**Storage schema:** +- `blocks` -- blocks by height (zero-padded key), JSON metadata + hex blob. +- `block_index` -- hash-to-height reverse index. +- `transactions` -- tx hash to JSON metadata + hex blob. +- `spent_keys` -- key image to block height (double-spend index). +- `outputs:{amount}` -- global output index per amount. + +**Core operations:** +- `chain.go` -- `Chain` struct with `New()`, `Height()`, `TopBlock()`. +- `store.go` -- `PutBlock`, `GetBlockByHeight/Hash`, `PutTransaction`, + `GetTransaction`, `HasTransaction`. +- `index.go` -- `MarkSpent`, `IsSpent`, `PutOutput`, `GetOutput`, `OutputCount`. +- `validate.go` -- Header validation (previous block linkage, height sequence, + block size). +- `sync.go` -- `Sync(client)` blocking RPC poll loop. Fetches blocks in batches + of 10, decodes wire blobs, validates headers, indexes transactions/outputs/ + key images, verifies block hashes. + +**Testing:** +- Unit tests with go-store `:memory:` for all CRUD operations and validation. +- Mock RPC server sync tests. +- Build-tagged integration test (`//go:build integration`) syncing first 10 + blocks from C++ testnet daemon on `localhost:46941`. + --- ## Key Types diff --git a/docs/history.md b/docs/history.md index f64fd0b..201a300 100644 --- a/docs/history.md +++ b/docs/history.md @@ -345,11 +345,34 @@ All passing with `-race` and `go vet`. 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 Validation (Planned) +## Phase 5 -- Chain Storage and Sync Client -Implement `chain/` with blockchain storage (using `go-store` for persistence), -block validation, transaction verification, and mempool management. UTXO set -tracking with output index. +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 (Planned)