Devp2p Bal Sync

Block Access Lists (Snap-v2 BAL Heal) — Nethereum.DevP2P.Sync

Snap sync (devp2p-snap-sync) follows a rolling pivot as the chain advances, and Phase 3 heal re-fetches missing trie nodes when the root doesn't match. But there's a gap those mechanisms don't close by themselves: while Phase 2/3 is still streaming or healing, the live chain keeps producing blocks — and the account/storage ranges you already fetched at the old pivot are now stale relative to the new one. Re-streaming those ranges from scratch would waste everything already downloaded. Snap-v2's Block Access List (BAL) — a per-block account/storage/code/nonce/balance change set — lets you patch just the deltas instead. This is an advanced, opt-in path: everything here sits behind SnapSyncOrchestratorOptions.BalHealEnabled, which defaults to false.

Package

dotnet add package Nethereum.DevP2P.Sync

This skill assumes you've already read devp2p-snap-sync — BAL heal is a supplement to Phase 2/3, not a replacement. You also need peers advertising snap/2 — devp2p-peer-connect covers DevP2PConfig.AdvertiseSnap2, the flag that puts snap/2 in your own Hello.

Mental model: patch the frontier, don't re-stream it

Everything Phase 2 has already fetched has a frontier — the boundary of account/storage ranges already covered. When the pivot moves mid-flight, Snap/CatchUp's job is narrow and specific:

1. Fetch each intervening block's BAL from a peer.
2. Verify it against the block header's BAL-hash commitment (never trust an unverified change set).
3. Apply only the changes that land inside the already-fetched frontier — anything outside it will be picked up naturally when Phase 2/3 reaches that range anyway, so applying it early would be wasted (or worse, inconsistent) work.

This is the same trustless-fetch discipline as the rest of the sync engine (devp2p-full-sync, devp2p-snap-sync): nothing gets applied to state without being checked against a cryptographic commitment first.

Fetch: pulling raw BAL entries

IBlockAccessListFetcher (concrete: BlockAccessListFetcher) fetches raw BAL entries for a set of block references from serviceable peers, retrying and redistributing across peers on refusal, hash mismatch, or a stateless response:

// IBlockAccessListFetcher.FetchAsync — Snap/CatchUp/IBlockAccessListFetcher.cs:10
Task<IReadOnlyList<IReadOnlyList<AccountChanges>>> FetchAsync(
    IReadOnlyList<BalBlockRef> blocks, CancellationToken ct);

Each BalBlockRef is (byte[] BlockHash, byte[] BlockAccessListHash) — the block's identity plus the commitment the fetched entry must hash-match. The fetcher batches at most MaxHashesPerRequest (28) blocks per request within a ResponseByteBudget of 2 MiB, and throws InvalidOperationException if a block becomes unobtainable from every serviceable peer — there's no silent partial result to accidentally apply.

Verify: checking the commitment before trusting anything

BlockAccessListVerifier.Verify(expectedBalHashes, rawEntries) Keccak-hashes each raw entry against its expected commitment and decodes it via BlockAccessListRLPEncoder, returning one VerifiedBlockAccessList per entry:

• VerifiedBlockAccessList.Status (enum BlockAccessListStatus) is one of Verified / Unavailable / HashMismatch.
• Only on Verified does the result carry a decoded IReadOnlyList<AccountChanges> — an Unavailable or HashMismatch result carries nothing to apply.

This is the checkpoint that keeps a malicious or buggy peer from injecting fabricated balance/storage changes: a mismatched hash is discarded, not applied.

Apply: patching flat state and the trie

IBlockAccessListApplier (concrete: BlockAccessListApplier) is where verified changes actually land in storage:

// IBlockAccessListApplier.ApplyAsync — Snap/CatchUp/IBlockAccessListApplier.cs:10
Task ApplyAsync(IReadOnlyList<AccountChanges> blockAccessList, ISnapTaskFrontier frontier, CancellationToken ct = default);

ApplyAsync applies a verified block's AccountChanges — balance, nonce, code, and storage — into flat state (ISnapFlatStateWriter, plus IStateStore for code), and, when supplied, into the in-progress trie via IHealedStateWriter. Empty accounts are deleted, matching Ethereum's account-clearing rule. Within one account's changes, conflicting writes at different points in the block resolve last-writer-wins by BlockAccessIndex — not by list order:

Given balance changes at indices 3 (→ 500) and 0 (→ 100) submitted in that order, the applied balance is 500 — the change with the higher BlockAccessIndex wins, regardless of which one appears first in the list.

Confirmed in tests/Nethereum.DevP2P.Sync.UnitTests/CatchUp/BlockAccessListApplierTests.cs:24 (Given_BalanceAndNonceChanges_When_Applied_Then_PostValuesAreLastWriteByIndexNotByListOrder).