feat(core,cmd,eth,docs): handle chain config mismatch by cli flag

[gzliudan]

Proposed changes

Replace unconditional rewind-on-mismatch startup behavior with an explicit chain config mismatch policy exposed through --chain-config-mismatch-policy and ethconfig.Config.ChainConfigMismatchPolicy.

Behavior

Supported policies:

• exit (default): fail fast without mutating the database.
• rewind-and-update: rewind to compatErr.RewindTo and persist the resolved config.
• update-config-only: persist the resolved config without rewinding.
• ignore-mismatch: keep the in-memory config and skip database writes.

Writable opens preserve the selected recovery mode. Readonly opens reject policies that would require rewinds or writes.

Changes

• Thread the selected policy through CLI/config resolution and blockchain startup.
• Add validation and normalization for mismatch policy values.
• Update operator-facing error messages for readonly startup failures.
• Document the new startup behavior in the upgrade notes.

Types of changes

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

• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Changes that don't change source code or tests
• docs: Documentation only changes
• feat: A new feature
• fix: A bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• revert: Revert something
• style: Changes that do not affect the meaning of the code
• test: Adding missing tests or correcting existing tests

Impacted Components

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

• Consensus
• Account
• Network
• Geth
• Smart Contract
• External components
• Not sure (Please specify below)

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]

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: 2198e4c4-3b00-4b2f-91fd-126e3638836e

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

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[Copilot]

Pull request overview

This PR introduces an explicit operator-controlled startup policy for handling stored ChainConfig incompatibilities, replacing the previous unconditional “rewind and rewrite config” behavior with a CLI/TOML-configurable decision.

Changes:

• Add ChainConfigMismatchPolicy (TOML + --chain-config-mismatch-policy) with validated values and default exit.
• Thread the resolved policy through blockchain open paths and adjust readonly behavior to prevent any DB mutation.
• Update operator-facing error messages, docs, and tests to reflect the new startup semantics.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
core/chain_config_mismatch_policy.go	Defines mismatch policy enum + parsing/normalization/validation helpers.
core/chain_config_mismatch_policy_test.go	Adds unit tests for normalization and parsing behavior.
core/blockchain.go	Threads policy through open config and applies policy-specific actions on ConfigCompatError.
core/blockchain_test.go	Updates existing blockchain open tests and adds invalid-policy coverage.
cmd/utils/flags.go	Adds CLI flag, resolves policy from CLI/config, threads into MakeChain, and improves operator errors.
cmd/utils/flags_test.go	Updates tests for new error messages and adds tests for policy resolution precedence/validation.
cmd/XDC/main.go	Registers the new CLI flag on the XDC command.
cmd/XDC/chaincmd.go	Passes resolved policy from node config into MakeChain for chain commands.
cmd/XDC/genesis_startup_test.go	Updates startup tests to pass explicit policy where the old implicit rewind behavior is required.
eth/ethconfig/config.go	Adds ChainConfigMismatchPolicy to ethconfig.Config and defaults it to exit.
eth/ethconfig/gen_config.go	Regenerates TOML marshal/unmarshal to include ChainConfigMismatchPolicy.
eth/backend.go	Passes the configured mismatch policy into core.NewBlockChainExResolved.
docs/upgrade.md	Documents the new mismatch policy behaviors and operator guidance.

Files not reviewed (1)

• eth/ethconfig/gen_config.go: Generated file

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

• eth/ethconfig/gen_config.go: Generated file