diff --git a/README.md b/README.md index 6eb3cc5..ab2933c 100644 --- a/README.md +++ b/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 info -network mainnet +mithril-go list -network mainnet +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