feat(kotlin-sdk): one-time Orchard key shielded-invite API (inviter + claim)

[bfoss765]

What

Adds the one-time Orchard key shielded-invite API to the Kotlin SDK. Client-side only — no L2 protocol / consensus changes (nothing under rs-dpp, rs-drive, dapi).

• Inviter side — generateOneTimeOrchardKey() / orchardAddressFromSpendingKey() + the OneTimeOrchardKey type: generate a one-time Orchard spending key and the raw address the inviter funds a note to.
• Claim side — shieldedIdentityCreateFromOneTimeKey(...): a claimer, handed the one-time spending key, spends the funded note to create/top-up a shielded identity.

Backing Rust: rs-platform-wallet (shielded/keys.rs, operations.rs, sync.rs, platform_wallet.rs), rs-platform-wallet-ffi (shielded_send.rs), rs-unified-sdk-jni (funding.rs).

⚠️ Stacked on #4183

The claim side consumes decode_registration_pubkeys_blob + IdentityPubkeyCodec, both introduced by #4183. This branch is stacked on #4183, so until #4183 merges the diff below also contains #4183's changes. It will retarget to a clean diff once #4183 lands. Net-new files to review here:

• packages/rs-platform-wallet/src/wallet/shielded/keys.rs
• packages/rs-platform-wallet/src/wallet/shielded/operations.rs
• packages/rs-platform-wallet/src/wallet/shielded/sync.rs
• packages/rs-platform-wallet/src/wallet/shielded/mod.rs
• packages/rs-platform-wallet/src/wallet/platform_wallet.rs
• packages/rs-platform-wallet-ffi/src/shielded_send.rs
• packages/rs-unified-sdk-jni/src/funding.rs
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/FundingNative.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/PlatformWalletManager.kt
• packages/rs-platform-wallet/Cargo.toml (optional rand dep for the shielded feature)

Security note — identity key roles

The claim path decodes registration pubkeys through base's decode_registration_pubkeys_blob / row.to_ffi(), so key roles (purpose / security level) are caller-stamped (base's uniform registration convention) rather than derived in Rust. The role mapping is unchanged: key_id 0 → AUTH/MASTER, 1 → AUTH/CRITICAL, 2 → AUTH/HIGH, 3 → TRANSFER/CRITICAL. The reconciled JNI return also preserves the identity id on the unconfirmed-broadcast path.

Validation

• cargo test -p platform-wallet --features shielded — 624 lib tests + 3 new claim tests pass; inviter key-roundtrip tests pass.
• cargo build -p platform-wallet -p platform-wallet-ffi -p rs-unified-sdk-jni --features shielded — clean.
• ./gradlew :sdk:assemble — BUILD SUCCESSFUL (compileDebug/ReleaseKotlin).

Consumer follow-up (tracked separately, not in this PR)

The Android wallet's SdkShieldedUsernameCreation / SdkShieldedInviteCreation still call the claim API with List<IdentityKeyPreview>; they need adapting to List<IdentityPubkey> (stamping the roles above) before the full wallet builds against this SDK.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added configurable identity-key security policies, including authentication-gated and device-bound protection.
  • Added durable tracking and recovery for identity keys requiring repair, including restart support.
  • Added one-time Orchard key generation, address derivation, and shielded identity creation flows.
  • Added clearer typed errors for unavailable signing keys and platform-wallet “not found” conditions.
  • Added graceful handling when managed identities are removed during concurrent operations.

• Bug Fixes

  • Improved legacy key recovery and migration across security-policy changes.
  • Prevented invalid or mismatched keys from being stored during repair.

• Documentation

  • Updated Kotlin/Swift parity, migration, compatibility, and capability documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds policy-based Android keystore aliases, durable identity-key repair tracking with Room v8 migration support, structured signing error propagation across Kotlin, Rust, JNI, and Swift, one-time Orchard shielded identity creation, managed-identity error translation, and related tests and parity documentation.

Changes

Platform wallet and SDK updates

Layer / File(s)	Summary
Keystore policy and recovery packages/kotlin-sdk/sdk/src/main/.../security/*, KotlinExampleApp/.../WalletKeyHealthSheet.kt, security tests	Identity keys support AUTH_GATED and DEVICE_BOUND aliases, alias-aware recovery, lockless degradation, forced replacement, invalidation handling, and recoverability probing.
Durable pending-key repair and schema migration packages/kotlin-sdk/sdk/src/main/.../persistence/*, schemas/.../8.json, migration and persistence tests	Room v8 stores derivation breadcrumbs, while pending repair state is staged transactionally, reconstructed after restart, and cleared only after durable repair succeeds.
Typed signing ABI and error mappings packages/rs-sdk-ffi/src/signer.rs, packages/rs-unified-sdk-jni/src/signer.rs, Kotlin/Swift signer and error files, FFI tests	Signer completion callbacks now carry structured error codes, including signing-key-unavailable code 31; PlatformWallet not-found code 98 maps to the typed platform-wallet error.
One-time Orchard identity creation packages/rs-platform-wallet/src/wallet/shielded/*, FFI/JNI funding bridges, Kotlin funding and manager APIs	The SDK can generate one-time Orchard keys, derive addresses, scan foreign notes, and create shielded identities through the Type-20 flow.
Managed identity translation and parity records packages/rs-platform-wallet-ffi/src/dashpay.rs, Kotlin DashPay/wallet files, docs/*, parity summaries	Lookup outcomes distinguish invalid handles from unmanaged identities, and compatibility, capability, migration, and test coverage records are updated.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

• dashpay/platform#4183: Shares Kotlin keystore/error plumbing, durable pending-key repair, and structured signer completion changes.

Suggested labels: Client Only

Suggested reviewers: quantumexplorer, shumkov, lklimek

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a one-time Orchard shielded-invite API on inviter and claim sides.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thepastaclaw]

🕓 Ready for review — 9 ahead in queue (commit 5ba2794)
Queue position: 10/13 · 2 reviews active
ETA: start ~18:47 UTC · complete ~19:11 UTC (median 23m across 30 recent reviews; 2 slots)
Queued 58m ago · Last checked: 2026-07-24 16:50 UTC

[thepastaclaw]

Preliminary review — Codex only

The one-time Orchard invitation API follows the existing Type-20 construction, but four blocking issues remain in proof-wait compatibility, ambiguous-broadcast recovery, bearer-key handling, and FFI panic safety. The foreign-key scan also permits untrusted unfunded invitations to trigger an uncancellable genesis-to-tip scan.

Validated blockers were found in the Codex precheck. Sonnet is deferred until a fresh Codex revalidation clears the blocker gate.

Review provenance

• Codex reviewers: gpt-5.6-sol — general (completed), gpt-5.6-sol — security-auditor (completed), gpt-5.6-sol — ffi-engineer (completed)
• Verifier: gpt-5.6-sol — verifier
• Sonnet: not run (deferred by blocker gate)

🔴 4 blocking | 🟡 1 suggestion(s)

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `packages/rs-platform-wallet/src/wallet/shielded/operations.rs`:
- [BLOCKING] packages/rs-platform-wallet/src/wallet/shielded/operations.rs:1706-1709: Use the affected-state wait for the Type-20 claim
  The current v4.1-dev proof contract introduced by 31c69cf793 marks IdentityCreateFromShieldedPool proofs as affected-state snapshots because they authenticate the resulting identity and nullifiers but cannot bind the complete Orchard request. That commit changed the pool-funded sibling to `wait_for_affected_state`, while this new path still calls the strict `wait_for_response`. After rebasing, every valid claim proof will therefore produce `ExecutionNotProved`, enter the ambiguous fallback, and may be reported unconfirmed despite successful execution. On this older head, the same call accepts a snapshot without making that weaker guarantee explicit. Rebase onto the current proof API and use the affected-state wait, matching the sibling Type-20 path.
- [BLOCKING] packages/rs-platform-wallet/src/wallet/shielded/operations.rs:1733-1737: Persist a recovery path before returning an unconfirmed claim
  This branch returns `ShieldedBroadcastUnconfirmed` without persisting the byte-identical transition or any pending claim metadata. Unlike the pool-funded sibling at lines 1392-1407, there is no `PendingRedrive`; `poke_sync_on_unconfirmed` consequently starts a sync that has no record to process, and the foreign invitation notes are intentionally absent from every subwallet. If an ambiguously accepted transition was actually dropped, nothing safely rebroadcasts it. The Kotlin wrapper compounds this because `TeardownGate.withOp` uses prompt-cancellable `withContext(Dispatchers.IO)`: JNI cannot be interrupted, so cancellation can discard the tagged identity ID or typed unconfirmed exception after native broadcast completion. Persist a pending claim containing the identity ID/index, submitted-key metadata, and re-drivable transition before broadcasting, then reconcile it across cancellation and restart; an equivalent mechanism must safely rebroadcast and treat `NullifierAlreadySpent` as evidence that the original claim executed.

In `packages/rs-unified-sdk-jni/src/funding.rs`:
- [BLOCKING] packages/rs-unified-sdk-jni/src/funding.rs:829-833: Do not marshal the spending key through ordinary unsanitized buffers
  `oneTimeSk` is bearer spend authority for a funded invitation, but the generic `read_id32` leaves both its intermediate `Vec<u8>` and returned `[u8; 32]` unsanitized. The FFI and wallet layers create further plain-array copies. The generation direction similarly leaves native `sk`, combined `out`, and Kotlin's 75-byte source blob containing the spending key until their memory is reused or garbage-collected. This repository already uses `read_key32_zeroizing` for JNI private keys and explicitly scrubs invitation bearer scalars in `identity/network/invitation.rs`. Carry this key through `Zeroizing` buffers where possible and explicitly wipe all transient native and JVM arrays after copying out the one intentionally caller-owned key.

In `packages/rs-platform-wallet-ffi/src/shielded_send.rs`:
- [BLOCKING] packages/rs-platform-wallet-ffi/src/shielded_send.rs:1580-1590: OS RNG failure aborts before the JNI panic guard can run
  `generate_one_time_orchard_key` calls `OsRng.fill_bytes`, whose rand_core implementation panics when `try_fill_bytes` reports an entropy-source failure. Because that panic occurs inside this `extern "C"` export, it cannot unwind to the outer JNI `guard`; Rust aborts at the C ABI boundary first. An operating-system RNG failure can therefore terminate the Android process instead of producing a Java/native error. Change the generator to use `try_fill_bytes` and propagate a `PlatformWalletFFIResult` error, or place an internal panic fence inside this C export.

In `packages/rs-platform-wallet/src/wallet/shielded/sync.rs`:
- [SUGGESTION] packages/rs-platform-wallet/src/wallet/shielded/sync.rs:829-855: Unfunded invitation keys force an unbounded full-history scan
  Every syntactically valid invitation key starts at position 0 and keeps fetching, proof-verifying, and trial-decrypting chunks until enough value is found or the complete shielded history is exhausted. An attacker can generate valid but unfunded invitation keys, so the value-based early exit provides no bound for hostile input. The supplied birth-height hint is ignored, and cancellation of the Kotlin coroutine cannot interrupt the blocking JNI operation. Add an authenticated or otherwise safe starting position, a maximum resumable scan budget, or another preflight mechanism that prevents one invitation from forcing an unlimited genesis-to-tip scan.

[thepastaclaw]

🔴 Blocking: Use the affected-state wait for the Type-20 claim

The current v4.1-dev proof contract introduced by 31c69cf marks IdentityCreateFromShieldedPool proofs as affected-state snapshots because they authenticate the resulting identity and nullifiers but cannot bind the complete Orchard request. That commit changed the pool-funded sibling to wait_for_affected_state, while this new path still calls the strict wait_for_response. After rebasing, every valid claim proof will therefore produce ExecutionNotProved, enter the ambiguous fallback, and may be reported unconfirmed despite successful execution. On this older head, the same call accepts a snapshot without making that weaker guarantee explicit. Rebase onto the current proof API and use the affected-state wait, matching the sibling Type-20 path.

_{source: ['codex']}

[thepastaclaw]

🔴 Blocking: Persist a recovery path before returning an unconfirmed claim

This branch returns ShieldedBroadcastUnconfirmed without persisting the byte-identical transition or any pending claim metadata. Unlike the pool-funded sibling at lines 1392-1407, there is no PendingRedrive; poke_sync_on_unconfirmed consequently starts a sync that has no record to process, and the foreign invitation notes are intentionally absent from every subwallet. If an ambiguously accepted transition was actually dropped, nothing safely rebroadcasts it. The Kotlin wrapper compounds this because TeardownGate.withOp uses prompt-cancellable withContext(Dispatchers.IO): JNI cannot be interrupted, so cancellation can discard the tagged identity ID or typed unconfirmed exception after native broadcast completion. Persist a pending claim containing the identity ID/index, submitted-key metadata, and re-drivable transition before broadcasting, then reconcile it across cancellation and restart; an equivalent mechanism must safely rebroadcast and treat NullifierAlreadySpent as evidence that the original claim executed.

_{source: ['codex']}

[thepastaclaw]

🔴 Blocking: Do not marshal the spending key through ordinary unsanitized buffers

oneTimeSk is bearer spend authority for a funded invitation, but the generic read_id32 leaves both its intermediate Vec<u8> and returned [u8; 32] unsanitized. The FFI and wallet layers create further plain-array copies. The generation direction similarly leaves native sk, combined out, and Kotlin's 75-byte source blob containing the spending key until their memory is reused or garbage-collected. This repository already uses read_key32_zeroizing for JNI private keys and explicitly scrubs invitation bearer scalars in identity/network/invitation.rs. Carry this key through Zeroizing buffers where possible and explicitly wipe all transient native and JVM arrays after copying out the one intentionally caller-owned key.

_{source: ['codex']}

[thepastaclaw]

🔴 Blocking: OS RNG failure aborts before the JNI panic guard can run

generate_one_time_orchard_key calls OsRng.fill_bytes, whose rand_core implementation panics when try_fill_bytes reports an entropy-source failure. Because that panic occurs inside this extern "C" export, it cannot unwind to the outer JNI guard; Rust aborts at the C ABI boundary first. An operating-system RNG failure can therefore terminate the Android process instead of producing a Java/native error. Change the generator to use try_fill_bytes and propagate a PlatformWalletFFIResult error, or place an internal panic fence inside this C export.

_{source: ['codex']}

[thepastaclaw]

🟡 Suggestion: Unfunded invitation keys force an unbounded full-history scan

Every syntactically valid invitation key starts at position 0 and keeps fetching, proof-verifying, and trial-decrypting chunks until enough value is found or the complete shielded history is exhausted. An attacker can generate valid but unfunded invitation keys, so the value-based early exit provides no bound for hostile input. The supplied birth-height hint is ignored, and cancellation of the Kotlin coroutine cannot interrupt the blocking JNI operation. Add an authenticated or otherwise safe starting position, a maximum resumable scan budget, or another preflight mechanism that prevents one invitation from forcing an unlimited genesis-to-tip scan.

_{source: ['codex']}

[bfoss765]

Pushed fixes for two of the four blockers in 5ba2794d:

• RNG abort across the C ABI (shielded_send.rs / keys.rs) — generate_one_time_orchard_key now uses try_fill_bytes and returns a typed PlatformWalletError; the FFI export returns a PlatformWalletFFIResult error instead of letting a panic abort the process.
• One-time spend key through unsanitized buffers (funding.rs) — the one_time_sk read now goes through a read_key32_zeroizing helper (mirroring the existing transactions::read_key32_zeroizing), so the intermediate JNI buffer and the key are zeroized on drop.

The other two need more than a minimal edit — flagging for direction:

• Affected-state wait (operations.rs:1706) — wait_for_affected_state doesn't exist on this branch yet; it comes in with the rebase onto the current proof API (31c69cf793), which flips the contract for both Type-20 paths. The pool-funded sibling (operations.rs:1354) still calls wait_for_response on this head, so the claim path currently matches it. I'll make this change as part of that rebase, in lockstep across both paths, rather than substituting a symbol that isn't present yet.
• Persist a claim recovery record (operations.rs:1733) — the existing redrive scaffold is keyed by SubwalletId and driven by the per-subwallet sync loop, but a claim tracks a foreign one-time key that lives in no subwallet, so arm_redrive_record doesn't apply. Doing this correctly needs a new subwallet-less pending-claim record + a reconciliation path (restart / cancellation / nullifier-already-spent-as-success). That's a fund-safety design change I'd rather scope deliberately than guess — will follow up.

The unbounded genesis-to-tip scan on an unfunded claim is noted as a separate follow-up (a bound needs a chosen scan-budget so legitimate funded claims don't return empty).

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md (1)

674-675: 📐 Maintainability & Code Quality | 🔵 Trivial

Optional: silence MD038 while preserving the prefix's trailing space.

markdownlint flags the space inside `signer_error:key_unavailable: `. Since the trailing space is a meaningful part of the machine prefix, consider noting it in prose (e.g. "ends with a colon+space") instead of relying on the space inside the code span, so the lint passes without dropping the semantics.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md` around lines 674 - 675, Update
the documentation around the ProtocolError::Generic prefix to avoid placing a
trailing space inside the inline code span, while preserving the prefix
semantics by describing that it ends with a colon followed by a space in
surrounding prose.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/dashpay/KOTLIN_MIGRATION_LEFTOVERS.md`:
- Around line 57-69: Update the documentation text around the
`ProtocolError::Generic` prefix so the literal `signer_error:key_unavailable:`
code span contains no trailing space; describe or place the separator space
outside the backticks while preserving the prefix’s meaning.

In
`@packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/PlatformWalletPersistenceHandler.kt`:
- Around line 2673-2742: Update repairIdentityKeyDurably to coordinate the
durable repair with deleteWalletData and recordSigningKeyInvalidated through
withCallbackExclusion before invoking deriver.deriveAndStore(force = true),
preserving the existing breadcrumb, verification, persistence, and pending-state
behavior. Ensure native derivation calls are not executed while the callback
exclusion is held, following the established exclusion usage pattern.

In `@packages/rs-sdk-ffi/src/signer.rs`:
- Around line 179-188: Strip DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX from
signer error messages before surfacing them. Update both conversion paths—the
catch-all using error.to_string() and the ProtocolError implementation
formatting "DPP protocol error: {msg}"—to remove only this prefix while
preserving the existing error text and SigningKeyUnavailable mapping.

---

Nitpick comments:
In `@docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md`:
- Around line 674-675: Update the documentation around the
ProtocolError::Generic prefix to avoid placing a trailing space inside the
inline code span, while preserving the prefix semantics by describing that it
ends with a colon followed by a space in surrounding prose.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 54334ff6-0af1-44db-88ae-6cec9e5e8d8b

📥 Commits

Reviewing files that changed from the base of the PR and between 2842092 and 5ba2794.

📒 Files selected for processing (59)

• docs/dashpay/KOTLIN_MIGRATION_LEFTOVERS.md
• docs/sdk/KOTLIN_SWIFT_SHARED_PARITY_SPEC.md
• docs/sdk/sdk-parity-manifest.json
• packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/wallet/WalletKeyHealthSheet.kt
• packages/kotlin-sdk/PARITY_SUMMARY.md
• packages/kotlin-sdk/sdk/schemas/org.dashfoundation.dashsdk.persistence.DashDatabase/8.json
• packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/persistence/DashDatabaseMigrationTest.kt
• packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/security/KeystoreSignerInstrumentedTest.kt
• packages/kotlin-sdk/sdk/src/androidTest/kotlin/org/dashfoundation/dashsdk/security/WalletStorageOwnershipTest.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/FundingNative.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/SignerNative.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/identity/IdentityRegistration.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/DashDatabase.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/PlatformWalletPersistenceHandler.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/dao/PublicKeyDao.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/entities/PublicKeyEntity.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/IdentityKeyPrivateKeyDeriver.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/KeySecurityPolicy.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/KeySecurityPolicyUnavailableException.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/KeystoreManager.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/KeystoreSigner.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/WalletStorage.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/tokens/Dashpay.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedPlatformWallet.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/PlatformWalletManager.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/persistence/PlatformWalletPersistenceHandlerTest.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/security/KeySecurityPolicyTest.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/security/KeystoreKeyGenPolicyTest.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/security/KeystoreSignerCompletionCodeTest.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/security/WalletStorageUpgradeMatrixTest.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/tokens/ManagedIdentityNotFoundTranslationTest.kt
• packages/rs-platform-wallet-ffi/src/dashpay.rs
• packages/rs-platform-wallet-ffi/src/error.rs
• packages/rs-platform-wallet-ffi/src/shielded_send.rs
• packages/rs-platform-wallet/Cargo.toml
• packages/rs-platform-wallet/src/wallet/platform_wallet.rs
• packages/rs-platform-wallet/src/wallet/shielded/keys.rs
• packages/rs-platform-wallet/src/wallet/shielded/mod.rs
• packages/rs-platform-wallet/src/wallet/shielded/operations.rs
• packages/rs-platform-wallet/src/wallet/shielded/sync.rs
• packages/rs-sdk-ffi/src/signer.rs
• packages/rs-sdk-ffi/src/test_utils.rs
• packages/rs-sdk-ffi/src/token/claim.rs
• packages/rs-sdk-ffi/src/token/config_update.rs
• packages/rs-sdk-ffi/src/token/destroy_frozen_funds.rs
• packages/rs-sdk-ffi/src/token/emergency_action.rs
• packages/rs-sdk-ffi/src/token/freeze.rs
• packages/rs-sdk-ffi/src/token/mint.rs
• packages/rs-sdk-ffi/src/token/purchase.rs
• packages/rs-sdk-ffi/src/token/set_price.rs
• packages/rs-sdk-ffi/src/token/transfer.rs
• packages/rs-sdk-ffi/src/token/unfreeze.rs
• packages/rs-unified-sdk-jni/src/funding.rs
• packages/rs-unified-sdk-jni/src/signer.rs
• packages/swift-sdk/Sources/SwiftDashSDK/FFI/KeychainSigner.swift
• packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift
• packages/swift-sdk/SwiftTests/SwiftDashSDKTests/ErrorHandlingTests.swift

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix MD038 lint: trailing space inside code span.

markdownlint flags the trailing space inside `signer_error:key_unavailable: ` at line 66. Rephrase to keep the literal value visible without a raw trailing space in the code span (e.g. move the trailing space out of the backticks or note it separately) to avoid a lint failure.

📝 Suggested fix

-  Rust-internal segment rides the `signer_error:key_unavailable: ` prefix
+  Rust-internal segment rides the `signer_error:key_unavailable:` (trailing space) prefix

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- **`SigningKeyUnavailable` MESSAGE_MARKER fallback removal.** The signer's
	"missing key" failure now travels as a typed completion code (rs-sdk-ffi
	`DashSDKSignerErrorCode::SigningKeyUnavailable` → platform-wallet code 31 →
	`DashSdkError.PlatformWallet.SigningKeyUnavailable`). The message-marker
	sniff on the catch-all codes is retained ONLY for the #4191 merge-order
	transition and for conversion paths that lose the machine prefix — NOT for
	mixed old-native/new-Kotlin builds, which the completion JNI arity change
	(3→4 args) makes unsupported outright; delete it (and `MESSAGE_MARKER`'s
	matcher role) in the next minor release. Accepted residual until rs-dpp grows a typed variant: the
	Rust-internal segment rides the `signer_error:key_unavailable: ` prefix
	through `ProtocolError::Generic` (typed at both ABI edges, one Rust-owned
	constant bridging the string segment).
	- **`SigningKeyUnavailable` MESSAGE_MARKER fallback removal.** The signer's
	"missing key" failure now travels as a typed completion code (rs-sdk-ffi
	`DashSDKSignerErrorCode::SigningKeyUnavailable` → platform-wallet code 31 →
	`DashSdkError.PlatformWallet.SigningKeyUnavailable`). The message-marker
	sniff on the catch-all codes is retained ONLY for the `#4191` merge-order
	transition and for conversion paths that lose the machine prefix — NOT for
	mixed old-native/new-Kotlin builds, which the completion JNI arity change
	(3→4 args) makes unsupported outright; delete it (and `MESSAGE_MARKER`'s
	matcher role) in the next minor release. Accepted residual until rs-dpp grows a typed variant: the
	Rust-internal segment rides the `signer_error:key_unavailable:` (trailing space) prefix
	through `ProtocolError::Generic` (typed at both ABI edges, one Rust-owned
	constant bridging the string segment).

🧰 Tools

🪛 markdownlint-cli2 (0.23.0)

[warning] 66-66: Spaces inside code span elements

(MD038, no-space-in-code)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/dashpay/KOTLIN_MIGRATION_LEFTOVERS.md` around lines 57 - 69, Update the
documentation text around the `ProtocolError::Generic` prefix so the literal
`signer_error:key_unavailable:` code span contains no trailing space; describe
or place the separator space outside the backticks while preserving the prefix’s
meaning.

Source: Linters/SAST tools

[coderabbitai]

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Inspect how repairIdentityKey / repairIdentityKeyDurably is invoked and whether it holds callbackExclusion.
fd -t f 'PlatformWalletManager.kt' packages/kotlin-sdk | xargs -I{} sh -c 'echo "== {} =="; rg -n -C5 "repairIdentityKey|repairIdentityKeyDurably|withCallbackExclusion|recordSigningKeyInvalidated" {}'

Repository: dashpay/platform

Length of output: 4147

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== candidate files =="
fd -t f 'PlatformWalletManager.kt|PlatformWalletPersistenceHandler.kt|WalletStorage.kt' packages/kotlin-sdk | sort

echo
echo "== PlatformWalletManager relevant sections =="
file=$(fd -t f 'PlatformWalletManager.kt' packages/kotlin-sdk | head -n 1)
wc -l "$file"
rg -n -C 20 "fun repairIdentityKey|teardownGate|withCallbackExclusion|withPrivateKeyExclusion|deleteWalletData|recordSigningKeyInvalidated|identityIdsForWallet|privateKeyDeriver" "$file"

echo
echo "== PlatformWalletPersistenceHandler relevant definitions and usages =="
handler=$(fd -t f 'PlatformWalletPersistenceHandler.kt' packages/kotlin-sdk | head -n 1)
wc -l "$handler"
rg -n -C 12 "fun withCallbackExclusion|withCallbackExclusion|lock|callbackExclusion|fun .*repairIdentityKey|repairIdentityKeyDurably|recordSigningKeyInvalidated|deriveAndStore|deleteWallet|deleteWalletData|identityIdsForWallet|publicKeyDao|walletStorage|withPrivateKeyExclusion" "$handler"

Repository: dashpay/platform

Length of output: 50373

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== call graph-ish: all usages of PlatformWalletPersistenceHandler public methods across Kotlin SDK =="
rg -n -C 4 "PlatformWalletPersistenceHandler|repairIdentityKeyDurably|repairIdentityKey\(|withCallbackExclusion\(|withCallbackExclusion|deleteWalletData|identityIdsForWallet|recordSigningKeyInvalidated" packages/kotlin-sdk --glob '*.kt'

echo
echo "== exact lines range persistence handler =="
handler=$(fd -t f 'PlatformWalletPersistenceHandler.kt' packages/kotlin-sdk | head -n 1)
sed -n '2620,2775p' "$handler" | cat -n -v +s
sed -n '880,1060p' "$handler" | cat -n -v +s
sed -n '1320,1500p' "$handler" | cat -n -v +s
sed -n '1600,1800p' "$handler" | cat -n -v +s

echo
echo "== exact manager repair / delete sections =="
manager=$(fd -t f 'PlatformWalletManager.kt' packages/kotlin-sdk | head -n 1)
sed -n '470,525p' "$manager" | cat -n -v +s
sed -n '880,965p' "$manager" | cat -n -v +s

Repository: dashpay/platform

Length of output: 50373

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

handler=$(fd -t f 'PlatformWalletPersistenceHandler.kt' packages/kotlin-sdk | head -n 1)
manager=$(fd -t f 'PlatformWalletManager.kt' packages/kotlin-sdk | head -n 1)
wallet=$(fd -t f 'WalletStorage.kt' packages/kotlin-sdk | head -n 1)

echo "== persistence handler lock/section definitions =="
sed -n '220,340p' "$handler" | cat -n -v +s

echo
echo "== persistence handler deleteWalletDataLocked/wrapped deleteWalletData =="
rg -n -C 12 "deleteWalletDataLocked|fun deleteWalletData|withCallbackExclusion\\(" "$handler"

echo
echo "== persistence handler identity-key persistence APIs =="
rg -n -C 10 "recordSigningKeyInvalidated|pendingIdentityKeys|deriveAndStore|IdentityChangeSet|Identity.*Private|PrivateKeyDeriver|public_key" "$handler" | head -n 240

echo
echo "== manager repairIdentityKey =="
sed -n '487,522p' "$manager" | cat -n -v +s

echo
echo "== wallet storage locking definitions =="
sed -n '1,260p' "$wallet" | cat -n -v +s

Repository: dashpay/platform

Length of output: 240

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

handler=$(fd -t f 'PlatformWalletPersistenceHandler.kt' packages/kotlin-sdk | head -n 1)
manager=$(fd -t f 'PlatformWalletManager.kt' packages/kotlin-sdk | head -n 1)
wallet=$(fd -t f 'WalletStorage.kt' packages/kotlin-sdk | head -n 1)

echo "== persistence handler lock/section definitions =="
sed -n '220,340p' "$handler"

echo
echo "== persistence handler deleteWalletDataLocked/wrapped deleteWalletData =="
rg -n -C 12 "deleteWalletDataLocked|fun deleteWalletData|withCallbackExclusion\\(" "$handler"

echo
echo "== persistence handler identity-key persistence APIs =="
rg -n -C 10 "recordSigningKeyInvalidated|pendingIdentityKeys|deriveAndStore|IdentityChangeSet|Identity.*Private|PrivateKeyDeriver|public_key" "$handler" | head -n 240

echo
echo "== manager repairIdentityKey =="
sed -n '487,522p' "$manager"

echo
echo "== wallet storage locking definitions =="
sed -n '1,260p' "$wallet"

Repository: dashpay/platform

Length of output: 23034

---

Run identity-key repair under withCallbackExclusion before deriveAndStore(force = true).

repairIdentityKey only gates through teardownGate, while deleteWalletData uses withCallbackExclusion before cascading and recordSigningKeyInvalidated holds that exclusion on entry. A concurrent repair can derive/store an identity scalar while a deletion/persist sequence is updating/wiping the same wallet’s Room rows, leaving usable ciphertext behind the deletion or racing a row update. Move the durable derive/store path under withCallbackExclusion, avoiding native calls while the exclusion is held.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/persistence/PlatformWalletPersistenceHandler.kt`
around lines 2673 - 2742, Update repairIdentityKeyDurably to coordinate the
durable repair with deleteWalletData and recordSigningKeyInvalidated through
withCallbackExclusion before invoking deriver.deriveAndStore(force = true),
preserving the existing breadcrumb, verification, persistence, and pending-state
behavior. Ensure native derivation calls are not executed while the callback
exclusion is held, following the established exclusion usage pattern.

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -n -B3 -A15 'DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX' packages/rs-platform-wallet-ffi/src/error.rs

Repository: dashpay/platform

Length of output: 4571

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== candidate error.rs sections =="
sed -n '340,390p' packages/rs-platform-wallet-ffi/src/error.rs
echo
sed -n '440,485p' packages/rs-platform-wallet-ffi/src/error.rs
echo
sed -n '485,505p' packages/rs-platform-wallet-ffi/src/error.rs

echo
echo "== references to SigningKeyUnavailable / DASH_SDK prefix =="
rg -n 'ErrorSigningKeyUnavailable|DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX|signer_error:key_unavailable' packages/rs-sdk-ffi packages/rs-platform-wallet-ffi

Repository: dashpay/platform

Length of output: 6908

---

Strip the signer prefix before surfacing the error message.

ErrorSigningKeyUnavailable is restored correctly from rs_sdk_ffi::DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX, but both conversion paths still pass the message through unchanged: error.to_string() in the catch-all and format!("DPP protocol error: {msg}") in the ProtocolError impl. This leaves signer_error:key_unavailable: in the Kotlin/Swift error message text next to SigningKeyUnavailable.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/rs-sdk-ffi/src/signer.rs` around lines 179 - 188, Strip
DASH_SDK_SIGNER_ERR_KEY_UNAVAILABLE_PREFIX from signer error messages before
surfacing them. Update both conversion paths—the catch-all using
error.to_string() and the ProtocolError implementation formatting "DPP protocol
error: {msg}"—to remove only this prefix while preserving the existing error
text and SigningKeyUnavailable mapping.

[thepastaclaw]

Thanks for splitting the two structural items out rather than guessing on a fund-safety path. Direction from my side:

1. Affected-state wait: agreed — rebase onto current v4.1-dev first, then update the pool-funded and one-time-key Type-20 paths together to the new proof contract. I would not try to introduce wait_for_affected_state selectively on this older head.

2. Claim recovery remains blocking: please add a subwallet-less pending-claim record rather than reusing arm_redrive_record. Persist it before the first broadcast with enough data to replay the exact signed transition and identify/verify the intended result (derived identity ID/index and submitted-key metadata). Reconciliation after cancellation/restart should fetch and verify the derived identity first; if it is absent, rebroadcast the byte-identical transition. If rebroadcast reports NullifierAlreadySpent, fetch/verify the derived identity before declaring success; if it is still absent, surface a terminal conflict rather than silently clearing or rebuilding a different transition. Clear the record only after proof- or fetch-verified success. If that recovery work is moved to a follow-up, the claim API should remain gated/unexposed until the follow-up lands.

3. The key-hygiene blocker is only partially fixed in 5ba2794d: read_key32_zeroizing fixes the JNI input copy, but the claim path still copies the bearer key into a plain [u8; 32] in rs-platform-wallet-ffi and passes it by value into identity_create_from_one_time_key. The inviter path also still leaves native sk, native out, and Kotlin's 75-byte blob containing the key unwiped. Please carry the Rust copies in Zeroizing (or explicitly wipe them) and wipe the Kotlin source blob in a finally after copying out the intentionally caller-owned spendingKey.

The RNG/extern-C abort fix looks correct on inspection. Current head 5ba2794d is already queued for a fresh PastaClaw review, and CodeRabbit has completed its current-head pass.