fix(platform-wallet): atomic multi-pool address reservations (receive + core BIP44 receive/change) + change-loop refactor

[Claudius-Maginificent]

Issue being fixed or feature implemented

HD address hand-out in platform-wallet suffers a two-state race. The upstream key-wallet AddressPool models only unused → used, and used flips only when a positive-balance sync proves the address received funds. So next_unused-style hand-out returns the same derivation index to two concurrent callers until a payment lands — address reuse (a privacy + accounting hazard).

This PR closes that race across every affected pool, generalizing the receive-address "Reserved" bridge to a multi-pool model:

• DIP-17 platform-payment receive (the original bridge).
• Core BIP-44 external (receive) — CW-001.
• Core BIP-44 internal (change) — CW-002, which additionally collides with the in-flight send_to_addresses change-address peeks tracked in pending_change.

It also extracts the duplicated change-address selection loop (Phase 3) and folds in validated review feedback.

Note

Stacked on #3585 (base branch fix/dpns-case-and-utxo-race-v3.1-dev). Review/merge after #3585. The receive-address + multi-pool reservation work that earlier drafts of #3585 carried was moved here.

PA-001 (asset-lock funding) — verified PHANTOM, no change

The suspected asset-lock funding-address reuse race does not exist. build_asset_lock_transaction holds wallet_manager.write().await across the entire build — the funding-address peek (peek_next_funding_address → next_address(.., false)) and the builder's used-flip (next_private_key → mark_index_used) run under the same write guard. Two concurrent builds are fully serialized: the second peeks only after the first has marked its index used. No funding-pool reservation is required; asset_lock/build.rs is untouched.

What was done?

Ephemeral "Reserved" bridge, generalized to multiple pools (platform_addresses/address_reserve.rs)

• A process-global, Mutex-guarded reservation table supplies the missing reserved layer between unused and used, consulted/updated atomically while the caller holds the wallet write lock.
• Keyed by (wallet_id, PoolKind, account), where PoolKind ∈ {PlatformReceive, CoreReceive, CoreChange} keeps each pool's index space disjoint.
• Reservations are in-memory only (never serialized — no feat(platform-wallet)!: add platform-wallet-storage crate (sqlite persister) #3625 schema impact) and reclaimed by a 5-minute TTL sweep.

CW-001 — core BIP-44 receive + change reservation (core/wallet.rs, platform_addresses/{mod,provider,wallet}.rs)

• next_receive_address_for_account / next_change_address_for_account (+ blocking twins, behind FFI core_wallet_next_receive_address / core_wallet_next_change_address) route through CoreWallet::reserve_bip44_address, reaching the external/internal pool via managed_account_type_mut().address_pools_mut()[0|1] and picking through the bridge.

CW-002 — change consults in-flight send reservations (core/wallet.rs)

• The change pool is shared with the broadcast loop, which peeks change addresses into OutpointReservations.pending_change before a send confirms. The standalone change hand-out now consults that snapshot and retries; each rejected index stays bridge-reserved, so it converges to the first address that is neither bridge-reserved nor pending. The receive path uses an empty avoid-set.

Phase 3 — readability refactor (core/change_address.rs new, core/broadcast.rs, identity/network/payments.rs)

• The duplicated change-address peek/retry/commit loop in send_to_addresses and send_payment is extracted into one core::change_address::pick_and_reserve_change_address helper. Behavior is identical (same pending_change consultation, peek/commit ordering, retry, error mapping, lock scope).

Review-feedback fixes

• SEC-001 — drive the TTL sweep: sweep_expired(RESERVATION_TTL) is now called from PlatformPaymentAddressProvider::sync_finished (the natural per-completed-sync seam), reclaiming abandoned hand-outs across all pool kinds. RESERVATION_TTL (300s) shared from address_reserve.
• SEC-002 — observe the leak: the success-but-unreconciled broadcast branch already warned via tracing; it now reports leaked_reservations (count of slots pinned until restart) via new reserved_count() guard accessors.
• PROJ-001 — cross-reference the two reservation models (core/reservations RAII drop-release ⇄ platform_addresses/address_reserve global TTL-sweep) in each module header.

Upstream migration

This whole bridge is a deliberate stopgap. The proper home for the tri-state unused → reserved → used lifecycle is inside key-wallet's AddressPool — tracked at dashpay/rust-dashcore#791. The next_unused_and_reserve signature is intentionally shaped so the eventual swap is a one-liner with no call-site changes.

How Has This Been Tested?

• cargo test -p platform-wallet --all-features: 219 lib tests pass, 0 failed, 3 ignored (the 3 are pre-existing #[ignore] heavy variants).
• Concurrency: the always-on 1k-task stress test concurrent_reserve_no_duplicates (+ a #[ignore]d 10k variant) proves distinct hand-outs under parallel load; concurrent_same_utxo_sends_resolve_via_reservation_set proves the loser short-circuits with NoSpendableInputs.
• New unit tests: distinct_pool_kinds_do_not_collide (pool-kind index-space disjointness), next_change_address_skips_pending_change_reservation (CW-002), plus the existing distinct/reserved-skip/release/TTL suite re-parameterized over PoolKind.
• Behavior-preservation for the refactor: send_to_addresses_* and broadcast_and_reconcile_* pass unchanged.
• cargo check -p platform-wallet-ffi and cargo check -p dash-sdk: rc=0. cargo clippy -p platform-wallet --all-features --tests: 0 warnings. cargo fmt --check: clean.
• Downstream e2e pins (pa_005 / pa_008b / id_002 / id_005 / al_001) live on test(platform-wallet): e2e framework + full test suite — triage pins, Found-*/PA-* guards, fail-closed persist, Stage-2 merge #3549 / test(platform-wallet): shielded (Orchard) e2e suite — spec + Wave H harness #3727.

Breaking Changes

None. No public API or serialized/persisted form changed; reservations are ephemeral (in-memory, rebuilt empty on restart).

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

---

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

[coderabbitai]

Important

Review skipped

Draft detected.

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: 88af1ba9-db52-4179-9a93-c9836ceb0fc7

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 fix/platform-wallet-address-reserve-bridge

---

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 and usage tips.}