feat(key-wallet): stamp retained transaction records with their in-block position

[QuantumExplorer]

Issue being fixed or feature implemented

Fixes #890. Retained TransactionRecords carried no in-block position: BlockInfo held only {height, block_hash, timestamp}, account.transactions() iterates in txid order, and the index visible during block processing was discarded. Downstream consumers that aggregate a wallet's retained provider special transactions (dashpay/platform#4120's masternode list) therefore cannot replay Core's same-block apply order — RebuildListFromBlock applies same-block provider updates in block.vtx order, so with two updates for one proTxHash in a single block, the winner per field must be the later-positioned one, not whichever txid sorts higher.

What was done?

• BlockInfo gains position: Option<u32> (serde(default); None for contexts built without the containing block — FFI-supplied contexts, legacy persisted records), a position() accessor, and a with_position builder. BlockInfo::new keeps its 3-arg signature, so existing call sites are untouched.
• process_block_for_wallets enumerates block.txdata and stamps each record's context with its index. Chainlock promotion (apply_chain_lock) already copies the whole BlockInfo, so the position survives InBlock → InChainLockedBlock.
• New test test_block_processing_stamps_in_block_position: a two-tx block yields records stamped positions 0 and 1.

How Has This Been Tested?

cargo test -p key-wallet -p key-wallet-manager -p key-wallet-ffi — 548 + 233 + FFI suites, 0 failures.

Breaking Changes

None — additive field with a defaulted deserialization and an unchanged constructor signature.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Corrected transaction processing so each transaction retains its position within the block.
  • Block-processed wallet events now report accurate transaction indexes for all transactions.
  • Preserved transaction position information across processing contexts and serialized data.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 34325e21-8618-4c20-a5b8-1979289b05e4

📥 Commits

Reviewing files that changed from the base of the PR and between 7221d86 and 4943dcd.

📒 Files selected for processing (3)

• key-wallet-manager/src/event_tests.rs
• key-wallet-manager/src/process_block.rs
• key-wallet/src/transaction_checking/transaction_context.rs

---

📝 Walkthrough

Walkthrough

Block processing now stamps each wallet-relevant transaction with its index in the block. BlockInfo retains this optional position through transaction context handling, and a new test verifies positions in emitted wallet records.

Changes

Block Position Tracking

Layer / File(s)	Summary
Position metadata contract key-wallet/src/transaction_checking/transaction_context.rs	BlockInfo adds an optional position field, initializes it, serializes it with a default, and exposes builder/accessor methods.
Indexed block processing and validation key-wallet-manager/src/process_block.rs, key-wallet-manager/src/event_tests.rs	Block transactions are processed with per-transaction contexts carrying their indexes, and emitted records are tested for matching positions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• key-wallet: retained TransactionRecord/BlockInfo carries no in-block position — same-block provider updates can't be ordered #890 — The change implements propagation of each transaction’s in-block position into BlockInfo.

Suggested reviewers: xdustinface, zocolini

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: stamping retained transaction records with their in-block position.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/in-block-position-retained-records

---

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

[QuantumExplorer]

Reviewed

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.32%. Comparing base (7221d86) to head (4943dcd).
⚠️ Report is 1 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #891      +/-   ##
==========================================
- Coverage   74.34%   74.32%   -0.02%     
==========================================
  Files         327      327              
  Lines       74771    74779       +8     
==========================================
- Hits        55591    55582       -9     
- Misses      19180    19197      +17     

Flag	Coverage Δ
core	77.29% <ø> (ø)
ffi	50.30% <ø> (-0.01%)	⬇️
rpc	20.00% <ø> (ø)
spv	90.87% <ø> (-0.10%)	⬇️
wallet	74.41% <100.00%> (+<0.01%)	⬆️

Files with missing lines	Coverage Δ
key-wallet-manager/src/process_block.rs	90.82% <ø> (ø)
...et/src/transaction_checking/transaction_context.rs	70.21% <100.00%> (+6.11%)	⬆️

... and 5 files with indirect coverage changes