Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions packages/rs-platform-wallet-ffi/ERROR_CODE_REGISTRY.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ These are shipped ABI. Do not renumber.
| 98 | `NotFound` | Sentinel — `Option` returned as an error |
| 99 | `ErrorUnknown` | Sentinel — unmapped/flattened errors |

**Next allocatable integer: 77**: 27–76 are all claimed (27, 29, 31, 34–42
**Next allocatable integer: 82**: 27–81 are all claimed (27, 29, 31, 34–42
and 46 merged; 43–45 proposed by active #4313 at head `0302b188ab`; 47 and
48 proposed by active #4356 (47 renumbered from 42, 48 from 43 — see their
rows below); 49–54 proposed by active #4586 (the persister
Expand All @@ -128,7 +128,7 @@ renumbered from 59 when #5322 took that number on `v5.1-dev`); 61 proposed by
by open branches with no row here yet
(62 both `ErrorShieldedClaimBindingMismatch` and `ErrorIdentityRevisionMismatch`,
63–66 the invitation-claim preflight, 67 `ErrorShieldedTreeInconsistent`); 68
to 76 proposed for DashPay private contact requests; 28, 30,
to 76 proposed for DashPay private contact requests; 77–79 proposed by #5865 for the shielded spend plan; 80 proposed by #5860 for the failed recipient lookup of the external identity top-up; 81 proposed by #5924's tracked-lock identity recipient for `ErrorAssetLockRecipientUnknown`; 28, 30,
32 and 33 reserved). **28, 30,
32 and 33 are RESERVED, not free**: 28 and 30 were vacated when the
reservation trio moved to 34–36; 32 and 33 lapsed when their in-repo owners
Expand Down Expand Up @@ -192,6 +192,7 @@ Fork-era numbers remain in the collision history, which is immutable record.
| 74 | `ErrorPrivateContactStoreNotRead` | DashPay private contact requests | Proposed. Maps `PlatformWalletError::PrivateContactStoreNotRead`: DashPay's private contact request store was not read to its end for the identity, with the keys Platform proves it holds, before a contact request or acceptance, public or private, was decided (every one reads it from the identity's cursor first). Nothing was reserved, sealed, paid or broadcast; calling again continues the read from where it stopped. A node behind the store already seen, or keys that kept changing, stop it. It was reported as 71 before, which says not to submit again. Mapped by the blanket conversion and kept by the shielded spend contract (`map_spend_result`). Swift types it (`PlatformWalletError.privateContactStoreNotRead`, `ErrorHandlingTests` pin) and SwiftExampleApp offers a retry with no pending row; Kotlin types it (`DashSdkError.PlatformWallet.PrivateContactStoreNotRead`, `DashSdkErrorTest` pin) and KotlinExampleApp offers a retry with no pending row |
| 75 | `ErrorSdkPinnedBelowProtocolVersion` | DashPay private contact requests | Proposed. The SDK refused a request without sending it because the SDK itself is pinned below the protocol version the request needs (`dash_sdk::Error::ProtocolVersionNotActive` with `pinned`), whatever the network runs: for example every contact request's private store read with the SDK pinned below protocol version 15 on a network at 15. A network upgrade does not lift it; only raising or removing the pin does. Before, it shared 70 with a network proven below the version, which lifts by itself. Mapped by the blanket conversion. Swift types it (`PlatformWalletError.sdkPinnedBelowProtocolVersion`, `ErrorHandlingTests` pin) and SwiftExampleApp shows a developer-facing message; Kotlin types it (`DashSdkError.PlatformWallet.SdkPinnedBelowProtocolVersion`, `DashSdkErrorTest` pin) and KotlinExampleApp shows a developer-facing message |
| 76 | `ErrorPublicContactRequestUnconfirmed` | DashPay private contact requests | Proposed. Maps `PlatformWalletError::PublicContactRequestUnconfirmed`: a public contact request to that identity was broadcast and may have been delivered, and no proof settled its outcome yet, so the wallet holds the pair and signs nothing new to it, public or private. The send or accept that broadcast it reported 20; every later one is refused with 76 until a public contact request sync settles it (its document proved on Platform: recorded as sent; its transition proved unable to write it: the pair freed), broadcasting the same signed bytes again meanwhile. Not a private request pending (71). Mapped by the blanket conversion and by `map_spend_result`. `platform_wallet_get_public_contact_request_unconfirmed` reads the hold per pair (`DashPayView::public_contact_request_unconfirmed`; 7 for a sender the wallet does not hold). Swift types it (`PlatformWalletError.publicContactRequestUnconfirmed`, `ErrorHandlingTests` pin) and wraps the read (`ManagedPlatformWallet.publicContactRequestUnconfirmed`); SwiftExampleApp shows the pair as being checked, with no request or accept offered, until the read says settled, and its refreshes run the DashPay sync that settles it; Kotlin types it (`DashSdkError.PlatformWallet.PublicContactRequestUnconfirmed`, `DashSdkErrorTest` pin), bridges the read (`DashpayNative.publicContactRequestUnconfirmed`, `Dashpay.publicContactRequestsUnconfirmed`), and KotlinExampleApp shows the pair as SwiftExampleApp does |
| 81 | `ErrorAssetLockRecipientUnknown` | dashpay/platform#5924 (identity recipient recorded on an unbound top-up lock) | Proposed. Maps `PlatformWalletError::AssetLockRecipientUnknown`: an unbound identity top-up lock (`IdentityTopUpNotBound`) records no identity to pay — it was rebuilt from the chain, for example after a restore from the seed, and its credit output names none — so no resume pays it. Nothing was submitted or paid. Not retryable as is: the user assigns the lock a recipient (`platform_wallet_assign_identity_top_up_recipient`), after which a resume to that identity proceeds. A resume or assignment naming a different identity than the one recorded is 61, which this PR widens to identity recipients (`PlatformWalletError::AssetLockIdentityRecipientMismatch`). 77–79 are held by #5865 and 80 by #5860, neither yet on `v5.2-dev` |

**Code 31 left this table on 2026-08-04.** `ErrorSigningKeyUnavailable` sat here
as #4183's proposal until #4183 merged (`189a3abb1c`); it is now in the merged
Expand Down
19 changes: 19 additions & 0 deletions packages/rs-platform-wallet-ffi/src/asset_lock/manager.rs
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,19 @@ pub struct TrackedAssetLockFFI {
/// The raw 43-byte Orchard recipient a resume of this lock pays, valid
/// only when `has_shielded_recipient` is true (all zero otherwise).
pub shielded_recipient_raw_43: [u8; 43],
/// Whether `identity_recipient_32` carries the identity an unbound
/// identity top-up (funding type 2) pays. A resume of the lock pays that
/// identity and refuses any other.
pub has_identity_recipient: bool,
/// The identity a resume of this lock pays, valid only when
/// `has_identity_recipient` is true (all zero otherwise).
pub identity_recipient_32: [u8; 32],
/// An unbound identity top-up, not consumed, that records no identity
/// (rebuilt from the chain, for example after a restore from the seed):
/// no resume pays it until the user assigns it a recipient with
/// `platform_wallet_assign_identity_top_up_recipient`. Hosts list it
/// for the user rather than resuming it into one of their identities.
pub identity_recipient_unassigned: bool,
Comment on lines +41 to +53

@thepastaclaw thepastaclaw Nov 14, 2026 •

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.

✅ Withdrawn at 282c6df7; see the replies below.

🔴 Blocking: Tracked-lock array element strides changed without ABI negotiation

TrackedAssetLockFFI is returned as a contiguous bare-pointer array by asset_lock_manager_list_tracked_locks, and TrackedAssetLockEntryFFI is returned the same way by platform_wallet_tracked_asset_locks_list. Appending the identity-recipient fields changes sizeof and therefore the element stride. A host compiled against the previous header will index the second and later elements using the old stride, reading fields from the middle of the newer elements and potentially displaying or resuming the wrong lock. The paired free functions receive only the pointer and count, so they cannot recover the stride. The size-gated persistence extension does not protect these arrays. Preserve the existing V1 element types and add V2 list functions, or add explicit element-size/ABI negotiation.

source: gpt-6.1-sol (phase2-reviewer: general, architecture-layering, ffi-engineer, platform-versioning, rust-quality, security-auditor)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Declining, as on #5762 (#5762 (comment), withdrawn there): TrackedAssetLockFFI and TrackedAssetLockEntryFFI have no layout freeze or size negotiation, they are not part of the published persistence ABI, and their only consumers are the Swift and Kotlin SDKs built from this tree against the generated header. The appended fields are listed under Breaking Changes in the PR description.

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.

Withdrawn (re-reviewed at 282c6df7): The stated release model is sufficient for this diagnostic surface: it is not a frozen published persistence ABI, its supported Swift and Kotlin consumers rebuild against the new header, and the appended fields are explicitly called out as a host-breaking change. The separate persistence row remains size-gated.

}

/// Destroy an AssetLockManager handle.
Expand Down Expand Up @@ -95,6 +108,12 @@ pub unsafe extern "C" fn asset_lock_manager_list_tracked_locks(
has_proof: lock.proof.is_some(),
has_shielded_recipient: lock.shielded_recipient.is_some(),
shielded_recipient_raw_43: lock.shielded_recipient.unwrap_or([0; 43]),
has_identity_recipient: lock.identity_recipient.is_some(),
identity_recipient_32: lock
.identity_recipient
.map(|identity| identity.to_buffer())
.unwrap_or([0; 32]),
identity_recipient_unassigned: lock.is_unassigned_identity_top_up(),
}
})
.collect();
Expand Down
12 changes: 12 additions & 0 deletions packages/rs-platform-wallet-ffi/src/asset_lock/sync.rs
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,18 @@ fn parse_outpoint(txid: *const [u8; 32], vout: u32) -> dashcore::OutPoint {
/// the next stage's responsibility (e.g.
/// [`crate::platform_wallet_register_identity_with_funding_signer`]).
///
/// # Recorded recipients
///
/// This export hands back the proof and key path of any tracked lock, with
/// no check of whom the lock was built to pay. A lock that records a
/// recipient (`has_identity_recipient` / `has_shielded_recipient` on the
/// tracked-lock lists) must be consumed only for that recipient: the record
/// is wallet policy, not something the signature enforces, and whoever holds
/// the key can sign the lock to anyone. To top up an identity from a tracked
/// lock, use
/// [`crate::platform_wallet_resume_identity_top_up_to_recorded_recipient_signer`],
/// which pays the identity the lock records and no other.
///
/// # Timeouts
///
/// `timeout_secs` bounds only the stages that still have to WAIT for a
Expand Down
12 changes: 12 additions & 0 deletions packages/rs-platform-wallet-ffi/src/core_wallet_types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -935,6 +935,18 @@ pub struct TrackedAssetLockEntryFFI {
pub registration_index: u32,
pub instant_lock_present: bool,
pub chain_lock_height: u32,
/// Whether `identity_recipient` carries the identity an unbound identity
/// top-up (lock type 2) pays. A resume pays that identity and refuses any
/// other, the host's own identities included.
pub has_identity_recipient: bool,
/// Valid only when `has_identity_recipient` is true (all zero otherwise).
pub identity_recipient: [u8; 32],
/// An unbound identity top-up, not consumed, recording no identity
/// (rebuilt from the chain, for example after a restore from the seed).
/// No resume pays it; a host lists it for the user, who assigns a
/// recipient with `platform_wallet_assign_identity_top_up_recipient`,
/// rather than resuming it into one of the host's identities.
pub identity_recipient_unassigned: bool,
}

/// Snapshot of the per-account metadata for one account. Strings are
Expand Down
75 changes: 74 additions & 1 deletion packages/rs-platform-wallet-ffi/src/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -654,6 +654,11 @@ pub enum PlatformWalletFFIResultCode {
/// was submitted and nothing was paid; resume with the recorded recipient
/// (the row exposes it). Rows tracked before the recipient was recorded
/// carry none and accept the caller's.
///
/// Also an unbound identity top-up lock resumed (or assigned) to a
/// different identity than the one its row recorded
/// (`PlatformWalletError::AssetLockIdentityRecipientMismatch`): nothing
/// was submitted; resume to the recorded identity, which the row exposes.
ErrorAssetLockRecipientMismatch = 61,

/// Maps `PlatformWalletError::PrivateContactRequestNeedsPrivateReply`:
Expand Down Expand Up @@ -768,6 +773,16 @@ pub enum PlatformWalletFFIResultCode {
/// [`Self::ErrorPrivateContactRequestPending`] (71).
ErrorPublicContactRequestUnconfirmed = 76,

/// Maps `PlatformWalletError::AssetLockRecipientUnknown`: an unbound
/// identity top-up lock records no identity to pay (it was rebuilt from
/// the chain, for example after a restore from the seed, and its credit
/// output names none), so no resume pays it: it may have been meant for
/// someone else's identity. Nothing was submitted or paid. Not retryable
/// as is: the funds stay recoverable once the user assigns the lock a
/// recipient (`platform_wallet_assign_identity_top_up_recipient`),
/// after which a resume to that identity proceeds.
ErrorAssetLockRecipientUnknown = 81,

/// The named thing does not exist.
///
/// Originally (and still mostly) the code for every `Option` returned as an
Expand Down Expand Up @@ -1064,6 +1079,12 @@ impl From<PlatformWalletError> for PlatformWalletFFIResult {
PlatformWalletError::IdentityNotFound(..) => {
PlatformWalletFFIResultCode::ErrorIdentityNotFound
}
// A bound top-up lock whose identity (at its registration index)
// is not loaded yet: the identity is not found locally, and
// nothing was submitted.
PlatformWalletError::AssetLockIdentityNotLoaded { .. } => {
PlatformWalletFFIResultCode::ErrorIdentityNotFound
}
// The two shielded broadcast/wait variants. Today nothing routes
// them through this blanket impl — the dedicated match in
// `platform_wallet_manager_shielded_identity_create_from_pool`
Expand Down Expand Up @@ -1218,9 +1239,13 @@ impl From<PlatformWalletError> for PlatformWalletFFIResult {
PlatformWalletError::AssetLockTooManyInputs { .. } => {
PlatformWalletFFIResultCode::ErrorAssetLockTooManyInputs
}
PlatformWalletError::AssetLockRecipientMismatch { .. } => {
PlatformWalletError::AssetLockRecipientMismatch { .. }
| PlatformWalletError::AssetLockIdentityRecipientMismatch { .. } => {
PlatformWalletFFIResultCode::ErrorAssetLockRecipientMismatch
}
PlatformWalletError::AssetLockRecipientUnknown(..) => {
PlatformWalletFFIResultCode::ErrorAssetLockRecipientUnknown
}
// A quiesce/drain barrier that did not complete within budget
// (clear/reset paths). The host must fail closed: keep its
// callback context alive and skip any paired persistence wipe.
Expand Down Expand Up @@ -2600,6 +2625,54 @@ mod tests {
assert!(message.contains(&hex::encode(recorded)));
}

#[test]
fn should_map_an_unbound_top_up_resumed_to_another_identity_to_61() {
let recorded = dpp::prelude::Identifier::from([1u8; 32]);
let result: PlatformWalletFFIResult =
PlatformWalletError::AssetLockIdentityRecipientMismatch {
out_point: dashcore::OutPoint::null(),
recorded,
requested: dpp::prelude::Identifier::from([2u8; 32]),
}
.into();
assert_eq!(
result.code,
PlatformWalletFFIResultCode::ErrorAssetLockRecipientMismatch
);
assert!(message_of(&result).contains(&format!("{recorded}")));
}

/// A bound top-up lock whose identity the wallet has not loaded yet
/// crosses as "identity not found": nothing was submitted.
#[test]
fn should_report_a_bound_lock_without_its_identity_as_identity_not_found() {
let result: PlatformWalletFFIResult = PlatformWalletError::AssetLockIdentityNotLoaded {
out_point: dashcore::OutPoint::null(),
identity_index: 3,
}
.into();
assert_eq!(
result.code,
PlatformWalletFFIResultCode::ErrorIdentityNotFound
);
assert!(message_of(&result).contains("index 3"));
}

#[test]
fn should_pin_the_unassigned_unbound_top_up_code_at_81() {
assert_eq!(
PlatformWalletFFIResultCode::ErrorAssetLockRecipientUnknown as i32,
81
);
let result: PlatformWalletFFIResult =
PlatformWalletError::AssetLockRecipientUnknown(dashcore::OutPoint::null()).into();
assert_eq!(
result.code,
PlatformWalletFFIResultCode::ErrorAssetLockRecipientUnknown
);
assert!(message_of(&result).contains("assign a recipient"));
}

#[test]
fn asset_lock_input_conflict_code_is_pinned_at_47() {
use dashcore::OutPoint;
Expand Down
Loading
Loading