Devp2p Full Sync

Full Sync (Block Archive Backfill) — Nethereum.DevP2P.Sync

Once your node can connect to peers (devp2p-peer-connect) and is wired up as a SyncNode (devp2p-run-a-node), it needs the actual chain data: headers, bodies, and receipts for every block. This is Phase 1 of Nethereum's snap-first sync — downloading and verifying the block archive from [genesis..pivot] — and it's useful on its own even outside a full snap-sync run, for backfilling history behind an already snap-synced head.

Package

dotnet add package Nethereum.DevP2P.Sync

You need an IChainStoreBundle to persist into, an IPeerPool with at least one connected peer, and an IFetchRequestScheduler to fan requests across that pool.

Mental model: content-addressed, pipelined, resumable

Phase 1 downloads three things per block — headers, bodies (transactions + uncles), and receipts — and verifies every one of them cryptographically before it's trusted:

• Bodies are checked against the header's TransactionsHash and UnclesHash.
• Receipts are checked against the header's ReceiptHash.
• The parent-hash chain is validated within and across fetch batches.

A peer that returns bad data doesn't corrupt your archive — a mismatch is detected and the request is retried against another peer. This is the same trustless-fetch principle behind Phase 2 in snap sync (devp2p-snap-sync): never persist what you can't verify.

Run a bounded backfill

ParallelBlockBackfiller runs a concurrent pipeline — header producer/loader, body fetcher, receipt fetcher, and a persistence drain — over a shared BlockTaskQueue:

Task<BackfillResult> BackfillAsync(ulong startBlock, ulong endBlock, CancellationToken ct);
Task<BackfillResult> BackfillAsync(ulong startBlock, ulong endBlock, IBodyFillCursor cursor, CancellationToken ct);
Task<BackfillResult> BackfillAsync(ulong startBlock, ulong endBlock, bool headersFromStore, CancellationToken ct);

The headersFromStore: true overload is the one you reach for when headers are already persisted (laid down by a header skeleton, or by a previous partial run) and only bodies/receipts are missing:

var pool = new OnePeerPool();                 // your IPeerPool with a connected peer
var worker = new ServingWorker(chain);        // your IPeerRequestWorker implementation
var backfiller = new ParallelBlockBackfiller(scheduler, pool, worker, bundle);

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var result = await backfiller.BackfillAsync(3, 7, headersFromStore: true, cts.Token);

// result.Ran == true
// result.BlocksWritten == 5, result.TransactionsWritten == 5, result.ReceiptsWritten == 5
// bundle.Metadata.GetLastFetchedBody() advances to 7

BlocksWritten/TransactionsWritten/ReceiptsWritten tell you exactly what landed; bundle.Metadata.GetLastFetchedBody() is the durable cursor Phase 1 advances only over the contiguous persisted prefix — so a crash mid-fill leaves the cursor pointing at real, complete data, never past a gap.

Where the header skeleton comes from

The headersFromStore: true path assumes headers are already in the store. BackwardBlockWalker is what lays that skeleton down: it walks the chain backward from a trusted-tip hash anchor, validating the parent-hash chain as it goes, and optionally persisting bodies too. BlockTaskQueue — the producer/consumer queue underneath the backfiller — caps concurrent in-flight requests per peer per stage via maxInFlightPerPeer (default 1; the backfiller itself uses 4, so a fast peer can pipeline across the round trip instead of idling waiting for one response before sending the next request).

Keeping the tip band fed independently

Phase 1's archive backfill and the "keep the live tip fresh" job are deliberately separate concerns: TipBandBodyFollowService fills [execution-head+1 .. trusted-tip] with bodies and receipts so the block executor never starves waiting on the history drain to catch up. It's driven the same way as a bounded backfill, but against an IBodyFillCursor anchored at the execution head rather than a fixed [start, end] range:

var service = new TipBandBodyFollowService(scheduler, pool, bundle, activations);
var cursor = new ExecutionHeadBodyFillCursor(bundle);

await service.FillOnceAsync(backfiller, cursor, ct);
// cursor advances to the trusted tip independently of bundle.Metadata's archive body cursor

The archive cursor (bundle.Metadata.GetLastFetchedBody()) does not move when you drive the tip band this way — the two cursors track different things on purpose, so a slow archive backfill can never stall block execution at the tip.

Consuming blocks as a stream: IBlockSource

A follower doesn't call the backfiller directly in most cases — it consumes an IBlockSource, a chain-agnostic abstraction (defined in Nethereum.CoreChain) that streams blocks and reports when the source diverges from what was previously seen (a reorg or a bad peer). Two DevP2P-backed implementations exist:

• DevP2PBlockSource — a multi-peer source (built on the pool + scheduler) that a follower pulls from, reporting chain breaks so the caller can auto-rewind.
• PushedBlockSource — accepts blocks pushed to it (e.g. from a broadcast peer bridge) rather than pulling.

Note: these two types are named in the README's type table (role description, no method signature block); no tagged doc-example test covers constructing or streaming from either. Check src/Nethereum.CoreChain/Sync/IBlockSource.cs directly for the current interface shape before relying on it as stable.