fix(sdk)!: complete encrypted txMetadata parity

[shumkov]

Issue being fixed or feature implemented

Legacy Dash Wallet installations published encrypted txMetadata documents that current Kotlin and Swift SDKs must be able to create and read wire-compatibly. The original work was split across #4186, #4195, #4194, and this PR, while #4264 later reconstructed only the foundation layer. Those heads did not form one independently mergeable, fully reviewed state.

This PR now consolidates that merge intent directly onto v4.2-dev, while preserving the substantive contributor commits and authorship from the original chain. It also closes the native plaintext-lifetime gaps shared by both hosts. #4185 and rust-dashcore#916 remain a separate dependency chain and do not block this PR.

What was done?

• Implement the legacy versioned AES-CBC envelope, hardened key derivation, payload limits, and independent wire-compatibility vectors, including a blob captured from a stock dash-wallet 11.9 testnet install.
• Add complete encrypted-document create/fetch orchestration, resident-or-resolver key routing, paginated history scanning, and concurrency-safe automatic encryption-key index allocation.
• Keep plaintext-bearing payloads, AES state, JNI copies, and sensitive JSON/C-string allocations in zeroizing owners, including error and unwind paths. The dedicated sensitive free wipes the complete allocation, including its terminator, before deallocation.
• Route Kotlin create through one deferred Rust composite so validation, wallet/key resolution, and index lookup happen before JNI materializes its native plaintext copy; the copy and derived key material are dropped before broadcast.
• Expose equivalent Kotlin and Swift create/fetch APIs while leaving protocol-version validation in Rust. Both hosts document the unavoidable terminal JVM/Swift String residual symmetrically: runtime-managed strings and caller-owned ByteArray/Data cannot be reliably scrubbed by the SDK and must not be logged or retained.
• Fold the existing review must-fixes into the consolidated state: reject oversized payloads before copying, publish null output sentinels before fallible validation, guard native pointers on all exits, sanitize identifiers in breadcrumbs, and remove plaintext-dumping capture scaffolding.
• Preserve feat(sdk): add hardened encrypted txMetadata documents #4264's Kotlin error value by mapping platform-wallet code 2 to typed PlatformWallet.InvalidParameter while retaining Generic(nativeCode = 2) catch compatibility and the Rust-owned message.

After this PR lands, #4186, #4195, #4194, and the interim foundation reconstruction #4264 must not be merged separately; they can be closed as superseded.

How Has This Been Tested?

Red → green regression evidence:

• Mutating a valid envelope to an unsupported version was accepted before the fix and is now rejected.
• Restoring the old FFI fetch order makes empty/failing-fetch tests observe one resolver call instead of zero; the corrected order passes, while a positive decrypt path proves the resolver is still called exactly once when needed.
• Deferred JNI ownership probes failed before the shared composite existed and now pin validation/index resolution before payload materialization and payload/key destruction before broadcast.
• Compile-time cipher-state checks failed without the aes/cbc zeroization features and now prove both encryptor and decryptor implement ZeroizeOnDrop.
• The live public fixture first exposed history growth from 2 to 17 documents; the test now finds and validates the two exact captured legacy document IDs rather than assuming an unrelated total count.
• Before the Kotlin error-mapping fix, the regression did not compile because PlatformWallet.InvalidParameter was absent; it now maps platform-wallet code 2 to the typed subtype while still satisfying existing Generic branches and preserving the core message.

Final verification:

• cargo fmt --all -- --check and git diff --check — passed.
• cargo test -p platform-encryption — 19 passed.
• cargo test -p platform-wallet --lib — 536 passed.
• cargo test -p platform-wallet --test txmetadata_fetch — 1 network test intentionally ignored by default; the explicit ignored/live run passed against testnet.
• cargo test -p platform-wallet-ffi --lib — 239 passed.
• cargo test -p rs-unified-sdk-jni --lib — 50 passed.
• Targeted cargo clippy --all-targets — passed; 13 pre-existing warnings remain outside PR-owned code.
• Clean Android release build/verification for arm64-v8a and x86_64 — passed; exact nm checks found both create/fetch JNI exports. Kotlin debug assembly and unit tests passed. No Android device was attached, so connected-device tests were unavailable.
• Clean Apple release builds for iOS device, iOS simulator, and macOS, XCFramework generation, and SwiftExampleApp warnings-as-errors build — passed. Exact header and binary checks found all four public C exports on both iOS slices and confirmed the Rust-only deferred JNI helper is not exported.
• Swift package tests — 283 executed, 8 intentionally skipped integration tests, 0 failures. SwiftExampleApp simulator unit tests also passed.

Three independent final reviews covered shared security/correctness, Kotlin/Swift host parity, and Swift/Rust FFI ownership; all must-fixes were folded and the final reviewers reported no remaining blockers.

Breaking Changes

Rust source compatibility: OpenedTxMetadata.payload and DecryptedEncryptedDocument.payload change from Vec<u8> to Zeroizing<Vec<u8>>. The C fetch signature, JNI descriptor, Kotlin/Swift signatures, and JSON shape remain unchanged; the sensitive-free and encrypted-document functions are ABI-additive.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

Summary by CodeRabbit

• New Features
  • Added encrypted document creation and retrieval across Kotlin and Swift SDKs.
  • Supports automatic encryption-key index allocation or explicit indexes.
  • Added compatibility with legacy encrypted transaction metadata.
• Bug Fixes
  • Improved validation and error reporting for unsupported versions, oversized payloads, and invalid key indexes.
  • Encrypted fetches now safely skip malformed, unsupported, or undecryptable documents.
• Security
  • Improved clearing of sensitive plaintext, keys, and returned data.
  • Sanitized diagnostic logging to avoid exposing sensitive messages.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Encrypted txMetadata document flow

Layer / File(s)	Summary
Crypto and wire-compatible txMetadata contract packages/rs-platform-encryption/..., packages/rs-platform-wallet/src/wallet/identity/crypto/..., packages/rs-platform-wallet/tests/legacy_wire_compat/...	Adds legacy-compatible key derivation, AES-CBC framing, validation, zeroizing decryption, and compatibility fixtures.
Wallet encrypted-document orchestration packages/rs-platform-wallet/src/wallet/identity/network/..., packages/rs-platform-wallet/src/wallet/identity/..., packages/rs-platform-wallet/tests/...	Adds key-index allocation, encrypted-document preparation and fetching, pagination handling, decryption filtering, wallet wiring, and typed errors.
FFI encrypted-document boundary packages/rs-platform-wallet-ffi/src/..., packages/rs-platform-wallet-ffi/Cargo.toml	Adds FFI creation and fetch operations, sensitive JSON serialization, zeroizing string cleanup, panic containment, and error mapping.
JNI and Kotlin encrypted-document integration packages/rs-unified-sdk-jni/src/..., packages/kotlin-sdk/...	Adds JNI bridges, argument validation, sensitive output cleanup, sanitized breadcrumbs, Kotlin APIs, and tests.
Swift encrypted-document integration packages/swift-sdk/Sources/..., packages/swift-sdk/SwiftTests/...	Adds Swift creation and fetch APIs, pointer lifetime handling, version validation tests, and mnemonic memory-handling documentation.

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

Possibly related PRs

• dashpay/platform#4264: Direct continuation and hardening of the encrypted-document APIs across the same Rust, FFI, JNI, Kotlin, and validation paths.

Suggested reviewers: lklimek, quantumexplorer

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: completing encrypted txMetadata parity across SDK layers.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/txmetadata-decrypt-plaintext-lifetime

---

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.}

[shumkov]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (6)

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

189-194: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Mirror the fetch-side plaintext-residual caveat here.

documentFetchEncrypted's KDoc (Lines 223-227) tells callers the host String is plaintext-equivalent and unscrubuable. The create side takes a caller-owned plaintext ByteArray with the same property and no equivalent note — worth documenting symmetrically since the JNI copy is Zeroizing but the Kotlin-owned array is not.

📝 Proposed KDoc addition

      * `@param` payload the already-serialized opaque plaintext (a protobuf
      *   `TxMetadataBatch`); the SDK does not parse it.
+     *   The native copy is zeroized after the broadcast completes, but this
+     *   caller-owned `ByteArray` is not — overwrite it yourself once the call
+     *   returns if the plaintext must not linger on the JVM heap.
      * `@return` the confirmed document's canonical JSON (its 32-byte id is the
      *   base58 `$id` field).

🤖 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/ffi/TransactionsNative.kt`
around lines 189 - 194, Update the KDoc for the create-side transaction method
near the payload parameter to state that the caller-owned plaintext ByteArray is
plaintext-equivalent and cannot be scrubbed by the SDK; clarify that JNI
zeroization does not erase the Kotlin-owned array. Keep the existing parameter
and return documentation unchanged.

packages/rs-unified-sdk-jni/src/transactions.rs (1)

945-956: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low value

Optional: reuse a pointer guard for the create path's JSON too.

out_json is freed manually here, so a panic between the FFI return and line 956 leaks the allocation (ciphertext-only, so no plaintext exposure). A small non-sensitive analogue of SensitivePlatformWalletString would make both bridges structurally identical.

🤖 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-unified-sdk-jni/src/transactions.rs` around lines 945 - 956, Add
a non-sensitive RAII pointer guard for the encrypted document create path and
use it for out_json in place of the manual platform_wallet_string_free call.
Ensure the guard frees the FFI allocation on normal completion and during
unwinding, while preserving the existing null handling and JSON conversion in
the surrounding create flow.

packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift (1)

3482-3489: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Swift-side wire-version constant duplicates a Rust-owned protocol invariant.

seal_tx_metadata already rejects non-0/1 versions, so this guard hard-codes a wire constant in the Swift bridge purely for a faster error. If you keep it (the existing EncryptedDocumentVersionValidationTests rely on it), consider surfacing the accepted set from Rust rather than literals so the two can't drift.

As per coding guidelines: "In Swift, do not perform ... any reimplementation of protocol constants such as gap limits, key indices, or path shapes."

🤖 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/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift`
around lines 3482 - 3489, The version guard in seal_tx_metadata duplicates
Rust-owned protocol constants by hard-coding 0 and 1 in Swift. Remove this
Swift-side validation and let the Rust FFI enforce accepted versions, updating
EncryptedDocumentVersionValidationTests to assert the resulting propagated error
behavior without relying on the duplicated Swift guard.

Source: Coding guidelines

packages/rs-platform-wallet/src/wallet/identity/network/encrypted_document.rs (1)

226-234: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

WARN breadcrumbs contradict the stated "no identity-correlated data in logcat" rule.

breadcrumb's doc (Lines 216-220) justifies DEBUG precisely so identity/contract/document ids never reach logcat, yet every breadcrumb_error call site embeds owner= and doc= and lands at WARN (logcat-visible). The skip paths (un-materialized entry, missing fields, decrypt failure) are not exceptional enough to treat as one-off diagnostics. Consider truncating the ids (e.g. first 8 hex chars) in the WARN lines so on-device logs stay non-correlatable while remaining actionable.

🤖 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-platform-wallet/src/wallet/identity/network/encrypted_document.rs`
around lines 226 - 234, Update breadcrumb_error and its call sites to prevent
full identity, contract, and document identifiers from reaching WARN-level
logcat output. Truncate each embedded identifier to a non-correlatable short
prefix, such as the first eight hexadecimal characters, while retaining enough
context to distinguish failure or skip paths; leave normal breadcrumb handling
unchanged.

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

313-320: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

The {0, 1} version set is a protocol constant now duplicated in the host.

seal_tx_metadata already rejects any other byte, so this guard restates wire knowledge that the Kotlin SDK is supposed to leave in Rust — and it will silently reject a future version 2 that Rust accepts. If the fail-fast is worth keeping, consider exposing the allowed set from Rust (or a small FFI validation entry point) rather than hardcoding the literals here.

As per coding guidelines, "Do not implement derivation-path construction, policy-loop orchestration, mnemonic/seed processing across JNI, protocol constants... implement these in Rust instead."

🤖 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/documents/DocumentTransactions.kt`
around lines 313 - 320, The version validation in the document transaction flow
duplicates Rust-owned protocol knowledge. Remove the hardcoded require check for
version values 0 and 1 from the surrounding transaction-sealing method, leaving
validation to seal_tx_metadata; do not introduce another Kotlin-side constant or
validation path.

Source: Coding guidelines

packages/rs-platform-wallet/tests/txmetadata_fetch.rs (1)

241-258: 🔒 Security & Privacy | 🔵 Trivial | 💤 Low value

Capture scaffolding permanently prints decrypted plaintext and a recovery phrase.

The hardcoded mnemonic and the PLAINTEXT_HEX / PLAINTEXT_UTF8_LOSSY prints are justified for a designated-throwaway fixture wallet, and the doc comment says so explicitly. Once the vectors are captured into legacy_install_yabba2_wire_compat_vector, this helper's job is done — worth deleting it (or moving it to examples/) rather than leaving a permanent plaintext-dumping code path in the test tree that a future maintainer might re-point at a real wallet.

🤖 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-platform-wallet/tests/txmetadata_fetch.rs` around lines 241 -
258, Remove the temporary plaintext-dumping capture helper and its associated
hardcoded mnemonic/scaffolding from the test tree now that
legacy_install_yabba2_wire_compat_vector contains the vectors. Delete the
PLAINTEXT_HEX and PLAINTEXT_UTF8_LOSSY output along with the helper’s other
diagnostic prints, or move the complete capture utility to examples/ without
leaving a reusable decrypted-data path in tests.

🤖 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/sdk/TXMETADATA_DECRYPT_PLAINTEXT_LIFETIME_SPEC.md`:
- Line 66: Correct the spelling of “unsrubbable” to “unscrubbable” in both the
prose description and the Mermaid node, preserving all other wording and
behavior.

In `@packages/rs-platform-wallet/src/wallet/identity/crypto/tx_metadata.rs`:
- Around line 254-265: Update the derivation flow around derived.private_key in
the transaction metadata key function to explicitly call non_secure_erase()
after copying secret_bytes() and before returning the Zeroizing-wrapped scalar.
Revise the adjacent hygiene comment to remove the incorrect claim that SecretKey
is memzeroed on drop.

In `@packages/rs-platform-wallet/tests/txmetadata_fetch.rs`:
- Around line 57-59: Remove live testnet dependencies from the ignored tests,
including fetch_returns_both_legacy_txmetadata_documents and the second related
test. Mock the SDK/DAPI interactions so the wire query’s where-clause and
order-by shape are asserted offline; alternatively relocate the live probes
outside tests/ and keep hermetic coverage for the query behavior.

In `@packages/rs-unified-sdk-jni/src/support.rs`:
- Around line 78-86: In packages/rs-unified-sdk-jni/src/support.rs lines 78-86,
update take_pwffi_error to keep only the raw and offset codes in the warn! log,
and emit message separately with log::debug!. Apply the same change at lines
104-107: keep only code at warn! and move message to log::debug!, preserving the
existing code values and removing duplicate message emission.

---

Nitpick comments:
In
`@packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/documents/DocumentTransactions.kt`:
- Around line 313-320: The version validation in the document transaction flow
duplicates Rust-owned protocol knowledge. Remove the hardcoded require check for
version values 0 and 1 from the surrounding transaction-sealing method, leaving
validation to seal_tx_metadata; do not introduce another Kotlin-side constant or
validation path.

In
`@packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/TransactionsNative.kt`:
- Around line 189-194: Update the KDoc for the create-side transaction method
near the payload parameter to state that the caller-owned plaintext ByteArray is
plaintext-equivalent and cannot be scrubbed by the SDK; clarify that JNI
zeroization does not erase the Kotlin-owned array. Keep the existing parameter
and return documentation unchanged.

In
`@packages/rs-platform-wallet/src/wallet/identity/network/encrypted_document.rs`:
- Around line 226-234: Update breadcrumb_error and its call sites to prevent
full identity, contract, and document identifiers from reaching WARN-level
logcat output. Truncate each embedded identifier to a non-correlatable short
prefix, such as the first eight hexadecimal characters, while retaining enough
context to distinguish failure or skip paths; leave normal breadcrumb handling
unchanged.

In `@packages/rs-platform-wallet/tests/txmetadata_fetch.rs`:
- Around line 241-258: Remove the temporary plaintext-dumping capture helper and
its associated hardcoded mnemonic/scaffolding from the test tree now that
legacy_install_yabba2_wire_compat_vector contains the vectors. Delete the
PLAINTEXT_HEX and PLAINTEXT_UTF8_LOSSY output along with the helper’s other
diagnostic prints, or move the complete capture utility to examples/ without
leaving a reusable decrypted-data path in tests.

In `@packages/rs-unified-sdk-jni/src/transactions.rs`:
- Around line 945-956: Add a non-sensitive RAII pointer guard for the encrypted
document create path and use it for out_json in place of the manual
platform_wallet_string_free call. Ensure the guard frees the FFI allocation on
normal completion and during unwinding, while preserving the existing null
handling and JSON conversion in the surrounding create flow.

In
`@packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift`:
- Around line 3482-3489: The version guard in seal_tx_metadata duplicates
Rust-owned protocol constants by hard-coding 0 and 1 in Swift. Remove this
Swift-side validation and let the Rust FFI enforce accepted versions, updating
EncryptedDocumentVersionValidationTests to assert the resulting propagated error
behavior without relying on the duplicated Swift guard.

🪄 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: d8bf60e2-0712-41c6-8571-fd95bd90e173

📥 Commits

Reviewing files that changed from the base of the PR and between e1fb911 and e39703d.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (31)

• docs/sdk/TXMETADATA_DECRYPT_PLAINTEXT_LIFETIME_SPEC.md
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/documents/DocumentTransactions.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/TransactionsNative.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/documents/DocumentTransactionsVersionValidationTest.kt
• packages/rs-platform-encryption/Cargo.toml
• packages/rs-platform-encryption/src/aes.rs
• packages/rs-platform-encryption/src/lib.rs
• packages/rs-platform-wallet-ffi/Cargo.toml
• packages/rs-platform-wallet-ffi/src/document.rs
• packages/rs-platform-wallet-ffi/src/error.rs
• packages/rs-platform-wallet-ffi/src/lib.rs
• packages/rs-platform-wallet-ffi/src/tx_metadata_json.rs
• packages/rs-platform-wallet-ffi/src/types.rs
• packages/rs-platform-wallet/Cargo.toml
• packages/rs-platform-wallet/src/error.rs
• packages/rs-platform-wallet/src/lib.rs
• packages/rs-platform-wallet/src/wallet/identity/crypto/mod.rs
• packages/rs-platform-wallet/src/wallet/identity/crypto/tx_metadata.rs
• packages/rs-platform-wallet/src/wallet/identity/network/encrypted_document.rs
• packages/rs-platform-wallet/src/wallet/identity/network/identity_handle.rs
• packages/rs-platform-wallet/src/wallet/identity/network/mod.rs
• packages/rs-platform-wallet/src/wallet/identity/network/payments.rs
• packages/rs-platform-wallet/src/wallet/platform_wallet.rs
• packages/rs-platform-wallet/tests/legacy_wire_compat/LegacyDerivationPathCheck.java
• packages/rs-platform-wallet/tests/legacy_wire_compat/LegacyKeyN.java
• packages/rs-platform-wallet/tests/legacy_wire_compat/README.md
• packages/rs-platform-wallet/tests/txmetadata_fetch.rs
• packages/rs-unified-sdk-jni/src/support.rs
• packages/rs-unified-sdk-jni/src/transactions.rs
• packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift
• packages/swift-sdk/SwiftTests/SwiftDashSDKTests/EncryptedDocumentVersionValidationTests.swift

[shumkov]

Nitpick comments (6)

Declined on this U7 branch: all six suggestions target inherited dependency-stack code rather than the decrypt plaintext-lifetime change—#4186 owns the Kotlin create KDoc/version guard, JNI create JSON cleanup, wallet breadcrumbs, and capture helper; #4194 owns the Swift version guard. U7 is intentionally limited to the shared decrypt path and host residual documentation, so applying these here would duplicate parent/host fixes. They should land in their originating PRs and flow forward into this branch.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.55%. Comparing base (bfc8024) to head (f845f9d).
⚠️ Report is 4 commits behind head on v4.2-dev.

Additional details and impacted files

@@            Coverage Diff             @@
##           v4.2-dev    #4243    +/-   ##
==========================================
  Coverage     87.54%   87.55%            
==========================================
  Files          2670     2671     +1     
  Lines        338763   338973   +210     
==========================================
+ Hits         296583   296778   +195     
- Misses        42180    42195    +15     

Components	Coverage Δ
dpp	88.49% <ø> (ø)
drive	86.33% <ø> (+<0.01%)	⬆️
drive-abci	89.57% <ø> (ø)
sdk	∅ <ø> (∅)
dapi-client	∅ <ø> (∅)
platform-version	∅ <ø> (∅)
platform-value	92.88% <ø> (ø)
platform-wallet	∅ <ø> (∅)
drive-proof-verifier	49.60% <ø> (-0.19%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[thepastaclaw]

⛔ Blockers found — Sonnet deferred (commit f845f9d)
Canonical validated blockers: 1

[thepastaclaw]

Preliminary review — Codex only

The decrypt-side zeroizing ownership chain is coherent, but two blocking FFI boundary defects remain: oversized payloads are copied before deterministic rejection, and the sensitive fetch out-pointer is not cleared on every documented error path. The JNI guard is correctly installed immediately after ownership transfer, but its security-critical cleanup behavior lacks the regression coverage required by the implementation plan.

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 — rust-quality (completed), gpt-5.6-sol — ffi-engineer (completed)
• Verifier: gpt-5.6-sol — verifier
• Sonnet: not run (deferred by blocker gate)

🔴 2 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-ffi/src/document.rs`:
- [BLOCKING] packages/rs-platform-wallet-ffi/src/document.rs:440-450: Validate payload size before making the native plaintext copy
  Both encrypted-document create exports enter this shared code and copy all `payload_len` bytes before applying the deterministic 4063-byte limit. The auto-index path validates only later in `allocate_encryption_key_index`, while the explicit-index path does not validate until `prepare_encrypted_txmetadata_properties`, after `tx_metadata_key_master_for_wallet` may have invoked the host resolver and constructed an `ExtendedPrivKey`. An input guaranteed to return `TxMetadataPayloadTooLarge` can therefore create a large native plaintext allocation and potentially abort the process on allocation failure; through JNI, `convert_byte_array` has already created another full native copy. Call `ensure_tx_metadata_payload_fits(payload_len)` before `slice::from_raw_parts(...).to_vec()`, and expose the same maximum to the JNI layer so it can inspect the Java array length before conversion.
- [BLOCKING] packages/rs-platform-wallet-ffi/src/document.rs:591-594: Clear the sensitive out-pointer before validating other inputs
  The function documents that `*out_documents_json` is left null on every error, but it checks `document_type_name` before validating and clearing the out-pointer. If a caller reuses an output variable containing an earlier allocation and passes a null document type, this function returns without changing that stale pointer. A caller performing unconditional documented cleanup can then pass it to `platform_wallet_sensitive_string_free` again, causing a double free. Validate `out_documents_json` and publish the null sentinel before every other fallible input check.

In `packages/rs-unified-sdk-jni/src/transactions.rs`:
- [SUGGESTION] packages/rs-unified-sdk-jni/src/transactions.rs:53-109: Add regression tests for the JNI sensitive-pointer guard
  `SensitivePlatformWalletString` is the final native owner after the FFI transfers decrypted JSON, and the raw `NewStringUTF` path deliberately bypasses jni-rs allocation helpers. No JNI test references either component, even though the checked-in verification plan explicitly requires coverage. A future change that installs the guard after an early return, switches it to the ordinary string free, or fails to release on JNI allocation failure or unwind would compile and leave the current suite green. Add a testable release-callback seam covering normal drop, null ownership, early return, and unwind, and pin the ASCII/no-interior-NUL precondition required by `NewStringUTF`.

[shumkov]

@QuantumExplorer — a scheduling ask before I start the encrypted-txMetadata chain. Plan is four owned same-repository layers replacing #4186 / #4195 / #4194, plus this PR rebuilt as a surgical delta.

Where you're a hard dependency — three of the four layers touch packages/rs-unified-sdk-jni, packages/kotlin-sdk, or packages/rs-platform-encryption, none of which have a CODEOWNERS rule, so they fall to the catch-all * @QuantumExplorer:

• Foundation replacement (~3,200 lines; wallet + FFI + JNI + Kotlin)
• Allocator successor (wallet + FFI + JNI + Kotlin)
• Decrypt-lifetime layer (encryption + wallet + FFI + JNI + Kotlin/Swift docs)

Since I'm authoring all of them, I can't self-approve, so those three need you specifically.

Where you're not required — the Swift wrapper layer touches only packages/swift-sdk/, which has listed owners @QuantumExplorer @shumkov @llbartekll @ZocoLini. @llbartekll or @ZocoLini can approve that one as a non-author code owner. You're very welcome to review it too, but it doesn't have to wait on you.

So: three required approvals from you, each on a reconstructed v4.2-dev head. Stacked drafts are interface preflight only and won't request your review. The foundation is the heaviest — a ~3,200-line replacement that has never had an isolated full-diff review or an isolated Rust run.

Are you available over the next stretch? If not, the plan's stop condition says we don't start.

[coderabbitai]

🧹 Nitpick comments (3)

packages/rs-unified-sdk-jni/src/transactions.rs (1)

1455-1498: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

The source-text test pins formatting and comment text, not behavior.

production_jni_create_routes_through_one_deferred_composite reads its own file and matches literal source fragments. Two of the assertions break on changes that do not alter behavior:

• Line 1464 depends on the doc comment /// Fetch + DECRYPT every encrypted wallet-contract document staying verbatim. Any edit to that sentence makes the split panic with "encrypted-create export must end before the fetch export".
• Line 1487 requires the exact normalized fragment payload_len, || match env.convert_byte_array(&payload). A rustfmt release that wraps the closure differently, or an inline comment between the two arguments, fails the test while the bridge is still correct.

Consider keeping the call-count and negative assertions, and dropping the adjacency assertion at line 1487. Alternatively, mark the delimiter with a stable marker comment instead of prose.

🤖 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-unified-sdk-jni/src/transactions.rs` around lines 1455 - 1498,
The source-text test production_jni_create_routes_through_one_deferred_composite
relies on unstable documentation and formatting. Replace the prose doc-comment
delimiter with a stable source marker or another behavior-independent boundary,
and remove the exact normalized payload_len closure assertion; retain the
composite-call count, single array-conversion count, and negative
allocator/second-create assertions.

packages/rs-platform-wallet/src/wallet/identity/network/encrypted_document.rs (2)

584-642: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider extracting the shared body of the two encryption-context resolvers.

resolve_encryption_context and resolve_encryption_context_blocking differ only in how they acquire the read guard. The remaining ~20 lines — wallet-info lookup, managed-identity lookup, identity_index check, identity clone, wallet clone — are duplicated verbatim, including the error messages. A future change to one resolver can silently diverge from the other.

Extract the post-lock logic into one private helper that takes the guard, then keep the two public entry points as thin wrappers.

♻️ Sketch of the shared helper

fn resolve_from_guard(
    &self,
    wm: &WalletManager<PlatformWalletInfo>,
    owner_identity_id: &Identifier,
) -> Result<(dpp::identity::Identity, u32, key_wallet::wallet::Wallet), PlatformWalletError> {
    // existing body, unchanged
}

async fn resolve_encryption_context(&self, owner: &Identifier) -> Result<..> {
    let wm = self.wallet_manager.read().await;
    self.resolve_from_guard(&wm, owner)
}

fn resolve_encryption_context_blocking(&self, owner: &Identifier) -> Result<..> {
    let wm = self.wallet_manager.blocking_read();
    self.resolve_from_guard(&wm, owner)
}

🤖 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-platform-wallet/src/wallet/identity/network/encrypted_document.rs`
around lines 584 - 642, Extract the duplicated wallet-info and managed-identity
resolution logic from resolve_encryption_context and
resolve_encryption_context_blocking into a private resolve_from_guard helper
accepting the read guard and owner identity. Keep both existing resolvers as
thin wrappers that acquire their respective async or blocking guard, delegate to
the helper, and preserve all current return types and error behavior.

---

1030-1061: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

The scan has no upper bound on pages or accumulated entries.

PaginationProgress stops a scan only when a cursor repeats. A source that keeps returning full pages with fresh cursors makes the loop run forever, and raw_docs grows without bound in the process. Both query_owned_encrypted_documents callers are affected: the fetch path and count_owned_txmetadata_documents, which is on the create path.

The stall detector already owns the "when do we stop" decision, so a maximum page count fits there. issued_cursors also grows one entry per page, so the same cap bounds it.

This needs a faulty or hostile Drive to trigger, so it is hardening rather than an active defect.

🛡️ Sketch of a page cap in `record_page`

 impl PaginationProgress {
+    /// Upper bound on pages one scan may read. At `PAGE = 100` this covers
+    /// far more documents than any wallet holds, so reaching it means the
+    /// source is not behaving.
+    const MAX_PAGES: usize = 1_000;
+
     fn record_page(
         &mut self,
         page_len: usize,
         page_limit: usize,
         last_id: Option<Identifier>,
     ) -> Result<NextPage, PlatformWalletError> {
         self.pages_read += 1;
 
         // A page the source could not fill is the last page.
         if page_len < page_limit {
             return Ok(NextPage::Done);
         }
+
+        if self.pages_read >= Self::MAX_PAGES {
+            return Err(PlatformWalletError::EncryptedDocumentPaginationStalled {
+                pages: self.pages_read,
+            });
+        }

Also applies to: 1099-1146

🤖 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-platform-wallet/src/wallet/identity/network/encrypted_document.rs`
around lines 1030 - 1061, Update PaginationProgress::record_page to enforce a
maximum page count before accepting another full page, returning the established
pagination-limit error when the cap is reached. Define or reuse a shared maximum
so both query_owned_encrypted_documents callers, including
count_owned_txmetadata_documents, stop consistently and issued_cursors/raw_docs
remain bounded; preserve existing short-page completion and repeated-cursor
stall behavior.

🤖 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.

Nitpick comments:
In
`@packages/rs-platform-wallet/src/wallet/identity/network/encrypted_document.rs`:
- Around line 584-642: Extract the duplicated wallet-info and managed-identity
resolution logic from resolve_encryption_context and
resolve_encryption_context_blocking into a private resolve_from_guard helper
accepting the read guard and owner identity. Keep both existing resolvers as
thin wrappers that acquire their respective async or blocking guard, delegate to
the helper, and preserve all current return types and error behavior.
- Around line 1030-1061: Update PaginationProgress::record_page to enforce a
maximum page count before accepting another full page, returning the established
pagination-limit error when the cap is reached. Define or reuse a shared maximum
so both query_owned_encrypted_documents callers, including
count_owned_txmetadata_documents, stop consistently and issued_cursors/raw_docs
remain bounded; preserve existing short-page completion and repeated-cursor
stall behavior.

In `@packages/rs-unified-sdk-jni/src/transactions.rs`:
- Around line 1455-1498: The source-text test
production_jni_create_routes_through_one_deferred_composite relies on unstable
documentation and formatting. Replace the prose doc-comment delimiter with a
stable source marker or another behavior-independent boundary, and remove the
exact normalized payload_len closure assertion; retain the composite-call count,
single array-conversion count, and negative allocator/second-create assertions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 68d79281-7825-4b21-b8bc-f9cf19489357

📥 Commits

Reviewing files that changed from the base of the PR and between 9870f4f and 188549c.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (24)

• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/documents/DocumentTransactions.kt
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/TransactionsNative.kt
• packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/documents/DocumentTransactionsEncryptionKeyIndexTest.kt
• packages/rs-platform-encryption/Cargo.toml
• packages/rs-platform-encryption/src/aes.rs
• packages/rs-platform-wallet-ffi/src/document.rs
• packages/rs-platform-wallet-ffi/src/error.rs
• packages/rs-platform-wallet-ffi/src/lib.rs
• packages/rs-platform-wallet-ffi/src/runtime.rs
• packages/rs-platform-wallet-ffi/src/tx_metadata_json.rs
• packages/rs-platform-wallet/src/error.rs
• packages/rs-platform-wallet/src/wallet/identity/crypto/tx_metadata.rs
• packages/rs-platform-wallet/src/wallet/identity/network/encrypted_document.rs
• packages/rs-platform-wallet/src/wallet/identity/network/identity_handle.rs
• packages/rs-platform-wallet/src/wallet/platform_wallet.rs
• packages/rs-platform-wallet/tests/legacy_wire_compat/LegacyDerivationPathCheck.java
• packages/rs-platform-wallet/tests/legacy_wire_compat/README.md
• packages/rs-platform-wallet/tests/txmetadata_fetch.rs
• packages/rs-unified-sdk-jni/src/support.rs
• packages/rs-unified-sdk-jni/src/transactions.rs
• packages/swift-sdk/Sources/SwiftDashSDK/Core/Wallet/WalletStorage.swift
• packages/swift-sdk/Sources/SwiftDashSDK/FFI/MnemonicResolverAndPersister.swift
• packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/ManagedPlatformWallet.swift
• packages/swift-sdk/SwiftTests/SwiftDashSDKTests/EncryptedDocumentVersionValidationTests.swift

🚧 Files skipped from review as they are similar to previous changes (7)

• packages/rs-platform-encryption/Cargo.toml
• packages/rs-platform-wallet/src/wallet/platform_wallet.rs
• packages/rs-platform-wallet/tests/legacy_wire_compat/LegacyDerivationPathCheck.java
• packages/rs-platform-wallet/tests/legacy_wire_compat/README.md
• packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/documents/DocumentTransactions.kt
• packages/rs-platform-encryption/src/aes.rs
• packages/rs-platform-wallet-ffi/src/tx_metadata_json.rs

[shumkov]

Fresh CodeRabbit nitpick disposition on 188549cdf7:

• The JNI production-route source check is intentionally retained. Unit seams prove the deferred composite behavior, but only this structural regression proves the exported JNI method actually routes through that composite exactly once, converts the array exactly once inside the materializer, and does not call the standalone allocator/create exports. It normalizes whitespace, and the stronger adjacency assertion is deliberate for this security-sensitive ownership order. The stable behavior tests remain the primary coverage; this is a production-wiring tripwire.
• The duplicated post-lock resolver body is acknowledged but not refactored here. The async and blocking entry points intentionally differ at lock acquisition, current behavior is covered, and extracting a helper would be maintenance-only churn outside the surgical security/parity scope.
• The unbounded fresh-cursor pagination case is acknowledged as availability hardening, not a correctness blocker. Create-side legacy compatibility requires scanning complete history; choosing an arbitrary cap would introduce a new policy and could reject a legitimate high-history wallet. Repeated/stalled cursors are already rejected, and the independent security review accepted the remaining hostile-source/OOM case as a future P2 hardening item.

All required CI is green on the current head, all inline threads are resolved, and PastaClaw re-review has been requested to clear its stale pre-fix CHANGES_REQUESTED review.

[shumkov]

@thepastaclaw please re-review current head 188549cdf7. All three findings from the stale 9870f4f5d7 changes-requested review are addressed: payload length is rejected before JNI/native copying, the sensitive output sentinel is published before other validation, and the JNI ownership guard has regression coverage for cleanup and production routing. Replies are on the original threads, every thread is resolved, and all CI is green.

[thepastaclaw]

Preliminary review — Codex only

Carried forward: the payload-size pre-copy blocker and sensitive out-pointer blocker are fixed at the current head, while the prior JNI guard test-coverage suggestion remains valid because the added tests do not verify which free function is called. Genuinely new: the create orchestration materializes native plaintext before potentially blocking wallet/key resolution. That new in-scope security issue is blocking, so changes are required.

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 — rust-quality (completed), gpt-5.6-sol — ffi-engineer (completed)
• Verifier: gpt-5.6-sol — verifier
• Sonnet: not run (deferred by blocker gate)

🔴 1 blocking

1 carried-forward finding(s) already raised on this PR; not re-posting as new inline comments.

🤖 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-ffi/src/document.rs`:
- [BLOCKING] packages/rs-platform-wallet-ffi/src/document.rs:1051-1064: Resolve the encryption context before materializing plaintext
  `settle_index_and_materialize_payload` has already invoked the deferred JNI callback and returned an owned `Zeroizing<Vec<u8>>` before `tx_metadata_key_master_for_wallet` acquires wallet state and may synchronously invoke the host mnemonic resolver. The Kotlin resolver performs blocking DataStore/Keystore retrieval, and the Swift resolver reads Keychain data that may require authentication, so this stage can stall while the new native plaintext copy remains resident. Resolver failure, missing identity context, or encryption-key selection failure also discards a copy that never needed to be created. Refactor the sequence to preflight, settle the index, resolve the wallet identity and key source, materialize the payload, seal and drop all secrets, then broadcast. Add an ordering regression proving the materializer is not invoked when context or resolver resolution fails.

[thepastaclaw]

🔴 Blocking: Resolve the encryption context before materializing plaintext

settle_index_and_materialize_payload has already invoked the deferred JNI callback and returned an owned Zeroizing<Vec<u8>> before tx_metadata_key_master_for_wallet acquires wallet state and may synchronously invoke the host mnemonic resolver. The Kotlin resolver performs blocking DataStore/Keystore retrieval, and the Swift resolver reads Keychain data that may require authentication, so this stage can stall while the new native plaintext copy remains resident. Resolver failure, missing identity context, or encryption-key selection failure also discards a copy that never needed to be created. Refactor the sequence to preflight, settle the index, resolve the wallet identity and key source, materialize the payload, seal and drop all secrets, then broadcast. Add an ordering regression proving the materializer is not invoked when context or resolver resolution fails.

_{source: ['codex']}