feat(sdk-ffi): structured SigningKeyUnavailable discriminator across the signer wire

Replace end-to-end message sniffing for the signer's "missing key" failure
with a typed discriminator (dashpay#4060 finding 7):

- rs-sdk-ffi: DashSDKSignerErrorCode { Generic = 0, SigningKeyUnavailable =
  1, AuthenticationFailed = 2 (reserved) }; SignCompletionCallback and
  dash_sdk_sign_async_completion gain error_code: i32 (before
  error_message). SignResult stays Result<Vec<u8>, ProtocolError> (a new
  rs-dpp ProtocolError variant would carry serialization blast radius), so
  code 1 rides the single Rust-owned machine prefix
  DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX through
  ProtocolError::Generic — typed at both ABI edges, one constant bridging
  the string segment. This is an internal coordinated ABI change: every
  piece versions together in this monorepo.
- rs-platform-wallet-ffi: PlatformWalletFFIResultCode::
  ErrorSigningKeyUnavailable = 31 (codes 26-28 are reserved for dashpay#4185's
  reservation-token errors and 29/30 for dashpay#4184's asset-lock errors on
  sibling branches — documented in the enum as dashpay#4184 does). The
  From<dpp::ProtocolError> conversion restores the typed code from the
  prefix FIRST (before the loose keyword sniffs), and the
  From<PlatformWalletError> blanket impl restores it on the catch-all only
  (dedicated retry-semantics codes are never overridden) — covering the
  Sdk(dash_sdk::Error::Protocol(..)) wrapping path.
- JNI/Kotlin: SignerNative.completeSign(token, signature, errorCode,
  errorMessage); KeystoreSigner passes SIGNER_ERROR_CODE_KEY_UNAVAILABLE on
  the null-key branch (keeping the MESSAGE_MARKER text for the transition
  window) and Generic everywhere else. DashSdkError maps 31 →
  PlatformWallet.SigningKeyUnavailable; the dashpay#4191 marker sniff on the
  catch-all codes remains as a deprecated old-native fallback with a
  removal note tied to the next minor release.
- Swift: KeychainSigner trampolines forward the code (missing-row /
  missing-scalar outcomes classify as 1); PlatformWalletResultCode gains
  errorSigningKeyUnavailable = 31 → PlatformWalletError
  .signingKeyUnavailable (Kotlin parity).
- Tests: rs-sdk-ffi completion-code tests (prefix present for code 1,
  absent for generic), platform-wallet-ffi prefix→31 tests on both
  conversion points, Kotlin code-31 + fallback-marker tests, Swift mapping
  and trampoline-classifier tests.

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

Author: bfoss765

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt

@@ -182,12 +182,13 @@ sealed class DashSdkError(
          * is missing (never derived, wiped, or written under a different
          * Keystore alias/policy) rather than the operation itself failing.
          *
-         * Signing failures originate as free text in
-         * `KeystoreSigner.completeSign` (the "[MESSAGE_MARKER] <pubkeyHex>"
-         * string), travel through Rust, and come back under the catch-all
-         * platform-wallet codes; [fromPlatformWalletNative] recognizes the
-         * marker on the Kotlin boundary and surfaces this typed error so
-         * hosts can route users to key repair (e.g.
+         * Primary path (dashpay/platform#4060 finding 7): `KeystoreSigner`
+         * completes with the STRUCTURED
+         * `SignerNative.SIGNER_ERROR_CODE_KEY_UNAVAILABLE`, which travels
+         * typed across the Rust boundary and returns as
+         * `PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable` (31) —
+         * mapped directly here, no message inspection involved. Hosts route
+         * users to key repair (e.g.
          * `PlatformWalletManager.repairIdentityKey`) instead of treating it
          * as an opaque [Generic] failure. Not retryable as-is — the key must
          * be (re-)derived first.
@@ -197,9 +198,17 @@ sealed class DashSdkError(
             companion object {
                 /**
                  * Stable prefix of the `KeystoreSigner` "missing key"
-                 * completion error. `KeystoreSigner` builds its message from
-                 * this constant, so the emitter and the matcher cannot
-                 * drift.
+                 * completion error message. `KeystoreSigner` builds its
+                 * message from this constant, so the emitter and the matcher
+                 * cannot drift.
+                 *
+                 * DEPRECATED as a discriminator: superseded by the typed
+                 * code-31 mapping above; the marker match is retained only
+                 * for the transition window where an old native library
+                 * (pre-code-31) is paired with new Kotlin during partial
+                 * builds. Remove the fallback (and this constant's matcher
+                 * role) in the next minor release once the native artifacts
+                 * are guaranteed current.
                  */
                 const val MESSAGE_MARKER = "no private key stored for"
             }
@@ -280,11 +289,13 @@ sealed class DashSdkError(
          * [PlatformWallet] subtree — mirror of Swift's
          * `PlatformWalletError(result:)` construction. Retry-semantics-bearing
          * codes get dedicated types; the rest fall through to
-         * [PlatformWallet.Generic] — except the `KeystoreSigner` "missing
-         * key" completion error, which travels as free text through Rust and
-         * is recognized by its [PlatformWallet.SigningKeyUnavailable]
-         * message marker here (only on the catch-all codes, so the dedicated
-         * retry-semantics types are never overridden).
+         * [PlatformWallet.Generic]. The `KeystoreSigner` "missing key"
+         * completion arrives TYPED as code 31
+         * (`ErrorSigningKeyUnavailable`, dashpay/platform#4060 finding 7);
+         * the legacy message-marker sniff on the catch-all codes is a
+         * deprecated transition fallback for old native libraries (never
+         * applied to the dedicated retry-semantics types, so those are
+         * never overridden).
          */
         private fun fromPlatformWalletNative(
             code: Int,
@@ -294,6 +305,10 @@ sealed class DashSdkError(
             // PlatformWalletFFIResultCode variants (platform-wallet-ffi/src/error.rs)
             1 -> PlatformWallet.InvalidHandle(message, cause) // ErrorInvalidHandle
             6 -> // ErrorWalletOperation
+                // @Deprecated fallback: the marker sniff survives only for
+                // old-native/new-Kotlin partial builds; the typed code 31
+                // below is the real discriminator (#4060 finding 7). Remove
+                // with MESSAGE_MARKER's matcher role next minor release.
                 if (isSigningKeyUnavailable(message)) {
                     PlatformWallet.SigningKeyUnavailable(message, cause)
                 } else {
@@ -321,7 +336,15 @@ sealed class DashSdkError(
             23 -> PlatformWallet.AssetLockNotTracked(message, cause) // ErrorAssetLockNotTracked
             24 -> PlatformWallet.AssetLockAlreadyConsumed(message, cause) // ErrorAssetLockAlreadyConsumed
             25 -> PlatformWallet.AssetLockFundingMismatch(message, cause) // ErrorAssetLockFundingMismatch
+            // ErrorSigningKeyUnavailable — the STRUCTURED signer
+            // discriminator (dashpay/platform#4060 finding 7): the typed
+            // completion code rides the whole Rust round-trip, no message
+            // sniffing involved. (Codes 26-30 are reserved by sibling PRs
+            // #4185 / #4184 — see PlatformWalletFFIResultCode.)
+            31 -> PlatformWallet.SigningKeyUnavailable(message, cause)
             else ->
+                // @Deprecated fallback — see the code-6 arm; code 31 is the
+                // real discriminator.
                 if (isSigningKeyUnavailable(message)) {
                     PlatformWallet.SigningKeyUnavailable(message, cause)
                 } else {

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/SignerNative.kt

@@ -6,6 +6,22 @@ package org.dashfoundation.dashsdk.ffi
  */
 internal object SignerNative {
 
+    /**
+     * `DashSDKSignerErrorCode::Generic` — unclassified signing failure
+     * (the historical behavior). Mirrors `rs-sdk-ffi/src/signer.rs`.
+     */
+    const val SIGNER_ERROR_CODE_GENERIC = 0
+
+    /**
+     * `DashSDKSignerErrorCode::SigningKeyUnavailable` — the signer has no
+     * usable private key for the requested public key; the operation itself
+     * did not fail. Travels typed across the completion ABI and comes back
+     * as `PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable` (31) →
+     * `DashSdkError.PlatformWallet.SigningKeyUnavailable`
+     * (dashpay/platform#4060 finding 7). Mirrors `rs-sdk-ffi/src/signer.rs`.
+     */
+    const val SIGNER_ERROR_CODE_KEY_UNAVAILABLE = 1
+
     /** Create a native `SignerHandle` backed by [bridge] (held as GlobalRef). */
     external fun createSigner(bridge: NativeSignerBridge): Long
 
@@ -14,9 +30,16 @@ internal object SignerNative {
 
     /**
      * Complete an in-flight sign request. Exactly once per token; pass
-     * either a signature or an error message.
+     * either a signature or an error message. [errorCode] is a
+     * `DashSDKSignerErrorCode` discriminant classifying a failure
+     * ([SIGNER_ERROR_CODE_GENERIC] when unclassified; ignored on success).
      */
-    external fun completeSign(token: Long, signature: ByteArray?, errorMessage: String?)
+    external fun completeSign(
+        token: Long,
+        signature: ByteArray?,
+        errorCode: Int,
+        errorMessage: String?,
+    )
 
     /**
      * One-shot ECDSA sign: raw 32-byte private key + payload → signature,

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/KeystoreSigner.kt

@@ -84,6 +84,7 @@ class KeystoreSigner(
                 SignerNative.completeSign(
                     completionToken,
                     null,
+                    SignerNative.SIGNER_ERROR_CODE_GENERIC,
                     e.message ?: "signing failed",
                 )
             }
@@ -101,23 +102,37 @@ class KeystoreSigner(
             val storageKey = storageKeyFor(pubkeyBytes)
             key = retrieveKeyWithAuth(storageKey)
             if (key == null) {
-                // Built from the shared marker so the error survives the
-                // Rust round-trip and comes back typed as
-                // DashSdkError.PlatformWallet.SigningKeyUnavailable (the
-                // fromPlatformWalletNative message match) instead of Generic.
+                // The typed SIGNER_ERROR_CODE_KEY_UNAVAILABLE rides the
+                // completion ABI and comes back as platform-wallet code 31 →
+                // DashSdkError.PlatformWallet.SigningKeyUnavailable
+                // (dashpay/platform#4060 finding 7). The MESSAGE_MARKER text
+                // is ALSO kept during the transition window so an old native
+                // library paired with new Kotlin (partial builds) still maps
+                // via the deprecated message fallback.
                 SignerNative.completeSign(
                     completionToken,
                     null,
+                    SignerNative.SIGNER_ERROR_CODE_KEY_UNAVAILABLE,
                     "${DashSdkError.PlatformWallet.SigningKeyUnavailable.MESSAGE_MARKER} " +
                         "${storageKey.take(16)}…",
                 )
                 return
             }
             val signature = SignerNative.signWithPrivateKey(key, network.ffiValue, data)
             if (signature != null) {
-                SignerNative.completeSign(completionToken, signature, null)
+                SignerNative.completeSign(
+                    completionToken,
+                    signature,
+                    SignerNative.SIGNER_ERROR_CODE_GENERIC,
+                    null,
+                )
             } else {
-                SignerNative.completeSign(completionToken, null, "signing returned no data")
+                SignerNative.completeSign(
+                    completionToken,
+                    null,
+                    SignerNative.SIGNER_ERROR_CODE_GENERIC,
+                    "signing returned no data",
+                )
             }
         } finally {
             key?.fill(0)
@@ -146,6 +161,7 @@ class KeystoreSigner(
             SignerNative.completeSign(
                 completionToken,
                 null,
+                SignerNative.SIGNER_ERROR_CODE_GENERIC,
                 "no platform address row for $hashHex",
             )
             return
@@ -157,6 +173,7 @@ class KeystoreSigner(
             SignerNative.completeSign(
                 completionToken,
                 null,
+                SignerNative.SIGNER_ERROR_CODE_GENERIC,
                 "no signable platform address row for $hashHex " +
                     "(no candidate has both a derivation path and a stored mnemonic)",
             )
@@ -170,6 +187,7 @@ class KeystoreSigner(
             SignerNative.completeSign(
                 completionToken,
                 null,
+                SignerNative.SIGNER_ERROR_CODE_GENERIC,
                 "no mnemonic stored for wallet of platform address $hashHex",
             )
             return
@@ -183,9 +201,19 @@ class KeystoreSigner(
             SignerNative.signWithMnemonicAndPathInto(m, path, net, payload)
         }
         if (signature != null) {
-            SignerNative.completeSign(completionToken, signature, null)
+            SignerNative.completeSign(
+                completionToken,
+                signature,
+                SignerNative.SIGNER_ERROR_CODE_GENERIC,
+                null,
+            )
         } else {
-            SignerNative.completeSign(completionToken, null, "signing returned no data")
+            SignerNative.completeSign(
+                completionToken,
+                null,
+                SignerNative.SIGNER_ERROR_CODE_GENERIC,
+                "signing returned no data",
+            )
         }
     }
 

packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt

@@ -128,14 +128,29 @@ class DashSdkErrorTest {
         assertFalse("Generic platform-wallet errors are not retryable", mapped.isRetryable)
     }
 
+    @Test
+    fun signingKeyUnavailableCode31MapsTyped() {
+        // The STRUCTURED discriminator (dashpay/platform#4060 finding 7):
+        // PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable (31) maps
+        // to the typed error on the code alone — no message inspection.
+        val offset = DashSdkError.PLATFORM_WALLET_CODE_OFFSET
+        val mapped = DashSdkError.fromNative(
+            DashSDKException(offset + 31, "arbitrary human text, no marker"),
+        )
+        assertTrue(mapped is DashSdkError.PlatformWallet.SigningKeyUnavailable)
+        assertFalse(mapped.isRetryable)
+    }
+
     @Test
     fun signingKeyUnavailableIsRecognizedByItsMessageMarker() {
         val offset = DashSdkError.PLATFORM_WALLET_CODE_OFFSET
         val marker = DashSdkError.PlatformWallet.SigningKeyUnavailable.MESSAGE_MARKER
-        // The KeystoreSigner completion error travels as free text through
-        // Rust and returns under the catch-all codes (ErrorUnknown = 99 via
-        // the blanket PlatformWalletError conversion, sometimes wrapped as
-        // ErrorWalletOperation = 6) — both must surface typed (#4052).
+        // DEPRECATED transition fallback: an OLD native library (pre the
+        // typed code 31) still returns the completion error as free text
+        // under the catch-all codes (ErrorUnknown = 99 via the blanket
+        // PlatformWalletError conversion, sometimes wrapped as
+        // ErrorWalletOperation = 6) — both must keep surfacing typed until
+        // the fallback's removal (#4052, #4060 finding 7).
         for (code in intArrayOf(6, 99)) {
             val mapped = DashSdkError.fromNative(
                 DashSDKException(offset + code, "Signing failed: $marker deadbeef00112233…"),

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

@@ -168,6 +168,27 @@ pub enum PlatformWalletFFIResultCode {
     /// Existing-lock recovery attempted to use a lock for the wrong funding
     /// family or bound identity index.
     ErrorAssetLockFundingMismatch = 25,
+    // Codes 26-28 are reserved: the deferred-payment reservation-token errors
+    // (ErrorStaleReservationToken / ErrorReservationTokenConsumed /
+    // ErrorReservationWalletMismatch) claim them on the split-build-broadcast
+    // branch (dashpay/platform#4185), and 29/30 belong to the asset-lock
+    // funding errors (ErrorAssetLockInsufficientFunds /
+    // ErrorAssetLockCrossDomainConsentRequired) on the multi-account branch
+    // (dashpay/platform#4184); allocating any of them here too would merge
+    // without textual conflict and silently misclassify across hosts.
+    /// A state transition could not be signed because the signer has no
+    /// usable private key for the requested public key — the stored blob is
+    /// missing, stranded, or written under a different Keystore/Keychain
+    /// alias — rather than the operation itself failing. Restored from the
+    /// typed signer completion code
+    /// ([`rs_sdk_ffi::DashSDKSignerErrorCode::SigningKeyUnavailable`]) via
+    /// the stable machine prefix
+    /// [`rs_sdk_ffi::DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX`] riding the
+    /// `ProtocolError::Generic` segment (dashpay/platform#4060 finding 7).
+    /// Hosts route this to key repair instead of treating it as an opaque
+    /// wallet-operation failure. Not retryable as-is — the key must be
+    /// (re-)derived first.
+    ErrorSigningKeyUnavailable = 31,
 
     NotFound = 98, // Used exclusively for all the Option that are retuned as errors
     ErrorUnknown = 99,
@@ -329,6 +350,19 @@ impl From<PlatformWalletError> for PlatformWalletFFIResult {
             PlatformWalletError::AssetLockFundingMismatch { .. } => {
                 PlatformWalletFFIResultCode::ErrorAssetLockFundingMismatch
             }
+            // A signer failure can also reach this blanket impl wrapped as
+            // `PlatformWalletError::Sdk(dash_sdk::Error::Protocol(..))` (any
+            // wallet operation that propagates the SDK error via `?`). The
+            // typed discriminator rides the stable machine prefix in the
+            // rendered message — restore it here too, but ONLY on the
+            // catch-all: the dedicated retry-semantics codes above are never
+            // overridden (dashpay/platform#4060 finding 7).
+            _ if error
+                .to_string()
+                .contains(rs_sdk_ffi::DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX) =>
+            {
+                PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable
+            }
             _ => PlatformWalletFFIResultCode::ErrorUnknown,
         };
         PlatformWalletFFIResult::err(code, error.to_string())
@@ -421,7 +455,13 @@ impl From<bincode::error::DecodeError> for PlatformWalletFFIResult {
 impl From<dpp::ProtocolError> for PlatformWalletFFIResult {
     fn from(e: dpp::ProtocolError) -> Self {
         let msg = e.to_string();
-        let code = if msg.contains("identifier") {
+        // The signer's typed SigningKeyUnavailable completion rides the
+        // stable machine prefix through ProtocolError::Generic
+        // (dashpay/platform#4060 finding 7) — restore the typed code FIRST,
+        // before any of the loose keyword sniffs below can misroute it.
+        let code = if msg.contains(rs_sdk_ffi::DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX) {
+            PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable
+        } else if msg.contains("identifier") {
             PlatformWalletFFIResultCode::ErrorInvalidIdentifier
         } else if msg.contains("deserialization") || msg.contains("decode") {
             PlatformWalletFFIResultCode::ErrorDeserialization
@@ -810,4 +850,52 @@ mod tests {
         let result: PlatformWalletFFIResult = err.into();
         assert_eq!(result.code, PlatformWalletFFIResultCode::ErrorUnknown);
     }
+
+    /// The typed SigningKeyUnavailable signer completion rides the stable
+    /// machine prefix through `ProtocolError::Generic`; the conversion must
+    /// restore code 31 (dashpay/platform#4060 finding 7) — and must do so
+    /// BEFORE the loose keyword sniffs (the human message may well contain
+    /// "identifier" or similar).
+    #[test]
+    fn signer_key_unavailable_prefix_maps_to_code_31() {
+        let e = dpp::ProtocolError::Generic(format!(
+            "{}no private key stored for identifier 02abcd",
+            rs_sdk_ffi::DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX
+        ));
+        let result: PlatformWalletFFIResult = e.into();
+        assert_eq!(
+            result.code,
+            PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable
+        );
+    }
+
+    /// The same prefix arriving wrapped in the SDK-error path (the blanket
+    /// `From<PlatformWalletError>` catch-all) restores code 31 too — but
+    /// only on the catch-all; typed variants keep their codes.
+    #[test]
+    fn signer_key_unavailable_prefix_maps_on_the_sdk_catch_all() {
+        let err = PlatformWalletError::Sdk(dash_sdk::Error::Protocol(dpp::ProtocolError::Generic(
+            format!(
+                "{}no private key stored for 02abcd",
+                rs_sdk_ffi::DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX
+            ),
+        )));
+        let result: PlatformWalletFFIResult = err.into();
+        assert_eq!(
+            result.code,
+            PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable
+        );
+    }
+
+    /// A generic protocol error without the prefix keeps the historical
+    /// mapping — no message sniffing beyond the machine prefix.
+    #[test]
+    fn generic_protocol_error_without_prefix_is_unchanged() {
+        let e = dpp::ProtocolError::Generic("no private key stored for 02abcd".to_string());
+        let result: PlatformWalletFFIResult = e.into();
+        assert_eq!(
+            result.code,
+            PlatformWalletFFIResultCode::ErrorWalletOperation
+        );
+    }
 }