fix(cicd,cmd,consensus/XDPoS,eth): fix fast sync by wgr523 · Pull Request #2272 · XinFinOrg/XDPoSChain

wgr523 · 2026-04-03T12:39:42Z

Proposed changes

Fix fast sync. I'll add a doc about how to do fast sync. Tested on private net and devnet.

Types of changes

What types of changes does your code introduce to XDC network?
Put an ✅ in the boxes that apply

Impacted Components

Which parts of the codebase does this PR touch?
Put an ✅ in the boxes that apply

Checklist

Put an ✅ in the boxes once you have confirmed below actions (or provide reasons on not doing so) that

This PR has sufficient test coverage (unit/integration test) OR I have provided reason in the PR description for not having test coverage
Tested on a private network from the genesis block and monitored the chain operating correctly for multiple epochs.
Provide an end-to-end test plan in the PR description on how to manually test it on the devnet/testnet.
Tested the backwards compatibility.
Tested with XDC nodes running this version co-exist with those running the previous version.
Relevant documentation has been updated as part of this PR
N/A

Add new CLI flags to configure a fixed pivot block for fast sync: - --fastsyncpivotnumber: Pivot block number (0 = use default calculation) - --fastsyncpivothash: Pivot block hash for verification Changes: - Add FastSyncPivotNumber and FastSyncPivotHash to ethconfig.Config - Add pivotNumber and pivotHash fields to Downloader struct - Add SetPivotBlock() method to configure pivot before sync - Use configured pivot in syncWithPeer instead of dynamic calculation - Prevent pivot block from moving during sync when configured - Verify pivot block header hash after state sync completes - Add state root verification after state sync completes This allows operators to sync from a specific trusted checkpoint block instead of relying on the dynamic pivot calculation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Changes: - Add pivotGapNumbers field to Downloader struct - Calculate gap pivot numbers in SetPivotBlock() - Sync gap pivot states in processFastSyncContent() before primary pivot

coderabbitai · 2026-04-03T12:39:54Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a4d00b5a-3191-46c2-9849-708f557a4b95

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fixfastsync-new

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

This PR aims to fix fast sync on XDPoSChain by making fast sync pivot selection configurable (number/hash/root), adding “gap pivot” state sync + snapshot generation, and adjusting consensus header verification behavior to better support fast-sync header insertion.

Changes:

Add fast-sync pivot configuration to ethconfig (TOML + CLI flags) and wire it into the downloader at node startup.
Extend the downloader to support a fixed pivot, optional pivot hash verification, gap-pivot state syncs, and snapshot generation.
Adjust XDPoS v1/v2 header verification and epoch-switch info lookup to support reduced verification modes used during header-chain validation.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
eth/ethconfig/config.go	Adds FastSyncPivot* fields to the eth configuration struct.
eth/ethconfig/gen_config.go	Updates TOML marshal/unmarshal for the new fast-sync pivot fields.
eth/downloader/statesync.go	Removes an outdated comment about fast sync usage.
eth/downloader/downloader.go	Implements configurable pivot/gap pivot logic and snapshot generation; changes fast-sync header verification constants/behavior.
eth/backend.go	Wires configured pivot settings into the downloader during backend initialization.
consensus/XDPoS/engines/engine_v2/verifyHeader.go	Adjusts verification flow to use header-provided validators/penalties when not full-verifying.
consensus/XDPoS/engines/engine_v2/utils.go	Updates getEpochSwitchInfo call sites for new signature.
consensus/XDPoS/engines/engine_v2/timeout.go	Updates getEpochSwitchInfo call sites for new signature.
consensus/XDPoS/engines/engine_v2/snapshot.go	Exports snapshot constructor/storage helpers (NewSnapshot/StoreSnapshot).
consensus/XDPoS/engines/engine_v2/snapshot_test.go	Updates tests to use exported snapshot helpers.
consensus/XDPoS/engines/engine_v2/epochSwitch.go	Refactors getEpochSwitchInfo to accept parent-header slices for VerifyHeaders optimization and softens snapshot failure handling.
consensus/XDPoS/engines/engine_v2/engine.go	Updates snapshot usage and verifyQC/getEpochSwitchInfo interactions for new signatures/exports.
consensus/XDPoS/engines/engine_v1/engine.go	Skips checkpoint signer checks when not doing full verification.
cmd/XDC/main.go	Registers new CLI flags for fast-sync pivot configuration.
cmd/utils/flags.go	Defines and applies new fast-sync pivot flags into ethconfig.
cicd/testnet/start.sh	Adds environment-driven fast-sync pivot args.
cicd/mainnet/start.sh	Adds environment-driven fast-sync pivot args.
cicd/local/start.sh	Adds environment-driven fast-sync pivot args.
cicd/devnet/start.sh	Adds environment-driven fast-sync pivot args.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-03T14:08:43Z

eth/downloader/downloader.go

+	fsHeaderCheckFrequency = 0               // Verification frequency of the downloaded headers during fast sync
 	fsHeaderSafetyNet      = 2048            // Number of headers to discard in case a chain violation is detected
-	fsHeaderForceVerify    = 24              // Number of headers to verify before and after the pivot to accept it
+	fsHeaderForceVerify    = 0               // Number of headers to verify before and after the pivot to accept it
 	fsHeaderContCheck      = 3 * time.Second // Time interval to check for header continuations during state download


Setting fsHeaderCheckFrequency/fsHeaderForceVerify to 0 disables all header verification in HeaderChain.ValidateHeaderChain during fast sync. This makes it possible to persist invalid headers/receipt-chain data because InsertReceiptChain does not re-run consensus header verification. Please keep non-zero verification (e.g., restore previous constants or ensure at least pivot-adjacent chunks are fully verified) to avoid accepting invalid chains.

eth/downloader/downloader.go

cmd/utils/flags.go

Copilot · 2026-04-03T14:08:44Z

eth/downloader/downloader.go

+		}
+	}
+	sort.Slice(ms, func(i, j int) bool {
+		return ms[i].Stake.Cmp(ms[j].Stake) >= 0


sort.Slice requires a strict weak ordering. Using Cmp(...) >= 0 returns true for equal stakes too, which violates the comparator contract and can lead to unstable/incorrect sorting. Use > 0 for descending order (and optionally add a deterministic tie-breaker, e.g., address bytes).

Suggested change

return ms[i].Stake.Cmp(ms[j].Stake) >= 0

cmp := ms[i].Stake.Cmp(ms[j].Stake)

if cmp != 0 {

return cmp > 0

}

return ms[i].Address.Hex() < ms[j].Address.Hex()

Copilot · 2026-04-03T14:08:45Z

eth/downloader/downloader.go

+	// Calculate all gap pivot numbers: N - N%Epoch - Gap  where x < N
+
+	baseGap := number - number%d.blockchain.Config().XDPoS.Epoch - d.blockchain.Config().XDPoS.Gap
+	d.pivotGapLock.Lock()
+	d.pivotGapNumbers = nil
+	for i := uint64(0); ; i++ {
+		gapNumber := baseGap + d.blockchain.Config().XDPoS.Epoch*i
+		if gapNumber >= number {
+			break
+		}
+		d.pivotGapNumbers = append(d.pivotGapNumbers, gapNumber)
+	}
+	if len(d.pivotGapNumbers) > 0 {
+		log.Info("SetPivotBlock calculated gap pivots", "primary", number, "gapCount", len(d.pivotGapNumbers), "gaps", d.pivotGapNumbers)
+	}
+	d.pivotGapLock.Unlock()


Downloader now supports configured pivot number/hash/root plus gap pivot state sync + snapshot generation, but downloader_test.go doesn’t exercise these code paths (SetPivotBlock, pivot hash mismatch handling, gap pivot syncing). Adding targeted tests would help prevent regressions in fast sync behavior and validate the new configuration semantics.

Suggested change

// Calculate all gap pivot numbers: N - N%Epoch - Gap where x < N

baseGap := number - number%d.blockchain.Config().XDPoS.Epoch - d.blockchain.Config().XDPoS.Gap

d.pivotGapLock.Lock()

d.pivotGapNumbers = nil

for i := uint64(0); ; i++ {

gapNumber := baseGap + d.blockchain.Config().XDPoS.Epoch*i

if gapNumber >= number {

break

}

d.pivotGapNumbers = append(d.pivotGapNumbers, gapNumber)

}

if len(d.pivotGapNumbers) > 0 {

log.Info("SetPivotBlock calculated gap pivots", "primary", number, "gapCount", len(d.pivotGapNumbers), "gaps", d.pivotGapNumbers)

}

d.pivotGapLock.Unlock()

// Calculate all gap pivot numbers: N - N%Epoch - Gap where gap pivot < N.

config := d.blockchain.Config().XDPoS

epoch := config.Epoch

gap := config.Gap

d.pivotGapLock.Lock()

defer d.pivotGapLock.Unlock()

d.pivotGapNumbers = nil

if epoch == 0 {

return

}

aligned := number - number%epoch

if aligned < gap {

return

}

baseGap := aligned - gap

for gapNumber := baseGap; gapNumber < number; {

d.pivotGapNumbers = append(d.pivotGapNumbers, gapNumber)

if gapNumber > ^uint64(0)-epoch {

break

}

gapNumber += epoch

}

if len(d.pivotGapNumbers) > 0 {

log.Info("SetPivotBlock calculated gap pivots", "primary", number, "gapCount", len(d.pivotGapNumbers), "gaps", d.pivotGapNumbers)

}

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

wgr523 and others added 20 commits March 31, 2026 21:51

feat: try to make full sync work. add log in syncState

c0f15e9

fix: when error getting snapshot, skip the error

23fcba6

chore: add fast sync args into docker entry start.sh

3724c25

style: more log about pivot

e6bd9b1

feat: add FASTSYNC_PIVOT_ROOT, remove unnecessary verify

144522d

feat: re-add verify header for block after pivot

0283f08

feat(downloader): sync multiple gap pivots during fast sync

7c90905

Changes: - Add pivotGapNumbers field to Downloader struct - Calculate gap pivot numbers in SetPivotBlock() - Sync gap pivot states in processFastSyncContent() before primary pivot

feat: move gap sync state after pivot sync state

3493c0d

feat: let processHeader wiat for state sync

1d56bf3

feat: add generateSnapshot in downloader for state sync

fbd8f9f

feat: generate snapshot after state sync

ba6eb2d

skip all header full verify during fast sync

e55af5f

chore: add fastsync args to devnet start.sh

1845dab

fix: statedb function, and better root choice in fast sync

f499084

feat: when fullVerify=false, skip checkSignersOnCheckpoint

5b3204b

fix: gen_config.go

d403c2b

style: clean code comment

8f0705a

feat: in fastsync make multiple headers feasible rather than one-by-one

d6618b3

feat: add fastsync args in start.sh

1f36fd3

wgr523 requested review from benjamin202410, gzliudan and wanwiset25 April 3, 2026 12:41

gzliudan requested review from AnilChinchawale, anunay-xin, Copilot and liam-lai April 3, 2026 14:01

Copilot started reviewing on behalf of gzliudan April 3, 2026 14:02 View session

Copilot AI reviewed Apr 3, 2026

View reviewed changes

gzliudan changed the title ~~Fix fast sync~~ fix(cicd,cmd,consensus/XDPoS,eth): fix fast sync Apr 3, 2026

wgr523 and others added 3 commits April 6, 2026 20:39

Update cmd/utils/flags.go or better check on flags

b3bd2fa

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix: use xdc_sort; better flags

cfd954c

test: add fast sync pivot gap tests

b04ac82

wgr523 force-pushed the fixfastsync-new branch from 62ad130 to b04ac82 Compare April 6, 2026 14:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(cicd,cmd,consensus/XDPoS,eth): fix fast sync#2272

fix(cicd,cmd,consensus/XDPoS,eth): fix fast sync#2272
wgr523 wants to merge 23 commits intodev-upgradefrom
fixfastsync-new

wgr523 commented Apr 3, 2026

Uh oh!

coderabbitai bot commented Apr 3, 2026 •

edited

Loading

Review skipped

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-		return ms[i].Stake.Cmp(ms[j].Stake) >= 0
+		cmp := ms[i].Stake.Cmp(ms[j].Stake)
+		if cmp != 0 {
+			return cmp > 0
+		}
+		return ms[i].Address.Hex() < ms[j].Address.Hex()

Conversation

wgr523 commented Apr 3, 2026

Proposed changes

Types of changes

Impacted Components

Checklist

Uh oh!

coderabbitai bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai bot commented Apr 3, 2026 •

edited

Loading