fix(sdk): reject unpaired surrogates before signing, and correct the length-prefix docs

Review findings 2 and 5 on #4259.

The Kotlin and Swift docs described the digest's length prefix in each
language's own string units — `message.length` (UTF-16 code units) and
`message.count` (grapheme clusters). The format prefixes the UTF-8 BYTE
count; the three agree only for ASCII. Corrected to
`message.toByteArray(Charsets.UTF_8).size` and `message.utf8.count`.

That doc bug has a real counterpart: a Kotlin `String` is an unvalidated
UTF-16 sequence and may hold an unpaired surrogate, which has no UTF-8
encoding. Every conversion below is lenient and they do not even agree —
the JNI bridge's string read substitutes U+FFFD, while
`toByteArray(Charsets.UTF_8)` substitutes '?' (verified on JDK 17). So
the wallet would sign bytes the caller never wrote and return a signature
that verifies for a different message, silently, and "verbatim" in the
docs would be false.

Rejected at the Kotlin entry point, the last layer that still holds the
exact UTF-16 and can explain why. Marshalling a UTF-8 ByteArray across
the JNI instead — the other option raised in review — would NOT fix this:
Kotlin's own encoder is equally lossy, so it would relocate the silent
substitution and change it from U+FFFD to '?' while widening the FFI
surface. Well-formed strings are unaffected. The lossy `get_string`
read is the shared `read_cstring_required` behaviour on every JNI string
parameter in the crate, so it is a codebase-wide convention rather than
something this path introduced; flagged rather than changed here.

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

Author: HashEngineering

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedPlatformWallet.kt

@@ -180,7 +180,10 @@ class ManagedPlatformWallet internal constructor(
      * CrowdNode's server-side check.
      *
      * **The format.** The signed digest is
-     * `SHA256d(prefix ‖ varint(message.length) ‖ message)`, where the prefix is
+     * `SHA256d(prefix ‖ varint(bytes.size) ‖ bytes)` over
+     * `bytes = message.toByteArray(Charsets.UTF_8)`: the length prefix counts
+     * **UTF-8 bytes**, not `String.length`, which counts UTF-16 code units and
+     * diverges for any non-ASCII text. The prefix is
      * the historical `"\x19DarkCoin Signed Message:\n"` — *not* `"Dash"`. Dash
      * inherited that string from before the rename and every existing verifier
      * depends on it, so it can never change. The returned signature is the
@@ -223,9 +226,13 @@ class ManagedPlatformWallet internal constructor(
      *
      * @param address the P2PKH address whose key signs; must be one this wallet
      *   owns and has derived.
-     * @param message the string to sign, **verbatim**. It is length-prefixed
-     *   into the digest, so trailing whitespace and newlines are significant and
-     *   the verifier must receive the identical bytes. An empty string is valid.
+     * @param message the string to sign, **verbatim** as UTF-8. It is
+     *   length-prefixed into the digest, so trailing whitespace and newlines are
+     *   significant and the verifier must receive the identical bytes. An empty
+     *   string is valid. Must be well-formed text: a string holding an unpaired
+     *   UTF-16 surrogate has no UTF-8 encoding and is rejected with
+     *   [IllegalArgumentException] rather than signed after a silent
+     *   substitution.
      * @param coreSignerHandle the manager's `MnemonicResolverHandle`
      *   (`PlatformWalletManager.mnemonicResolverHandle`); no private key crosses
      *   the boundary.
@@ -237,6 +244,18 @@ class ManagedPlatformWallet internal constructor(
         coreSignerHandle: Long,
     ): String = gate.op {
         require(address.isNotEmpty()) { "address must not be empty" }
+        // The digest commits to the message's UTF-8 bytes, but a Kotlin String
+        // is an unvalidated UTF-16 sequence and may hold an unpaired surrogate,
+        // which has no UTF-8 encoding at all. Every conversion below is LENIENT
+        // and they do not even agree: the JNI bridge's String read substitutes
+        // U+FFFD, while `toByteArray(Charsets.UTF_8)` substitutes '?'. Either
+        // way the wallet would sign bytes the caller never wrote and hand back a
+        // signature that verifies for a different message — silently. Rejected
+        // here, the one layer that still has the exact UTF-16 and can say why.
+        require(message.hasNoUnpairedSurrogate()) {
+            "message must be well-formed text: it contains an unpaired UTF-16 surrogate, " +
+                "which has no UTF-8 encoding and would be silently substituted before signing"
+        }
 
         mapNativeErrors {
             coreWallet().use { core ->
@@ -245,6 +264,30 @@ class ManagedPlatformWallet internal constructor(
         }
     }
 
+    /**
+     * Whether every UTF-16 surrogate in this string is part of a well-formed
+     * high/low pair — i.e. whether the string has an exact UTF-8 encoding.
+     *
+     * Scanned directly rather than via a strict `CharsetEncoder` to keep the
+     * check allocation-free on the hot path; the two agree on exactly which
+     * strings are encodable.
+     */
+    private fun String.hasNoUnpairedSurrogate(): Boolean {
+        var i = 0
+        while (i < length) {
+            val c = this[i]
+            when {
+                c.isHighSurrogate() -> {
+                    if (i + 1 >= length || !this[i + 1].isLowSurrogate()) return false
+                    i += 2
+                }
+                c.isLowSurrogate() -> return false
+                else -> i++
+            }
+        }
+        return true
+    }
+
     /**
      * The wallet's Platform-payment addresses that currently hold credits,
      * each as a [FundingInput] whose `credits` is the full cached balance —

packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/CoreWallet/ManagedCoreWallet.swift

@@ -142,8 +142,11 @@ public class ManagedCoreWallet {
     /// RPC, and verifiable by `verifymessage`, `ECKey.verifyMessage`, and
     /// CrowdNode's server-side check.
     ///
-    /// The signed digest is `SHA256d(prefix ‖ varint(message.count) ‖ message)`,
-    /// where the prefix is the historical `"\u{19}DarkCoin Signed Message:\n"` —
+    /// The signed digest is
+    /// `SHA256d(prefix ‖ varint(message.utf8.count) ‖ message.utf8)`: the length
+    /// prefix counts **UTF-8 bytes**, not `String.count`, which counts grapheme
+    /// clusters and diverges for any non-ASCII text.
+    /// The prefix is the historical `"\u{19}DarkCoin Signed Message:\n"` —
     /// *not* `"Dash"`. Dash inherited that string from before the rename and
     /// every existing verifier depends on it, so it can never change. The
     /// returned signature is the 65-byte BIP-137-style recoverable form