backport: assumeutxo M3 — crash-safe background completion (bitcoin#25740, #27862, #28050, #27746)

[PastaPastaPasta]

Issue being fixed or feature implemented

M2 (#51) wired up dual-chainstate EvoDB roles but left two integration
items open: promoting snapshot markers to the legacy key at completion, and
an independent (non-shared-cache) comparison of background vs. snapshot
state before a background chainstate is allowed to complete and replace the
snapshot. Without crash-safe completion, a power loss mid-promotion can
destroy a valid, already-validated snapshot. This is milestone 3/7. The
execution plan and per-unit ledger (M3 section) are tracked outside the repo
in a private gist, not checked in: https://gist.github.com/PastaPastaPasta/aa52b1f89fb74a0566ba3b5e15afab6a

PR 3/7 in the stacked series — base is M2 (assumeutxo/m2-evodb-roles).

What was done?

• bitcoin#27862 (moved here from M1 since it depends on M3's
  SnapshotCompletionResult) and bitcoin#28050 — FAILURE_FATAL bypasses
  the reindex prompt in Dash's init else-if structure;
  FAILURE_INSUFFICIENT_DBCACHE intentionally absent until bitcoin#27596
  lands in M5.
• bitcoin#25740 — crash-safe background-validation completion. Round 1
  adversarial review found four issues: crash-unsafe promote-before-swap
  ordering (including missing fsync gaps), MN-list comparison that wasn't
  actually independent of the shared cache, a nullopt base-height skip that
  could mask on-disk corruption, and unsynced activation metadata — all
  fixed. Dash adaptation: crash-safe completion lifecycle (renames +
  DirectoryCommit before a synced, idempotent PromoteSnapshotMarkers;
  RecoverSnapshotCleanup state machine run at load); independent MN-list
  verification via a per-connect NORMAL-identity captured hash slot compared
  against the activation-recorded snapshot hash at completion (not read from
  shared cache). Both M2 integration TODOs (marker promotion, holistic
  base-state comparison) are discharged here.
• bitcoin#27746 (13 upstream commits) — per-chainstate candidate admission.
  Round 1 review found ResetBlockFailureFlags bypassed per-chainstate
  admission (background could admit non-base-path forks and starve the
  active set) and that InvalidateBlock's cache could reinsert
  ChainLock-conflicting candidates — both fixed, including a
  BLOCK_CONFLICT_CHAINLOCK exclusion in TryAddBlockIndexCandidate and a
  dual-chainstate regression test.

How Has This Been Tested?

• make check: exit 0, 0 failures.
• Functional subset: feature_init, feature_reindex, feature_pruning,
  feature_dip3_deterministicmns ×2, feature_llmq_signing ×2,
  feature_llmq_rotation, feature_llmq_chainlocks, feature_mnehf,
  feature_asset_locks, rpc_invalidateblock — all 12 passed.
• Lint: circular-dependencies and whitespace PASS; python lint deferred to CI.
• 2 review rounds each for assumeutxo: background validation completion bitcoin/bitcoin#25740 and Rework validation logic for assumeutxo bitcoin/bitcoin#27746; 1 round for validation: Stricter assumeutxo error handling when renaming chainstates bitcoin/bitcoin#27862/test: make assumeUTXO test capture the expected fatal error bitcoin/bitcoin#28050;
  milestone gate PASS on 2026-07-11.

Breaking Changes

None. Background validation completion is now fully wired (UTXO-hash +
MN-list-hash + EvoDB-marker checks, crash-safe promotion/cleanup with
load-time recovery) but is not yet reachable — loadtxoutset itself is
still unexposed until M5.

Checklist:

• I have performed a self-review of my own code
• I have added or updated relevant unit/integration/functional/e2e tests
• I have made corresponding changes to the documentation (docs rewrite lands in M7/B8)
• I have assigned this pull request to a milestone

[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 Plus

Run ID: 1c0946c2-20ba-42fd-a86b-4ee0a0e5ccfd

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 assumeutxo/m3-background-completion

---

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.}