Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
fc16a19
feat(platform-wallet): plan a shielded spend with its exact fee and s…
romchornyi Nov 11, 2026
dc97f28
feat(swift-sdk): plan a shielded spend and spend against the plan
romchornyi Nov 11, 2026
9987774
fix(platform-wallet): bind the planned shielded spend to one protocol…
romchornyi Nov 11, 2026
b1439de
feat(dpp): add the most shielded actions one transition can carry
romchornyi Nov 12, 2026
d87d16c
fix(platform-wallet): bound shielded note selection by the state tran…
romchornyi Nov 12, 2026
be3bb2e
fix(platform-wallet): refuse a shielded spend when the protocol versi…
romchornyi Nov 12, 2026
bdabbbd
fix(platform-wallet): plan a shielded withdrawal with its Core fee
romchornyi Nov 12, 2026
dbb05dd
fix(platform-wallet): order equal-value notes by nullifier and descri…
romchornyi Nov 12, 2026
692b731
feat(dpp): share shielded withdrawal preflight and recipient output
romchornyi Nov 12, 2026
226946f
fix(platform-wallet): plan withdrawals with DPP's preflight and round…
romchornyi Nov 12, 2026
58ee1cb
fix(platform-wallet): check the captured protocol version and fee rig…
romchornyi Nov 12, 2026
defb090
fix(platform-wallet): check a shielded spend against the verified net…
romchornyi Nov 12, 2026
13bf4e5
fix(platform-wallet): keep recovery from dispatching a shielded spend…
romchornyi Nov 12, 2026
084d1f8
fix(platform-wallet): refuse a shielded spend plan for a transition n…
romchornyi Nov 12, 2026
69fed53
docs(dpp): justify the in-place extractions in shipped withdrawal gen…
romchornyi Nov 12, 2026
40b07fa
fix(platform-wallet): recheck the pricing version after the store rea…
romchornyi Nov 12, 2026
5d64902
fix(platform-wallet): check the spend context before every shielded d…
romchornyi Nov 12, 2026
4cbf6b6
fix(platform-wallet): size the shielded seeding batch with its asset-…
romchornyi Nov 12, 2026
3cfaed4
fix(platform-wallet): rebroadcast a recovered shielded spend through …
romchornyi Nov 13, 2026
e74382b
Merge remote-tracking branch 'origin/v5.1-dev' into feat/platform-wal…
romchornyi Nov 13, 2026
2715247
fix(platform-wallet): keep the reservations of a recovery record whos…
romchornyi Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions docs/sdk/sdk-parity-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,13 @@
"platform_wallet_manager_persistence_capabilities": "packages/rs-platform-wallet-ffi/src/manager.rs",
"platform_wallet_manager_send_private_contact_request": "packages/rs-platform-wallet-ffi/src/private_contact_request.rs",
"platform_wallet_manager_shielded_fund_from_wallet_drain": "packages/rs-platform-wallet-ffi/src/shielded_wallet_drain.rs",
"platform_wallet_manager_shielded_identity_top_up_from_pool_with_plan": "packages/rs-platform-wallet-ffi/src/shielded_send.rs",
"platform_wallet_manager_shielded_plan_spend": "packages/rs-platform-wallet-ffi/src/shielded_send.rs",
"platform_wallet_manager_shielded_transfer_with_plan": "packages/rs-platform-wallet-ffi/src/shielded_send.rs",
"platform_wallet_manager_shielded_unshield_with_plan": "packages/rs-platform-wallet-ffi/src/shielded_send.rs",
"platform_wallet_manager_shielded_wallet_drain_preview": "packages/rs-platform-wallet-ffi/src/shielded_wallet_drain.rs",
"platform_wallet_manager_shielded_wallet_drain_status": "packages/rs-platform-wallet-ffi/src/shielded_wallet_drain.rs",
"platform_wallet_manager_shielded_withdraw_with_plan": "packages/rs-platform-wallet-ffi/src/shielded_send.rs",
"platform_wallet_manager_spv_rescan_filters": "packages/rs-platform-wallet-ffi/src/spv.rs",
"platform_wallet_manager_sync_fault_detected": "packages/rs-platform-wallet-ffi/src/manager.rs",
"platform_wallet_resume_identity_with_existing_asset_lock_signer": "packages/rs-platform-wallet-ffi/src/identity_registration_funded_with_signer.rs",
Expand Down Expand Up @@ -1979,6 +1984,75 @@
}
]
},
{
"id": "shielded.spend_plan",
"title": "Plan a shielded spend with its exact fee and spend against that plan (code 77)",
"area": "correctness",
"shared_apis": [
"platform_wallet_manager_shielded_plan_spend",
"platform_wallet_manager_shielded_transfer_with_plan",
"platform_wallet_manager_shielded_unshield_with_plan",
"platform_wallet_manager_shielded_withdraw_with_plan",
"platform_wallet_manager_shielded_identity_top_up_from_pool_with_plan"
],
"required_persistence_capabilities": [],
"hosts": {
"swift": {
"sdk": "supported",
"example_app": "unsupported",
"restart": "not_applicable",
"reason": "PlatformWalletManager.shieldedPlanSpend returns a ShieldedSpendPlan (kind, amount, exact fee, total input and debited, note count, digest) for an exact amount or a sweep, and shieldedTransfer, shieldedUnshield, shieldedWithdraw and shieldedIdentityTopUpFromPool each have an overload taking an explicit plan, whose digest goes to the _with_plan export, beside their unchanged original signatures; code 77 is typed as PlatformWalletError.shieldedPlanChanged and code 78 (a spend of more notes than one transition spends) as PlatformWalletError.shieldedSpendTooManyNotes (ErrorHandlingTests pins). A plan is read-only, so there is nothing to resume after a restart. SwiftExampleApp does not plan its shielded spends."
},
"kotlin": {
"sdk": "unsupported",
"example_app": "unsupported",
"restart": "not_applicable",
"reason": "Code 77 maps to DashSdkError.PlatformWallet.ShieldedPlanChanged (DashSdkErrorTest), but no JNI wrapper plans a shielded spend or spends against a plan."
}
},
"verification": [
{
"host": "swift",
"kind": "unit",
"file": "packages/swift-sdk/SwiftTests/SwiftDashSDKTests/ShieldedSpendPlanTests.swift",
"id": "testShouldDecodeEveryFieldOfThePlan",
"command": "cd packages/swift-sdk && xcodebuild test -scheme SwiftDashSDK -sdk iphonesimulator -destination \"platform=iOS Simulator,name=iPhone 17\" ARCHS=arm64 -only-testing:SwiftDashSDKTests/ShieldedSpendPlanTests",
"covers_restart": false
},
{
"host": "swift",
"kind": "unit",
"file": "packages/swift-sdk/SwiftTests/SwiftDashSDKTests/ShieldedSpendPlanTests.swift",
"id": "testShouldPassAPlanToEverySpendsFFI",
"command": "cd packages/swift-sdk && xcodebuild test -scheme SwiftDashSDK -sdk iphonesimulator -destination \"platform=iOS Simulator,name=iPhone 17\" ARCHS=arm64 -only-testing:SwiftDashSDKTests/ShieldedSpendPlanTests",
"covers_restart": false
},
{
"host": "swift",
"kind": "unit",
"file": "packages/swift-sdk/SwiftTests/SwiftDashSDKTests/ErrorHandlingTests.swift",
"id": "testShouldReportAChangedShieldedPlanByItsOwnCode",
"command": "cd packages/swift-sdk && xcodebuild test -scheme SwiftDashSDK -sdk iphonesimulator -destination \"platform=iOS Simulator,name=iPhone 17\" ARCHS=arm64 -only-testing:SwiftDashSDKTests/ErrorHandlingTests",
"covers_restart": false
},
{
"host": "shared",
"kind": "unit",
"file": "packages/rs-platform-wallet/src/wallet/shielded/operations.rs",
"id": "should_refuse_a_plan_whose_notes_moved_and_reserve_nothing",
"command": "cargo test -p platform-wallet --features shielded --lib should_refuse_a_plan_whose_notes_moved_and_reserve_nothing",
"covers_restart": false
},
{
"host": "shared",
"kind": "unit",
"file": "packages/rs-platform-wallet-ffi/src/shielded_send.rs",
"id": "should_reject_a_spend_plan_with_null_pointers_or_an_unknown_kind",
"command": "cargo test -p platform-wallet-ffi --features platform-wallet-ffi/shielded --lib should_reject_a_spend_plan_with_null_pointers_or_an_unknown_kind",
"covers_restart": false
}
]
},
{
"id": "network.adaptive_quorum_source",
"title": "Adaptive quorum-key source (Auto/SPV/Trusted) served by the wallet manager's SPV",
Expand Down
15 changes: 8 additions & 7 deletions packages/kotlin-sdk/PARITY_SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,23 @@
# Kotlin/Swift executable parity summary

Audit baseline: `PR #3999 @ 6dbc72a54df72d26eb9c4a014b425d2b95134e4e`
Capabilities tracked: **30**
Capabilities tracked: **31**

## Status counts

| Host | Surface | Supported | Partial | Unsupported | Not applicable |
| --- | --- | ---: | ---: | ---: | ---: |
| Swift | SDK | 17 | 11 | 1 | 1 |
| Swift | Example app | 5 | 14 | 2 | 9 |
| Kotlin | SDK | 14 | 14 | 1 | 1 |
| Kotlin | Example app | 6 | 13 | 1 | 10 |
| Swift | SDK | 18 | 11 | 1 | 1 |
| Swift | Example app | 5 | 14 | 3 | 9 |
| Kotlin | SDK | 14 | 14 | 2 | 1 |
| Kotlin | Example app | 6 | 13 | 2 | 10 |

## Restart coverage

| Host | Tested | Required | Not applicable |
| --- | ---: | ---: | ---: |
| Swift | 2 | 10 | 18 |
| Kotlin | 5 | 8 | 17 |
| Swift | 2 | 10 | 19 |
| Kotlin | 5 | 8 | 18 |

## Capability status

Expand Down Expand Up @@ -53,6 +53,7 @@ Capabilities tracked: **30**
| `persistence.pending_identity_key_repair` | unsupported / unsupported / not_applicable | supported / not-applicable / tested |
| `errors.signing_key_unavailable_discriminator` | supported / not-applicable / not_applicable | supported / not-applicable / not_applicable |
| `shielded.core_wallet_drain` | supported / unsupported / tested | unsupported / unsupported / not_applicable |
| `shielded.spend_plan` | supported / unsupported / not_applicable | unsupported / unsupported / not_applicable |
| `network.adaptive_quorum_source` | supported / supported / tested | supported / supported / tested |

Source: [`docs/sdk/sdk-parity-manifest.json`](../../docs/sdk/sdk-parity-manifest.json).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -795,6 +795,38 @@ sealed class DashSdkError(
class PublicContactRequestUnconfirmed(message: String, cause: Throwable? = null) :
PlatformWallet(message, cause)

/**
* `ErrorShieldedPlanChanged` (native code 77). A shielded spend run
* against a plan (`platform_wallet_manager_shielded_plan_spend`, then
* a `_with_plan` spend) selected different notes or a different fee
* than the plan, as the wallet's notes changed since. Nothing was
* reserved, built or broadcast: plan again and confirm the new fee.
* ← Swift `PlatformWalletError.shieldedPlanChanged`.
*/
class ShieldedPlanChanged(message: String, cause: Throwable? = null) :
PlatformWallet(message, cause)

/**
* `ErrorShieldedSpendTooManyNotes` (native code 78). The wallet's
* notes cover a shielded spend, or its plan, only with more notes
* than one shielded transition spends
* (`max_shielded_actions_per_transition`). Nothing was reserved, built or
* broadcast: a smaller amount fits, or the notes can be merged first.
* ← Swift `PlatformWalletError.shieldedSpendTooManyNotes`.
*/
class ShieldedSpendTooManyNotes(message: String, cause: Throwable? = null) :
PlatformWallet(message, cause)

/**
* `ErrorShieldedWithdrawalAmountOutOfRange` (native code 79). A
* shielded withdrawal, or its plan, reserves an amount for Core below
* the protocol minimum for its Core fee rate or above the maximum.
* Nothing was reserved, built or broadcast: another amount fits.
* ← Swift `PlatformWalletError.shieldedWithdrawalAmountOutOfRange`.
*/
class ShieldedWithdrawalAmountOutOfRange(message: String, cause: Throwable? = null) :
PlatformWallet(message, cause)

/**
* Any other `PlatformWalletFFIResultCode` without a dedicated type.
* Carries the platform-wallet [nativeCode] (already de-offset) and
Expand Down Expand Up @@ -1004,6 +1036,9 @@ sealed class DashSdkError(
74 -> PlatformWallet.PrivateContactStoreNotRead(message, cause) // ErrorPrivateContactStoreNotRead
75 -> PlatformWallet.SdkPinnedBelowProtocolVersion(message, cause) // ErrorSdkPinnedBelowProtocolVersion
76 -> PlatformWallet.PublicContactRequestUnconfirmed(message, cause) // ErrorPublicContactRequestUnconfirmed
77 -> PlatformWallet.ShieldedPlanChanged(message, cause) // ErrorShieldedPlanChanged
78 -> PlatformWallet.ShieldedSpendTooManyNotes(message, cause) // ErrorShieldedSpendTooManyNotes
79 -> PlatformWallet.ShieldedWithdrawalAmountOutOfRange(message, cause) // ErrorShieldedWithdrawalAmountOutOfRange
else ->
// @Deprecated fallback — see the code-6 arm; code 31 is the
// real discriminator.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -400,6 +400,54 @@ class DashSdkErrorTest {
assertFalse("a sync settles it, not a retry", mapped.isRetryable)
}

/**
* A shielded spend run against a plan whose notes moved since has its own
* code, apart from an unconfirmed spend (18): nothing was sent, and the
* spend needs a new plan and a new confirmation, not a retry.
*/
@Test
fun shouldReportAChangedShieldedPlanByItsOwnCode() {
val detail = "the shielded spend no longer selects the planned notes"
val native = DashSDKException(DashSdkError.PLATFORM_WALLET_CODE_OFFSET + 77, detail)
val mapped = DashSdkError.fromNative(native)
assertTrue(mapped is DashSdkError.PlatformWallet.ShieldedPlanChanged)
assertFalse(mapped is DashSdkError.PlatformWallet.ShieldedSpendUnconfirmed)
assertEquals(detail, mapped.message)
assertFalse("plan again and confirm, not a retry", mapped.isRetryable)
}

/**
* A shielded spend the notes cover only with more notes than one
* transition spends has its own code: nothing was sent, and a smaller
* amount fits, so it is neither a retry nor a balance shortfall (41).
*/
@Test
fun shouldReportAShieldedSpendOfTooManyNotesByItsOwnCode() {
val detail = "Shielded spend needs 17 notes, more than the 16 one transition can spend"
val native = DashSDKException(DashSdkError.PLATFORM_WALLET_CODE_OFFSET + 78, detail)
val mapped = DashSdkError.fromNative(native)
assertTrue(mapped is DashSdkError.PlatformWallet.ShieldedSpendTooManyNotes)
assertFalse(mapped is DashSdkError.PlatformWallet.PlatformShieldCapacityExceeded)
assertEquals(detail, mapped.message)
assertFalse("a smaller amount fits, not a retry", mapped.isRetryable)
}

/**
* A shielded withdrawal amount outside the protocol bounds has its own
* code: nothing was sent, and another amount fits, so it is neither a
* retry nor a balance shortfall (41).
*/
@Test
fun shouldReportAWithdrawalAmountOutOfRangeByItsOwnCode() {
val detail = "Shielded withdrawal amount 1 is outside the allowed range 1000000 to 50000000000000"
val native = DashSDKException(DashSdkError.PLATFORM_WALLET_CODE_OFFSET + 79, detail)
val mapped = DashSdkError.fromNative(native)
assertTrue(mapped is DashSdkError.PlatformWallet.ShieldedWithdrawalAmountOutOfRange)
assertFalse(mapped is DashSdkError.PlatformWallet.PlatformShieldCapacityExceeded)
assertEquals(detail, mapped.message)
assertFalse("another amount fits, not a retry", mapped.isRetryable)
}

@Test
fun platformShieldCapacityCode41MapsTyped() {
val message =
Expand Down
127 changes: 127 additions & 0 deletions packages/rs-dpp/src/shielded/builder/max_actions_tests.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
use super::test_helpers::{test_orchard_address, test_spendable_note, TestProver};
use super::*;
use crate::address_funds::PlatformAddress;
use crate::identity::core_script::CoreScript;
use crate::serialization::PlatformSerializable;
use crate::shielded::max_shielded_actions_per_transition;
use crate::state_transition::StateTransition;
use crate::withdrawal::Pooling;
use grovedb_commitment_tree::{
Anchor, ExtractedNoteCommitment, FullViewingKey, SpendAuthorizingKey, SpendingKey,
};
use platform_value::Identifier;
use platform_version::version::PlatformVersion;

const NOTE_VALUE: u64 = 100_000_000_000;

fn keys() -> (FullViewingKey, SpendAuthorizingKey) {
let sk = SpendingKey::from_bytes([42u8; 32]).expect("valid spending key bytes");
(FullViewingKey::from(&sk), SpendAuthorizingKey::from(&sk))
}

fn notes(count: usize) -> Vec<SpendableNote> {
(0..count)
.map(|_| test_spendable_note(NOTE_VALUE))
.collect()
}

fn anchor() -> Anchor {
let note = test_spendable_note(NOTE_VALUE);
note.merkle_path
.root(ExtractedNoteCommitment::from(note.note.commitment()))
}

fn size(st: &StateTransition) -> usize {
st.serialize_to_bytes().expect("serialize").len()
}

/// The serialized size of each kind of shielded spend with `actions` spent notes (one action
/// per note), keyed by kind.
fn spend_sizes(actions: usize) -> Vec<(&'static str, usize)> {
let pv = PlatformVersion::latest();
let (fvk, ask) = keys();
let addr = test_orchard_address();
let (transfer, _) = build_shielded_transfer_transition(
notes(actions),
&addr,
1_000,
&addr,
&fvk,
&ask,
anchor(),
&TestProver,
[0u8; 36],
pv,
)
.expect("transfer");
let (unshield, _) = build_unshield_transition(
notes(actions),
PlatformAddress::P2pkh([1u8; 20]),
1_000,
&addr,
&fvk,
&ask,
anchor(),
&TestProver,
[0u8; 36],
pv,
)
.expect("unshield");
let (withdrawal, _) = build_shielded_withdrawal_transition(
notes(actions),
1_000_000,
CoreScript::new_p2pkh([1u8; 20]),
1,
Pooling::Never,
&addr,
&fvk,
&ask,
anchor(),
&TestProver,
[0u8; 36],
pv,
)
.expect("withdrawal");
let (top_up, _) = build_identity_top_up_from_shielded_pool_transition(
notes(actions),
Identifier::new([3u8; 32]),
1_000,
&addr,
&fvk,
&ask,
anchor(),
&TestProver,
[0u8; 36],
pv,
)
.expect("top up");
vec![
("transfer", size(&transfer)),
("unshield", size(&unshield)),
("withdrawal", size(&withdrawal)),
("identity top up", size(&top_up)),
]
}

/// The helper's action count fits `max_state_transition_size` in real serializations of every
/// shielded spend kind, and one action more does not fit any of them.
#[test]
fn should_bound_the_actions_of_every_spend_kind_by_the_transition_size_limit() {
let pv = PlatformVersion::latest();
let max_size = pv.system_limits.max_state_transition_size as usize;
let bound = usize::from(max_shielded_actions_per_transition(pv));

for (kind, bytes) in spend_sizes(bound) {
assert!(
bytes <= max_size,
"{kind}: {bound} actions serialize to {bytes} B, over the {max_size} B limit"
);
}
for (kind, bytes) in spend_sizes(bound + 1) {
assert!(
bytes > max_size,
"{kind}: {} actions serialize to {bytes} B, which still fits the {max_size} B limit",
bound + 1
);
}
}
3 changes: 3 additions & 0 deletions packages/rs-dpp/src/shielded/builder/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -521,6 +521,9 @@ pub(crate) mod test_helpers {
}
}

#[cfg(test)]
mod max_actions_tests;

#[cfg(test)]
mod mod_tests {
use super::test_helpers::{test_orchard_address, test_spendable_note, TestProver};
Expand Down
Loading
Loading