chain.toml V2 target format: what we're building toward

**Parent:** #20617

# chain.toml V2 target format

Documents the end-state V2 — what the manifest, trust model, and runtime coordination look like when all feature work lands. Builds on the [baseline](#20618) by adding publish/consume lifecycle, consumer coordination, and cryptographic verification where a proof scheme is available.

Canonical design in [chain-toml-v2-format.md](https://github.com/erigontech/erigon-documents/blob/main/ethereum/design/erigon-archive/chain-toml-v2-format.md); this issue summarises the delta vs baseline.

## Target features

| Feature | What changes | Why it matters |
|---------|--------------|----------------|
| **Feature flag** (`--snap.manifest.mode={off,dual,v2}`) | New CLI flag gates publish and consume behaviour | Parallel V1/V2 operation during dev; no production disruption |
| **File source field** (`local | preverified | peer`) | New orthogonal-to-trust column on every file entry | Consumer can distinguish advertiser provenance from trust level; unblocks quorum logic |
| **Typed block entries** | `Blocks []BlockFileEntry` replaces `map[string]string` | Consistent with domains; per-block trust/source |
| **Merged flag** | Per-file `Merged bool` in `DomainFileEntry` | Consumer prefers merged files in selection (fewer downloads, less tracking) |
| **Proof root** | Optional `ProofRoot` per file; linked to canonical chain state | `TrustVerified` becomes cryptographically enforceable rather than advertiser assertion |
| **ENR extensions** | `V2InfoHash`, `MinStep` (prune window), `ProofScheme` | Peers discover V2 without leaving V1; consumers avoid pruned peers |
| **Publish lifecycle** | Storage inventory change → debounce → regenerate V2 → rebuild torrent → update ENR | Manifest stays current without manual intervention; other components subscribe |
| **Consumer gap-fill** | `CompareDomainCoverage`, `DownloadRequest`, multi-peer selection policy | Nodes actually use V2 to close coverage gaps across merge-divergent peers |
| **Quorum for TrustConsensus** | Require M distinct peers advertise same (Name, Hash) before download | Defeats isolated-bad-actor Sybil attacks at the format layer |
| **Atomic rotation on merge** | `inv.ReplaceWithMerge` — add merged, remove replaced, single lock | No coverage gaps during file rotation; inventory and chain.toml stay consistent |
| **Prune-window filtering** | `FilterByPruneConfig`, ENR `MinStep` field | No wasted bandwidth downloading files outside retention; skip pruned peers |
| **Event-driven coordination** | Storage ⇄ downloader ⇄ sentry via framework event bus | Clean gRPC-boundary handling; remote-downloader mode doesn't need these events |

## Feature details (linked to design doc sections)

Each feature below is described in detail in the [canonical design doc](https://github.com/erigontech/erigon-documents/blob/main/ethereum/design/erigon-archive/chain-toml-v2-format.md). The section numbers match the doc structure.

### File format extensions (§2 of design doc)

- `Source` field added to `DomainFileEntry` and new `BlockFileEntry` — orthogonal to trust (§2.2)
- `Merged` flag on `DomainFileEntry` (§2.3)
- `ProofRoot` optional per file (§2.4)

Example:

```toml
[[domains.accounts.files]]
name = "v1.0-accounts.0-2048.kv"
range = [0, 2048]
hash = "abc1..."
trust = "verified"
source = "local"
merged = true
proof_root = "0x..." # optional; present when a proof scheme is active
```

### Trust model (§3)

- `TrustVerified` becomes cryptographically enforceable with `ProofRoot` populated (§3.1)
- Consumer policy via `--snap.trust={none,consensus,verified}`, quorum via `--snap.trust.quorum` (§3.2)
- Trust promotion / demotion rules (§3.3)

### ENR entry (§4)

- `V2InfoHash` advertises V2 torrent hash alongside V1 (§4.1)
- `MinStep` advertises the node's retention floor (§4.2)
- `ProofScheme` identifies the proof scheme in use (§4.3)

### Publish lifecycle (§6)

- Downloader subscribes to `SnapshotInventoryChanged` events from storage
- Debounces ~200ms before regen + torrent rebuild + ENR update
- Deterministic output (same inventory → identical TOML)
- Feature flag controls parallel V1/V2 publish

### Consumer gap-fill (§7)

- `CompareDomainCoverage(local *Inventory, remote *ChainTomlV2) []DownloadRequest`
- File selection policy: trust > merged > gap-fit > source > peer health
- Quorum enforcement before downloading `TrustConsensus` files
- Post-download verification + trust promotion

### Atomic rotation (§8)

- `inv.ReplaceWithMerge(domain, merged, replaced)` — single-lock atomic swap
- No transient state with neither old nor new files visible
- Event emission drives manifest + torrent updates

### Prune filtering (§9)

- Advertiser omits files below retention floor from manifest
- `Coverage[0]` starts at node's lowest retained step
- Consumer skips peers whose `MinStep > requested step`

### Event-driven coordination (§10)

- 11 events across storage/downloader/sentry (full catalog in [storage-component-design.md](https://github.com/erigontech/erigon-documents/blob/main/ethereum/design/erigon-archive/storage-component-design.md))
- Sync vs async ordering semantics documented per event
- In-process only — no gRPC boundary issues

## Invariants added at target

Preserved from baseline (see sub-issue A) plus:

6. **Inventory rotations are atomic.** `ReplaceWithMerge` is the only approved path; no separate add-then-remove races.
7. **Manifest regeneration is deterministic.** Same inventory + same trust state → byte-identical TOML.
8. **Event delivery is in-process.** Events never cross the gRPC boundary. Remote downloaders use gRPC RPCs.
9. **Feature flag gates publish, not parse.** V2-capable nodes parse V2 regardless of mode; only generation/advertising is suppressed when `mode=off`.
10. **Proof verification is consumer-side.** Advertiser declares `ProofRoot`; consumer independently recomputes after download.

## Open questions

1. **ProofScheme encoding.** Enum in ENR is compact but inflexible. Alternative: string identifier. Blocked on qmtree scheme selection.
2. **Manifest TTL for quorum.** How long does a peer's manifest stay valid in consensus calculations? Starting at 1h; may need adjustment from devnet testing.
3. **Peer reputation.** Currently stateless per-manifest evaluation. May need persistent peer scores for repeat bad actors.
4. **V1 sunset.** When does V1 generation stop? Probably one release cycle after V2 is mainnet-authoritative. Needs explicit decision.

## Delivery phases

See [distribution-implementation.md](https://github.com/erigontech/erigon-documents/blob/main/ethereum/design/erigon-archive/distribution-implementation.md) for the phased plan. Each phase produces a reviewable increment on top of the baseline; the target is reached when all phases land.