core, miner, consensus/bor, eth, triedb/pathdb: pipelined state root computation for block import

[pratikspatil024]

Description

Overlaps state-root computation (SRC) of block N with transaction execution of block N+1 during block import. Execution of N+1 opens state at the last committed trie root plus an in-memory FlatDiff overlay of block N's mutations, while a background SRC goroutine commits block N and computes its root. Disabled by default — enabled with [pipeline] enable-import-src = true.

Built on top of the delayed SRC PoC: instead of just deferring SRC, it pipelines SRC with the next block's work.

Measured impact

Mainnet full node (n2d-standard-16, path scheme, BlockSTM enforce), ~64k-block catch-up windows, block-weight and traffic-character controlled across adjacent weekday ranges:

configuration	agg mgasps	vs baseline
pipeline off	291.0	—
pipeline on	346.4	+19.0%
pipeline off + producewitnesses	255.3	—
pipeline on + producewitnesses	293.7	+15.0%

Per-block overhead beyond raw execution dropped from ~45–50ms to ~18ms. Zero root_mismatch, pipeline fallbacks, or execution errors across the benchmark campaign (~500k blocks imported under the pipeline).

How it works — import

When importing block N (pipeline active):

1. Execute block N at the last committed root + FlatDiff overlay from block N−1
2. Run ValidateStateCheap (gas, bloom, receipt root — no IntermediateRoot)
3. Extract block N's FlatDiff via CommitSnapshot (~1ms, no trie hashing)
4. Collect the previous SRC(N−1): verify its root, write + announce the witness, trie GC
5. Write block metadata and advance the head immediately (sync protocol sees it)
6. Store the FlatDiff so StateAt/RPC reads (eth_call, eth_estimateGas, pending reads) are correct during the pipeline window
7. Spawn SRC(N) in the background — it overlaps with block N+1's execution
8. Continue to the next block without waiting for SRC(N)

Two supporting optimizations ship with the pipeline:

• pathdb trie-node index (triedb/pathdb/lookup_nodes.go): a reference-counted (owner, path, hash) → blob map over live diff layers. reader.Node resolves in one probe instead of walking up to 128 diff layers per read (the walk measured ~44% of process CPU during catch-up). The hash is part of the key, so a hit is correct by construction; a definitive miss reads the disk layer directly. This index is always on (not gated by the pipeline flag) — it is a read-path cache whose misses fall through to the existing walk, adding ~250MB steady-state at 128 diff layers.
• Warm-node handoff (core/state/warm_snapshot.go, pipeline.warm-snapshot, default on): when witnesses are produced, the execution-side trie prefetcher is detached and handed to SRC, which builds an immutable hash-verified snapshot of the loaded trie nodes and consults it before pathdb. No effect when witnesses are off.

Review-sensitive properties

• The head advances before the state root is verified. ValidateStateCheap gates insertion; the full root check happens asynchronously in the SRC goroutine. A mismatch fires chain/imports/pipelined/root_mismatch (a hard alarm that must stay 0) and errors the pipeline. Sync compensates: hasPendingPipelinedHeadState keeps the node in full-sync while a head-state commit is in flight.
• WIT protocol behavior: WitnessReadyEvent now push-announces witness availability to stateless peers (replacing a 10s poll); GetWitness serving waits for in-flight SRC (bounded, with a header-existence DoS guard) and reads uncached so peer traffic can't evict import-critical cache entries.
• Witness completeness: the SRC uses a trie-only reader (NewTrieOnly) so every read walks the MPT and proof paths land in the witness; parity tests assert proof-node-set equality and stateless replay (ProcessBlockWithWitnesses) across all configurations. PropagateReadsTo in checkAndCommitSpan captures the validator-contract proof nodes read via a copied statedb; EIP-2935 accounts are touched into the read set.
• Lifecycle: one SRC goroutine + one auto-collection goroutine per pipelined block, registered on bc.wg; pending SRC is flushed on reorg, gap, or error.
• No database schema change (BlockChainVersion unchanged); nothing forces a resync.

Production-side (miner) pipelining: landed but disabled

miner/pipeline.go contains the speculative-sealing counterpart (FlatDiff extraction after FinalizeForPipeline, background SRC, speculative N+1 build, async chain write). It is hard-disabled: isPipelineEligible returns false unconditionally and no config exposes it (the worker/pipeline/enabled gauge is always 0). Pre-Rio seal-recovery interaction makes speculative Prepare fail; re-enablement is future work and the gating logic is preserved in comments. Reviewers can treat the miner path as dormant code with test coverage.

Config

[pipeline]
enable-import-src = false   # master gate (default: disabled)
import-src-logs   = false   # verbose pipeline logging
warm-snapshot     = true    # witness-producing nodes only; leave on

Notable negative results baked into the design (so nobody re-litigates them): the exec-side trie prefetcher and the speculative block prefetcher are load-bearing via shared-cache warming — disabling either regresses 25–75% — so neither is configurable (pipeline.exec-prefetch existed briefly on the feature branch and was removed).

Executed tests

• Parity suites (hash + path schemes, -race): pipelined vs sequential roots/hashes, witness proof-node-set parity + stateless replay, FlatDiff mutation/overlay suites, self-destruct integration, pathdb node-index unit tests (fork refcounting, deletion markers, definitive-miss semantics), tests/bor integration.
• Mainnet catch-up benchmark campaign (2026-07-10 → 2026-07-21): 12 instrumented legs covering the pipeline × witness matrix with per-leg lane analysis (exec / SRC / commit / overlap) and CPU+mutex profiling.
• RPC correctness under pipelined import: a deterministic window test (core/pipelined_window_test.go, SRC goroutine held open via test hook) pins the overlay/trie semantics of the "head advanced, root not yet committed" interval; an end-to-end battery (tests/bor/pipelined_rpc_test.go) drives 12 read methods against a live-syncing importer at pinned heights and latest, checks sync-time vs settled response identity, and verifies full per-height parity vs a non-pipelined BP including cryptographic account-proof verification. Handlers that need committed trie nodes (eth_getProof, debug_storageRangeAt) gate on WaitForPipelinedStateCommit instead of erroring transiently inside the window.
• Diffguard mutation testing (50% sampling): 89.9% overall kill rate, 93.6% on tier-1 logic.
• Pending before ready-for-review: 24h tip-following soak, kurtosis devnet e2e with reorgs, witness-sync devnet check.

Quality gates — declared deviations

Three CI gates fail for structural reasons; each is intentional and listed here rather than suppressed:

• Cognitive complexity / function size (diffguard, Quality metrics job): insertChainWithWitnesses, IntermediateRoot, getStateObject, and updateTrie exceed thresholds. All four are legacy hot-path giants that this PR extends in place; refactoring them is high-risk consensus-path churn that belongs in a dedicated cleanup, not a feature PR. New-code violations were extracted below thresholds (applyFlatMutationFast, runSRCCompute, FinalizeForPipeline, witness-collection loops deduped into addObjectWitness). nodeWalk is a rename of pre-existing upstream logic. The reported core -> core dependency cycle is a tool artifact (self-cycle).
• SonarCloud duplication (8.2% vs ≤3%): 941 of 1039 duplicated lines are test scaffolding (pipelined test variants deliberately share setup with their non-pipelined siblings so the comparison stays literal). Remaining production duplication was removed in this PR (addObjectWitness, commitSprintWork reuse); ValidateStateCheap intentionally mirrors ValidateState's shape.
• codecov/patch (46% vs 90% target): project coverage is up (+0.02%); the patch metric only counts unit-test instrumentation and misses the integration/e2e suites where most pipeline coverage lives (tests/bor, kurtosis). The 90% patch bar on a 12.7k-line PR spanning hot paths is not attainable without duplicating e2e coverage as unit tests.

Rollout notes

Backwards-compatible; off by default; no coordinated upgrade required. Not consensus-affecting: the pipeline computes the identical root on the identical commit path, one block later in wall-clock, and aborts on mismatch. Operator-facing changes when enabled: witness-ready latency trails the block by one SRC cycle (~210ms end-to-end vs ~143ms inline). Related: #2312 implements an alternative trie-node index on develop; this PR lands first and #2312 rebases.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[claude]

Code Review

Found 6 issues: 4 bugs and 2 security concerns.

Bugs

1. miner/worker.go:1117 — writeElapsed always measures ~0 (broken metric)
   writeElapsed is computed immediately after writeStart, before either write call executes. The original code had the write call between writeStart and writeElapsed. The writeBlockAndSetHeadTimer metric will always report approximately zero. Fix: move writeElapsed := time.Since(writeStart) to after the if/else block.
   

   bor/miner/worker.go

   Lines 1116 to 1123 in 07345ad

   	writeStart := time.Now()
   	writeElapsed := time.Since(writeStart)
   	if task.pipelined {
   	_, err = w.chain.WriteBlockAndSetHeadPipelined(block, receipts, logs, task.state, true, task.witnessBytes)
   	} else {
   	_, err = w.chain.WriteBlockAndSetHead(block, receipts, logs, task.state, true)
   	}
   	writeBlockAndSetHeadTimer.Update(writeElapsed)

2. miner/pipeline.go:380-383 — nil pointer dereference when chainHead == nil
   When chainHead is nil, the || short-circuits to true and enters the if-body, where chainHead.Number.Uint64() panics. This is in the block production path. Per security-common.md: No panics in consensus, sync, or block production paths. Fix: split the nil check from the number check into separate if-blocks.
   

   bor/miner/pipeline.go

   Lines 379 to 384 in 07345ad

   	chainHead := w.chain.CurrentBlock()
   	if chainHead == nil || chainHead.Number.Uint64() != blockNNum {
   	log.Error("Pipelined SRC: chain head mismatch after waiting", "expected", blockNNum,
   	"got", chainHead.Number.Uint64())
   	return
   	}

3. core/stateless/witness.go:101 — NewWitness no longer copies the context header (mutation risk)
   The old code did ctx := types.CopyHeader(context) and zeroed Root/ReceiptHash. The new code stores the caller pointer directly. In miner/worker.go:1196, the raw header pointer is passed — this header is later mutated in place. The Witness will silently see those mutations. See state-security.md threat model.
   

   bor/core/stateless/witness.go

   Lines 88 to 107 in 07345ad

   	func NewWitness(context *types.Header, chain HeaderReader) (*Witness, error) {
   	// When building witnesses, retrieve the parent header, which will *always*
   	// be included to act as a trustless pre-root hash container
   	var headers []*types.Header
   	if chain != nil {
   	parent := chain.GetHeader(context.ParentHash, context.Number.Uint64()-1)
   	if parent == nil {
   	return nil, errors.New("failed to retrieve parent header")
   	}
   	headers = append(headers, parent)
   	}
   	// Create the witness with a reconstructed gutted out block
   	return &Witness{
   	context: context,
   	Headers: headers,
   	Codes: make(map[string]struct{}),
   	State: make(map[string]struct{}),
   	chain: chain,
   	}, nil
   	}

4. miner/pipeline.go:124 — SetLastFlatDiff stores a provisional header hash that never matches
   env.header.Hash() lacks both Root and the seal signature. In PostExecutionStateAt, the comparison uses the sealed header — so FlatDiff overlay path is never taken. The txpool falls back to StateAt(header.Root) which may fail if SRC hasn't committed. Same issue at lines 521 and 783.
   

   bor/miner/pipeline.go

   Lines 123 to 125 in 07345ad

   	w.chain.SetLastFlatDiff(flatDiff, env.header.Hash())
   	// Note: this counts block N as "entering the pipeline." If Prepare() fails

Security Concerns

5. core/stateless/witness.go:56 — pre-state root validation anchored to untrusted witness data
   The old ValidateWitnessPreState took a caller-supplied expectedPreStateRoot. The new version fetches the parent using witness.context.ParentHash (from the witness itself). For peer-received witnesses, no call site verifies witness.context.ParentHash == block.ParentHash(). A malicious peer could bypass the pre-state root check. Per state-security.md and security-common.md peer-triggerable escalation.
   

   bor/core/stateless/witness.go

   Lines 49 to 71 in 07345ad

   	// Get the witness context header (the block this witness is for).
   	contextHeader := witness.Header()
   	if contextHeader == nil {
   	return fmt.Errorf("witness context header is nil")
   	}
   	// Get the parent block header from the chain.
   	parentHeader := headerReader.GetHeader(contextHeader.ParentHash, contextHeader.Number.Uint64()-1)
   	if parentHeader == nil {
   	return fmt.Errorf("parent block header not found: parentHash=%x, parentNumber=%d",
   	contextHeader.ParentHash, contextHeader.Number.Uint64()-1)
   	}
   	// Get witness pre-state root (from first header which should be parent).
   	witnessPreStateRoot := witness.Root()
   	// Compare with actual parent block's state root.
   	if witnessPreStateRoot != parentHeader.Root {
   	return fmt.Errorf("witness pre-state root mismatch: witness=%x, parent=%x, blockNumber=%d",
   	witnessPreStateRoot, parentHeader.Root, contextHeader.Number.Uint64())
   	}
   	return nil

6. core/blockchain.go:4402 — SpawnSRCGoroutine uses raw go func() without panic recovery
   The old code used bc.wg.Go(func() { ... }) for lifecycle-safe goroutine management. The new code uses bc.wg.Add(1) + raw go func(). If the goroutine panics, the process crashes without graceful shutdown. Per security-common.md: No panics in block production paths.
   

   bor/core/blockchain.go

   Lines 4399 to 4410 in 07345ad

   	pending.wg.Add(1)
   	bc.wg.Add(1)
   	go func() {
   	defer bc.wg.Done()
   	defer pending.wg.Done()
   	tmpDB, err := state.New(parentRoot, bc.statedb)
   	if err != nil {
   	log.Error("Pipelined SRC: failed to open tmpDB", "parentRoot", parentRoot, "err", err)
   	pending.err = err
   	return

[claude]

Code Review

Found 5 issues in miner/worker.go and miner/pipeline.go. Checked for bugs and CLAUDE.md compliance.

---

1. Bug: writeElapsed always ~0ns (miner/worker.go L1116-L1123)

writeElapsed := time.Since(writeStart) is computed immediately after writeStart := time.Now(), before either WriteBlockAndSetHeadPipelined or WriteBlockAndSetHead executes. writeBlockAndSetHeadTimer always records ~0, and workerMgaspsTimer (line 1148) reports inflated MGas/s. Fix: move writeElapsed := time.Since(writeStart) to after the if/else block.

---

2. Bug: nil pointer dereference (miner/pipeline.go L379-L384)

When chainHead is nil, the || short-circuits into the if-body, but chainHead.Number.Uint64() in log.Error dereferences nil and panics. Per CLAUDE.md: No panics in consensus, sync, or block production paths. Fix: split into two if-checks.

---

3. Bug: unchecked type assertion (miner/pipeline.go L335-L341)

borEngine, _ := w.engine.(*bor.Bor) discards the ok boolean. If w.engine is not *bor.Bor, borEngine is nil and borEngine.AssembleBlock(...) panics. The same assertion at line 96 correctly checks ok. Fix: check ok and return early.

---

4. Bug: goroutine leak on 5 return paths (miner/pipeline.go L293-L345)

initialFillDone channel (line 293) goroutine is not drained on return paths at lines 345, 357, 371, 373, 383. Only WaitForSRC error (line 331) and happy path (line 390) drain it. Fix: defer drain after line 293.

---

5. Bug: trie DB race after SpawnSRCGoroutine (miner/pipeline.go L206-L229)

SpawnSRCGoroutine called at line 213 launches a goroutine doing CommitWithUpdate. If StateAtWithFlatDiff fails (line 219) or GetHeader returns nil (line 228), fallbackToSequential does IntermediateRoot inline on the same parent root concurrently. The comments at lines 206-211 identify this as causing missing trie node / layer stale errors but only guard the Prepare() case. Fix: WaitForSRC() before fallbackToSequential, or move spawn after preconditions.

[codecov]

Codecov Report

❌ Patch coverage is 90.49415% with 252 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.04%. Comparing base (55cac19) to head (11636e8).
⚠️ Report is 4 commits behind head on develop.

Files with missing lines	Patch %	Lines
miner/pipeline.go	89.89%	66 Missing and 14 partials ⚠️
miner/worker.go	84.72%	35 Missing and 9 partials ⚠️
tests/bor/helper.go	63.15%	21 Missing and 7 partials ⚠️
eth/backend.go	59.37%	13 Missing ⚠️
consensus/bor/bor.go	89.58%	8 Missing and 2 partials ⚠️
core/state/trie_prefetcher.go	86.11%	6 Missing and 4 partials ⚠️
core/state/state_object.go	79.48%	6 Missing and 2 partials ⚠️
eth/api_debug.go	0.00%	8 Missing ⚠️
eth/sync.go	0.00%	7 Missing and 1 partial ⚠️
eth/handler.go	87.50%	6 Missing and 1 partial ⚠️
... and 10 more

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2180      +/-   ##
===========================================
+ Coverage    54.07%   55.04%   +0.96%     
===========================================
  Files          907      911       +4     
  Lines       162012   165339    +3327     
===========================================
+ Hits         87615    91018    +3403     
+ Misses       68984    68889      -95     
- Partials      5413     5432      +19     

Files with missing lines	Coverage Δ
core/block_validator.go	58.69% <100.00%> (+9.13%)	⬆️
core/blockchain.go	71.63% <ø> (+8.55%)	⬆️
core/blockchain_insert.go	78.50% <100.00%> (+1.27%)	⬆️
core/evm.go	93.67% <100.00%> (+19.65%)	⬆️
core/state/database.go	57.46% <100.00%> (+4.33%)	⬆️
core/state/warm_snapshot.go	100.00% <100.00%> (ø)
core/stateless/encoding.go	63.49% <ø> (ø)
core/stateless/witness.go	44.64% <100.00%> (+6.02%)	⬆️
core/txpool/blobpool/blobpool.go	54.87% <100.00%> (ø)
core/types/block.go	43.19% <ø> (ø)
... and 30 more

... and 25 files with indirect coverage changes

Files with missing lines	Coverage Δ
core/block_validator.go	58.69% <100.00%> (+9.13%)	⬆️
core/blockchain.go	71.63% <ø> (+8.55%)	⬆️
core/blockchain_insert.go	78.50% <100.00%> (+1.27%)	⬆️
core/evm.go	93.67% <100.00%> (+19.65%)	⬆️
core/state/database.go	57.46% <100.00%> (+4.33%)	⬆️
core/state/warm_snapshot.go	100.00% <100.00%> (ø)
core/stateless/encoding.go	63.49% <ø> (ø)
core/stateless/witness.go	44.64% <100.00%> (+6.02%)	⬆️
core/txpool/blobpool/blobpool.go	54.87% <100.00%> (ø)
core/types/block.go	43.19% <ø> (ø)
... and 30 more

... and 25 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[lucca30]

Additionally, the 500ms buffer previously reserved after transaction execution for SRC is removed when the pipeline is active. Transactions now get the full block time for inclusion since SRC runs in the background.

I am okay with the idea of removing the remaining 100ms.

We already reduced this buffer from 500ms to 100ms in v2.7.1, and from what we have seen so far, this remaining time looks small enough that removing it seems reasonable.

My main concern is not the removal of the 100ms itself. My concern is the cost of pipelining SRC with the next block production.

In other words: by doing SRC in parallel with block building, how much do we impact SRC time itself?

Do we expect SRC to remain roughly the same, or does it become meaningfully slower because it is now competing with the next block production? That is the part I would like to understand better.

I think this is basically a TPS vs finality question:

• on one side, we gain more block time for transaction inclusion, which is good for TPS
• on the other side, if SRC takes longer to complete, we may delay block completion, which could hurt finality

So I am supportive of the direction, but I think the key question is still:

How much TPS do we gain, and how much finality do we lose, if any, by making SRC fully pipelined with block production?

If the impact on SRC time is only slight, then the tradeoff is probably clearly worth it.

But if SRC time increases materially once it is pipelined with block production, then we should make that tradeoff explicit

[cffls]

Do we expect SRC to remain roughly the same, or does it become meaningfully slower because it is now competing with the next block production? That is the part I would like to understand better.

I think SRC will be roughly the same, because the time consuming part, trie nodes prefetching, is already running at the same time with tx execution today, and this PR doesn't change this behavior.

[claude]

Code Review

Found 3 issues in core/blockchain.go. Checked for bugs and CLAUDE.md compliance.

1. Missing ValidateReorg guard in pipelined import path (HIGH) — The non-pipelined path checks forker.ValidateReorg per-block before writing to prevent a race with newly-whitelisted Heimdall milestones/checkpoints. The pipelined path skips this check, allowing a block that conflicts with a freshly-anchored milestone to be accepted as chain head.

2. writeHeadBlock called without chainmu in auto-collection goroutine (HIGH) — On root mismatch, the recovery goroutine calls writeHeadBlock(parentBlock) which has a documented contract requiring the mu mutex to be held. The goroutine does not acquire it, creating a data race on chain head state.

3. flushPendingImportSRC error silently discarded (HIGH) — The function returns a meaningful error (SRC failure or root mismatch from a previously-committed block) but the error is discarded with _ in the block-error cleanup path. Every other call site handles this error.

[claude]

Inline Review Comments

Since inline comments could not be posted via the review API, here are the detailed findings with line references:

---

Issue 1 (HIGH): Missing ValidateReorg guard in pipelined import path — core/blockchain.go:3457

The non-pipelined path (lines 3618-3631) calls forker.ValidateReorg per-block immediately before writing to DB to prevent a race where a Heimdall milestone/checkpoint is whitelisted during block execution. The pipelined path skips this check entirely, calling writeBlockAndSetHeadPipelined without a preceding ValidateReorg. A block that conflicts with a freshly-anchored Heimdall milestone or checkpoint can be accepted as chain head in pipelined mode. The upfront check at line 3103 runs before execution begins and does not close this window.

Fix: Add the same per-block ValidateReorg guard before writeBlockAndSetHeadPipelined.

CLAUDE.md: blockchain-security.md and consensus-security.md

---

Issue 2 (HIGH): writeHeadBlock called without chainmu in auto-collection goroutine — core/blockchain.go:3507

writeHeadBlock has a documented contract at line 1733: "this function assumes that the mu mutex is held!". The auto-collection goroutine calls it without acquiring chainmu. After insertChainWithWitnesses returns and releases chainmu, this goroutine may still be running. If a root mismatch is detected, writeHeadBlock is called without the mutex — while another goroutine could concurrently acquire chainmu for a new InsertChain call. This is a data race on chain head state.

Fix: Acquire bc.chainmu.Lock() before calling writeHeadBlock in the error recovery path.

CLAUDE.md: security-common.md — "Shared mutable state protected by mutex or atomic operations"

---

Issue 3 (HIGH): flushPendingImportSRC error silently discarded — core/blockchain.go:3407

flushPendingImportSRC() returns a meaningful error (state root mismatch or SRC failure from a previously-committed block). Discarding it with _ means a block with a bad state root could persist undetected. Every other call site handles this error (line 1784, line 3328).

Fix: Replace _ = bc.flushPendingImportSRC() with if err := bc.flushPendingImportSRC(); err != nil { log.Error(...) } consistent with other call sites.

CLAUDE.md: security-common.md — "Error values checked — never discard errors with _ in security-sensitive paths"

[pratikspatil024]

Re: the review-level HasState()/rewindHead analysis from claude[bot] — confirming the ruled-out reasoning is correct: pendingImportHeadHash/pendingImportHeadStart and pendingImportSRC are process-local and zero-valued on a fresh process, so crash-recovery rewindHashHead/rewindPathHead at startup never see pipelined-pending state as available; on a live SetHead the grace window only covers a root whose SRC commit is already in flight and bounded. No code change needed.

[Copilot]

Pull request overview

Copilot reviewed 72 out of 73 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 74 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

core/stateless/witness.go:76

• contextHeader.Number.Uint64()-1 underflows when the witness context header is block 0, causing a parent lookup at MaxUint64 (and misleading error messages). Add an explicit Number==0 guard and compute parentNum once for both lookup and error reporting.

This issue also appears on line 109 of the same file.

	parentHeader := headerReader.GetHeader(contextHeader.ParentHash, contextHeader.Number.Uint64()-1)
	if parentHeader == nil {
		return fmt.Errorf("parent block header not found: parentHash=%x, parentNumber=%d",
			contextHeader.ParentHash, contextHeader.Number.Uint64()-1)
	}

core/stateless/witness.go:113

• In NewWitness, context.Number.Uint64()-1 can underflow for block 0 and will also panic if context/context.Number is nil (the latter can occur if callers pass an empty header while chain != nil). Add validation and use a computed parentNum for both the lookup and error path.

		parent := chain.GetHeader(context.ParentHash, context.Number.Uint64()-1)
		if parent == nil {
			return nil, errors.New("failed to retrieve parent header")
		}
		headers = append(headers, parent)

[Copilot]

Pull request overview

Copilot reviewed 74 out of 75 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

core/stateless/witness.go:72

• ValidateWitnessPreState dereferences expectedBlock.Number and contextHeader.Number without nil/zero guards. Since this is an exported function, a caller passing an incomplete header (Number == nil) or a genesis/zero-number context will panic or underflow in the parent lookup (Number-1). Add defensive checks and return a descriptive error instead of panicking.

	// Verify the witness is for the expected block — a malicious peer could
	// craft a witness with a different ParentHash to bypass the pre-state check.
	if expectedBlock != nil {
		if contextHeader.ParentHash != expectedBlock.ParentHash {
			return fmt.Errorf("witness ParentHash mismatch: witness=%x, expected=%x, blockNumber=%d",
				contextHeader.ParentHash, expectedBlock.ParentHash, expectedBlock.Number.Uint64())
		}
		if contextHeader.Number.Uint64() != expectedBlock.Number.Uint64() {
			return fmt.Errorf("witness block number mismatch: witness=%d, expected=%d",
				contextHeader.Number.Uint64(), expectedBlock.Number.Uint64())
		}
	}

eth/handler.go:629

• witnessReadyCh is subscribed to an event.Feed, and Feed.Send blocks until all subscriber channels accept the value (see event/feed.go:71-72). With a buffer of 10, a burst of WitnessReadyEvent during fast catch-up can backpressure the SRC goroutine at bc.witnessReadyFeed.Send, potentially reducing import throughput. Consider using a larger buffer (similar to txChanSize) to avoid stalling the pipeline on transient handler/peer slowness.

[Copilot]

Pull request overview

Copilot reviewed 75 out of 76 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

eth/handler.go:629

• The witness-ready event subscription uses a channel buffer of 10. publishImportWitness emits witnessReadyFeed.Send(...) from the SRC auto-collection goroutine, and event.Feed.Send is synchronous; if this channel fills, it can backpressure that goroutine (delaying collectedCh close and potentially timing out WaitForPipelinedStateCommit/witness waits). Use a larger buffer consistent with other hot-path event channels to avoid stalling pipelined import under bursty witness production.
  tests/bor/pipelined_rpc_test.go:81
• This integration test creates two nodes backed by temporary datadirs but never removes those directories. Over many integration runs (or retries), this can leak disk space in CI runners. Since node.Node exposes DataDir(), add t.Cleanup to remove the temp dirs after the stacks are closed.
  core/state/database.go:207
• The new TrieOnlyReader helper delegates to newTrieReader, which can open either MPT or Verkle depending on the underlying triedb. The comment currently states it is "only the trie (MPT)" and that it is required for witness building, which is MPT-specific. Please adjust the comment so it matches the actual behavior and doesn’t mislead Verkle callers.

// TrieOnlyReader returns a state reader that uses only the trie (MPT), skipping
// flat/snapshot readers. This ensures all account and storage reads walk the trie,
// which is required for witness building — the witness captures trie nodes during
// the walk. Without this, flat readers short-circuit the trie and proof paths are
// never captured.

[Copilot]

Pull request overview

Copilot reviewed 75 out of 76 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 79 out of 80 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

eth/handler.go:627

• witnessReadyCh is subscribed to core.BlockChain.witnessReadyFeed. event.Feed.Send can block when a subscriber channel is full (slow subscribers are not dropped), so a buffer of 10 risks stalling the pipelined SRC collection path under high import throughput (or slow peer iteration), extending the “head advanced, witness/state not committed yet” window. Consider using a larger buffer to keep witness-ready announcements from backpressuring import/SRC.

[Copilot]

Pull request overview

Copilot reviewed 81 out of 82 changed files in this pull request and generated 1 comment.