feat(kotlin-sdk): split build/broadcast with reservation release for BIP70-style deferred submission

[bfoss765]

Splits transaction build from broadcast for BIP70-style deferred submission: a signed-payment registry with reservation release, a deferred-payment token bounded to the reservation's lifetime, native code 27 for stale reservation tokens, token sweeping only when the final wallet write wins, and routing of deferred builds through the atomic finalize-and-register path — across rs-platform-wallet, platform-wallet-ffi, rs-unified-sdk-jni, and the Kotlin SDK surface.

Re-opens #4090 which was auto-closed when the #3999 base branch was deleted; rebased onto v4.1-dev. All seven original commits replayed cleanly — no hunks needed to be dropped as already-absorbed.

Verified: cargo test -p platform-wallet -p platform-wallet-ffi -p rs-unified-sdk-jni all pass (504 / 229 / 10); :sdk:assembleRelease + sdk unit tests pass.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added support for deferred signed payments, enabling transactions to be built and signed before later broadcast or release.
  • Added payment details including transaction ID, raw transaction data, fees, and reservation tokens.
  • Added idempotent reservation release for abandoned payments.
  • Added typed reservation and wallet-mismatch errors across supported SDKs.
• Bug Fixes
  • Improved cleanup when wallets close while deferred payments remain active.
  • Prevented reservations from being used with the wrong wallet, after expiration, or more than once.

---

Why the token registry instead of the V2 handle surface

The deferred BIP70/BIP270 flow uses the reservation-token registry rather than the V2 finalized-transaction handle for two concrete reasons. First, ownership and cleanup: the token is wrapped in an owning, AutoCloseable Kotlin object with a GC/Cleaner backstop, so a payment that is signed but then abandoned — the merchant server never acks, the user backs out, or the coroutine is cancelled after the native registration returned — always releases its funding reservation, for free, without the caller having to remember to abandon a handle. Second, the token path carries a lifetime bound the V2 handle does not: it stamps each token with the reservation's own pre-signing height and refuses to act once that reservation could have aged into key-wallet's TTL sweep, so a slow external signer can never let a stale token spend against an outpoint the wallet already swept and re-selected. A pinned V2 CoreWallet handle has no such age guard and would keep the old wallet actionable indefinitely. Both paths now share one wallet-generation identity and one teardown policy, so the V2 surface stays correct for the immediate send it was built for while the deferred flow gets the GC-safe, age-bounded ownership it needs. A follow-up adds the age guard to the V2 handle path itself (it becomes live the moment iOS does deferred sends).

Review-response summary (2026-07-21)

All five lifetime findings addressed as merge blockers, one commit each, with regression tests:

1. Destroy vs teardown: final-alias platform_wallet_destroy releases the generation's reservations against the still-live wallet; actual generation removal drops tokens and V2 handles — token cleanup is now tied to wallet-generation removal.
2. Height carry: the pre-signing reservation height travels on SignedCoreTransaction and register uses it — no post-signing resample; boundary test pins the TTL margin.
3. One generation identity: CoreWallet::is_same_generation (per-generation identity) is checked by BOTH the V2-handle and registry-token paths, with one teardown policy.
4. Cancellation-safe ownership: SignedCoreTransaction is an owning AutoCloseable with a NativeCleaner backstop; round-2 adds object-owning broadcastSigned/releaseReservation overloads that hold the object reachable across the native call and disarm the backstop on consumption (the bare-token forms remain but document the reachability requirement).
5. Validate-under-lock: broadcast peeks and consumes atomically under one lock hold (network I/O outside the lock); a wrong-wallet caller leaves the owner's token untouched, pinned by test.

Also per review: the dead core_wallet_signed_payment_register four-layer chain is deleted; the single stale-token code is split into typed siblings 27 ErrorStaleReservationToken / 28 ErrorReservationTokenConsumed / 29 ErrorReservationWalletMismatch (code 26 is not used by this PR — upstream now owns it as ErrorTransactionBroadcastRejected; both the Kotlin and Swift enums on this branch map 27/28/29 explicitly); the stale buildSignedPayment KDoc is fixed.

Error-code allocation note. These 27 / 28 / 29 allocations are being reconciled repo-wide in the error-code registry PR #4261. That registry records that ErrorReservationWalletMismatch = 29 on this branch currently collides with ErrorAssetLockInsufficientFunds = 29 on the asset-lock PR #4184, and that code 30 is free after #4184's re-scope (the variant previously reserved at 30 is not defined anywhere). The resolution of record is that #4184 keeps 29 and this PR moves its mismatch code to 30; that renumber has not yet landed on this head.

Local test evidence (fork PRs skip the Rust CI suite): platform-wallet --lib 508 passed, platform-wallet-ffi --lib 197 passed, clippy/fmt clean, Kotlin :sdk:testDebugUnitTest green.

[coderabbitai]

Warning

Review limit reached

@bfoss765, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 37 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0f2f7701-3eb1-4b33-a7d3-37e7b2f345da

📥 Commits

Reviewing files that changed from the base of the PR and between b5023dc and 8813e98.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (12)

• Cargo.toml
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/WalletManagerNative.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedPlatformWallet.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt
• packages/rs-platform-wallet-ffi/src/core_wallet/signed_payment.rs
• packages/rs-platform-wallet-ffi/src/error.rs
• packages/rs-platform-wallet-ffi/src/manager.rs
• packages/rs-platform-wallet/src/manager/wallet_lifecycle.rs
• packages/rs-platform-wallet/src/wallet/platform_wallet.rs
• packages/rs-unified-sdk-jni/src/wallet_manager.rs
• packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift

📝 Walkthrough

Walkthrough

Adds deferred Core signed-payment flows across the Rust wallet, FFI, JNI, Kotlin SDK, and Swift SDK. Payments can be built, reserved, broadcast, or released with generation-bound reservation tokens and typed errors.

Changes

Deferred signed payment lifecycle

Layer / File(s)	Summary
Wallet generation and reservation registry packages/rs-platform-wallet/src/wallet/core/*, packages/rs-platform-wallet/src/wallet/signed_payment_registry.rs, packages/rs-platform-wallet/src/manager/*	Adds generation-bound reservations, atomic registration, broadcast, release, expiry handling, teardown synchronization, and wallet recreation checks.
Native FFI lifecycle packages/rs-platform-wallet-ffi/src/core_wallet/*, packages/rs-platform-wallet-ffi/src/manager.rs, packages/rs-platform-wallet-ffi/src/error.rs, packages/rs-platform-wallet-ffi/src/wallet.rs	Adds deferred finalization, token broadcast and release, generation validation, error codes, handle cleanup, and lifecycle tests.
JNI and Kotlin API packages/rs-unified-sdk-jni/src/wallet_manager.rs, packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/*, packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/*	Adds signed-payment construction, ownership cleanup, broadcast and release operations, native bindings, typed errors, and JVM tests.
Swift and workspace support packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift, packages/rs-platform-wallet/src/test_support.rs, Cargo.toml	Maps reservation errors in Swift, adds wallet test fixtures, and updates Rust dependency sources.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant KotlinSDK
  participant JNI
  participant NativeFFI
  participant SignedPaymentRegistry
  participant CoreWallet
  KotlinSDK->>JNI: finalize signed payment
  JNI->>NativeFFI: fund, reserve, sign, and register
  NativeFFI->>SignedPaymentRegistry: store payment and token
  KotlinSDK->>JNI: broadcast or release token
  JNI->>NativeFFI: execute token operation
  NativeFFI->>SignedPaymentRegistry: broadcast or release reservation
  SignedPaymentRegistry->>CoreWallet: update reservation state

Loading

Possibly related issues

• Unify the two signed-payment concepts (build_signed_payment ↔ reservation-token finalize) #4263: Covers the reservation-token signed-payment lifecycle implemented by this change.
• [kotlin-sdk] Split build/broadcast with reservation release for BIP70-style deferred submission #4089: Covers the deferred build, broadcast, and release API implemented by this change.

Possibly related PRs

• dashpay/platform#4247: Adds related Kotlin/FFI signed-payment construction extended by this change.
• dashpay/platform#4264: Adds related typed DashSdkError.PlatformWallet mappings and tests.

Suggested reviewers: lklimek, llbartekll, quantumexplorer, shumkov, 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 Kotlin SDK change: separating payment construction and broadcasting with reservation release for deferred submission.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 💡 1

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch port/v4.1/split-build-broadcast

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

[thepastaclaw]

🕓 Ready for review — 2 ahead in queue (commit 8813e98)
Queue position: 3/16 · 2 reviews active
ETA: start ~04:03 UTC · complete ~04:19 UTC (median 16m across 30 recent reviews; 2 slots)
Queued 4h 16m ago · Last checked: 2026-08-04 03:40 UTC

[shumkov]

The core design is right (atomic finalize-and-register closes the double-selection race; reservation lifecycle is leak-free and the test matrix is strong). But two structural asks before merge:

• core_wallet_signed_payment_register → coreWalletRegisterSignedPayment → WalletManagerNative → ManagedCoreWallet.registerSignedPayment is a dead four-layer chain with zero callers after the finalize routing — and it's the unsafe variant (its age guard baselines at registration time, so the TTL protection is structurally defeated). Please delete it (or state explicitly why it stays), especially given refactor(sdk): dedup shared wallet code + remove dead FFI/JNI chains #4106 just removed this class of dead chains.
• The FFI now has two parallel deferred-tx lifecycles: the V2 handle surface Swift uses (core_wallet_tx_builder_finalize/broadcast/abandon_v2) and this token registry. There are real reasons to prefer the token here (V2's GC-backstop free releases the reservation; V2 has no age guard) — but they're stated nowhere, and V2 retains exactly the stale-release hazard this PR defends against. Please add the why-not-V2 rationale to the PR body and file a follow-up for the V2 age guard (it becomes live the moment iOS does deferred sends).

Minor: error code 26 conflates already-consumed (possibly paid!) / wallet-mismatch / aged-out — a payment UX can't tell "maybe paid" from "definitely not"; at minimum fix the doc, ideally split. Stale KDoc on buildSignedPayment still describes the pre-finalize shape. No Swift bindings for the new surface — fine, but track it.

[bfoss765]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedCoreWallet.kt (1)

58-75: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Deprecate or remove the legacy registerSignedPayment bridge. It has no Kotlin callers in this repo, so keeping it unmarked only leaves a dead ABI surface in place. If it must remain for compatibility, add @Deprecated and point docs to the atomic finalizeSignedPayment flow.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedCoreWallet.kt`
around lines 58 - 75, Deprecate the internal registerSignedPayment bridge
because it has no Kotlin callers and exposes a legacy ABI surface; if
compatibility requires retaining it, add `@Deprecated` and update its KDoc to
direct callers to the atomic finalizeSignedPayment flow, otherwise remove the
method.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedPlatformWallet.kt`:
- Around line 249-257: Update the KDoc paragraph for the method containing
finalizeSignedPayment to describe the atomic finalizeSignedPayment flow instead
of the deprecated new/addOutput*/setFunding/buildSigned sequence. State that
finalizeSignedPayment atomically selects, reserves, signs, and registers the
inputs, while preserving the existing explanation that broadcastSigned and
releaseReservation use the resulting token.

In `@packages/rs-platform-wallet-ffi/src/error.rs`:
- Around line 171-179: Update the documentation for ErrorStaleReservationToken
to explicitly include SignedPaymentError::StaleReservationToken alongside
StaleToken and WalletMismatch, and distinguish the unknown/consumed-token,
wrong-wallet-instance, and aged-out reservation cases with their respective host
semantics. Review the broadcast handler’s mapping and error details so hosts can
determine whether the reservation expired versus was consumed or belongs to
another wallet, without changing the shared error code.

---

Nitpick comments:
In
`@packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedCoreWallet.kt`:
- Around line 58-75: Deprecate the internal registerSignedPayment bridge because
it has no Kotlin callers and exposes a legacy ABI surface; if compatibility
requires retaining it, add `@Deprecated` and update its KDoc to direct callers to
the atomic finalizeSignedPayment flow, otherwise remove the method.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 038310fd-6fae-4081-961e-4fe849c78f63

📥 Commits

Reviewing files that changed from the base of the PR and between 8b466ab and 32cd702.

📒 Files selected for processing (19)

• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/WalletManagerNative.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/CoreTransactionBuilder.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedCoreWallet.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedPlatformWallet.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt
• packages/rs-platform-wallet-ffi/src/core_wallet/mod.rs
• packages/rs-platform-wallet-ffi/src/core_wallet/signed_payment.rs
• packages/rs-platform-wallet-ffi/src/core_wallet/transaction_builder.rs
• packages/rs-platform-wallet-ffi/src/error.rs
• packages/rs-platform-wallet-ffi/src/handle.rs
• packages/rs-platform-wallet-ffi/src/wallet.rs
• packages/rs-platform-wallet/src/lib.rs
• packages/rs-platform-wallet/src/test_support.rs
• packages/rs-platform-wallet/src/wallet/core/broadcast.rs
• packages/rs-platform-wallet/src/wallet/core/wallet.rs
• packages/rs-platform-wallet/src/wallet/mod.rs
• packages/rs-platform-wallet/src/wallet/signed_payment_registry.rs
• packages/rs-unified-sdk-jni/src/wallet_manager.rs

[shumkov]

Additional/strengthened lifetime findings after checking the existing threads:

1. Final-alias destruction consumes registry tokens without releasing live reservations. platform_wallet_destroy calls remove_entries_for_wallet, which only drops entries. Destroying the last wrapper alias does not necessarily remove the logical wallet from its manager, so the same wallet can be handed out again while those inputs remain reserved until TTL. Token cleanup should be tied to actual wallet-generation removal, or release while the original generation is still live.
2. Reservation age and token age start on opposite sides of external signing. The reservation height is captured before sign_tx(...).await, while register samples a fresh height afterward. A slow external signer can let the reservation be swept/reselected while the newly minted token still appears fresh. Carry the original reservation height in SignedCoreTransaction and register with it.
3. The V2 handle and registry-token paths have incompatible wallet-generation rules. V2 storage pins an old CoreWallet and validates only wallet ID, while registry tokens use manager identity plus wallet ID. After wallet recreation, an old V2 handle can act through the old manager while the new manager selects the same inputs. Both paths need one generation identity and one teardown policy.
4. Kotlin cancellation can orphan a token. buildSignedPayment returns a plain value through cancellable withContext(IO). If cancellation is observed after the blocking JNI registration returns, the token is discarded without a Cleaner/release path. Return an owning closeable object or make publication/release cancellation-safe.
5. Wrong-wallet broadcast consumes the token before checking its binding. SignedPaymentRegistry::broadcast removes first and validates second, so a mismatched caller destroys the original wallet's token and leaves its reservation until TTL. Validate under the lock, then atomically consume only a matching entry.

The existing age and dual-lifecycle comments point in the right direction; I would treat them as merge blockers rather than follow-ups because they can produce conflicting spends or stranded reservations.

[bfoss765]

All five lifetime findings are fixed as merge blockers and pushed, one commit each with regression tests: destroy releases the generation's reservations while teardown drops tokens and V2 handles; the pre-signing reservation height travels on SignedCoreTransaction into register; one generation identity across both the V2-handle and token paths; cancellation-safe ownership (an owning AutoCloseable with a Cleaner backstop, plus object-owning broadcastSigned/releaseReservation overloads that keep the payment reachable across the native call); and validate-then-consume under a single lock hold with network I/O outside it. The dead register chain is deleted, code 26 is split into typed 26/27/28 siblings (Kotlin-only host impact; Swift falls through safely), and the why-token-not-V2 rationale is in the PR body.

The V2 age guard you asked to file as a follow-up is implemented as a stacked PR: the V2 broadcast refuses at the same shared threshold off the same pre-signing height stamp (abandon works at any age), with exact-boundary tests on both account types.

[shumkov]

Consolidated re-verification (two independent passes). All five lifetime findings are genuinely fixed with discriminating regression tests, the dead register chain is fully deleted, the why-not-V2 rationale landed, and the error split into 26/27/28 (with txid carried on 27) is right. Two issues remain from the deeper pass:

1. Generation validation and reservation mutation are not atomic. The registry validates is_same_generation and then mutates after releasing its lock (core/wallet.rs:70-98,321-338, core/broadcast.rs:111-124, core/transaction.rs:257-268) — a same-ID wallet recreation between validation and cleanup can make old cleanup release the new generation's reservation. Bind the cleanup to a generation-local handle, or validate-and-mutate under a single manager lock, and cover same-ID recreation in the tests.

2. Deferred CoinJoin finalization can leak reservations until TTL. The FFI finalize path (transaction_builder.rs:170-293) reserves inputs, but registry rejection/abandon/free releases only when an account_type handle is present — CoinJoin-funded deferred payments left without one keep their funds reserved until the 24-block TTL. Retain a releasable account handle in the registry entry.

Minor: signed_payment.rs:40-45 still documents the pre-split error semantics (repeated-broadcast / re-created-wallet now yield 27/28, not 26), and the PR body should cite #4196 by number as the V2-side follow-up.

[shumkov]

Addendum: the missing Swift mappings for the new codes belong to this PR too, not only #4196 — PlatformWalletResult.swift:68-70 jumps from code 25 straight to 98, so 26/27/28 (introduced here) all surface as .errorUnknown on iOS. Fine to fix in either PR, but one of the two must carry it before the pair lands.

[bfoss765]

Both remaining blockers fixed (510 platform-wallet tests):

1. Atomic validate-and-mutate — reservation cleanup now re-validates the wallet generation (Arc::ptr_eq on the per-generation balance Arc) AND mutates the ReservationSet under a single manager read-lock hold. A same-id recreation needs the write lock and so can't interleave — provably atomic, covered by a new regression test that recreates between register and release and asserts the input stays reserved.
2. CoinJoin releasable handle — the registry entry now retains the full AccountTypePreference (incl. CoinJoin), so a rejected/abandoned CoinJoin-funded deferred payment releases immediately instead of waiting out the 24-block TTL (tested).

Swift now maps 26/27/28 to typed StaleReservationToken/ReservationTokenConsumed/ReservationWalletMismatch (exhaustive init(result:), message parity with Kotlin); the stale-broadcast doc is corrected. The V2 handle path is the follow-up in #4196.

One conscious scoping note: the immediate-send reject-release path (reservations.rs) shares the same theoretical generation window but a far narrower one — synchronous build→broadcast, no persisted token surviving a restart, CoinJoin not used for immediate sends — so this PR scopes the guard to the deferred registry + V2 handle paths your finding named. Happy to extend it there too if you'd prefer.

[shumkov]

Round-3 verification (two independent passes, reconciled): both previous blockers are genuinely fixed — the generation-safe release validates and mutates under one manager read-lock hold (and recreation requires the write lock, so no interleave), and CoinJoin entries now retain a releasable AccountTypePreference handle with a production-path regression test.

One new P1 (shared with #4196) — freshness and release are still two separate decisions:

• A reservation stamped at height 100 passes the age guard at 119; the broadcast await can span more than the 4-block margin; sync reaches 124, key-wallet's TTL sweeps the reservation and another build re-reserves the same outpoint; the rejected-broadcast cleanup then releases the new reservation by outpoint.
• Fix: read the current height, validate generation, and mutate as one guarded operation under the release lock; re-check freshness after the broadcast await before the Rejected-release; cover the signing-failure release path too. The existing tests prove endpoint states — add a barrier-controlled interleaving test that forces check → sweep → re-reserve → release.

Also before merge: rebase (branch is CONFLICTING with v4.1-dev), and please cite #4196 by number in the body as the V2-side sibling. Nit: new comments carry fix-round narration — provenance belongs in the PR description.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/rs-platform-wallet-ffi/src/core_wallet/transaction_builder.rs (1)

154-173: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the shared generation-gate block into one helper.

Lines 154-173 and lines 276-295 are the same gate: acquire generation_payment_guard, read is_current_generation, abandon on a dead generation, return NotFound. Only the message text differs. Both blocks must stay identical for the teardown invariant to hold on both the V2-handle path and the deferred-token path. A single helper removes the risk that a future change lands on one path only.

♻️ Suggested helper

/// Acquire this generation's payment gate and verify the generation is still
/// current. Returns `Err(result)` after reconciling the build's reservation
/// when the wallet was removed or re-created during signing.
fn enter_live_generation<'a>(
    wallet: &'a platform_wallet::PlatformWallet,
    finalized: &platform_wallet::SignedCoreTransaction,
    not_found_message: &str,
) -> Result<tokio::sync::RwLockReadGuard<'a, ()>, PlatformWalletFFIResult> {
    let (lifecycle, live) = runtime().block_on(async {
        let gate = wallet.core().generation_payment_guard().await;
        let live = wallet.core().is_current_generation().await;
        (gate, live)
    });
    if live {
        return Ok(lifecycle);
    }
    drop(lifecycle);
    runtime().block_on(wallet.core().abandon_transaction(finalized));
    Err(PlatformWalletFFIResult::err(
        PlatformWalletFFIResultCode::NotFound,
        not_found_message.to_string(),
    ))
}

Then each call site becomes:

-    let (_lifecycle, wallet_is_live) = runtime().block_on(async {
-        let gate = wallet.core().generation_payment_guard().await;
-        let live = wallet.core().is_current_generation().await;
-        (gate, live)
-    });
-    if !wallet_is_live {
-        runtime().block_on(wallet.core().abandon_transaction(&finalized));
-        return PlatformWalletFFIResult::err(
-            PlatformWalletFFIResultCode::NotFound,
-            "wallet is no longer registered in the manager (removed or re-created while the \
-             transaction was being signed); no transaction handle was published and its \
-             reservation was reconciled"
-                .to_string(),
-        );
-    }
+    let _lifecycle = match enter_live_generation(
+        &wallet,
+        &finalized,
+        "wallet is no longer registered in the manager (removed or re-created while the \
+         transaction was being signed); no transaction handle was published and its \
+         reservation was reconciled",
+    ) {
+        Ok(guard) => guard,
+        Err(result) => return result,
+    };

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/rs-platform-wallet-ffi/src/core_wallet/transaction_builder.rs`
around lines 154 - 173, Extract the duplicated generation gate and
dead-generation reconciliation from the V2-handle and deferred-token paths into
a shared enter_live_generation helper. Have it acquire and return the payment
guard for live generations, otherwise release the guard, abandon the finalized
transaction, and return NotFound using the caller-provided message. Replace both
existing blocks with this helper while preserving each path’s distinct error
message and guard lifetime.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/rs-platform-wallet-ffi/src/error.rs`:
- Around line 205-209: Record the reserved error-code assignments in a durable
registry by creating or updating ERROR_CODE_REGISTRY.md to map
ErrorAssetLockInsufficientFunds to 29 and ErrorReservationWalletMismatch to 30,
or remove the stale registry reference from the ErrorReservationWalletMismatch
documentation.

---

Nitpick comments:
In `@packages/rs-platform-wallet-ffi/src/core_wallet/transaction_builder.rs`:
- Around line 154-173: Extract the duplicated generation gate and
dead-generation reconciliation from the V2-handle and deferred-token paths into
a shared enter_live_generation helper. Have it acquire and return the payment
guard for live generations, otherwise release the guard, abandon the finalized
transaction, and return NotFound using the caller-provided message. Replace both
existing blocks with this helper while preserving each path’s distinct error
message and guard lifetime.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: fcb68778-c02c-41fa-9170-df3e834cd62f

📥 Commits

Reviewing files that changed from the base of the PR and between 0b0d5c7 and 6be6748.

📒 Files selected for processing (25)

• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/WalletManagerNative.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/wallet/SignedCoreTransactionTest.kt
• packages/rs-platform-wallet-ffi/src/core_wallet/broadcast.rs
• packages/rs-platform-wallet-ffi/src/core_wallet/signed_payment.rs
• packages/rs-platform-wallet-ffi/src/core_wallet/transaction_builder.rs
• packages/rs-platform-wallet-ffi/src/error.rs
• packages/rs-platform-wallet-ffi/src/handle.rs
• packages/rs-platform-wallet-ffi/src/manager.rs
• packages/rs-platform-wallet/src/manager/load.rs
• packages/rs-platform-wallet/src/manager/wallet_lifecycle.rs
• packages/rs-platform-wallet/src/test_support.rs
• packages/rs-platform-wallet/src/wallet/apply.rs
• packages/rs-platform-wallet/src/wallet/asset_lock/sync/recovery.rs
• packages/rs-platform-wallet/src/wallet/core/generation.rs
• packages/rs-platform-wallet/src/wallet/core/mod.rs
• packages/rs-platform-wallet/src/wallet/core/transaction.rs
• packages/rs-platform-wallet/src/wallet/core/wallet.rs
• packages/rs-platform-wallet/src/wallet/identity/network/contact_requests.rs
• packages/rs-platform-wallet/src/wallet/platform_wallet.rs
• packages/rs-platform-wallet/src/wallet/platform_wallet_traits.rs
• packages/rs-platform-wallet/src/wallet/signed_payment_registry.rs
• packages/rs-unified-sdk-jni/src/wallet_manager.rs
• packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift

💤 Files with no reviewable changes (1)

• packages/rs-platform-wallet-ffi/src/handle.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/wallet/SignedCoreTransactionTest.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/WalletManagerNative.kt

[bfoss765]

@thepastaclaw The 03:57 preliminary review is answered — requesting revalidation at the current head b5023dcbce.

• Blocker 1 (same-ID registration racing the two-map removal) is fixed in 6be67488 — the remover now carries the validated Arc<PlatformWallet> out of the retry loop and removes the public-map entry only while it still Arc::ptr_eq-matches that generation, with a deterministic rendezvous regression test (removal_leaves_a_generation_registered_during_it_intact) that fails 10/10 against the previous code. Full mechanism and design rationale in the comment above (2026-08-02 15:08).
• Blocker 2 (Cargo.toml fork pin) is externally gated: it clears when feat(key-wallet): owner-tagged reservations to close the broadcast-release TOCTOU (platform#4185) rust-dashcore#916 merges and the eight entries plus Cargo.lock are repinned to the Dash-owned revision. test(dapi-client): fix broken SimplifiedMasternodeListDAPIAddressProvider test #916 is CI-green (35 checks passing) and CodeRabbit-approved, waiting only on its required human CODEOWNER review — nothing on this PR can advance it.
• Since then, b5023dcbce (doc-only) removed a dangling ERROR_CODE_REGISTRY.md reference flagged by CodeRabbit; no code change.

cargo fmt --check clean; cargo test -p platform-wallet-ffi -p platform-wallet green at the head — 514 + 212 unit tests, 0 failed. Please re-run the gate (including the deferred Sonnet pass) at b5023dcbce.

[bfoss765]

Renumbered the deferred-token trio: 27/28/30 → 34/35/36

#4268 merged into v4.2-dev and took 27 for ErrorShutdownIncomplete, which is the number this PR's ErrorStaleReservationToken was on. That number is merged ABI now, so this branch had to move.

I moved all three rather than just the colliding one, and moved them above every number currently claimed by anything:

	owner
27	ErrorShutdownIncomplete — merged, #4268
29	ErrorAssetLockInsufficientFunds — #4184
31	ErrorSigningKeyUnavailable — #4183/#4259
32	ErrorTransactionBuild — #4247/#4256
33	ErrorTransactionSigning — #4256

So 32/33/34 was not available; the trio is now the contiguous block 34–36. 28 and 30 are vacated and left free rather than back-filled, so a reviewer who saw the old numbering can't find a familiar number attached to an unfamiliar meaning. #4256 got the identical move; registry updated in #4261.

Applied at 32 sites (every line that carried one of the old numbers) — Rust enum + rustdoc cross-refs, signed_payment.rs, the JNI rustdoc, Kotlin mapping/KDoc/tests, and the Swift mirror. The Swift and Kotlin mirrors have no compile-time cross-ABI check, so those were verified by grep rather than by the compiler.

Also addressed the three open suggestions

platform_wallet.rs:52 — generation Arc publicly assignable. Valid, applied. PlatformWalletInfo.generation is now pub(crate). It was reachable mutably from outside the crate via state_mut() / state_mut_blocking(), so downstream safe code could swap the Arc while PlatformWallet and CoreWallet kept the original — splitting the identity Arc::ptr_eq compares. is_current_generation() would then reject a live wallet, generation-bound reservation cleanup would no-op, and teardown would exclude through a different gate than the payments it must fence. Every construction and mutation site is already inside the crate, so this is not a downstream break.

ManagedPlatformWallet.kt:316 — cancellation discards the token. Valid, applied as suggested. buildSignedPayment now runs under opWithCleanupOnCancellation with cleanup = { it.close() }. Native finalization mints the token before the blocking JNI call returns, so withContext's prompt-cancellation handoff could drop the completed SignedCoreTransaction and leave the reservation to the GC Cleaner or the TTL. Updated the KDoc, which previously described the GC backstop as the only cleanup on that path.

DashSdkError.kt — code 26 falls through to Generic. Valid, applied. Added PlatformWallet.TransactionBroadcastRejected and mapped 26 to it, so a definitively-rejected, consumed-and-released payment is distinguishable from an unrelated generic wallet failure. isRetryable stays false — the reservation and token are already gone, so it is not retryable in place; it has to be rebuilt. Pinned in DashSdkErrorTest, including an explicit "must not fall through to Generic" assertion.

Verification

• cargo fmt --check clean.
• cargo test -p platform-wallet-ffi -p platform-wallet: 767 passed, 0 failed (514 + 212 + 26 + 9 + 6).
• ./gradlew :sdk:test: 190 tests, 0 failures, 0 errors on both debug and release variants.
• Swift is unverified by compilation — no Swift toolchain run here. Its four numeric sites were checked by grep against the Rust enum.

One note for whoever picks it up: this branch is not rebased onto current v4.2-dev, so it does not yet contain ErrorShutdownIncomplete itself. The renumber is what makes that merge clean — upstream's 27 now lands in an empty slot instead of colliding.

[bfoss765]

@thepastaclaw re-requesting at the ACTUAL current head 3dec7749 — the earlier request cited b5023dcb, which was superseded 20 minutes later by the error-code renumber (27/28/30 → 34/35/36, forced by #4268 merging ErrorShutdownIncomplete = 27 into v4.2-dev ABI; see #4261 for the registry record). Both prior blockers are addressed at this head: the same-ID registration race is fixed in 6be67488 (regression test fails 10/10 against the old code), and the Cargo.toml fork pin remains externally gated on dashpay/rust-dashcore#916 (green, CodeRabbit-approved, awaiting human merge). Please revalidate including the deferred Sonnet pass.

[bfoss765]

Restacked: this PR is now the base of a 3-PR stack

Stack order (bottom → top): #4185 → #4247 → #4256

These three PRs previously branched independently from the same point and each rewrote the deferred-payment lifecycle, so no two could be merged without hundreds of conflicted lines in signed_payment_registry.rs / core/send.rs. They are now a clean linear stack: a change to any one rebases mechanically instead of re-triggering that reconciliation.

This PR is unchanged in content. Its commits are byte-identical to before; the only new commit is a merge of current v4.2-dev.

What changed

• Merged current v4.2-dev (post-feat(platform-wallet): registry-owned coordinator lifecycle with Rust-owned FFI callback contexts #4268). Sole conflict was PlatformWalletResult.swift, five hunks, all additive on both sides — feat(platform-wallet): registry-owned coordinator lifecycle with Rust-owned FFI callback contexts #4268 adds errorShutdownIncomplete = 27, this PR adds the deferred-token trio at 34-36. Both kept; no renumbering was needed because the trio was already placed above feat(platform-wallet): registry-owned coordinator lifecycle with Rust-owned FFI callback contexts #4268's claim.
• mergeable is back to MERGEABLE.

Relationship to #4268 (merged upstream 2026-08-02)

#4268 owns the coordinator — the async task registry and Rust-owned FFI callback contexts (platform-wallet-ffi's manager.rs / event_handler.rs / persistence.rs, the manager sync loops). This PR owns the wallet generation — the per-generation balance Arc plus its payment/teardown gate (wallet/core/generation.rs, manager/wallet_lifecycle.rs, wallet/signed_payment_registry.rs). The two file sets are disjoint and every one of this PR's files merged cleanly. The only overlap was the error-code space, resolved above.

Error-code registry (#4261) after the stack

code	name	owner
27	ErrorShutdownIncomplete	#4268 (merged)
28, 30	vacated but RESERVED	—
29	ErrorAssetLockInsufficientFunds	#4184
31	ErrorSigningKeyUnavailable	#4183/#4259
32	ErrorTransactionBuild	#4247
33	ErrorTransactionSigning	#4256
34/35/36	deferred-token trio	#4185
37	ErrorShieldedInviteAlreadyClaimed	#4204

Identical in Rust, Kotlin and Swift; verified for duplicates in all three.

Still open on this PR

The blocking finding 205eb14c72e3 (workspace deps pinned to bfoss765/rust-dashcore @ e99959ce) is not fixed and cannot be fixed here: the owner-tagged reservation API this PR depends on exists only on that fork, and its upstream PR dashpay/rust-dashcore#916 is still OPEN / BLOCKED / REVIEW_REQUIRED. Repointing the eight workspace entries at the Dash-owned repo today would fail to build. This PR cannot merge until #916 lands, after which the pins and Cargo.lock must move to the corresponding Dash-owned revision.