feat(swift-sdk): send, receive and accept DashPay private contact requests

packages/rs-platform-wallet-ffi/ERROR_CODE_REGISTRY.md

@@ -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: 61** — 27–60 are all claimed (27, 29, 31, 34–42
+**Next allocatable integer: 72**: 27–71 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
@@ -123,7 +123,11 @@ shield debits and durable recovery errors; 58 proposed by #4799 for an unavailab
 identity balance response; 59 proposed by #5322 for an SPV
 teardown that needs a process restart; 60 proposed by the pooled Core-to-shielded
 wallet drain for `ErrorAssetLockTooManyInputs` (Rust, Swift and Kotlin mirrors —
-renumbered from 59 when #5322 took that number on `v5.1-dev`); 28, 30,
+renumbered from 59 when #5322 took that number on `v5.1-dev`); 61–67 held
+by open branches with no row here yet (61 `ErrorAssetLockRecipientMismatch`,
+62 both `ErrorShieldedClaimBindingMismatch` and `ErrorIdentityRevisionMismatch`,
+63–66 the invitation-claim preflight, 67 `ErrorShieldedTreeInconsistent`); 68
+to 71 proposed for DashPay private contact requests; 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
@@ -177,6 +181,10 @@ Fork-era numbers remain in the collision history, which is immutable record.
 | 58 | `ErrorIdentityBalanceUnavailable` | #4799 | Proposed — Platform returned no balance for a managed identity. Retrying the read is safe; this is distinct from missing wallet ownership and must not trigger registration or funding |
 | 59 | `ErrorSpvProcessRestartRequired` | #5322 | Proposed — SPV startup or teardown panicked; restart the host process. Not retryable, unlike 27, which SPV start, stop and storage clear now return while an SPV teardown is still running. Typed in Rust, Swift and Kotlin (the PR also types 27 on Kotlin) |
 | 60 | `ErrorAssetLockTooManyInputs` | Core-to-shielded pooled Max | Proposed — an asset lock needs more inputs than one may carry (100 on Dash Core relay policy and Platform consensus): the full drain, or since #5712 a fixed amount held only in many small coins (identity registration, top-up, invitation, platform-address funding). Two meanings. On a build: nothing was broadcast, the reservation is released, no partial drain, and a rebuild after consolidating is safe. On the resume of a tracked `Built` / `Broadcast` lock over the cap (since #5714): it is not re-sent, but an earlier attempt may have reached peers; the row stays tracked and nothing is released. Rust, Swift and Kotlin retain the typed refusal. Renumbered from 59 after #5322 claimed it |
+| 68 | `ErrorPrivateContactRequestNeedsPrivateReply` | DashPay private contact requests (FFI and Swift) | Proposed. The contact requests with that identity came or went privately (protocol version 15), so a `contactRequest` document to it, in reply or as a rotation, would publish the relationship: the public accept refuses a reply, and the public send refuses a request or a rotation. Nothing was sent; the host accepts with `platform_wallet_manager_accept_contact_request_replying_in_kind` (which picks the reply itself, so a host calling it does not route on 68) or `platform_wallet_manager_accept_private_contact_request`, or sends with `platform_wallet_manager_send_private_contact_request`. Taken above 61–67, which open branches already hold. Rust and Swift (raw case, `init(ffi:)` arm, typed `PlatformWalletError.privateContactRequestNeedsPrivateReply` and an `ErrorHandlingTests` pin) carry it; Kotlin falls through to `PlatformWallet.Generic`, which keeps the integer |
+| 69 | `ErrorShieldedBuildRequired` | DashPay private contact requests (FFI, Swift and Kotlin) | Proposed. The operation needs the shielded pool and the library was built without the `shielded` feature. Today only `platform_wallet_manager_accept_contact_request_replying_in_kind`, exported in every build, returns it, for a request that came privately: its private reply is paid from the pool. Nothing was sent; a public or adopted reply works on such a build. Not retryable on the same build. No existing code meant "shielded unsupported" (`ErrorWalletOperation` with a not-configured message is a runtime state of a shielded build), so it takes the next free number. Swift (raw case, `init(ffi:)` arm, typed `PlatformWalletError.shieldedBuildRequired`, `ErrorHandlingTests` pin) and Kotlin (`DashSdkError.PlatformWallet.ShieldedBuildRequired`, `DashSdkErrorTest` pin) type it |
+| 70 | `ErrorProtocolVersionNotActive` | DashPay private contact requests (FFI, Swift and Kotlin) | Proposed. The SDK refused a request without sending it (`dash_sdk::Error::ProtocolVersionNotActive`), because the network is proven at a protocol version below the one that serves it or the SDK is pinned below it: for example the private contact request sync on a network before protocol version 15. Expected on such a network, so a host may stay quiet about it; it lifts when the network upgrades. Mapped by the blanket conversion for every operation that propagates the SDK error. A refusal that may lift sooner (`is_transient_protocol_version_refusal`: the network's version could not be confirmed) keeps the catch-all `ErrorUnknown`, as before. Previously both fell to `ErrorUnknown`. Swift (`PlatformWalletError.protocolVersionNotActive`) and Kotlin (`DashSdkError.PlatformWallet.ProtocolVersionNotActive`) type it |
+| 71 | `ErrorPrivateContactRequestPending` | DashPay private contact requests (FFI, Swift and Kotlin) | Proposed. Maps `PlatformWalletError::PrivateContactRequestPending`: a private contact request to that identity is in flight (another private send or reply reserved it before sealing), or was paid for and a short read-back sync did not find the entry in the store yet; or the identity's private store could not be read to its end before its first private send or accept since load, which the wallet reads first so that a reply paid for in an earlier process is adopted rather than paid for again. Nothing new was paid; a later private contact request sync, or a retry, settles it. Pending, not failed: the host must not submit it again. Returned by the private send, the private accept and the in-kind accept; the shielded spend contract (`map_spend_result`) keeps the code rather than flattening it to `ErrorWalletOperation`. Swift (`PlatformWalletError.privateContactRequestPending`, `ErrorHandlingTests` pin) and Kotlin (`DashSdkError.PlatformWallet.PrivateContactRequestPending`, `DashSdkErrorTest` pin) type it, and both example apps keep the submission pending |
 
 **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

packages/rs-platform-wallet-ffi/src/contact_persistence.rs

@@ -214,6 +214,46 @@ pub struct ContactIgnoredSenderFFI {
     pub is_ignored: bool,
 }
 
+/// One identity's read position in DashPay's private contact request store
+/// ([`ContactChangeSet::private_contact_requests_positions`]), for the
+/// private contact request scan state callbacks on
+/// [`PersistenceCallbacksExtension`](crate::persistence::PersistenceCallbacksExtension).
+///
+/// Flat POD. The host stores one row per `(wallet_id, identity_id)`,
+/// replacing the previous one, and hands it back unchanged at load: a lower
+/// `position` than the stored one is a rewind, not a stale write.
+///
+/// [`ContactChangeSet::private_contact_requests_positions`]: platform_wallet::changeset::ContactChangeSet::private_contact_requests_positions
+#[repr(C)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PrivateContactRequestsPositionFFI {
+    /// The wallet-owned identity reading the store.
+    pub identity_id: [u8; 32],
+    /// The store position the identity reads from next.
+    pub position: u64,
+    /// The fingerprint of the scanning keys `position` holds for. Opaque
+    /// to the host: store it and return it as it came.
+    pub key_fingerprint: [u8; 32],
+}
+
+/// The shielded address `contact_id`'s tracked private request to
+/// `owner_id` carries ([`ContactChangeSet::private_shielded_addresses`]).
+///
+/// Flat POD. The host stores one row per `(wallet_id, owner_id,
+/// contact_id)`, replacing the previous one.
+///
+/// [`ContactChangeSet::private_shielded_addresses`]: platform_wallet::changeset::ContactChangeSet::private_shielded_addresses
+#[repr(C)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PrivateShieldedAddressFFI {
+    /// The wallet-owned identity the request is to.
+    pub owner_id: [u8; 32],
+    /// The contact who sent the request.
+    pub contact_id: [u8; 32],
+    /// The raw 43-byte Orchard payment address.
+    pub address: [u8; 43],
+}
+
 // Compile-time guards. Pin the expected layouts so any reshape on
 // the Rust side fails the cargo build before it can ship a dylib
 // the Swift side will mis-parse at runtime.

packages/rs-platform-wallet-ffi/src/dashpay.rs

@@ -190,7 +190,7 @@ impl ContactRequestHandleArray {
     }
 
     /// Copy a slice of contact requests into the global handle storage.
-    fn from_requests(requests: Vec<ContactRequest>) -> Self {
+    pub(crate) fn from_requests(requests: Vec<ContactRequest>) -> Self {
         if requests.is_empty() {
             return Self::empty();
         }
@@ -325,22 +325,9 @@ pub unsafe extern "C" fn platform_wallet_send_contact_request_with_signer(
     } else {
         Some(unwrap_result_or_return!(CStr::from_ptr(account_label).to_str()).to_string())
     };
-    let proof: Option<Vec<u8>> = if auto_accept_proof.is_null() || auto_accept_proof_len == 0 {
-        None
-    } else {
-        // Defense-in-depth: bound the copy at the DIP-15 auto-accept proof
-        // ceiling (102 bytes) BEFORE allocating, so a malformed binding or a
-        // hostile (ptr, len) pair can't force an oversized allocation. The SDK
-        // re-validates the exact 38..=102 range after this.
-        if auto_accept_proof_len > 102 {
-            return crate::error::PlatformWalletFFIResult::err(
-                crate::error::PlatformWalletFFIResultCode::ErrorInvalidParameter,
-                format!(
-                    "auto_accept_proof length {auto_accept_proof_len} exceeds the DIP-15 maximum of 102 bytes"
-                ),
-            );
-        }
-        Some(std::slice::from_raw_parts(auto_accept_proof, auto_accept_proof_len).to_vec())
+    let proof = match read_auto_accept_proof(auto_accept_proof, auto_accept_proof_len) {
+        Ok(proof) => proof,
+        Err(result) => return result,
     };
 
     let signer_addr = signer_handle as usize;
@@ -380,6 +367,31 @@ pub unsafe extern "C" fn platform_wallet_send_contact_request_with_signer(
     PlatformWalletFFIResult::ok()
 }
 
+/// Copy an optional auto-accept proof from `(ptr, len)`; `(null, 0)` omits it.
+///
+/// Defense-in-depth: the copy is bounded at the DIP-15 auto-accept proof
+/// ceiling (102 bytes) BEFORE allocating, so a malformed binding or a hostile
+/// (ptr, len) pair can't force an oversized allocation. The SDK re-validates
+/// the exact 38..=102 range after this.
+///
+/// # Safety
+/// A non-null `ptr` must point to `len` readable bytes.
+pub(crate) unsafe fn read_auto_accept_proof(
+    ptr: *const u8,
+    len: usize,
+) -> Result<Option<Vec<u8>>, PlatformWalletFFIResult> {
+    if ptr.is_null() || len == 0 {
+        return Ok(None);
+    }
+    if len > 102 {
+        return Err(PlatformWalletFFIResult::err(
+            PlatformWalletFFIResultCode::ErrorInvalidParameter,
+            format!("auto_accept_proof length {len} exceeds the DIP-15 maximum of 102 bytes"),
+        ));
+    }
+    Ok(Some(std::slice::from_raw_parts(ptr, len).to_vec()))
+}
+
 /// Send a contact request from a scanned DIP-15 auto-accept QR
 /// (`dash:?du=<username>&dapk=<key_blob>`). Resolves the QR's username to the
 /// owner's identity, decodes the handed auto-accept key, signs the proof over
@@ -1752,6 +1764,83 @@ pub unsafe extern "C" fn platform_wallet_drainable_contact_crypto_count(
 mod tests {
     use super::*;
 
+    mod private_store_scan_errors {
+        use super::*;
+        use platform_wallet::ContactCryptoProvider;
+        use rs_sdk_ffi::{
+            dash_sdk_mnemonic_resolver_create, dash_sdk_mnemonic_resolver_destroy,
+            mnemonic_resolver_result,
+        };
+        use std::ffi::c_void;
+        use std::str::FromStr;
+
+        unsafe extern "C" fn no_mnemonic(
+            _ctx: *const c_void,
+            _wallet_id_bytes: *const u8,
+            _out_buf: *mut c_char,
+            _out_capacity: usize,
+            _out_len: *mut usize,
+        ) -> i32 {
+            mnemonic_resolver_result::NOT_FOUND
+        }
+
+        unsafe extern "C" fn noop_destroy(_ctx: *mut c_void) {}
+
+        /// A scan of the private store whose resolver holds no mnemonic for the
+        /// wallet reaches the host as the key-unavailable outcome (code 31), as
+        /// a signer's missing key does, so the host routes it to key repair
+        /// instead of reading a generic failure.
+        #[test]
+        fn should_report_a_missing_mnemonic_while_scanning_as_key_unavailable() {
+            let resolver = unsafe {
+                dash_sdk_mnemonic_resolver_create(std::ptr::null_mut(), no_mnemonic, noop_destroy)
+            };
+            let provider = unsafe {
+                resolver_contact_crypto_provider(resolver, [0u8; 32], key_wallet::Network::Testnet)
+            };
+            let keys = PrivateDocumentKeyPaths {
+                recipients: vec![(
+                    Identifier::from([0xB0; 32]),
+                    vec![(
+                        2,
+                        key_wallet::bip32::DerivationPath::from_str("m/9'/1'/5'/0'/0'/1'/2'")
+                            .expect("valid path"),
+                    )],
+                )],
+                senders: Vec::new(),
+            };
+            let page = PrivateDocumentEntries {
+                entries: Vec::new(),
+                total_count: 0,
+            };
+            let error = runtime()
+                .block_on(provider.scan_private_document_page(
+                    &keys,
+                    Identifier::from([0xD0; 32]),
+                    "privateContactRequest",
+                    0,
+                    &page,
+                ))
+                .expect_err("no mnemonic, no keys");
+            let result = PlatformWalletFFIResult::from(error);
+            assert_eq!(
+                result.code,
+                PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable
+            );
+
+            // Another resolver failure keeps the code it had.
+            let other = PlatformWalletFFIResult::from(private_document_signer_error(
+                MnemonicResolverSignerError::BufferTooSmall,
+            ));
+            assert_ne!(
+                other.code,
+                PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable
+            );
+
+            unsafe { dash_sdk_mnemonic_resolver_destroy(resolver) };
+        }
+    }
+
     /// A test wallet's mnemonic, counting how often the resolver reads it.
     unsafe extern "C" fn counting_resolve(
         ctx: *const std::ffi::c_void,