refactor(platform-wallet): generate txMetadata indices locally

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/documents/DocumentTransactions.kt

@@ -263,23 +263,19 @@ class DocumentTransactions internal constructor(
      * `keyIndex` field) is chosen SDK-side to match the legacy stack, so the key
      * never crosses the FFI boundary.
      *
-     * ### `encryptionKeyIndex` allocation (dashpay/platform#4186 follow-up)
-     * Leave [encryptionKeyIndex] `null` (the default) to let the SDK allocate
-     * the per-document index in Rust from authoritative Platform state — the
-     * host-thin path. Rust counts the identity's existing txMetadata documents
-     * on Platform and uses `1 + count` (matching dash-wallet's retired
-     * `1 + countAllRequests()` semantics EXACTLY), serialized under the wallet's
-     * allocator mutex so concurrent creates through the same process never pick
-     * the same index. The index is best-effort unique PER DEVICE; a cross-device
-     * duplicate is not data-loss (each document stores its own index and the
-     * reader derives that document's key from it, so both decrypt independently).
+     * ### `encryptionKeyIndex` selection (dashpay/platform#4186 follow-up)
+     * Leave [encryptionKeyIndex] `null` (the default) to let the SDK generate
+     * the per-document index in Rust — the host-thin path. Rust draws a valid
+     * non-zero 31-bit BIP-32 child index from the operating-system CSPRNG. The
+     * index is a derivation input stored on each document, not a protocol
+     * sequence number; a repeated index is non-lossy because each document also
+     * has a fresh IV and readers derive from that document's stored fields.
      *
      * Passing an explicit non-negative [encryptionKeyIndex] is retained ONLY for
-     * migration / tests and is discouraged: the host must NOT reintroduce a
-     * caller-supplied `1 + countAllRequests()` counter (concurrent callers /
-     * devices could collide, and it violates the host-thin key-index rule).
+     * migration / tests and is discouraged: hosts should not own derivation
+     * index policy.
      *
-     * @param encryptionKeyIndex `null` to let the SDK allocate the index
+     * @param encryptionKeyIndex `null` to let the SDK generate the index
      *   (preferred); or an explicit non-negative per-document index
      *   (migration / tests only).
      * @param version payload version byte (`1` = protobuf, as the wallet writes).
@@ -325,7 +321,7 @@ class DocumentTransactions internal constructor(
                 ownerId,
                 contractId,
                 documentType,
-                // -1 is the JNI sentinel for "let Rust allocate the index".
+                // -1 is the JNI sentinel for "let Rust generate the index".
                 encryptionKeyIndex ?: -1,
                 version,
                 payload,

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

@@ -181,11 +181,11 @@ internal object TransactionsNative {
      *   whose txMetadata AES key derives on demand through the resolver.
      *   Ignored for wallets with resident private keys.
      * @param encryptionKeyIndex the per-document index, OR `-1` to let the SDK
-     *   allocate it in Rust from authoritative Platform state
-     *   (dashpay/platform#4186 follow-up). A non-negative value routes to the
-     *   explicit-index FFI export (migration / tests); `-1` routes to
-     *   `platform_wallet_create_encrypted_document_with_signer_auto_index`, which
-     *   omits the index. Values `< -1` are rejected.
+     *   generate it in Rust with the operating-system CSPRNG. A non-negative
+     *   value routes to the explicit-index FFI export (migration / tests);
+     *   `-1` routes to
+     *   `platform_wallet_create_encrypted_document_with_signer_auto_index`,
+     *   which omits the index. Values `< -1` are rejected.
      * @param version payload version byte (`1` = protobuf, as the wallet writes).
      * @param payload the already-serialized opaque plaintext (a protobuf
      *   `TxMetadataBatch`); the SDK does not parse it.

packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/documents/DocumentTransactionsVersionValidationTest.kt

@@ -19,7 +19,7 @@ import org.junit.Test
  *    an out-of-range byte would silently seal a document the legacy stack can't
  *    decode.
  * 2. `encryptionKeyIndex` (dashpay/platform#4186 follow-up): `null` is the
- *    preferred path (Rust allocates the index from Platform state); an explicit
+ *    preferred path (Rust generates the per-document index); an explicit
  *    value, when supplied, must be non-negative.
  *
  * Paths that PASS validation proceed into native and can't be fully unit-tested
@@ -68,7 +68,7 @@ class DocumentTransactionsVersionValidationTest {
 
     /**
      * An explicit NEGATIVE index (the migration/test-only path) is rejected by
-     * the `require`. `null` (the allocate-in-Rust path) is the only way to omit
+     * the `require`. `null` (the generate-in-Rust path) is the only way to omit
      * an index; a negative explicit value is a caller error.
      */
     @Test
@@ -96,7 +96,7 @@ class DocumentTransactionsVersionValidationTest {
 
     /**
      * The no-index path (`encryptionKeyIndex` omitted → `null`, the default and
-     * preferred allocate-in-Rust route) must PASS the argument guards. With all
+     * preferred generate-in-Rust route) must PASS the argument guards. With all
      * other inputs valid, the only failure that can surface is the native call
      * itself (no JNI library in a JVM unit test), NOT an
      * [IllegalArgumentException] from our `require`s — proving `null` is a valid
@@ -115,7 +115,7 @@ class DocumentTransactionsVersionValidationTest {
                     version = 1,
                     payload = payload,
                     signerHandle = 0L,
-                    // encryptionKeyIndex omitted → null → allocate in Rust.
+                    // encryptionKeyIndex omitted → null → generate in Rust.
                 )
             }
         }.exceptionOrNull()