Skip to content

platform-wallet FFI: report whether a failed payment may have left the wallet, so hosts stop classifying error codes themselves #5926

Open

Description

@romchornyi

Expected Behavior

Every failed payment operation (Core asset-lock funding, identity top-up, Platform address transfer and withdrawal, shielded spend and shield) tells the host, as data on the result, whether the payment may have left the wallet: not sent (nothing can execute; safe to offer a retry), may have been sent (wait for sync; do not offer a second payment), and, for asset-lock routes, an asset lock is held with its outpoint. Swift and Kotlin pass it through; apps read it.

Current Behavior

Rust already knows the answer and keeps it crate-private: BroadcastDelivery::{Admitted, MaybeDelivered, NeverDelivered}. Only an error code crosses the FFI, so each layer above rebuilds the classification from code identity:

  • The FFI has two error-to-code tables: the blanket From<PlatformWalletError> and the allow-list map_spend_result, which flattens anything it does not list to ErrorWalletOperation (6). A new variant must be added to it by hand (feat(swift-sdk): shieldedShieldFromIdentityToRecipient #5863 had to add code 58 after review).
  • Kotlin decides retry-safety per error class (DashSdkError.isRetryable, default false); Swift's isRetryable is derived from an error category, not from delivery.
  • Apps decide it again. Dash Wallet iOS has several tables with different lists and an "in progress" default (Follow-ups from the review of #1254: one unconfirmed predicate, probe migration, test coverage dashwallet-ios#1361 tracks merging them on the app side); Android defaults to "not retryable". The same code can therefore mean "retry" on one platform and "wait" on the other.
  • Every new error code costs edits in three repos (Rust variant, FFI mapping, Swift enum, Kotlin class and isRetryable, the apps' tables), and the tables already lag: a code that Rust narrows (e.g. code 16 to "never left the wallet") keeps its old meaning in every host until each one is updated.

Possible Solution

  • Classify once in rs-platform-wallet, next to BroadcastDelivery: a public PaymentDelivery { NotSent, MaybeSent } for every PlatformWalletError a payment operation can return, plus the outpoint when an asset lock is held. Errors raised before any broadcast are NotSent by construction; errors after a dispatch inherit BroadcastDelivery.
  • Carry it as a field of PlatformWalletFFIResult (or export a pure code → class function, if a struct change is unwelcome). map_spend_result becomes a view of it.
  • Swift and Kotlin expose it on their error types (delivery), and isRetryable reads it. Document in ERROR_CODE_REGISTRY.md that hosts must use it rather than code lists.
  • Tests: one table test in Rust that every PlatformWalletError variant has a class, so a new variant cannot ship without one.

Steps to Reproduce

Architecture finding, no runtime reproduction. Compare how one code is treated: code 16 (shieldedBroadcastFailed) is "not sent" in Rust on v5.2-dev, "in progress" in Dash Wallet iOS, and isRetryable = false in Kotlin.

Context

The cost of a wrong class is a duplicate payment (retry offered while the first may land) or a stuck one (no retry offered while nothing was sent). Related: dashpay/dashwallet-ios#1361 (app-side "one predicate"), #5556 (delivery evidence in the SDK), #5665, #5916.

Your Environment

platform v5.2-dev at a7669077c5.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions