docs: Phase 5 chain storage and sync client documentation

Co-Authored-By: Charon <charon@lethean.io>

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

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)