readme: reflect actual status + document verification sprint plan

- status table: what's working vs what's next
- sprint plan for genesis Ed25519 (wiring) and STM BLS (the real work)
- concrete pointers: upstream mithril-common for signed_message derivation,
  blst Go bindings for BLS12-381

README.md

@@ -18,25 +18,94 @@ static binary with no runtime dependencies — useful for:
 
 ## Status
 
-**Early development — not usable yet.** Current state:
+**Download + extract pipeline working. Verification is the next milestone.**
 
-- [x] Module scaffold, network configs, aggregator REST client
-- [x] `list` command hits the aggregator and enumerates cardano-database snapshots
-- [ ] `download` — range-chunk parallel HTTP, SHA-256 integrity, resume
-- [ ] `extract` — streamed zstd + tar decompression
-- [ ] Genesis Ed25519 verification (per-network bootstrap key)
-- [ ] STM BLS12-381 aggregate-signature verification (the hard part)
-- [ ] Incremental / ancillary artifact support
+| Piece | Status |
+|---|---|
+| Aggregator REST client | ✅ list, get, cert, chain |
+| `list` / `show` / `info` / `cert` commands | ✅ working against mainnet + preprod |
+| Resumable HTTP download (single stream, SHA hook) | ✅ |
+| Streamed zstd+tar extract (tar-slip defended) | ✅ |
+| `download` — digests + ancillary | ✅ (immutables loop pending) |
+| Genesis Ed25519 verification | ⚠️ stubbed, needs signed_message derivation wired |
+| STM BLS12-381 aggregate verification | ❌ the sprint — see below |
 
-## Usage (eventual)
+## Usage
 
 ```
 mithril-go info    -network mainnet
 mithril-go list    -network mainnet
-mithril-go download -network mainnet -out ./db latest
-mithril-go verify   -network mainnet ./db
+mithril-go show    -network mainnet latest
+mithril-go cert    -network mainnet head
+mithril-go cert    -network mainnet -chain head         # walk to genesis
+mithril-go download -network preprod -out ./db latest   # digests + ancillary
 ```
 
+## Verification sprint plan
+
+The verification story splits into two layers:
+
+### 1. Genesis Ed25519 verification
+
+The genesis certificate (terminates the chain; its `previous_hash` is
+empty and `genesis_signature` is non-empty) is signed by a static
+Ed25519 key baked into this client per network (`internal/networks`).
+
+- Key encoding: the Mithril genesis key is serialized as an ASCII-
+  representation of a 32-byte array literal (e.g. `"[191,66,...]"`)
+  then hex-encoded. Decoder needs to unwrap both levels before handing
+  32 raw bytes to `ed25519.Verify`.
+- Signed payload: `signed_message` field (32 bytes hex) is the output
+  of hashing the serialized `protocol_message` — the exact hash
+  function and canonicalization must match the Rust reference
+  (`mithril-common/src/protocol/` in the upstream repo). Likely
+  Blake2b-256 over a deterministic CBOR or JSON encoding; needs
+  confirming against upstream.
+- Wire location: `internal/verify/verify.go` → `Genesis(...)`.
+
+### 2. STM BLS12-381 aggregate verification
+
+Every non-genesis certificate carries a `multi_signature` that is an
+STM (Stake-based Threshold Multi-signature) aggregate proof over BLS12-381.
+
+- Scheme: Chotard/Kiayias/Peters "Stake-based Threshold Multisignatures"
+  (Mithril paper §5-6).
+- Library: `github.com/supranational/blst` Go bindings (IETF-draft
+  BLS12-381 operations; production-grade, consensus layers use it).
+- Inputs:
+  - `next_aggregate_verification_key` from the previous-epoch cert's
+    `protocol_message` (the "trust handoff" between certs)
+  - `multi_signature` bytes (CBOR-encoded STM aggregate signature)
+  - `signed_message` (what was signed)
+- Output: pass/fail, plus the epoch-boundary decision to promote
+  that cert's `next_aggregate_verification_key` for use by the NEXT
+  verification.
+- Wire location: `internal/verify/verify.go` → `STM(...)`.
+
+### Downstream once verification lands
+
+- `verify` subcommand: takes a snapshot directory, walks the cert chain,
+  verifies genesis Ed25519 + each STM signature in order, validates the
+  `merkle_root` against the digests manifest's computed root, reports
+  per-stage pass/fail.
+- Per-immutable SHA check against the `digests.json` manifest (already
+  downloaded — 16836 entries for preprod as of epoch 284).
+- Full immutables loop for the `download -immutables` path.
+
+## Dependencies
+
+- `github.com/klauspost/compress/zstd` — pure Go zstd decoder
+- (pending) BLS12-381: `github.com/supranational/blst` via its Go bindings
+
+## Building
+
+```
+go build -o mithril-go ./cmd/mithril-go
+```
+
+Produces a single static binary (~9.5 MB). CGo is not used; cross-
+compilation is `GOOS=linux GOARCH=arm64 go build ./cmd/mithril-go`.
+
 ## License
 
 TBD