chain.toml V2 baseline: what ships first (PR #20527)

**Parent:** #20617

# chain.toml V2 baseline — what's on main

Documents V2 as it exists on `main` today, landed via PR #20527. This is the starting point for incremental V2 development. The baseline is deliberately narrow: it establishes the data model and invariants without yet adding publish/consume lifecycle.

## What's in the baseline

### Format (`db/downloader/chaintoml_v2.go`)

```go
type ChainTomlV2 struct {
Version int // always 2
Blocks map[string]string // filename → hash (flat, like V1)
Meta map[string]string // erigondb.toml, salt-*.txt
Domains map[string]*DomainManifest // "accounts", "storage", "code", "commitment"
}

type DomainManifest struct {
Coverage [2]uint64 // [from, to) steps covered by Files
Files []DomainFileEntry
}

type DomainFileEntry struct {
Name string
Range [2]uint64
Hash string
Trust string // "none" | "consensus" | "verified"
}
```

### Inventory (`node/components/storage/snapshot/inventory.go`)

Thread-safe tracker of local and remote-advertised files, organised by domain. Fields: `Domain`, `FromStep`, `ToStep`, `Name`, `Size`, `TorrentHash`, `Trust`, `Local`, `Seeding`.

Populated from disk at startup via `populate.go`. Aggregator file-change callbacks update it incrementally.

### Trust model (`node/components/storage/snapshot/trust.go`)

Three incremental levels: `TrustNone` (content integrity only) → `TrustConsensus` (M-of-N peer agreement) → `TrustVerified` (cryptographic provenance — local generation, preverified registry, or UCAN-chained; segment-proof enforcement comes later).

### Canonicity filter

`GenerateV2` includes only files at canonical (power-of-2 aligned) boundaries in the domains section. Unmerged backlog stays local. Two nodes at different merge states thus publish comparable subsets.

### ENR extensions (`p2p/enr/chain_toml.go`)

Three baseline fields (`AuthoritativeBlocks`, `KnownBlocks`, `InfoHash`) plus two V2 extensions: `DomainSteps` and `MergeDepth`. Backwards-compatible RLP — old 3-field entries decode cleanly.

### Range arithmetic (`node/components/storage/snapshot/ranges.go`)

StepRange normalisation, coverage computation, gap analysis, union/intersection.

## What the baseline does NOT do

These are intentionally deferred to later phases — V2 is runtime-only data today, not yet a live manifest format:

| Gap | Consequence |
|-----|-------------|
| No publish lifecycle — V2 manifest is not written to disk or seeded | V2 is publisher-only data model; peers can't read it |
| No ENR update for V2 — `InfoHash` is V1's hash | Peers discover V1, never V2 |
| No consumer path — downloading node ignores V2 sections | V2 is compiled in but dormant |
| No gap-fill logic | Consumer can't use V2 to decide what to download |
| No file provenance tag (source = local/preverified/peer) | Only trust is exposed; can't distinguish local file from peer claim |
| No atomic rotation on merge | Manual inventory update needed when merges complete |
| No prune-window filtering | All range requests sent regardless of peer retention |
| No feature flag | V2 code is compiled in but unused — no runtime switch |
| No segment-proof enforcement | `trust=verified` is advertiser's assertion, not cryptographic fact |

## Invariants established by the baseline

Even narrow as it is, the baseline establishes invariants subsequent phases must preserve:

1. **Versioned-first parsing.** Any manifest with a non-zero `version` field is parsed as that version. No silent fallback.
2. **Canonical layout convergence.** Every canonical file's range satisfies the power-of-2 and alignment rules. All nodes converge to the same canonical files.
3. **Coverage is published, not local.** `Coverage` reflects published files only, not local backlog.
4. **Trust is monotonic.** Trust may be promoted (e.g. `none → consensus`) but never demoted without re-verification.
5. **ENR additions are trailing RLP fields.** Any future ENR metadata appends; never reorders.

## Test coverage

- `chaintoml_v2_test.go` — round-trip marshal/unmarshal, version detection, canonicity filter, trust filter
- `inventory_test.go` — file add/remove, domain separation, local/remote separation
- `ranges_test.go` — step range arithmetic, normalisation
- `canonical_test.go` — convergent merge, canonical boundary detection
- `p2p/enr/chain_toml_test.go` — RLP round-trip with and without trailing fields

## What ships next

See parent umbrella issue for rollout plan. The immediate next phase is the feature flag (`--snap.manifest.mode`) to enable parallel V1/V2 operation.