Epic: ION fast-sync overlay — trustless anchor bootstrap + content-availability gossip

[LiranCohen]

Problem

A fresh ion-node's bootstrap cost is dominated by downloading every full block from ION activation (mainnet 667,000) to tip and scanning each for OP_RETURN anchors — BIP158 filters exclude OP_RETURN, so neutrino/compact-filters can't help. That's hundreds of GB and, worse, much of it is no longer available: most Bitcoin peers prune, so historical full-block serving is poor and rate-limited. ION also has a second availability weakness — anchored content can disappear from IPFS when it's unpinned/GC'd (we observe this live as pendingRetryable > 0).

This epic builds an ION-native overlay so nodes can discover each other and bootstrap a new node from a peer's already-computed anchor index + content — fast, and resilient to both Bitcoin pruning and IPFS unpinning.

The trust reframe (what's verifiable vs. trusted)

An anchor decomposes into three claims with very different trust properties:

Claim	Trustless?	How
Anchor tx exists at block H, index I	✅ yes, cheap	Merkle inclusion proof against the node's own PoW-verified header chain (~12 hashes + raw tx)
Anchored content (Sidetree files) is authentic	✅ yes, trivial	CID is the content hash — content-addressed, self-verifying
The peer sent all anchors (no omissions)	❌ no	Would require seeing every tx in every block = the download we're avoiding

So a peer cannot forge a DID — inclusion proofs + content-addressing make it impossible, and the node applies its own validity rules (#99 op-count, #69 writer-drop) to the provided txs, so it is its own validity authority. The only attack is omission (hiding an anchor to fake non-existence or roll back an update/deactivate).

This is the same trust model the codebase already uses for --esplora-api: untrusted hint, verified against our own PoW chain, fails closed. Fast-sync generalizes it from one tx to the whole anchor set.

Omission defenses (layered)

1. Trust-then-verify (primary). Serve immediately but mark answers provisional (published:false — the existing late-publishing model), and run the slow full-block scan in the background, reconciling. A discovered omission → ban the peer, correct state. When background scan catches up → drop provisional = fully trustless, just eventually.
2. Union over diverse peers. Each anchor is inclusion-proven, so the union of several ION peers' anchor sets is safe to take — omission then needs all of them to collude on the same anchor. Reuse netgroup diversity.
3. Always full-verify the tip. Recent blocks are downloaded in full anyway (live anchor detection), so the trust window is historical only.
4. Random sampling audits. Fully download a random sample of historical blocks and check the peer reported the same anchors — bounds how much a peer can omit before being caught.

The trust anchor under all of it is the node's own PoW header chain (synced from diverse peers, hardened by #1/#4). The overlay can only omit, never forge — so eclipse of the overlay degrades to "slow/incomplete," not "wrong."

Locked decisions

• Trust posture: eventually-fully-trustless via trust-then-verify (matches the provisional model).
• Goal: both speed and content availability; build the foundational trustless slice (verifiable anchor bundles) first.
• Scope: bootstrap pull first; architecture leaves room for ongoing anchor/content gossip between running nodes.

Architecture / work breakdown (child issues)

1. Merkle inclusion proofs (internal/chain) — the pure primitive: compute + verify a Bitcoin merkle branch against a header's merkle root. No deps. [first]
2. Verifiable anchor bundles (store + indexer) — retain the merkle branch (+ anchor tx + its first-input prevout tx + that prevout's branch) at scan time, so a node can later serve a self-contained, PoW-verifiable bundle (~10–20 MB for the whole index). Opt-in "serve fast-sync."
3. ION overlay discovery & handshake (p2p) — an ION service bit (advertised in version/addrv2), a capability handshake gating the custom messages, and bootstrap/seed nodes (don't rely on vanilla Bitcoin gossip alone).
4. Fast-sync wire protocol (p2p) — getanchors/anchors (range → verifiable bundles) and getcas/cas (CID → content blob).
5. Fast-sync client + provisional serving + background reconciliation — pull bundles, verify inclusion against own headers, apply own validity rules, project as provisional; background full-scan reconciles & drops provisional; omission → ban.
6. CAS content gossip (anti-unpinning) — serve/fetch content-addressed blobs between ION peers, self-verifying by CID; cures IPFS unavailability. Arguably the biggest standalone win.
7. Preferential two-tier peering — a preferred ION-peer pool layered over a diverse Bitcoin-peer pool, without shrinking header-chain diversity (the eclipse trust anchor). Two pools, two purposes.

Fit / prior art

No anchor-gossip overlay exists in reference ION (it re-scans Bitcoin), so this is net-new. It reuses the codebase's existing trust philosophy (untrusted-hint-verified-against-PoW), the provisional/published:false model, and the netgroup-diversity peer logic.

Child issues will be linked below.

[LiranCohen]

Child issues (dependency-ordered)

• 1/7 fast-sync 1/7: Bitcoin merkle inclusion proofs (compute + verify) #112 — Bitcoin merkle inclusion proofs (primitive, no deps) ← executing first
• 2/7 fast-sync 2/7: verifiable anchor bundles — retain proof data at scan time #113 — verifiable anchor bundles (retain proof data at scan time)
• 3/7 fast-sync 3/7: ION overlay discovery & capability handshake #114 — ION overlay discovery & capability handshake
• 4/7 fast-sync 4/7: fast-sync wire protocol (getanchors/anchors, getcas/cas) #115 — fast-sync wire protocol (getanchors/anchors, getcas/cas)
• 5/7 fast-sync 5/7: fast-sync client + provisional serving + background reconciliation #116 — fast-sync client + provisional serving + background reconciliation
• 6/7 fast-sync 6/7: CAS content gossip (anti-unpinning availability) #117 — CAS content gossip (anti-unpinning availability)
• 7/7 fast-sync 7/7: preferential two-tier peering (eclipse-safe) #118 — preferential two-tier peering (eclipse-safe)

[LiranCohen]

Progress: foundational trustless layer landed.

• ✅ 1/7 fast-sync 1/7: Bitcoin merkle inclusion proofs (compute + verify) #112 — merkle inclusion proofs (PR feat(chain): Bitcoin merkle inclusion proofs (#112) #119)
• ✅ 2/7 fast-sync 2/7: verifiable anchor bundles — retain proof data at scan time #113 — verifiable anchor bundles, captured at scan time (PR feat(fastsync): verifiable anchor bundles, captured at scan time (#113) #120)
• ⏭️ 3/7 fast-sync 3/7: ION overlay discovery & capability handshake #114 — overlay discovery & handshake (next)

The two trustless primitives are in: a node can prove an anchor's chain position against its own PoW headers (#112), and capture/serve a self-contained verifiable bundle without retaining full blocks (#113). Remaining pieces are the networking layer (#114 discovery/handshake → #115 wire protocol → #116 client + trust-then-verify) and the availability/peering refinements (#117 CAS gossip, #118 two-tier peering).