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

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: 8a0183f2-f9f0-44ea-9f4c-454910fd161b

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

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 9 comments.

Comments suppressed due to low confidence (1)

eth/downloader/downloader.go:523

When a fixed pivot is configured, syncWithPeer does not validate that pivotNumber is <= the remote height. If pivotNumber is greater than the chain head, header fetching can terminate while d.committed stays 0, potentially stalling fast sync. Consider validating d.pivotNumber <= height (and also d.pivotNumber > 0) up front and returning a configuration error if it's out of range.

		if d.pivotNumber != 0 {
			// Use configured pivot block
			log.Info("Using configured pivot block", "number", d.pivotNumber)
			pivot = d.pivotNumber
			if pivot <= origin {
				origin = pivot - 1
			}
		} else if height <= uint64(fsMinFullBlocks) {
			origin = 0
		} else {
			pivot = height - uint64(fsMinFullBlocks)
			if pivot <= origin {

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

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

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

benjamin202410 · 2026-05-29T09:53:21Z

+		*/
+		// Retrieve the snapshot needed to verify this header and cache it
+		snap, err := x.snapshot(chain, number-1, header.ParentHash, parents, nil)
+		if err != nil {


add error log

benjamin202410 · 2026-05-29T09:53:28Z

+		err = x.checkSignersOnCheckpoint(chain, header, signers)
+		if err == nil {
+			return x.verifySeal(chain, header, parents, fullVerify)
+		}


add error log, you can put info or debug level since you already handled it

benjamin202410 · 2026-05-29T09:53:53Z

-		return x.verifySeal(chain, header, parents, fullVerify)
+		signers, err = x.getSignersFromContract(chain, header)
+		if err != nil {
+			return err


add error log

benjamin202410 · 2026-05-29T09:55:10Z

+		err = x.checkSignersOnCheckpoint(chain, header, signers)
+		if err == nil {
+			return x.verifySeal(chain, header, parents, fullVerify)
+		}


what if it is still err != nil?

benjamin202410 · 2026-05-29T10:03:34Z

-func (x *XDPoS_v2) getEpochSwitchInfo(chain consensus.ChainReader, header *types.Header, hash common.Hash) (*types.EpochSwitchInfo, error) {
+// headers is allow to be nil. if not nil, headers contain header (as last item) and its parents if any, which can be used to avoid
+// fetching from the database during recursive lookups (useful during VerifyHeaders).
+func (x *XDPoS_v2) getEpochSwitchInfo(chain consensus.ChainReader, headers []*types.Header, hash common.Hash) (*types.EpochSwitchInfo, error) {


need to discuss the headers []*types.Header input

anunay-xin · 2026-06-01T11:54:09Z

-			standbynodes = common.RemoveItemFromArray(standbynodes, penalties)
+		snap, err := x.getSnapshot(chain, h.Number.Uint64(), false)
+		if err != nil {
+			log.Warn("[getEpochSwitchInfo] Adaptor v2 getSnapshot has error, cannot get standbynodes", "err", err)


We have moved this from error to warn, we won't know if snapshot has error, is it expected behaviour?

anunay-xin · 2026-06-01T13:15:58Z

+	d.pivotGapNumbers = nil
+	for i := uint64(0); ; i++ {
+		gapNumber := baseGap + epoch*i
+		if gapNumber >= number {


pivot block is excluded from gap snapshot generation when it itself a gap block
Suppose pivot number is 1350, for i=1 gapnumber=1350 and number=1350 so pivotGapNumbers won't include 1350 as 1350>=1350, so snapshot won't exist for this
Please let me know if I am understanding this correctly

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

Comment thread eth/downloader/downloader.go

Comment thread eth/downloader/downloader.go

Comment thread eth/downloader/downloader.go

Comment thread cmd/utils/flags.go Outdated

Comment thread eth/downloader/downloader.go

Comment thread eth/downloader/downloader.go

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

wgr523 force-pushed the fixfastsync-new branch 2 times, most recently from b04ac82 to 7b85d50 Compare April 12, 2026 15:18

benjamin202410 reviewed Apr 13, 2026

View reviewed changes

Comment thread cicd/devnet/start.sh Outdated

benjamin202410 reviewed Apr 13, 2026

View reviewed changes

Comment thread eth/downloader/downloader.go Outdated

gzliudan requested a review from Copilot April 19, 2026 14:53

Copilot started reviewing on behalf of gzliudan April 19, 2026 14:53 View session

Copilot AI reviewed Apr 19, 2026

View reviewed changes

wgr523 force-pushed the fixfastsync-new branch from 1ba23e0 to b496cd2 Compare May 27, 2026 14:58

wgr523 and others added 11 commits May 29, 2026 00:16

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

c5c0950

fix: when error getting snapshot, skip the error

73e04a4

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

446ba17

style: more log about pivot

6cc2043

feat: add FASTSYNC_PIVOT_ROOT, remove unnecessary verify

6aa00e2

feat: re-add verify header for block after pivot

2206e0f

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

0e306cb

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

c48be7b

feat: let processHeader wiat for state sync

182db43

feat: add generateSnapshot in downloader for state sync

c23c181

wgr523 and others added 16 commits May 29, 2026 00:16

feat: generate snapshot after state sync

fd6a008

skip all header full verify during fast sync

5158ac4

chore: add fastsync args to devnet start.sh

d8a9883

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

52351b0

feat: when fullVerify=false, skip checkSignersOnCheckpoint

fdfeb9f

fix: gen_config.go

16f35fd

style: clean code comment

06dafce

feat: add fastsync args in start.sh

0f21ff8

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

1c1f905

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

fix: use xdc_sort; better flags

57ca2c9

test: add fast sync pivot gap tests

be33591

chore: require all three fastsync pivot params together in cicd start.sh

47611b7

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

4010320

fix: if configured pivot <= origin, start at origin. fix comment

25123fa

fix: fix by PR comment

3bd1aca

fix: validate fastsync pivot flags strictly

a6da06f

wgr523 force-pushed the fixfastsync-new branch from b496cd2 to a6da06f Compare May 28, 2026 17:23

benjamin202410 reviewed May 29, 2026

View reviewed changes

Comment thread eth/downloader/downloader.go

benjamin202410 reviewed May 29, 2026

View reviewed changes

Comment thread eth/downloader/downloader.go Outdated

wgr523 and others added 2 commits May 29, 2026 22:22

style: better v1 verifyheader style, better start.sh

379902e

update log title

e468601

benjamin202410 approved these changes May 29, 2026

View reviewed changes

anunay-xin reviewed Jun 1, 2026

View reviewed changes

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benjamin202410 May 29, 2026

Choose a reason for hiding this comment

Uh oh!

benjamin202410 May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjamin202410 May 29, 2026

Choose a reason for hiding this comment

Uh oh!

benjamin202410 May 29, 2026

Choose a reason for hiding this comment

Uh oh!

wgr523 May 29, 2026

Choose a reason for hiding this comment

Uh oh!

benjamin202410 May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

anunay-xin Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

anunay-xin Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

coderabbitai Bot commented Apr 3, 2026 •

edited

Loading

benjamin202410 May 29, 2026 •

edited

Loading