[Claudius-Maginificent]

Basic explanation

TL;DR: Keep one complete wallet history entry when an old withdrawal is delivered again after upgrading.

Value: Upgrades retain one complete history entry and the amounts of transactions spending its outputs.

Risks: Looking up an adopted old identifier returns the current identifier. Exceptional withdrawal lookups scan wallet-scoped evidence; no performance benchmark is claimed.

User story

As a wallet user, I want previously recorded withdrawals and their spending history to retain their amounts and details after an upgrade.

Scenario

Base flow

A wallet upgrades an old database and later receives the same withdrawal again.

Actual behavior

The changed transaction identifier can produce two history entries, split ownership details, and leave an older spending entry's amount unrepaired.

Expected behavior

History retains one complete entry and the correct spending amounts. Signed transaction bytes remain unchanged.

Detailed discussion

Issue being fixed or feature implemented

Follow-up to #5150, specifically canonical redelivery of historical AssetUnlock records. Addresses 5150-11, including the duplicate report. This separate PR is stacked on #5781, the bulk-validation prerequisite on #5150. Shared replay in #5220 remains a later integration gate.

What was done?

• Resolve validated legacy AssetUnlock identities to an active canonical history record. Reconcile existing duplicate records through the same resolver and preserve known ownership details.
• Keep old physical rows as metadata anchors; use the existing immutable original-record archive only as verified identity evidence. No schema migration, financial outpoint/claim rewrite, or raw signed-prevout change.
• Repair consumers reached through either historical identity, including when their coin was already stored before the identity relationship became known.
• Preserve compatible active same-transaction context through the existing wallet helper; reject conflicting confirmed contexts atomically. Archives never grant ownership/finality or resurrect removed history.
• Keep exact physical backend readers separate from public history projection, and retain Strict/Recovery column-drift behavior and diagnostic counts.

The normal exact-canonical upsert policy is unchanged. No FFI ABI, binding or dependency-pin changes. Exceptional AssetUnlock lookups scan wallet-scoped history/archive evidence; no performance benchmark is claimed. A later #5220 integration must validate physical-record replay against these aliases; it is not part of this PR.

How Has This Been Tested?

• 169 selected wallet/storage tests passed, including 21 new cases for migration→redelivery, pre-existing duplicates, multiple quorum instances, accounting repair, context promotion/conflict, rollback/retry, wallet isolation, immutable archives and Recovery behavior.
• New literal fixture from the actual historical writer, with a real known-key P2PKH SIGHASH_ALL consumer. Signature and raw bytes survive migration/redelivery; rewriting its prevout invalidates the signature. This does not claim funding quorum validity or chain inclusion.
• Scoped all-feature/all-target CI Clippy for platform-wallet and platform-wallet-storage passed with --no-deps -D warnings; format check passed.
• After the clean merge of fix(wallet-storage): validate transaction bodies during bulk history load #5781, 40 unique integration tests passed on the final tree: 21 alias cases, 11 identity/legacy/drift cases and eight accounting cases. Wallet/storage CI Clippy and formatting also passed on that tree.
• Independent review passed the original feature and final parent integration at 2876cf47.
• Exact source provenance and verification evidence. No full workspace or network test claim.

Breaking Changes

After canonical adoption, public history lookup by a legacy alias returns the canonical record and identifier. Legacy-only records keep their old identifiers until adoption. WalletStorageError gains HistoryAliasContextConflict; it is already non-exhaustive, so downstream matches already require a wildcard. No database-schema or FFI-ABI break.

Checklist:

• I have performed a self-review of my own code
• My Rust changes follow the coding conventions
• I have commented my code, particularly in hard-to-understand areas
• I have added relevant unit/integration tests
• I have added "!" to the title and described the API behavior changes
• I have documented the resolver and public helper contracts in code
• Independent review of the final parent integration completed
• I have assigned this pull request to a milestone

No GroveDB structure, system contract schema, or shipped consensus generation changes.

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[thepastaclaw]

🕓 Review not started yet because this PR is a draft.

• Request normal review — click when the PR is ready for review.
• Request priority review — click to move this review to the front of the queue.

Commit 268a84f. Normal review starts when eligible; priority review starts as soon as a slot is available.