Skip to content

fix(platform-wallet): save shielded spend records before broadcast and report unproved outcomes as unconfirmed - #5837

Merged
QuantumExplorer merged 7 commits into
feat/platform-wallet-private-contact-requestsfrom
claude/gallant-chatelet-454d30
Nov 10, 2026
Merged

QuantumExplorer merged 7 commits into
feat/platform-wallet-private-contact-requestsfrom
claude/gallant-chatelet-454d30

Conversation

@QuantumExplorer

@QuantumExplorer QuantumExplorer commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Basic explanation

What this does: When the wallet sends a signed transaction to the network, it does not always learn what happened to it: the app can be closed, or a node can answer with an error after it already passed the transaction on. This PR makes two things true in platform-wallet. First, every shielded spend (transfer, unshield, withdrawal, identity top-up and identity create from the pool) now writes its recovery record to disk before it sends anything, not after a wait has already failed. Second, a shield from Platform addresses and a masternode credit withdrawal now report "unconfirmed" whenever a send attempt could have reached a node, and "failed" only when nothing was sent at all. A shield is also reported as done only when the proof that comes back shows its source addresses were spent from.

Value: A wallet that is closed or crashes in the middle of a spend comes back knowing about that spend: the notes stay reserved, the exact signed transaction is still there, and the next sync finishes the job. And a host app is no longer told "failed, try again" for a shield or a masternode withdrawal whose outcome is not known, so it does not offer a retry while the first attempt can still go through.

Risks: Medium for user experience, low for funds, none for consensus (client code only). The noticeable change: a shield or a masternode withdrawal attempted with no working connection (a node that refuses the connection, an offline device with addresses configured) now reads "unconfirmed" instead of "failed", because a transport error cannot show that nothing was sent. For a shield, that leaves its activity row pending with nothing that resolves it automatically if it never executes (see "What has no automatic resolution"). A shield also no longer returns the address nonce mismatch code that hosts could retry on. A shield that succeeds now leaves its activity row pending until the shielded scan sees its note, where it used to be marked confirmed on return. Spends hold their notes in a few more cases than before (an exit during the broadcast), until the anchor-prune pass releases them.

Issue being fixed or feature implemented

Stacked on #5810, which gave the private document payment a recovery record saved before its broadcast and a broadcast that keeps what every send attempt proved. Two older behaviours next to it did not match that:

  1. The other note-consuming spends saved their recovery record only after the result wait had returned "unconfirmed", and note reservations live in memory. A process that exited during the send attempts or the wait restarted with no record and no reservation.
  2. shield_to and the masternode credit withdrawal classified the SDK's final broadcast error, treating a node's refusal (Unavailable among them) and a node's consensus verdict as a definitive failure. The SDK's retry returns only its last error, and no proof backs a node's answer.

The masternode withdrawal half of 2 is what #5665 asks for. This PR does not add the typed "definitive failure" variant that issue also proposes.

What was done?

1. Every note-consuming spend saves its recovery record before its first broadcast

save_spend_then_broadcast (new, wallet/shielded/operations.rs) is now the only way a transfer, unshield, withdrawal, identity top-up or identity create reaches the network. It attaches the anchor to each reservation, saves the PendingRedrive record with arm_redrive_before_broadcast (no private contact payment), hands the notes over with nothing awaited in between, and only then broadcasts. A spend whose record cannot be saved, or that has no activity entry to key it by, is refused with nothing sent.

settle_failed_spend (new) replaces the five copies of the failure handling:

How the spend ended Notes Saved record Activity row Reported as
Failed before its record was saved (anchor fetch, build, save) released none failed the error
Its transition never left the wallet (refused before anything was sent) released retired, in the same store guard (retire_undelivered) failed ShieldedBroadcastFailed
Never left, but a redrive pass claimed a re-broadcast of the record meanwhile kept kept pending unconfirmed
Record saved and a send attempt may have reached a node, whatever error ended it kept kept pending unconfirmed

Before, a process exit between the broadcast and the result:

reserve notes (memory) -> build -> broadcast -> [exit]
restart: no record, no reservation; the notes are selectable again

After:

reserve notes (memory) -> build -> save record (disk) -> broadcast -> [exit]
restart: the store restores the reservation from the record;
         the redrive pass re-broadcasts the same bytes;
         the scan that sees the nullifier spent drops the record

Each spend kind's exits were checked against that table. Two more changes came out of it:

  • Identity create builds its transition before the record is saved (the record holds those bytes), and its broadcast, result wait and fetch-by-derived-id fallback moved into broadcast_identity_create. A proved result of an unexpected shape whose identity cannot be synthesized used to release the notes; it is now unconfirmed, with the derived identity id.
  • error_releases_note_reservation, arm_redrive_record and the unclassified broadcast_shielded_spend wrapper are gone: whether notes are released is decided by whether the record was saved and whether the transition left the wallet, not by the error's variant.

The private document payment path from #5810 is untouched.

2. Shields from Platform addresses and masternode credit withdrawals report "unconfirmed" once a send attempt may have reached a node

Both now broadcast with broadcast_tracking_delivery (which no longer needs the shielded feature) and settle in one place each: settle_shield and settle_masternode_withdrawal.

Outcome shield_to before shield_to now Masternode withdrawal before Masternode withdrawal now
No address to send to failed failed (ShieldedBroadcastFailed), row failed failed failed (InvalidIdentityData)
Broadcast answered Unavailable, or another refusal failed, row failed waits for the result; unconfirmed if not proved, row pending failed waits; MasternodeWithdrawalUnconfirmed if not proved
Broadcast answered with a consensus verdict failed (a stale nonce: AddressNonceMismatch) waits; unconfirmed if not proved failed waits; unconfirmed if not proved
Broadcast answered that an input address's nonce is ahead of the node (a node that is behind) the SDK sent the same bytes to another node the same bytes go to the next send attempt's node, within the retry budget not applicable (no address input) not applicable
Result wait answered with a consensus verdict failed, row failed unconfirmed, row pending failed unconfirmed
Result wait timed out unconfirmed unconfirmed unconfirmed unconfirmed
Verified result reads every input address at or past the nonce the shield signed success, row confirmed success, row pending until the scan sees the note proved balance proved balance
Verified result of another shape (for a shield: not an address snapshot, an input left out, an input below its signed nonce) success, row confirmed unconfirmed, row pending unconfirmed when it carries no identity balance the same

The reason an unconfirmed shield reports keeps what the broadcast was answered with, including the funds-shortfall detail. An unconfirmed masternode withdrawal's reason keeps it too.

What a shield's result proves. The proof behind a shield's result authenticates its input addresses as of the proof's block, not the shield's execution. shield_to used to mark the activity row confirmed on any verified result. It now succeeds only when that result reads every input address at or past the nonce the shield signed (shield_inputs_read_spent); any other verified result is unconfirmed. In both cases the row stays pending until the scan observes the note commitment, which is what the shield from an identity already does.

The one answer that keeps the send attempts going. broadcast_tracking_delivery sends in single attempts so that it can keep what each one proved. That also turned off, for a shield, the SDK's own failover for a node that is behind (one that reads an input address's nonce as ahead of its own state). The tracker now sends the same signed bytes again on exactly that answer, reading the SDK's rule (is_address_nonce_ahead, made public in dash-sdk), and the broadcast stays "may have been delivered". No retryable nonce error is surfaced. Unlike the SDK's loop, a single attempt does not exclude the node that answered, so a later attempt can reach it again and use up one of the budget's attempts.

What resolves each, and what has no automatic resolution. Neither flow got a durable guard on its signed transition in this PR:

  • Shield from Platform addresses. The proof that a signed shield can no longer execute is its input addresses' nonces: once a proved read shows one of them used, the shield executed or another transition took its place. A shield that executed is confirmed automatically, by the scan that sees its note commitment (for a recipient's note, through the outgoing viewing key). Nothing reads the nonces for it, so a shield that never executes leaves its row pending, and nothing stops a second shield from the same addresses meanwhile. A guard was left out because the store treats every record without nullifiers as an identity-funded shield (store open, the identity guard lookup, the coordinator's passes and the recovery FFI all fail closed on anything else), so it needs its own record class, a nonce-reading pass and a "shield pending" refusal for hosts.
  • Masternode credit withdrawal. The proof is the identity nonce the withdrawal signed with (identity_nonce_proves_unused already implements the read for the identity-funded shield). This path has no store at all (it also serves tracked masternodes with a host-supplied key), so nothing is saved and nothing resolves it automatically: as before, the host must re-read the claimable balance before it submits again.
  • shield_from_identity_to already held a durable guard and is unchanged.

FFI. No new result code. Updated docs for 16, 17, 18, 21 and 42 in error.rs, the spend mapping comments in shielded_send.rs, the masternode withdrawal export's doc, and the notes of rows 16, 18, 21 and 42 in ERROR_CODE_REGISTRY.md:

  • 18 ErrorShieldedSpendUnconfirmed is what a shield now returns for the rows above; 16 ErrorShieldedBroadcastFailed only for a shield that never left the wallet.
  • 21 ErrorAddressNonceMismatch is no longer returned by a shield. Transfers and withdrawals from Platform addresses and identity registrations and top-ups from them still return it.
  • 42 ErrorMasternodeWithdrawalUnconfirmed covers the rows above.

The Swift and Kotlin doc comments state the same contract for 16, 17, 18, 21 and 42: PlatformWalletResult.swift, the shield, note spend and masternode withdrawal method docs (PlatformWalletManagerShieldedSync.swift, PlatformWalletManagerMasternodes.swift), DashSdkError.kt and PlatformWalletManager.kt.

The example apps follow the same wording:

  • The failure stage both apps attribute to the broadcast step is renamed broadcastNotSent (Swift) and BroadcastNotSent (Kotlin): code 16 means the transition was refused before anything was sent, not that Platform rejected it. The step it marks is unchanged.
  • In the Swift example app, the unconfirmed identity create no longer reads "Broadcast succeeded, confirmation pending" and "was broadcast and accepted": it reads "Result not confirmed" and "may have reached the network". The unconfirmed masternode withdrawal message changes the same way.
  • The Kotlin ShieldedSpendUnconfirmed message no longer says the wallet keeps the spent notes reserved, which is not so for a shield from Platform addresses.

These are the only Swift and Kotlin code changes: two enum case renames with their uses, and string literals.

Also. broadcast_definitely_failed is renamed broadcast_was_refused and its doc rewritten: it is not proof of anything, and its one remaining caller (the identity-funded shield) only uses it to skip the result wait for a proven nonce read, reporting unconfirmed either way. The module doc of broadcast_outcome.rs says what is true now. Stale "reservations are in-memory only" docs in store.rs, error.rs and operations.rs were corrected. settle_failed_spend logs the typed cause of a saved spend's failure before it reports it as unconfirmed.

How Has This Been Tested?

New tests, all named should ...:

  • should_restore_a_spend_that_exited_between_its_broadcast_and_its_result: the record is on the file before the broadcast closure runs; the spend is dropped while its result is pending; the reopened store holds the reservation and the exact signed bytes; the redrive pass re-broadcasts them; marking the nullifier spent removes the record for good.
  • should_release_a_failed_spend_s_notes_only_when_its_transition_cannot_execute: the five rows of the settlement (never delivered, never delivered with a claimed re-broadcast, unconfirmed, another error after the save, save failed).
  • should_keep_a_spend_that_may_have_reached_a_node_until_it_resolves, should_retire_the_record_of_a_spend_that_never_left_the_wallet, should_not_dispatch_a_spend_whose_record_cannot_be_saved: each run for both code paths (the shared path, as a transfer, and identity create) through the production functions, on a mock SDK and on a network SDK with no address.
  • should_report_a_shield_unconfirmed_once_a_dispatch_may_have_reached_a_node, should_report_a_shield_failed_only_when_nothing_was_sent, should_accept_a_shield_whose_inputs_read_spent_and_leave_its_row_to_the_scan, should_report_a_shield_unconfirmed_when_its_result_does_not_read_its_inputs_spent.
  • should_report_a_masternode_withdrawal_unconfirmed_once_a_dispatch_may_have_reached_a_node (the reason keeps the wait's and the broadcast's answers), should_report_a_masternode_withdrawal_failed_only_when_nothing_was_sent, should_return_a_masternode_withdrawal_s_proved_balance.
  • should_send_a_transition_a_node_is_behind_on_to_another_node, should_end_the_dispatches_on_a_verdict_no_other_node_changes: the tracker keeps sending on the one answer the SDK fails over on, and ends the attempts on every other verdict.
  • should_report_a_shield_unconfirmed_when_its_node_refuses_the_connection, should_report_a_masternode_withdrawal_unconfirmed_when_its_node_refuses_the_connection, should_track_the_delivery_of_a_broadcast_through_a_network_sdk: through a real SDK whose only node is a loopback port the test holds bound and never listens on (so it refuses every connection and nothing else can take it), and one with no address.

Commands run locally:

cargo test -p platform-wallet --lib --features shielded,test-utils -- shielded masternode broadcast_outcome
cargo test -p platform-wallet --lib --features test-utils -- masternode broadcast_outcome
cargo test -p platform-wallet-ffi --lib --features shielded -- shielded_send error
cargo clippy -p platform-wallet --features shielded,test-utils --all-targets -- -D warnings
cargo clippy -p platform-wallet-ffi --features shielded --all-targets -- -D warnings
cargo test -p dash-sdk --lib -- transition::broadcast
# in packages/kotlin-sdk
./gradlew :sdk:compileDebugKotlin :app:compileDebugKotlin :sdk:testDebugUnitTest --tests '*DashSdkErrorTest' :app:testDebugUnitTest --tests '*RegistrationCoordinatorTest'
cargo fmt --all

Results, on the branch with #5810's current head merged in: 419 tests pass in platform-wallet with shielded, 130 without it, 101 in platform-wallet-ffi, 25 in dash-sdk; both clippy runs are clean; cargo fmt --all --check is clean. The Kotlin SDK and example app compile, and DashSdkErrorTest (26) and RegistrationCoordinatorTest (12) pass. The changed Swift files pass swiftc -parse (syntax only).

Mutation checks: each new behaviour was reverted on its own and the tests above rerun.

Behaviour reverted Tests that then fail
The record is not saved before the broadcast 5
The notes are not handed over once the record is saved 3
A never-delivered spend is released although a re-broadcast of its record was claimed 1
A spend whose record is saved is released on an error other than "unconfirmed" 2
Identity create: a broadcast refused before anything was sent is not marked as never delivered 1
Identity create broadcasts without the save step 3
The shared path broadcasts without the save step 3
Shield: a node's refusal of the broadcast reads as failed 3
Shield: a consensus verdict on the result wait reads as failed 1
Shield: a broadcast that never left reads as unconfirmed 2
Masternode withdrawal: a node's refusal of the broadcast reads as failed 3
Masternode withdrawal: a consensus verdict on the result wait reads as failed 1
Masternode withdrawal: a broadcast that never left reads as unconfirmed 2
A node that is behind ends the send attempts (no failover) 1
Every verdict keeps the send attempts going 2
Shield: any verified result reads as its inputs spent 1
Shield: an input below its signed nonce is accepted 1
Shield: an input at its signed nonce is refused 1
Shield: an input the result leaves out is accepted 1
Shield: a transition that names no input is accepted 1
Shield: the row is marked confirmed on return 1
Masternode withdrawal: the reason drops what the broadcast was answered with 1

All 22 were caught, and the tree was restored after each. Rows 1 to 3 and 5 to 7 were run before the review fixes, on code those fixes did not change. Rows 4 and 8 to 13 were rerun on the current head, and the last nine were run on the review fixes before the latest commits of #5810 were merged in.

Not run: the full platform-wallet, platform-wallet-ffi and dash-sdk suites, the workspace build and cargo check --workspace --all-targets, the Swift build and the Swift example app's tests (the changed Swift files were only syntax-checked), the Kotlin emulator tests, and anything against a live network. No spend was exercised end to end with a real prover: the tests drive the production save, broadcast and settlement functions with hand-built transitions. cargo clippy -p platform-wallet --features test-utils --all-targets -- -D warnings (without shielded) fails on two unused methods in wallet/asset_lock that this PR does not touch; they are only called from shielded code.

Breaking Changes

None for consensus. Host-visible behaviour changes: the result codes in the table above (a shield no longer returns 21, and returns 18 where it returned 16 for a node's refusal or verdict; a masternode withdrawal returns 42 where it returned an ordinary error for the same), and a note-consuming spend with no activity entry is now refused before it is broadcast (our builders always produce one). A shield from Platform addresses that succeeds returns with its activity row pending, not confirmed: the shielded scan confirms it. The text of the Kotlin ShieldedSpendUnconfirmed message changed. dash_sdk::platform::transition::broadcast::is_address_nonce_ahead is now public.

Checklist:

  • I have performed a self-review of my own code
  • My Rust, FFI, WASM, Swift or Kotlin changes follow the coding conventions
  • 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
  • If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request
  • If I added or changed a system contract's document schemas, I checked the contract viewer link posted on this pull request

For repository code-owners and collaborators only

  • I have assigned this pull request to a milestone

🤖 Generated with Claude Code

QuantumExplorer and others added 2 commits November 10, 2026 15:03
…d report unproved outcomes as unconfirmed

Every note-consuming shielded spend (transfer, unshield, withdrawal,
identity top-up, identity create) now saves its recovery record durably
before its first dispatch, through one shared step, instead of after a
result wait returned unconfirmed. A process that exits during the
dispatches or the wait restarts with the notes' reservation and the
exact signed transition, and the redrive pass resolves it. A failed
spend is settled in one place: its notes are released, and its record
retired with them, only when it failed before the record was saved or
its transition never left the wallet.

A shield from Platform addresses and a masternode credit withdrawal now
broadcast keeping what every dispatch proved, and report unconfirmed
once a dispatch may have reached a node: an endpoint's refusal or
consensus verdict no longer reads as failed. Only a transition refused
before anything was sent is failed. Neither keeps a durable record of
its signed transition yet.

broadcast_definitely_failed is renamed broadcast_was_refused: it is no
proof, and its one caller left reports unconfirmed either way. No FFI
result code is added; the docs of codes 16, 17, 18, 21 and 42 and the
error code registry say what each operation returns now.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ude/gallant-chatelet-454d30

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

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

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
  • 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

@thepastaclaw

thepastaclaw commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

🕓 Review not started yet because the new head is waiting for the 30-minute push debounce.

  • 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 d2ad1ca. Normal review starts when eligible; priority review starts as soon as a slot is available.

@thepastaclaw thepastaclaw left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Final validation — Phase 1 + Phase 2

The save-before-broadcast refactor is generally sound, but two in-scope blocking correctness issues remain. Address-funded shields lose the SDK's same-transition nonce-ahead failover, and any affected-state snapshot is treated as proof that the shield executed, allowing a false confirmed result. Additional non-blocking issues affect diagnostics, test determinism, and public documentation; the supplied CI has Kotlin checks passing but no Rust validation check.

🔴 2 blocking | 🟡 5 suggestion(s)

2 finding(s) not shown inline (the lines are not part of this PR's diff)

🟡 Suggestion: Update mobile documentation for the revised shield outcome contract
packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift:69-76

The native mapping now reports a dispatched shield nonce verdict as code 18, while code 21 is reserved for transfers, withdrawals, registrations, and top-ups from Platform addresses. These Swift comments still describe code 21 as covering a shield and say that its notes are released and safe to retry. The Kotlin documentation also still describes code 16 as a definitive relay or CheckTx rejection, although the new tracking path reports endpoint refusals and consensus verdicts as unconfirmed when a dispatch may have reached a node. The stale public documentation can lead host applications to retry a transition that must not be retried. Update the Swift and Kotlin comments to match the new never-delivered versus possibly-delivered contract.

source: muse-spark-1.3-contributor (phase1-reviewer: general, rust-quality); gpt-6.1-sol (phase2-reviewer: general, architecture-layering, ffi-engineer, rust-quality, security-auditor); gpt-6-astra (phase2-reviewer: ffi-engineer, rust-quality)

🟡 Suggestion: Make SpendFailure's delivery state unrepresentable
packages/rs-platform-wallet/src/wallet/shielded/operations.rs:4454-4471

SpendFailure stores the error and the independent never_delivered boolean separately. From<PlatformWalletError> defaults the flag to false, while the two never-delivered construction sites must remember to set it to true. A future caller can therefore construct an invalid pairing that compiles but causes settlement to retain notes and report an unconfirmed outcome instead of retiring the record. Use an enum or named constructors such as SpendFailure::never_delivered and SpendFailure::maybe_delivered so the error classification and settlement behavior cannot diverge.

source: muse-spark-1.3-contributor (phase1-reviewer: general, rust-quality)

Review provenance

Source: reviewer 1: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 2: gpt-6.1-sol (agent: phase2-reviewer, role: architecture-layering); reviewer 3: gpt-6.1-sol (agent: phase2-reviewer, role: ffi-engineer); reviewer 4: gpt-6.1-sol (agent: phase2-reviewer, role: rust-quality); reviewer 5: gpt-6.1-sol (agent: phase2-reviewer, role: security-auditor); reviewer 6: gpt-6-astra (agent: phase2-reviewer, role: ffi-engineer); reviewer 7: gpt-6-astra (agent: phase2-reviewer, role: rust-quality); reviewer 8: muse-spark-1.3-contributor (agent: phase1-reviewer, role: general); reviewer 9: muse-spark-1.3-contributor (agent: phase1-reviewer, role: rust-quality); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)

  • Triage: critical by gpt-6.1-sol (effort low) — The large, intricate changes in save_spend_then_broadcast, settle_failed_spend, and masternode withdrawal handling alter shielded funds movement, note reservation, signed-transaction persistence, and broadcast outcome classification.
  • Phase 1 reviewers: muse-spark-1.3-contributor — general (completed, effort xhigh); agent phase1-reviewer, muse-spark-1.3-contributor — rust-quality (completed, effort xhigh); agent phase1-reviewer
  • Phase 1 model: muse-spark-1.3-contributor — not quota-gated; passed over gemini-3.8-flash-high (antigravity quota lookup failed), glm-5.3-flash (not used above high effort; tier asks max)
  • Single stage: Phase 1 and Phase 2 reviewed this head side by side, with no blocker gate between them (triage tier)
  • Fresh verifier: gpt-6.1-sol — final-verifier; agent sol-verifier
  • Phase 2 reviewers: gpt-6.1-sol — general (completed, effort xhigh); agent phase2-reviewer, gpt-6.1-sol — architecture-layering (completed, effort xhigh); agent phase2-reviewer, gpt-6.1-sol — ffi-engineer (completed, effort xhigh); agent phase2-reviewer, gpt-6.1-sol — rust-quality (completed, effort xhigh); agent phase2-reviewer, gpt-6.1-sol — security-auditor (completed, effort xhigh); agent phase2-reviewer, gpt-6-astra — ffi-engineer (completed, effort xhigh); agent phase2-reviewer, gpt-6-astra — rust-quality (completed, effort xhigh); agent phase2-reviewer
  • Model comparison: every Phase-2 reviewer also ran on gpt-6-astra; the verifier weighed both sets without knowing which model wrote which
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review (PastaClaw). How to work through them:
- Verify each finding against the code; fix only what is real, as narrowly as the finding.
- If a finding is wrong, decline it on its thread in one or two sentences; the bot answers once and stops.
- To defer one, link a tracking issue on its thread (or reply asking the bot to file one).
- Suggestions are optional: fix them forward in a later PR rather than pushing another round just for them.
- Address every current finding in one push: self-review the full diff first, and don't push piecemeal.
- Keep the PR's scope; don't grow it to satisfy hardening suggestions.
- Carried items were raised in an earlier round: read the thread first, and don't re-fix what you already fixed, declined or deferred there. Disputed and deferred items are already handled and are not listed.

In `packages/rs-platform-wallet/src/wallet/shielded/operations.rs`:
- [BLOCKING] packages/rs-platform-wallet/src/wallet/shielded/operations.rs:769-779: Address-funded shields lose same-transition nonce-ahead failover
  `broadcast_tracking_delivery` invokes `StateTransition::broadcast` with `retries: Some(0)` and stops tracking immediately when it receives a consensus rejection. The SDK's existing `broadcast_with_retries` logic specifically retries an `AddressInvalidNonceError` when the submitted address nonce is ahead of the responding node, resending the same signed bytes to another node; however, with a zero retry budget that path exits before the additional-error retry can occur, and the tracker returns `MaybeDelivered` at the first consensus error. A shield whose nonce was fetched from a caught-up node can therefore stop at a lagging first broadcaster even when another configured node could admit the exact transition. The result wait then cannot find the transition, and this address-funded shield has no durable redrive record. Preserve the SDK-owned same-byte nonce-ahead failover while retaining the delivery uncertainty in the wallet; do not solve this by restoring a host-visible retryable nonce error that could sign a second shield.
- [BLOCKING] packages/rs-platform-wallet/src/wallet/shielded/operations.rs:730-735: Do not confirm a shield from an affected-state snapshot
  `wait_for_affected_state` is explicitly documented by the SDK as returning a height-pinned snapshot, not evidence that this specific transition executed. `settle_shield` nevertheless marks the activity row `Confirmed` and returns success for any successful `StateTransitionProofResult`, including the test's `VerifiedTokenBalanceAbsence`. Drive's shield verifier only authenticates the input address state at the proof's block; another transition could have changed that state, or the submitted shield could still be absent. This can report success for a shield whose recipient note was never created. Keep the activity pending and return an unconfirmed result until the shield output commitment is observed by the scan or equivalent transition-specific execution evidence is available.
- [SUGGESTION] packages/rs-platform-wallet/src/wallet/shielded/operations.rs:3928-3935: Preserve the original cause when converting a saved-spend failure
  Once the reservation has been handed over, every non-unconfirmed error is converted into `ShieldedSpendUnconfirmed` using only `other.to_string()`. This intentionally preserves the conservative outcome, but it erases the original `PlatformWalletError` discriminant and source chain, so callers and diagnostics can no longer distinguish a store failure, wait failure, or another typed error. Preserve the typed cause as a source or structured field, or at minimum log it before wrapping, while keeping the unconfirmed classification unchanged.
- [SUGGESTION] packages/rs-platform-wallet/src/wallet/shielded/operations.rs:4454-4471: Make SpendFailure's delivery state unrepresentable
  `SpendFailure` stores the error and the independent `never_delivered` boolean separately. `From<PlatformWalletError>` defaults the flag to `false`, while the two never-delivered construction sites must remember to set it to `true`. A future caller can therefore construct an invalid pairing that compiles but causes settlement to retain notes and report an unconfirmed outcome instead of retiring the record. Use an enum or named constructors such as `SpendFailure::never_delivered` and `SpendFailure::maybe_delivered` so the error classification and settlement behavior cannot diverge.

In `packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift`:
- [SUGGESTION] packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift:69-76: Update mobile documentation for the revised shield outcome contract
  The native mapping now reports a dispatched shield nonce verdict as code 18, while code 21 is reserved for transfers, withdrawals, registrations, and top-ups from Platform addresses. These Swift comments still describe code 21 as covering a shield and say that its notes are released and safe to retry. The Kotlin documentation also still describes code 16 as a definitive relay or CheckTx rejection, although the new tracking path reports endpoint refusals and consensus verdicts as unconfirmed when a dispatch may have reached a node. The stale public documentation can lead host applications to retry a transition that must not be retried. Update the Swift and Kotlin comments to match the new never-delivered versus possibly-delivered contract.

In `packages/rs-platform-wallet/src/wallet/masternode_withdrawal.rs`:
- [SUGGESTION] packages/rs-platform-wallet/src/wallet/masternode_withdrawal.rs:552-571: Preserve the broadcast cause in unconfirmed withdrawal errors
  The `MaybeDelivered(e)` branch consumes the broadcast error after writing it only to tracing. If the subsequent result wait fails, the returned `MasternodeWithdrawalUnconfirmed.reason` contains only the wait error and loses useful information such as an endpoint's insufficient-balance or nonce verdict. This behavior is newly relevant because those refusals now enter the `MaybeDelivered` path instead of being returned directly. Retain the broadcast answer alongside the wait failure, as `settle_shield` does, without changing the conservative unconfirmed classification.

In `packages/rs-platform-wallet/src/broadcast_outcome.rs`:
- [SUGGESTION] packages/rs-platform-wallet/src/broadcast_outcome.rs:303-310: Avoid racing on a released ephemeral port in refusal tests
  `sdk_refusing_connections` binds an ephemeral loopback port and drops the listener before the SDK request begins. Another test or process can claim that port in the gap, causing the test to exercise an unrelated service or wait on a different network failure instead of deterministically testing connection refusal. Prefer an injected transport failure for unit coverage, or keep a controlled test endpoint alive through the request and close it deliberately with a short deadline.
Out-of-scope follow-up suggestions (2)

These are valid observations, but they are outside this PR's scope and should be handled in separate issues or author/maintainer-requested PRs rather than blocking this review.

  • Extend delivery tracking to the remaining address-funded operations — Transfers, Platform-address withdrawals, and identity registrations and top-ups still promote a final endpoint nonce verdict to code 21 and can cause a host retry to sign a second transition. Those paths are not changed by this PR, which deliberately limits tracking to shields and masternode withdrawals, but they share the same unauthenticated-final-error hazard.
    • Follow-up: Open or extend a follow-up wallet/SDK change, alongside the transport-history work tracked by #5556, to preserve delivery history and define safe nonce-retry behavior for all address-funded paths.
  • Add durable reconciliation for address-funded shields and masternode withdrawals — The newly unconfirmed address-funded shield and masternode withdrawal paths still persist no signed-transition guard and have no automatic proof-backed resolution. A crash or unresolved wait can therefore leave a pending operation without preventing a replacement submission or proving that the original can no longer execute. This limitation predates the change and is acknowledged by the PR, but it remains important for safe recovery.
    • Follow-up: Implement a follow-up rs-platform-wallet recovery change that persists the signed transition and its input or identity nonce, prevents replacement submissions while unresolved, and reconciles through proof-verified nonce and outcome evidence exposed through thin bindings.

QuantumExplorer and others added 5 commits November 10, 2026 17:27
…d keep sending when a node is behind

A shield from Platform addresses:

- succeeds only when its verified result reads every input address at or
  past the nonce the shield signed; any other verified result is
  unconfirmed. Its activity row stays pending until the scan observes the
  note, as the shield from an identity's does: the result proves the input
  addresses as of its block, not the shield's execution.
- keeps its send attempts going on the one answer the SDK's own broadcast
  fails over on, a node that reads an input address's nonce as ahead of
  its own state: the same signed bytes go to the next attempt's node, and
  the broadcast stays maybe delivered. `is_address_nonce_ahead` is public
  in dash-sdk so the tracker reads the SDK's rule.

Also: an unconfirmed masternode withdrawal's reason keeps what its
broadcast was answered with; the typed cause of a saved spend's failure is
logged before it is reported as unconfirmed; the broadcast tests hold
their refusing loopback port bound and unlistened instead of releasing it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…n the Swift and Kotlin docs

Result codes 16, 18, 21 and 42 read as the Rust wallet now returns them:
16 only for a transition that never left the wallet, 18 and 42 once a
send attempt may have reached a node and the result is not proved, and 21
no longer for a shield. Comments only.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ude/gallant-chatelet-454d30

Both sides kept in the docs of result codes 16 and 18 (the FFI error enum
and its registry): the base branch's wording for note spends and the
identity create, this branch's for a shield from Platform addresses.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…and Kotlin example apps and docs

The example apps and the remaining SDK docs described a failed shielded
broadcast as a rejection by Platform, and an unconfirmed outcome as a
broadcast that was accepted. A failed one never left the wallet, and an
unconfirmed one may have reached a node with its result not proved.

- The failure stage both apps attribute to the broadcast step is renamed
  `broadcastNotSent` (Swift) and `BroadcastNotSent` (Kotlin).
- The unconfirmed identity create and masternode withdrawal messages in
  the Swift example app no longer say the broadcast succeeded.
- The Kotlin `ShieldedSpendUnconfirmed` message no longer says notes stay
  reserved, which is not so for a shield from Platform addresses.
- The doc comments for code 17 and for the note spend methods state the
  same contract.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ude/gallant-chatelet-454d30

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@QuantumExplorer
QuantumExplorer merged commit 034b73d into feat/platform-wallet-private-contact-requests Nov 10, 2026
9 of 10 checks passed
@QuantumExplorer
QuantumExplorer deleted the claude/gallant-chatelet-454d30 branch November 10, 2026 12:23
QuantumExplorer added a commit that referenced this pull request Nov 10, 2026
…uests

Brings in #5556 (shared broadcast keeps uncertain submission outcomes),
#5823 (proven state transition outcome, getRecentStateTransitionStatus),
#5815, #5834, #5825, #5835, #5838 and #5839.

One textual conflict, in packages/rs-sdk/src/platform/transition/broadcast.rs
at the end of broadcast_with_retries. This branch (#5837) had the shared
broadcast fail over on a nonce-ahead answer and on a missing DPNS owner
(retry_with_additional_error, from #5562), and made is_address_nonce_ahead
public for the wallet's single-dispatch broadcast. #5556 replaced both
failovers with the plain shared retry, so that a concrete refusal ends
sending, with tests saying so (should_stop_on_nonce_rejection_without_
rebuilding_or_resending, should_stop_on_concrete_rejection_regardless_of_
node_failover_settings), and removed is_address_nonce_ahead and
is_missing_transition_owner. The file is taken as v5.1-dev has it.

The wallet's single-dispatch broadcast (broadcast_outcome::track_delivery)
still goes on to the next dispatch after a nonce-ahead answer, as #5837
meant: the classifier moves into broadcast_outcome.rs, unchanged, and its
doc no longer says the SDK's own broadcast fails over too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
QuantumExplorer added a commit that referenced this pull request Nov 10, 2026
…tact-requests' into feat/ffi-swift-private-contact-requests

Brings in the wallet at 207bd72: #5837 merged into it, v5.1-dev
(#5556, #5823 and others), and the spend contract keeping code 20.

Conflicts:
- shielded_send.rs: the wallet's catch_spend_panic doc is taken, and the
  function stays pub(crate), as the private contact request exports call
  it.
- PlatformWalletResult.swift: the wallet's docs for 16 and 18 (the result
  code and the typed error) are taken. They are newer: a note spend's
  verdict and a shield's are both 18.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
QuantumExplorer added a commit that referenced this pull request Nov 10, 2026
…equests' into feat/kotlin-private-contact-requests

Brings in the FFI branch at 994d392, with the wallet at 207bd72
(#5837 merged into it, v5.1-dev, and the spend contract keeping code 20).

The one conflict was DashSdkError.kt, in the ShieldedSpendUnconfirmed and
ShieldedBroadcastFailed KDocs. Both take the wallet's newer wording: a
note spend's verdict and a shield's are both 18.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants