diff --git a/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/services/IdentityRegistrationController.kt b/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/services/IdentityRegistrationController.kt index d5c38601053..184bc463eae 100644 --- a/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/services/IdentityRegistrationController.kt +++ b/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/services/IdentityRegistrationController.kt @@ -65,10 +65,10 @@ class IdentityRegistrationController( data class Failed(val message: String) : Phase /** - * Broadcast-succeeded-but-confirmation-failed terminal state - * (shielded only). The identity at [identityId] MAY already be live; - * the slot must stay held so a re-submission can't burn funds against - * the registered-key-hash check. + * Unconfirmed terminal state (shielded only): the transition may have + * reached a node and its result is not proved. The identity at + * [identityId] MAY already be live; the slot must stay held so a + * re-submission can't burn funds against the registered-key-hash check. */ data class Unconfirmed(val identityId: ByteArray, val message: String) : Phase { override fun equals(other: Any?): Boolean = @@ -90,12 +90,13 @@ class IdentityRegistrationController( /** * Which stage a shielded [Phase.Failed] failed at, so the progress - * screen can attribute the red marker. Only [BroadcastRejected] is - * attributable with confidence; every other failure leaves this null and - * the progress screen falls back to its elapsed-time heuristic. + * screen can attribute the red marker. Only [BroadcastNotSent] (the + * transition was refused before anything was sent) is attributable with + * confidence; every other failure leaves this null and the progress + * screen falls back to its elapsed-time heuristic. * ← Swift `FailureStage`. */ - enum class FailureStage { BroadcastRejected } + enum class FailureStage { BroadcastNotSent } private val _phase = MutableStateFlow(Phase.Idle) val phase: StateFlow = _phase.asStateFlow() @@ -136,7 +137,7 @@ class IdentityRegistrationController( fun submit( body: suspend () -> ByteArray, isUnconfirmed: (Throwable) -> ByteArray? = { null }, - isBroadcastRejected: (Throwable) -> Boolean = { false }, + isBroadcastNotSent: (Throwable) -> Boolean = { false }, ) { when (_phase.value) { is Phase.Idle, is Phase.PreparingKeys, is Phase.Failed -> Unit @@ -157,7 +158,7 @@ class IdentityRegistrationController( terminalAt = now() _phase.value = Phase.Unconfirmed(unconfirmedId, e.message ?: "Confirmation pending") } else { - _failureStage.value = if (isBroadcastRejected(e)) FailureStage.BroadcastRejected else null + _failureStage.value = if (isBroadcastNotSent(e)) FailureStage.BroadcastNotSent else null terminalAt = now() _phase.value = Phase.Failed(e.message ?: "Registration failed") } diff --git a/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/services/RegistrationCoordinator.kt b/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/services/RegistrationCoordinator.kt index 553f3b0967a..69c590ef517 100644 --- a/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/services/RegistrationCoordinator.kt +++ b/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/services/RegistrationCoordinator.kt @@ -73,7 +73,7 @@ class RegistrationCoordinator( fundingKind: IdentityRegistrationController.FundingKind = IdentityRegistrationController.FundingKind.AssetLock, body: suspend () -> ByteArray, isUnconfirmed: (Throwable) -> ByteArray? = { null }, - isBroadcastRejected: (Throwable) -> Boolean = { false }, + isBroadcastNotSent: (Throwable) -> Boolean = { false }, ): IdentityRegistrationController { val key = SlotKey(walletId.toHex(), identityIndex) val existing = _controllers.value[key] @@ -89,7 +89,7 @@ class RegistrationCoordinator( -> { // Legitimate restart: a fresh idle controller, or a retry after failure. existing.enterPreparingKeys() - existing.submit(body, isUnconfirmed, isBroadcastRejected) + existing.submit(body, isUnconfirmed, isBroadcastNotSent) scheduleRetentionSweep(key, existing) return existing } @@ -98,7 +98,7 @@ class RegistrationCoordinator( val controller = IdentityRegistrationController(walletId, identityIndex, fundingKind, scope, now) _controllers.update { it + (key to controller) } controller.enterPreparingKeys() - controller.submit(body, isUnconfirmed, isBroadcastRejected) + controller.submit(body, isUnconfirmed, isBroadcastNotSent) scheduleRetentionSweep(key, controller) return controller } diff --git a/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/wallet/SendTransactionScreen.kt b/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/wallet/SendTransactionScreen.kt index 5656d273640..783128fef29 100644 --- a/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/wallet/SendTransactionScreen.kt +++ b/packages/kotlin-sdk/KotlinExampleApp/app/src/main/java/org/dashfoundation/example/ui/wallet/SendTransactionScreen.kt @@ -730,10 +730,11 @@ fun SendTransactionScreen( } } } catch (e: DashSdkError.PlatformWallet.ShieldedSpendUnconfirmed) { - // Broadcast accepted but its execution result couldn't - // be confirmed — the spend may already be on chain and - // the notes stay reserved Rust-side, so this must NOT - // read as a retryable failure (← SendViewModel.swift:790). + // It may have reached a node and its result is not + // proved (a node's refusal or verdict included), so it + // may already be on chain and a retry signs a second + // transition: this must NOT read as a retryable + // failure (← SendViewModel.swift:790). successMessage = "Transaction may have gone through — waiting for " + "the next shielded sync to confirm. Do not retry." } catch (t: Throwable) { diff --git a/packages/kotlin-sdk/KotlinExampleApp/app/src/test/java/org/dashfoundation/example/services/RegistrationCoordinatorTest.kt b/packages/kotlin-sdk/KotlinExampleApp/app/src/test/java/org/dashfoundation/example/services/RegistrationCoordinatorTest.kt index ccb9e56868f..d4d86bacbfd 100644 --- a/packages/kotlin-sdk/KotlinExampleApp/app/src/test/java/org/dashfoundation/example/services/RegistrationCoordinatorTest.kt +++ b/packages/kotlin-sdk/KotlinExampleApp/app/src/test/java/org/dashfoundation/example/services/RegistrationCoordinatorTest.kt @@ -110,7 +110,7 @@ class RegistrationCoordinatorTest { } @Test - fun `broadcast-rejected classifier sets failure stage`() = runTest { + fun `broadcast-not-sent classifier sets failure stage`() = runTest { val coordinator = coordinator() val gate = CompletableDeferred() @@ -119,14 +119,14 @@ class RegistrationCoordinatorTest { identityIndex = 0, fundingKind = IdentityRegistrationController.FundingKind.ShieldedPool, body = { gate.await() }, - isBroadcastRejected = { true }, + isBroadcastNotSent = { true }, ) - gate.completeExceptionally(RuntimeException("broadcast rejected")) + gate.completeExceptionally(RuntimeException("nothing was sent")) advanceUntilIdle() assertTrue(controller.phase.value is Phase.Failed) assertEquals( - IdentityRegistrationController.FailureStage.BroadcastRejected, + IdentityRegistrationController.FailureStage.BroadcastNotSent, controller.failureStage.value, ) } diff --git a/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt b/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt index 608af6563b3..81b2ea92985 100644 --- a/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt +++ b/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt @@ -274,31 +274,32 @@ sealed class DashSdkError( /** * `ErrorShieldedSpendUnconfirmed` (native code 18). A shielded spend - * (transfer / unshield / withdraw / shield) was broadcast and - * accepted, but its execution result couldn't be confirmed — it may - * already be on chain. Rust intentionally KEEPS the spent notes' - * reservations, so the caller must NOT retry (a retry would rebuild - * the bundle against other notes and could double-spend); the next - * shielded sync reconciles the outcome. The Android analog of + * (transfer / unshield / withdraw / shield from Platform addresses) + * may have reached a node and its result is not proved (a failed + * result wait, a node's refusal or a consensus verdict, stale address + * nonce included), so it may already be on chain. Do NOT retry: a + * retry signs a second transition. Spends keep their notes reserved + * for the wallet to resolve; a shield stays pending until the + * shielded scan observes its note. The Android analog of * Swift's `PlatformWalletError.shieldedSpendUnconfirmed`, which the * iOS send flow surfaces as a non-retryable "may have gone through" * outcome rather than an error. */ class ShieldedSpendUnconfirmed(message: String, cause: Throwable? = null) : PlatformWallet( - "$message (do NOT retry: the spend may already be on chain; " + - "the wallet keeps the spent notes reserved until the next " + - "shielded sync reconciles the outcome)", + "$message (do NOT retry: it may already be on chain or may " + + "still execute, and a retry signs a second transition)", cause, ) /** * `ErrorMasternodeWithdrawalUnconfirmed` (native code 42). A - * masternode (evonode) identity credit withdrawal was broadcast and - * accepted, but its execution result couldn't be confirmed — it may - * already have executed, and the identity nonce was consumed for it, - * so a blind retry could submit a SECOND withdrawal. Do NOT retry; - * re-read the identity's claimable balance and reconcile first. The + * masternode (evonode) identity credit withdrawal may have reached a + * node and its remaining balance is not proved (a failed result wait, + * a node's refusal or a consensus verdict included). It may have + * executed; a retry signs a second withdrawal with the next identity + * nonce. Do NOT retry; re-read the claimable balance first. Only a + * failure before anything was sent keeps an ordinary code. The * Android analog of Swift's * `PlatformWalletError.masternodeWithdrawalUnconfirmed`. */ @@ -311,10 +312,10 @@ sealed class DashSdkError( /** * `ErrorShieldedBroadcastFailed` (native code 16). A DEFINITIVE - * non-execution outcome — relay/CheckTx rejected the transaction - * before it entered the chain, and any note reservations were - * released. Safe to retry (the opposite of the ambiguous - * [ShieldedSpendUnconfirmed]). + * non-execution outcome: the transition never left the wallet + * (refused before anything was sent), so it can never execute, and + * any note reservations were released. Safe to retry (the opposite + * of the ambiguous [ShieldedSpendUnconfirmed]). */ class ShieldedBroadcastFailed(message: String, cause: Throwable? = null) : PlatformWallet(message, cause) { diff --git a/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/PlatformWalletManager.kt b/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/PlatformWalletManager.kt index 5f074a73d5b..325504110da 100644 --- a/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/PlatformWalletManager.kt +++ b/packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/PlatformWalletManager.kt @@ -2010,10 +2010,11 @@ class PlatformWalletManager( // (cached by [bindShielded]), so no signer or resolver handle crosses // JNI — matching the Swift counterparts, which take no signer either. // Each blocks for the ~30s Halo 2 proof on Dispatchers.IO. On the - // AMBIGUOUS outcome (broadcast accepted, execution unconfirmed) they - // throw [org.dashfoundation.dashsdk.errors.DashSdkError.PlatformWallet.ShieldedSpendUnconfirmed] - // — the caller must NOT retry (the spent notes stay reserved Rust-side; - // the next shielded sync reconciles the outcome). + // AMBIGUOUS outcome (the spend may have reached a node and its result is + // not proved, a node's refusal or verdict included) they + // throw [org.dashfoundation.dashsdk.errors.DashSdkError.PlatformWallet.ShieldedSpendUnconfirmed]: + // the caller must NOT retry (the spent notes stay reserved Rust-side + // until a later shielded sync resolves them). /** * Shielded → shielded transfer (Type 16) — port of Swift's diff --git a/packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt b/packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt index b75887fe615..ff568acb553 100644 --- a/packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt +++ b/packages/kotlin-sdk/sdk/src/test/kotlin/org/dashfoundation/dashsdk/errors/DashSdkErrorTest.kt @@ -146,7 +146,7 @@ class DashSdkErrorTest { DashSdkError.fromNative(DashSDKException(offset + 18, "ambiguous spend")) assertTrue(spendUnconfirmed is DashSdkError.PlatformWallet.ShieldedSpendUnconfirmed) assertFalse( - "ShieldedSpendUnconfirmed must NOT be retryable (notes stay reserved)", + "ShieldedSpendUnconfirmed must NOT be retryable (a retry signs a second transition)", spendUnconfirmed.isRetryable, ) // The message must warn against retrying, like the broadcast sibling. diff --git a/packages/rs-platform-wallet-ffi/ERROR_CODE_REGISTRY.md b/packages/rs-platform-wallet-ffi/ERROR_CODE_REGISTRY.md index 390e568cecd..864882deb95 100644 --- a/packages/rs-platform-wallet-ffi/ERROR_CODE_REGISTRY.md +++ b/packages/rs-platform-wallet-ffi/ERROR_CODE_REGISTRY.md @@ -87,12 +87,12 @@ These are shipped ABI. Do not renumber. | 13 | `ErrorArithmeticOverflow` | Produced in-tree by `shielded_send.rs` (the shielded-send amount/fee overflow guard). Its rustdoc was corrected by #4360 (`e0b8baa850`), which documents the `PlatformWalletError::InputSumOverflow` mapping — the stale no-producer comment this row used to track is gone | | 14 | `ErrorNoSelectableInputs` | | | 15 | `ErrorWalletAlreadyExists` | | -| 16 | `ErrorShieldedBroadcastFailed` | | +| 16 | `ErrorShieldedBroadcastFailed` | Only a transition refused before anything was sent (no address to send it to, or the SDK's own refusal), its notes released. For a shielded spend that consumes notes, since #5810: an endpoint's verdict (CheckTx or execution, which no proof backs) and every transport failure after a dispatch, which note spends reported here before, now report 18, or 17 for an identity created from the pool. A shield from Platform addresses no longer reports an endpoint's refusal or verdict here either: that is 18 | | 17 | `ErrorShieldedBroadcastUnconfirmed` | | -| 18 | `ErrorShieldedSpendUnconfirmed` | | +| 18 | `ErrorShieldedSpendUnconfirmed` | Also, since #5810, what note spends (shielded transfers, unshields, withdrawals, identity top-ups and private document creations from the pool) reported as 16 before: an endpoint's verdict and any transport failure after a dispatch, as the transition may have been delivered. Also `ShieldedBroadcastMaybeDelivered`. The notes and the redrive record are kept, the record saved before the broadcast and the reservation restored from it after a restart; a host must not pay again with other notes. Also what a shield from Platform addresses returns once a dispatch may have reached a node and its result is not proved, an endpoint's refusal or consensus verdict included | | 19 | `ErrorShieldedNoRecordedAnchor` | | -| 20 | `ErrorTransactionBroadcastUnconfirmed` | | -| 21 | `ErrorAddressNonceMismatch` | | +| 20 | `ErrorTransactionBroadcastUnconfirmed` | Since #5556 also a Platform state transition the SDK reports unconfirmed after a possible acceptance (`dash_sdk::Error::StateTransitionResultUnconfirmed`), through the blanket conversion and the shielded spend contract (`map_spend_result`) alike: the host reconciles the original operation and does not retry | +| 21 | `ErrorAddressNonceMismatch` | No longer returned by a shield from Platform addresses: an endpoint's nonce verdict on a dispatched shield is 18. Transfers and withdrawals from Platform addresses, and identity registrations and top-ups from them, still return it | | 22 | `ErrorCoreInsufficientFunds` | | | 23 | `ErrorAssetLockNotTracked` | | | 24 | `ErrorAssetLockAlreadyConsumed` | | @@ -109,12 +109,12 @@ These are shipped ABI. Do not renumber. | 39 | `ErrorInsufficientIdentityCredits` | Merged 2026-08-09 by **#4348** (`6373e00f0c`) | | 40 | `ErrorContestedNameNotTradable` | Merged 2026-08-09 by **#4348** (`6373e00f0c`) | | 41 | `ErrorShieldedInsufficientBalance` | Merged 2026-08-11 by **#4360** (`e0b8baa850`) | -| 42 | `ErrorMasternodeWithdrawalUnconfirmed` | Merged 2026-08-22 by **#4451** (masternode-credit claiming). **Took the number active #4356 had claimed** for `ErrorAssetLockInputConflict` — see the proposed table's 42 note; #4356 renumbers via the frontier | +| 42 | `ErrorMasternodeWithdrawalUnconfirmed` | Merged 2026-08-22 by **#4451** (masternode-credit claiming). **Took the number active #4356 had claimed** for `ErrorAssetLockInputConflict`; see the proposed table's 42 note. #4356 renumbers via the frontier. Returned once a dispatch may have reached a node and the result is not proved, an endpoint's refusal or consensus verdict included; only a withdrawal that never left the wallet keeps an ordinary, retryable code | | 46 | `ErrorMasternodeListUnavailable` | Merged 2026-08-24 by **#4465** (`8dd964277`). Initially minted as 43 (already held by active #4313's `ErrorShieldedInviteAlreadyClaimed` across all three layers) — collision flagged in review and renumbered to the then-frontier same day, Rust and Swift together | | 98 | `NotFound` | Sentinel — `Option` returned as an error | | 99 | `ErrorUnknown` | Sentinel — unmapped/flattened errors | -**Next allocatable integer: 62** — 27–61 are all claimed (27, 29, 31, 34–42 +**Next allocatable integer: 76**: 27–75 are all claimed (27, 29, 31, 34–42 and 46 merged; 43–45 proposed by active #4313 at head `0302b188ab`; 47 and 48 proposed by active #4356 (47 renumbered from 42, 48 from 43 — see their rows below); 49–54 proposed by active #4586 (the persister @@ -124,7 +124,11 @@ identity balance response; 59 proposed by #5322 for an SPV teardown that needs a process restart; 60 proposed by the pooled Core-to-shielded wallet drain for `ErrorAssetLockTooManyInputs` (Rust, Swift and Kotlin mirrors — renumbered from 59 when #5322 took that number on `v5.1-dev`); 61 proposed by -#5603 for `ErrorAssetLockRecipientMismatch`; 28, 30, +#5603 for `ErrorAssetLockRecipientMismatch`; 62–67 held +by open branches with no row here yet +(62 both `ErrorShieldedClaimBindingMismatch` and `ErrorIdentityRevisionMismatch`, +63–66 the invitation-claim preflight, 67 `ErrorShieldedTreeInconsistent`); 68 +to 75 proposed for DashPay private contact requests; 28, 30, 32 and 33 reserved). **28, 30, 32 and 33 are RESERVED, not free**: 28 and 30 were vacated when the reservation trio moved to 34–36; 32 and 33 lapsed when their in-repo owners @@ -179,6 +183,15 @@ Fork-era numbers remain in the collision history, which is immutable record. | 59 | `ErrorSpvProcessRestartRequired` | #5322 | Proposed — SPV startup or teardown panicked; restart the host process. Not retryable, unlike 27, which SPV start, stop and storage clear now return while an SPV teardown is still running. Typed in Rust, Swift and Kotlin (the PR also types 27 on Kotlin) | | 60 | `ErrorAssetLockTooManyInputs` | Core-to-shielded pooled Max | Proposed — an asset lock needs more inputs than one may carry (100 on Dash Core relay policy, and in Platform consensus for an instant proof): the full drain, or since #5712 a fixed amount held only in many small coins (identity registration, top-up, invitation, platform-address funding). Two meanings. On a build: nothing was broadcast, the reservation is released, no partial drain, and a rebuild after consolidating is safe. On the resume of a tracked `Built` / `Broadcast` lock over the cap (since #5714): it is not re-sent, but an earlier attempt may have reached peers; the row stays tracked and nothing is released. Rust, Swift and Kotlin retain the typed refusal. Renumbered from 59 after #5322 claimed it | | 61 | `ErrorAssetLockRecipientMismatch` | dashpay/platform#5603 (tracked-lock shielded recipient) | Proposed — a shielded fund-from-asset-lock resume (the generic outpoint resume or a repeated-UUID wallet drain) names a different Orchard recipient than the one the tracked lock recorded when it was built. Nothing was submitted or paid; resume with the recorded recipient, which the row and `TrackedAssetLockFFI` expose. Rows tracked before recipients were recorded carry none and accept the caller's. Typed in Rust, Swift and Kotlin | +| 68 | `ErrorPrivateContactRequestNeedsPrivateReply` | DashPay private contact requests | Proposed. The contact requests with that identity came or went privately (protocol version 15), so a `contactRequest` document to it, in reply or as a rotation, would publish the relationship: the public accept refuses a reply, and the public send refuses a request or a rotation. Nothing was sent; the request goes privately instead, and the in-kind accept picks the private reply itself. The shielded spend contract (`map_spend_result`) keeps the code, as the in-kind accept can raise it. Taken above 61–67, which open branches already hold. The exports that send and accept contact requests, and the Swift and Kotlin typing, are added by the FFI PR (#5812) and the Kotlin PR (#5813); in this tree it reaches a host through the blanket conversion | +| 69 | `ErrorShieldedBuildRequired` | DashPay private contact requests | Proposed. The operation needs the shielded pool and the library was built without the `shielded` feature: accepting in kind a request that came privately, whose private reply is paid from the pool. Nothing was sent; a public or adopted reply works on such a build. Not retryable on the same build. No existing code meant "shielded unsupported" (`ErrorWalletOperation` with a not-configured message is a runtime state of a shielded build), so it takes the next free number. No export in this tree returns it yet: the in-kind accept export, and the Swift and Kotlin typing, are added by the FFI PR (#5812) and the Kotlin PR (#5813) | +| 70 | `ErrorProtocolVersionNotActive` | DashPay private contact requests | Proposed. The SDK refused a request without sending it (`dash_sdk::Error::ProtocolVersionNotActive`, not pinned) because the network is proven at a protocol version below the one that serves it: for example the private contact request sync on a network before protocol version 15. Expected on such a network, so a host may stay quiet about it; it lifts when the network upgrades. An SDK pinned below the required version has its own code, 75. Mapped by the blanket conversion for every operation that propagates the SDK error. A refusal that may lift sooner (`is_transient_protocol_version_refusal`: the network's version could not be confirmed) keeps the catch-all `ErrorUnknown`, as before. Previously both fell to `ErrorUnknown`. Swift and Kotlin typing is added by the FFI PR (#5812) and the Kotlin PR (#5813) | +| 71 | `ErrorPrivateContactRequestPending` | DashPay private contact requests | Proposed. Maps `PlatformWalletError::PrivateContactRequestPending`: a private contact request to that identity is in flight (another private send or reply reserved it before sealing), or was paid for and a short read-back sync did not find the entry in the store yet, or a private payment the shielded store's journal keeps unresolved holds the pair. Nothing new was paid; a later private contact request sync settles it once the entry is read back, and the shielded sync once the payment provably never executes. Pending, not failed: the host must not submit it again. A private store read that did not finish before the request was decided is 74, not 71. The shielded spend contract (`map_spend_result`) keeps the code rather than flattening it to `ErrorWalletOperation`. Swift and Kotlin typing is added by the FFI PR (#5812) and the Kotlin PR (#5813) | +| 72 | `ErrorPrivateContactPaymentsNotRestored` | DashPay private contact requests | Proposed. Maps `PlatformWalletError::PrivateContactPaymentsNotRestored`: wallet readiness, not one contact's pending request (71). The wallet's unconfirmed private payments may hold pairs no reservation shows yet, which only a restoration from the shielded store's journal shows. In a build with the `shielded` feature: the wallet was published (created or loaded) while no shielded store was configured, its persister declaring the private scan state (bit 15), which holds a wallet removed and registered again from the same seed, in this process or a new one; it was loaded after binding a shielded account in an earlier process; or its last restoration failed, or waits for a busy store. In every build: the identity was loaded with its private scan state marking a private payment that may be unresolved, or was added to a wallet whose backend kept its record marked after an earlier wallet under the id was removed (`ClientStartState::retained_private_contact_scan_states`). Contact requests and acceptances, public and private, are refused with nothing read, signed or broadcast until they are restored: configuring the shielded store restores them with no keys, as binding the wallet's shielded account does, and a contact request first retries a restoration once without waiting on the store; a private sync does not, and a build without the `shielded` feature never does. A host whose persister declares the private scan state configures the shielded store when it activates the manager, before loading or creating wallets: until it does, and while a failed configure is not retried, 72 holds. `platform_wallet_get_private_contact_readiness` reads whether the payments are restored and whether the last restoration failed (`private_payments_restore_failed`; the wallet's `PrivateContactReadiness::private_payments_restore_failure` holds the reason). Swift and Kotlin typing is added by the FFI PR (#5812) and the Kotlin PR (#5813); hosts treat it as held until the readiness reads restored | +| 73 | `ErrorPrivateContactRecoveryUnsupported` | DashPay private contact requests | Proposed. Maps `PlatformWalletError::PrivateContactRecoveryUnsupported`: the persister does not declare `PRIVATE_CONTACT_REQUEST_SCAN_STATE` (bit 15) together with `ATOMIC_CHANGESETS` (bit 0, with the changeset begin and end callbacks wired), so the private send, the private accept and the in-kind accept's private reply are refused before anything is sealed or paid. The payment's recovery marker could not survive a restart, and a process reopening the wallet without the `shielded` feature, or before the shielded store is configured, could publish the pair while the payment may still execute. Not retryable as it is: a host that persists the private contact request scan state in changesets it commits whole declares both. The FFI constant for bit 15 and the Swift and Kotlin typing are added by the FFI PR (#5812) and the Kotlin PR (#5813) | +| 74 | `ErrorPrivateContactStoreNotRead` | DashPay private contact requests | Proposed. Maps `PlatformWalletError::PrivateContactStoreNotRead`: DashPay's private contact request store was not read to its end for the identity, with the keys Platform proves it holds, before a contact request or acceptance, public or private, was decided (every one reads it from the identity's cursor first). Nothing was reserved, sealed, paid or broadcast; calling again continues the read from where it stopped. A node behind the store already seen, or keys that kept changing, stop it. It was reported as 71 before, which says not to submit again. Mapped by the blanket conversion and kept by the shielded spend contract (`map_spend_result`). Swift and Kotlin typing is added by the FFI PR (#5812) and the Kotlin PR (#5813) | +| 75 | `ErrorSdkPinnedBelowProtocolVersion` | DashPay private contact requests | Proposed. The SDK refused a request without sending it because the SDK itself is pinned below the protocol version the request needs (`dash_sdk::Error::ProtocolVersionNotActive` with `pinned`), whatever the network runs: for example every contact request's private store read with the SDK pinned below protocol version 15 on a network at 15. A network upgrade does not lift it; only raising or removing the pin does. Before, it shared 70 with a network proven below the version, which lifts by itself. Mapped by the blanket conversion. Swift and Kotlin typing is added by the FFI PR (#5812) and the Kotlin PR (#5813) | +| 76 | `ErrorPublicContactRequestUnconfirmed` | DashPay private contact requests | Proposed. Maps `PlatformWalletError::PublicContactRequestUnconfirmed`: a public contact request to that identity was broadcast and may have been delivered, and no proof settled its outcome yet, so the wallet holds the pair and signs nothing new to it, public or private. The send or accept that broadcast it reported 20; every later one is refused with 76 until a public contact request sync settles it (its document proved on Platform: recorded as sent; its transition proved unable to write it: the pair freed), broadcasting the same signed bytes again meanwhile. Not a private request pending (71). Mapped by the blanket conversion and by `map_spend_result`. Swift and Kotlin typing is added by the FFI PR (#5812) and the Kotlin PR (#5813) | **Code 31 left this table on 2026-08-04.** `ErrorSigningKeyUnavailable` sat here as #4183's proposal until #4183 merged (`189a3abb1c`); it is now in the merged diff --git a/packages/rs-platform-wallet-ffi/src/contact_request.rs b/packages/rs-platform-wallet-ffi/src/contact_request.rs index 433adc5d014..c61c43577ee 100644 --- a/packages/rs-platform-wallet-ffi/src/contact_request.rs +++ b/packages/rs-platform-wallet-ffi/src/contact_request.rs @@ -4,9 +4,10 @@ use crate::error::*; use crate::handle::*; +use crate::runtime::block_on_worker; use crate::types::*; use crate::{check_ptr, unwrap_option_or_return, unwrap_result_or_return}; -use platform_wallet::ContactRequest; +use platform_wallet::{ContactRequest, PrivateContactReadiness}; // Storage for contact requests lazy_static::lazy_static! { @@ -226,11 +227,340 @@ pub extern "C" fn contact_request_destroy(request_handle: Handle) -> PlatformWal } } +/// What a contact request from one of a wallet's identities waits for, as the +/// wallet decides it (`platform_wallet::PrivateContactReadiness`), for a host +/// to show rather than infer from the refusals it got. +#[repr(C)] +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct PrivateContactReadinessFFI { + /// Whether the wallet's private payments are restored for the identity. + /// While false, its contact requests and acceptances, public or private, + /// are refused with `ErrorPrivateContactPaymentsNotRestored` (72) until + /// the shielded store is configured or the wallet's shielded account + /// bound, or a contact request's own retry of a failed restoration + /// succeeds; no private sync lifts it. A build without the `shielded` + /// feature never does. + pub private_payments_restored: bool, + /// Whether a private sync read DashPay's private contact request store to + /// its end for the identity with its current keys. Every contact request + /// and acceptance reads it again from the cursor before it is decided, and + /// is refused with `ErrorPrivateContactStoreNotRead` (74) while that read + /// cannot finish. + pub private_store_read: bool, + /// Whether a private contact request the identity paid for may still be + /// unresolved: the marker its private scan state stores, or a payment the + /// shielded store's journal keeps unresolved. A journal record discharged + /// since is applied before the read. + pub unresolved_private_payment: bool, + /// Whether the last restoration of the wallet's private payments failed, + /// while `private_payments_restored` is false for it: then 72 holds until + /// a restoration succeeds, not only until one runs. The reason is in the + /// wallet's log; an export for it is left to the FFI PR. + pub private_payments_restore_failed: bool, +} + +impl From for PrivateContactReadinessFFI { + fn from(readiness: PrivateContactReadiness) -> Self { + Self { + private_payments_restored: readiness.private_payments_restored, + private_store_read: readiness.private_store_read, + unresolved_private_payment: readiness.unresolved_private_payment, + private_payments_restore_failed: readiness.private_payments_restore_failure.is_some(), + } + } +} + +/// What a contact request from `identity_id`, one of the wallet's identities, +/// waits for, as the wallet decides it, into `out_readiness` +/// ([`PrivateContactReadinessFFI`]): so a host tells "restoring private +/// payments" from "reading the private store" and from a contact's pending +/// request by the wallet's own state. Not a pure read: a journal record +/// discharged since (a payment proven never to execute) is applied first, +/// briefly taking the wallet's write lock, as a send would see it; then it +/// reads live wallet state. Why a failed restoration failed is +/// `platform_wallet_get_private_payments_restore_failure`; one pair's hold is +/// `platform_wallet_get_private_pair_held`. +/// +/// `out_readiness` is reset to all false first. An unknown `wallet_handle` is +/// `NotFound`; an identity the wallet does not hold is refused as its lookup +/// is. +/// +/// # Safety +/// - `identity_id` must point to 32 readable bytes. +/// - `out_readiness` must be a valid, writable pointer. +#[no_mangle] +pub unsafe extern "C" fn platform_wallet_get_private_contact_readiness( + wallet_handle: Handle, + identity_id: *const u8, + out_readiness: *mut PrivateContactReadinessFFI, +) -> PlatformWalletFFIResult { + check_ptr!(out_readiness); + unsafe { *out_readiness = PrivateContactReadinessFFI::default() }; + let identity_id = unwrap_result_or_return!(unsafe { read_identifier(identity_id) }); + // Look the identity up under the registry guard, but wait outside it: the + // read can wait on the wallet's write lock, and a registry read guard held + // across that wait would stall `platform_wallet_destroy` (a registry + // write) and every registry reader queued behind it. + let option = + PLATFORM_WALLET_STORAGE.with_item(wallet_handle, |wallet| wallet.identity().clone()); + let identity = unwrap_option_or_return!(option); + let readiness = unwrap_result_or_return!(block_on_worker(async move { + identity + .dashpay() + .private_contact_readiness(&identity_id) + .await + })); + unsafe { *out_readiness = readiness.into() }; + PlatformWalletFFIResult::ok() +} + #[cfg(test)] mod tests { use super::*; + + /// Each readiness flag reaches its own FFI field, alone: a conversion + /// that swapped or cleared one would show here. + #[test] + fn should_convert_each_readiness_flag_to_its_own_field() { + let restored = PrivateContactReadinessFFI::from(PrivateContactReadiness { + private_payments_restored: true, + private_store_read: false, + unresolved_private_payment: false, + private_payments_restore_failure: None, + }); + assert_eq!( + restored, + PrivateContactReadinessFFI { + private_payments_restored: true, + private_store_read: false, + unresolved_private_payment: false, + private_payments_restore_failed: false, + } + ); + let read = PrivateContactReadinessFFI::from(PrivateContactReadiness { + private_payments_restored: false, + private_store_read: true, + unresolved_private_payment: false, + private_payments_restore_failure: None, + }); + assert_eq!( + read, + PrivateContactReadinessFFI { + private_payments_restored: false, + private_store_read: true, + unresolved_private_payment: false, + private_payments_restore_failed: false, + } + ); + let unresolved = PrivateContactReadinessFFI::from(PrivateContactReadiness { + private_payments_restored: false, + private_store_read: false, + unresolved_private_payment: true, + private_payments_restore_failure: None, + }); + assert_eq!( + unresolved, + PrivateContactReadinessFFI { + private_payments_restored: false, + private_store_read: false, + unresolved_private_payment: true, + private_payments_restore_failed: false, + } + ); + let failed = PrivateContactReadinessFFI::from(PrivateContactReadiness { + private_payments_restored: false, + private_store_read: false, + unresolved_private_payment: false, + private_payments_restore_failure: Some("the journal does not read".to_string()), + }); + assert_eq!( + failed, + PrivateContactReadinessFFI { + private_payments_restored: false, + private_store_read: false, + unresolved_private_payment: false, + private_payments_restore_failed: true, + } + ); + } use dpp::prelude::Identifier; + /// The readiness of a fresh wallet's identity: nothing held, the store not + /// read yet, no private payment; then the identity's own state, once a + /// private sync read the store and once it was loaded with a private + /// payment that may be unresolved. A null out pointer, an unknown wallet + /// and an identity the wallet does not hold are refused, with the out + /// value reset. + #[test] + fn should_read_a_wallet_identity_s_private_contact_readiness() { + use dpp::identity::identity_public_key::v0::IdentityPublicKeyV0; + use dpp::identity::v0::IdentityV0; + use dpp::identity::{Identity, IdentityPublicKey, KeyType, Purpose, SecurityLevel}; + use dpp::platform_value::BinaryData; + use key_wallet::wallet::initialization::WalletAccountCreationOptions; + + assert_eq!( + unsafe { + platform_wallet_get_private_contact_readiness( + 1, + [0u8; 32].as_ptr(), + std::ptr::null_mut(), + ) + } + .code, + PlatformWalletFFIResultCode::ErrorNullPointer + ); + let mut readiness = PrivateContactReadinessFFI { + private_payments_restored: true, + private_store_read: true, + unresolved_private_payment: true, + private_payments_restore_failed: false, + }; + let unknown = unsafe { + platform_wallet_get_private_contact_readiness( + Handle::MAX, + [0u8; 32].as_ptr(), + &mut readiness, + ) + }; + assert_eq!(unknown.code, PlatformWalletFFIResultCode::NotFound); + assert_eq!(readiness, PrivateContactReadinessFFI::default(), "reset"); + + let manager = crate::test_fixtures::mock_manager(); + let wallet = crate::runtime::runtime() + .block_on(manager.create_wallet_from_seed_bytes( + key_wallet::Network::Testnet, + &[9; 64], + WalletAccountCreationOptions::Default, + Some(0), + )) + .expect("a wallet"); + let identity_id = Identifier::from([0xB2; 32]); + let key = dpp::secp256k1::PublicKey::from_secret_key( + &dpp::secp256k1::SecretKey::from_secret_bytes([4; 32]).expect("a secret key"), + ); + let identity = Identity::V0(IdentityV0 { + id: identity_id, + public_keys: [( + 1, + IdentityPublicKey::V0(IdentityPublicKeyV0 { + id: 1, + purpose: Purpose::ENCRYPTION, + security_level: SecurityLevel::MEDIUM, + contract_bounds: None, + key_type: KeyType::ECDSA_SECP256K1, + read_only: false, + data: BinaryData::new(key.serialize().to_vec()), + disabled_at: None, + }), + )] + .into_iter() + .collect(), + balance: 0, + revision: 0, + }); + crate::runtime::runtime().block_on(async { + let mut wm = wallet.wallet_manager().write().await; + wm.get_wallet_info_mut(&wallet.wallet_id()) + .expect("the wallet's info") + .identity_manager + .add_identity(identity, 0, wallet.wallet_id(), wallet.persister()) + .expect("the identity"); + }); + let handle = PLATFORM_WALLET_STORAGE.insert(wallet); + + let read = unsafe { + platform_wallet_get_private_contact_readiness( + handle, + identity_id.to_buffer().as_ptr(), + &mut readiness, + ) + }; + assert_eq!(read.code, PlatformWalletFFIResultCode::Success); + assert_eq!( + readiness, + PrivateContactReadinessFFI { + private_payments_restored: true, + private_store_read: false, + unresolved_private_payment: false, + private_payments_restore_failed: false, + } + ); + // The identity's own state, not a fresh identity's: once a private + // sync read the store to its end, and once loaded with a private + // payment that may be unresolved. + let readiness_now = |readiness: &mut PrivateContactReadinessFFI| { + let read = unsafe { + platform_wallet_get_private_contact_readiness( + handle, + identity_id.to_buffer().as_ptr(), + readiness, + ) + }; + assert_eq!(read.code, PlatformWalletFFIResultCode::Success); + }; + let with_identity = + |change: &dyn Fn(&mut platform_wallet::wallet::identity::ManagedIdentity)| { + PLATFORM_WALLET_STORAGE + .with_item(handle, |wallet| { + crate::runtime::runtime().block_on(async { + let mut wm = wallet.wallet_manager().write().await; + change( + wm.get_wallet_info_mut(&wallet.wallet_id()) + .expect("the wallet's info") + .identity_manager + .managed_identity_mut(&identity_id) + .expect("the identity"), + ); + }) + }) + .expect("the wallet"); + }; + with_identity(&|managed| managed.note_private_contact_requests_read_for_tests()); + readiness_now(&mut readiness); + assert_eq!( + readiness, + PrivateContactReadinessFFI { + private_payments_restored: true, + private_store_read: true, + unresolved_private_payment: false, + private_payments_restore_failed: false, + } + ); + with_identity(&|managed| { + managed.apply_private_contact_requests_position( + platform_wallet::changeset::PrivateContactRequestsPosition { + position: 0, + key_fingerprint: [0; 32], + private_payments_unresolved: true, + }, + ) + }); + readiness_now(&mut readiness); + assert_eq!( + readiness, + PrivateContactReadinessFFI { + private_payments_restored: false, + private_store_read: true, + unresolved_private_payment: true, + private_payments_restore_failed: false, + } + ); + let stranger = unsafe { + platform_wallet_get_private_contact_readiness( + handle, + [0xEE; 32].as_ptr(), + &mut readiness, + ) + }; + assert_eq!( + stranger.code, + PlatformWalletFFIResultCode::ErrorIdentityNotFound + ); + assert_eq!(readiness, PrivateContactReadinessFFI::default(), "reset"); + PLATFORM_WALLET_STORAGE.remove(handle); + } + #[test] fn test_contact_request_getters() { unsafe { diff --git a/packages/rs-platform-wallet-ffi/src/dashpay.rs b/packages/rs-platform-wallet-ffi/src/dashpay.rs index 85dde7ca6ea..fc04b02c647 100644 --- a/packages/rs-platform-wallet-ffi/src/dashpay.rs +++ b/packages/rs-platform-wallet-ffi/src/dashpay.rs @@ -35,8 +35,19 @@ use std::ffi::CStr; use std::os::raw::c_char; -use platform_wallet::ContactRequest; -use rs_sdk_ffi::{MnemonicResolverCoreSigner, MnemonicResolverHandle, SignerHandle, VTableSigner}; +use dash_sdk::platform::dashpay::PrivateContactRequest; +use dash_sdk::platform::private_document_entries::PrivateDocumentEntries; +use dash_sdk::platform::private_document_scan::PrivateDocumentScan; +use dpp::identity::{Identity, KeyID}; +use dpp::platform_value::BinaryData; +use dpp::prelude::{DataContract, Identifier}; +use dpp::version::PlatformVersion; +use dpp::ProtocolError; +use platform_wallet::{ContactRequest, PlatformWalletError, PrivateDocumentKeyPaths}; +use rs_sdk_ffi::{ + MnemonicResolverCoreSigner, MnemonicResolverHandle, MnemonicResolverSignerError, SignerHandle, + VTableSigner, +}; use crate::contact_request::CONTACT_REQUEST_STORAGE; use crate::core_wallet::classify_broadcast_result; @@ -1106,10 +1117,12 @@ impl platform_wallet::ContactCryptoProvider for ResolverContactCryptoProvider { path: &key_wallet::bip32::DerivationPath, ) -> Result { use key_wallet::signer::ExtendedPubKeySigner; + // A missing mnemonic stays the key-unavailable outcome: the private sync's seed check + // derives through here before any page is read. self.signer .extended_public_key(path) .await - .map_err(|e| platform_wallet::PlatformWalletError::InvalidIdentityData(e.to_string())) + .map_err(private_document_signer_error) } async fn ecdh_shared_secret( @@ -1222,6 +1235,95 @@ impl platform_wallet::ContactCryptoProvider for ResolverContactCryptoProvider { private_data: opened.private_data, }) } + + async fn scan_private_document_page( + &self, + keys: &PrivateDocumentKeyPaths, + data_contract_id: Identifier, + document_type_name: &str, + start_position: u64, + page: &PrivateDocumentEntries, + ) -> Result { + self.signer + .scan_private_document_page( + &keys.recipients, + &keys.senders, + data_contract_id, + document_type_name, + start_position, + page, + ) + .map_err(private_document_signer_error) + } + + async fn scan_private_document_pages( + &self, + keys: &PrivateDocumentKeyPaths, + data_contract_id: Identifier, + document_type_name: &str, + pages: &[(u64, &PrivateDocumentEntries)], + ) -> Result, PlatformWalletError> { + // One Keychain read for the batch, not one per page. + self.signer + .scan_private_document_pages( + &keys.recipients, + &keys.senders, + data_contract_id, + document_type_name, + pages, + ) + .map_err(private_document_signer_error) + } + + async fn seal_private_contact_request( + &self, + sender_encryption_key_path: &key_wallet::bip32::DerivationPath, + dashpay_contract: &DataContract, + sender: &Identity, + sender_encryption_key_id: KeyID, + signing_key_id: KeyID, + signature: &[u8; 65], + recipient: &Identity, + recipient_key_id: KeyID, + request: &PrivateContactRequest, + esk_seed: &[u8; 32], + platform_version: &PlatformVersion, + ) -> Result { + self.signer + .seal_private_contact_request( + sender_encryption_key_path, + dashpay_contract, + sender, + sender_encryption_key_id, + signing_key_id, + signature, + recipient, + recipient_key_id, + request, + esk_seed, + platform_version, + ) + .map_err(private_document_signer_error) + } +} + +/// A signer failure of a private document operation, or of the receiving xpub +/// derivation the private sync's seed check makes first, as a wallet error: the +/// SDK's refusal stays typed; a missing mnemonic is the key-unavailable +/// outcome (FFI code 31), carried as the signer's typed completion is, with +/// the reserved marker at position 0 of a `ProtocolError::Generic` payload +/// (`NotFound` renders it there), so the structural discriminator restores +/// it; the rest are reported as the other provider methods report theirs. +fn private_document_signer_error(error: MnemonicResolverSignerError) -> PlatformWalletError { + match error { + MnemonicResolverSignerError::PrivateContactRequest(error) => { + PlatformWalletError::Sdk(error) + } + error @ MnemonicResolverSignerError::NotFound => PlatformWalletError::Sdk( + dash_sdk::Error::Protocol(ProtocolError::Generic(error.to_string())), + ), + error => PlatformWalletError::InvalidIdentityData(error.to_string()), + } } /// Drain the persisted deferred-crypto queue using the Keychain signer for the @@ -1653,6 +1755,228 @@ pub unsafe extern "C" fn platform_wallet_drainable_contact_crypto_count( mod tests { use super::*; + /// A test wallet's mnemonic, counting how often the resolver reads it. + unsafe extern "C" fn counting_resolve( + ctx: *const std::ffi::c_void, + _wallet_id_bytes: *const u8, + out_buf: *mut c_char, + out_capacity: usize, + out_len: *mut usize, + ) -> i32 { + const PHRASE: &str = + "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon \ + abandon about"; + (*(ctx as *const std::sync::atomic::AtomicUsize)) + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); + let phrase = PHRASE.as_bytes(); + if phrase.len() + 1 > out_capacity { + return rs_sdk_ffi::mnemonic_resolver_result::BUFFER_TOO_SMALL; + } + std::ptr::copy_nonoverlapping(phrase.as_ptr() as *const c_char, out_buf, phrase.len()); + *out_buf.add(phrase.len()) = 0; + *out_len = phrase.len(); + rs_sdk_ffi::mnemonic_resolver_result::SUCCESS + } + + unsafe extern "C" fn missing_resolve( + _ctx: *const std::ffi::c_void, + _wallet_id_bytes: *const u8, + _out_buf: *mut c_char, + _out_capacity: usize, + _out_len: *mut usize, + ) -> i32 { + rs_sdk_ffi::mnemonic_resolver_result::NOT_FOUND + } + + unsafe extern "C" fn noop_destroy(_ctx: *mut std::ffi::c_void) {} + + /// A page of entries no key of the wallet opens. + fn store_page(start: u64, len: u64, total_count: u64) -> PrivateDocumentEntries { + PrivateDocumentEntries { + chunk_power: None, + entries: (start..start + len) + .map(|position| { + dash_sdk::platform::private_document_entries::PrivateDocumentEntry { + position, + block_height: position, + block_time_ms: position, + data: vec![position as u8; 589], + } + }) + .collect(), + total_count, + } + } + + /// The resolver-backed provider scans DashPay's private store, which a + /// public send or accept reads first: a page, and a batch of pages with + /// one Keychain read for the batch. A missing mnemonic is the + /// key-unavailable error, never an empty page. + #[test] + fn should_scan_a_page_and_a_batch_with_one_resolve_each() { + use platform_wallet::ContactCryptoProvider; + use std::str::FromStr; + + let path = + |path: &str| key_wallet::bip32::DerivationPath::from_str(path).expect("a valid path"); + let identity_id = Identifier::from([0xB0; 32]); + let keys = PrivateDocumentKeyPaths { + recipients: vec![(identity_id, vec![(2, path("m/9'/1'/5'/0'/0'/1'/2'"))])], + senders: vec![(identity_id, 1, path("m/9'/1'/5'/0'/0'/0'/1'"))], + }; + let contract_id = Identifier::from([0x44; 32]); + let resolves = std::sync::atomic::AtomicUsize::new(0); + let resolver = unsafe { + rs_sdk_ffi::dash_sdk_mnemonic_resolver_create( + &resolves as *const std::sync::atomic::AtomicUsize as *mut std::ffi::c_void, + counting_resolve, + noop_destroy, + ) + }; + let provider = unsafe { + resolver_contact_crypto_provider(resolver, [0u8; 32], key_wallet::Network::Testnet) + }; + let reads = || resolves.load(std::sync::atomic::Ordering::SeqCst); + let runtime = tokio::runtime::Builder::new_current_thread() + .build() + .expect("a runtime"); + + let first = store_page(0, 4, 6); + let page = runtime + .block_on(provider.scan_private_document_page( + &keys, + contract_id, + "privateContactRequest", + 0, + &first, + )) + .expect("the provider scans a page"); + assert_eq!(reads(), 1); + assert!(page.is_of_store(&contract_id, "privateContactRequest")); + assert_eq!(page.next_position, 4); + assert!(page.received.is_empty() && page.sent.is_empty() && page.rejected.is_empty()); + + let second = store_page(4, 2, 6); + let batch = runtime + .block_on(provider.scan_private_document_pages( + &keys, + contract_id, + "privateContactRequest", + &[(0, &first), (4, &second)], + )) + .expect("the provider scans a batch"); + assert_eq!(reads(), 2, "one Keychain read for the batch"); + assert_eq!( + batch + .iter() + .map(|scan| (scan.next_position, scan.is_complete())) + .collect::>(), + vec![(4, false), (6, true)] + ); + unsafe { rs_sdk_ffi::dash_sdk_mnemonic_resolver_destroy(resolver) }; + + let missing = unsafe { + rs_sdk_ffi::dash_sdk_mnemonic_resolver_create( + std::ptr::null_mut(), + missing_resolve, + noop_destroy, + ) + }; + let provider = unsafe { + resolver_contact_crypto_provider(missing, [0u8; 32], key_wallet::Network::Testnet) + }; + let refused = runtime.block_on(provider.scan_private_document_pages( + &keys, + contract_id, + "privateContactRequest", + &[(0, &first)], + )); + assert!( + matches!(refused, Err(PlatformWalletError::Sdk(_))), + "the key is unavailable: {refused:?}" + ); + unsafe { rs_sdk_ffi::dash_sdk_mnemonic_resolver_destroy(missing) }; + } + + /// A private sync whose resolver has no mnemonic is refused at its seed check, before any + /// page is read, with the key-unavailable code (31), as the page scan is, so a host routes + /// it to key repair rather than reporting an unknown failure. + #[test] + fn should_report_a_missing_mnemonic_at_the_private_sync_seed_check_as_key_unavailable() { + use dpp::identity::identity_public_key::v0::IdentityPublicKeyV0; + use dpp::identity::v0::IdentityV0; + use dpp::identity::{IdentityPublicKey, KeyType, Purpose, SecurityLevel}; + use key_wallet::wallet::initialization::WalletAccountCreationOptions; + + let manager = crate::test_fixtures::mock_manager(); + let wallet = runtime() + .block_on(manager.create_wallet_from_seed_bytes( + key_wallet::Network::Testnet, + &[7; 64], + WalletAccountCreationOptions::Default, + Some(0), + )) + .expect("a wallet"); + let key = dpp::secp256k1::PublicKey::from_secret_key( + &dpp::secp256k1::SecretKey::from_secret_bytes([3; 32]).expect("a secret key"), + ); + let identity = Identity::V0(IdentityV0 { + id: Identifier::from([0xB1; 32]), + public_keys: [( + 1, + IdentityPublicKey::V0(IdentityPublicKeyV0 { + id: 1, + purpose: Purpose::ENCRYPTION, + security_level: SecurityLevel::MEDIUM, + contract_bounds: None, + key_type: KeyType::ECDSA_SECP256K1, + read_only: false, + data: BinaryData::new(key.serialize().to_vec()), + disabled_at: None, + }), + )] + .into_iter() + .collect(), + balance: 0, + revision: 0, + }); + runtime().block_on(async { + let mut wm = wallet.wallet_manager().write().await; + wm.get_wallet_info_mut(&wallet.wallet_id()) + .expect("the wallet's info") + .identity_manager + .add_identity(identity, 0, wallet.wallet_id(), wallet.persister()) + .expect("the identity"); + }); + + let missing = unsafe { + rs_sdk_ffi::dash_sdk_mnemonic_resolver_create( + std::ptr::null_mut(), + missing_resolve, + noop_destroy, + ) + }; + let provider = unsafe { + resolver_contact_crypto_provider( + missing, + wallet.wallet_id(), + key_wallet::Network::Testnet, + ) + }; + let refused = runtime().block_on( + wallet + .identity() + .dashpay() + .sync_private_contact_requests(&provider, 1), + ); + let error = refused.expect_err("the mnemonic is missing"); + assert_eq!( + PlatformWalletFFIResult::from(error).code, + PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable + ); + unsafe { rs_sdk_ffi::dash_sdk_mnemonic_resolver_destroy(missing) }; + } + // Marshalling-boundary coverage for the verify entry point, replacing what // the removed attach FFI's input-validation tests upheld. The crypto // semantics (matching seed binds, wrong seed rejected) are pinned library- diff --git a/packages/rs-platform-wallet-ffi/src/error.rs b/packages/rs-platform-wallet-ffi/src/error.rs index a5293490f25..f6fa401a553 100644 --- a/packages/rs-platform-wallet-ffi/src/error.rs +++ b/packages/rs-platform-wallet-ffi/src/error.rs @@ -135,31 +135,51 @@ pub enum PlatformWalletFFIResultCode { /// result message for logging/detail. ErrorWalletAlreadyExists = 15, /// Maps `PlatformWalletError::ShieldedBroadcastFailed`. The shielded - /// transition (identity-create, unshield, transfer, or withdrawal) was - /// DEFINITIVELY not executed — either the relay/CheckTx rejected the - /// broadcast, or Platform reported the transition's own execution error. - /// Any note reservations were released and the caller is free to retry. + /// transition (a shield from Platform addresses, identity-create, + /// identity top-up, unshield, transfer, or withdrawal) was DEFINITIVELY + /// not executed: it never left the wallet, refused before anything was + /// sent (no address to send it to, or the SDK's own refusal). An + /// endpoint's refusal or verdict (CheckTx or execution) proves nothing, + /// as no proof backs it: that is [`Self::ErrorShieldedSpendUnconfirmed`] + /// ([`Self::ErrorShieldedBroadcastUnconfirmed`] for an identity create), + /// as is any broadcast that may have been delivered. Any note + /// reservations were released, with the spend's recovery record, and the + /// caller is free to retry. /// For identity-create, the new identity does NOT exist and /// `out_identity_id` is left untouched (still zeroed). ErrorShieldedBroadcastFailed = 16, /// Maps `PlatformWalletError::ShieldedBroadcastUnconfirmed`. The broadcast - /// was ACCEPTED by the relay but the SDK could not confirm its execution - /// result (a transient result-proof fetch/verify failure, not a platform - /// rejection), and a direct fetch of the derived id also came back empty. - /// The identity may already exist on chain, so the caller must NOT treat + /// was accepted by the relay, or may have been delivered, but the SDK + /// could not confirm its execution result (a broadcast attempt that failed + /// in transport, an endpoint's refusal or verdict, a result-proof + /// fetch/verify failure, …), and a direct fetch of the derived id also + /// came back empty. The wallet keeps the notes reserved and the create's + /// recovery record, which it saved before the broadcast. The identity may + /// already exist on chain, so the caller must NOT treat /// it as unregistered or re-submit. UNLIKE every other error code, /// `out_identity_id` IS written (the 32-byte derived id) on this code so /// the caller can hold the slot and surface the pending identity. ErrorShieldedBroadcastUnconfirmed = 17, - /// Maps `PlatformWalletError::ShieldedSpendUnconfirmed` (unshield / - /// shielded transfer / shielded withdrawal). The spend transition was - /// ACCEPTED by the relay but its execution result could not be confirmed - /// (DAPI wait timeout, result-proof fetch/verify failure, …). The spend - /// may have executed on chain, so the wallet intentionally KEEPS the - /// notes reserved: the next nullifier sync promotes them to spent if the - /// spend landed, and an app restart frees them if it never did. The host - /// must NOT auto-retry — a retry would select different unreserved notes - /// and could double-send if the original spend landed. + /// Maps `PlatformWalletError::ShieldedSpendUnconfirmed` (shield from + /// Platform addresses or from an identity / unshield / shielded transfer / + /// shielded withdrawal / identity top-up / private document create from + /// the pool; an identity created from the pool reports + /// [`Self::ErrorShieldedBroadcastUnconfirmed`] (17) instead), and + /// `PlatformWalletError::ShieldedBroadcastMaybeDelivered`. + /// The transition was accepted by the relay, or may have been delivered, + /// but its execution result could not be confirmed (a broadcast attempt + /// that failed in transport, an endpoint's refusal or consensus verdict, + /// a DAPI wait timeout, a result-proof fetch/verify failure, …). It may + /// have executed on chain, or may still execute. For a spend that consumes + /// notes the wallet intentionally KEEPS the notes reserved and its + /// recovery record, saved before the broadcast and restored after a + /// restart: the next nullifier sync promotes them to spent if the spend + /// landed, and the redrive and anchor-prune passes release them once it + /// provably never can. A shield from Platform addresses reserves nothing + /// and keeps no record: its activity row stays pending until the scan + /// sees its note. The host must NOT auto-retry: a retry would select + /// different unreserved notes, or sign a second shield with the inputs' + /// next nonces, and could double-send if the original landed. ErrorShieldedSpendUnconfirmed = 18, /// Maps `PlatformWalletError::ShieldedNoRecordedAnchor`. The wallet could /// not build the spend against any Platform-recorded anchor yet: its local @@ -185,15 +205,16 @@ pub enum PlatformWalletFFIResultCode { /// auto-retry. Shielded sibling: [`Self::ErrorShieldedSpendUnconfirmed`]. ErrorTransactionBroadcastUnconfirmed = 20, /// Maps `PlatformWalletError::AddressNonceMismatch`. Platform rejected an - /// address-funds transition (shield, or identity top-up-from-addresses) + /// address-funds transition (a transfer or withdrawal from Platform + /// addresses, or an identity registration or top-up from them) /// because the submitted address nonce raced Platform's expected next - /// value (a lagging DAPI replica stale read; consensus code 40603). Same - /// definitively-failed / notes-released / safe-to-retry contract as - /// [`Self::ErrorShieldedBroadcastFailed`] — the transition did NOT execute - /// and any note reservations were released (a shield reserves none) — but - /// as its OWN code so hosts can recognize this specific, self-healing + /// value (a lagging DAPI replica stale read; consensus code 40603). Its + /// OWN code so hosts can recognize this specific, self-healing /// failure and retry: the retry re-fetches the address nonce, resolving - /// the mismatch without host intervention. The submitted and Platform- + /// the mismatch without host intervention. A shield from Platform + /// addresses does not report it: an endpoint's nonce verdict on a shield + /// that was dispatched reads as [`Self::ErrorShieldedSpendUnconfirmed`], + /// as no proof backs it. The submitted and Platform- /// expected nonce values travel in the result `message` (the typed /// `Display`); they are not exposed as structured out-fields (that would /// require an ABI-breaking change to `PlatformWalletFFIResult`). @@ -430,13 +451,17 @@ pub enum PlatformWalletFFIResultCode { ErrorShieldedInsufficientBalance = 41, /// Maps `PlatformWalletError::MasternodeWithdrawalUnconfirmed`. A /// masternode (evonode) identity credit withdrawal was broadcast and - /// accepted, but its execution result could not be confirmed — it may - /// already have executed, and the identity nonce was consumed for it, so + /// accepted, or may have been delivered, but its execution result could + /// not be confirmed (a broadcast attempt that failed in transport, an + /// endpoint's refusal or consensus verdict, a wait timeout, …). It may + /// already have executed, or may still execute, and the identity nonce + /// was taken for it, so /// a blind retry could submit a SECOND withdrawal. The host must NOT /// retry; it must re-read the identity's claimable balance (and the - /// payout) and let the user decide from the reconciled state. Definitive - /// rejections (consensus errors, transport verdicts) keep their ordinary - /// codes and stay retryable. Siblings: [`Self::ErrorShieldedSpendUnconfirmed`], + /// payout) and let the user decide from the reconciled state. Only a + /// failure before the broadcast, or a broadcast refused before anything + /// was sent, keeps its ordinary code and stays retryable. Siblings: + /// [`Self::ErrorShieldedSpendUnconfirmed`], /// [`Self::ErrorTransactionBroadcastUnconfirmed`]. ErrorMasternodeWithdrawalUnconfirmed = 42, /// The deterministic masternode list isn't available yet (SPV not @@ -631,6 +656,115 @@ pub enum PlatformWalletFFIResultCode { /// carry none and accept the caller's. ErrorAssetLockRecipientMismatch = 61, + /// Maps `PlatformWalletError::PrivateContactRequestNeedsPrivateReply`: + /// the contact requests with that identity came or went privately + /// (protocol version 15), so a public `contactRequest` to it, in reply or + /// as a rotation, would publish the relationship. The public send and the + /// public accept refuse it, and nothing was sent: the request goes + /// privately instead, and the in-kind accept picks the private reply + /// itself. The shielded spend contract (`map_spend_result`) keeps the code, + /// as the in-kind accept can raise it. The exports that send and accept + /// contact requests are added by the FFI PR. 62 to 67 are claimed by open + /// branches, so this takes 68. + ErrorPrivateContactRequestNeedsPrivateReply = 68, + + /// The operation needs the shielded pool, and this library was built + /// without the `shielded` feature: accepting a contact request that came + /// privately in kind, whose private reply is paid from the pool (the + /// export is added by the FFI PR; no export in this crate returns it yet). + /// Nothing was sent. Not retryable on this build; a build with shielded + /// support accepts it. + ErrorShieldedBuildRequired = 69, + + /// The SDK refused the request without sending it: the network is proven + /// at a protocol version below the one that serves it (for example + /// DashPay's private contact request store before protocol version 15). + /// Expected on such a network, and lifts when the network upgrades. A + /// refusal from an SDK pinned below the required version is + /// [`Self::ErrorSdkPinnedBelowProtocolVersion`] (75). A refusal whose + /// query for the network's version failed keeps the catch-all code, + /// whether that may pass or comes from the SDK's own setup (a context + /// provider that cannot give quorum keys at all), as neither shows the + /// network runs an earlier version. + ErrorProtocolVersionNotActive = 70, + + /// Maps `PlatformWalletError::PrivateContactRequestPending`: a private + /// contact request to that identity is in flight (another send or reply + /// reserved it), or was paid for and is not yet read back from the store, + /// or a private payment the shielded store's journal keeps unresolved + /// holds the pair. Nothing new was paid. Pending, not failed: do not + /// submit it again. A later private contact request sync settles it once + /// the entry is read back, and the shielded sync once the payment provably + /// never executes. A read of the private store that did not finish before + /// the request was decided is not pending: it is + /// [`Self::ErrorPrivateContactStoreNotRead`] (74). + ErrorPrivateContactRequestPending = 71, + + /// Maps `PlatformWalletError::PrivateContactPaymentsNotRestored`: the + /// wallet, not one contact, is held, as its unconfirmed private payments + /// may hold pairs no reservation shows yet, which only a restoration from + /// the shielded store's journal shows. No contact request, public or + /// private, is sent or accepted, nothing signed or broadcast, until they + /// are restored. In a build with the `shielded` feature: the wallet was + /// published (created or loaded) while no shielded store was configured, + /// its persister declaring the private scan state (bit 15); it was loaded + /// after binding a shielded account in an earlier process; or its last + /// restoration failed, or waits for a busy store. In every build: the + /// identity was loaded with its private scan state marking a private + /// payment that may be unresolved, or was added to a wallet whose backend + /// kept its record marked after an earlier wallet under the id was + /// removed. Configuring the shielded store restores + /// them with no keys, as binding the wallet's shielded account does, and a + /// contact request retries a failed restoration once without waiting; a + /// private sync does not. A host whose persister declares the private + /// scan state configures the shielded store when the manager is + /// activated, before loading or creating wallets: until it does, and + /// while a failed configure is not retried, 72 holds. + /// `platform_wallet_get_private_contact_readiness` reads whether they are + /// restored and whether the last restoration failed. A build without the + /// `shielded` feature never restores them. + ErrorPrivateContactPaymentsNotRestored = 72, + + /// Maps `PlatformWalletError::PrivateContactRecoveryUnsupported`: the + /// persister does not declare that it keeps the private contact request + /// scan state (`PRIVATE_CONTACT_REQUEST_SCAN_STATE`, bit 15) in atomic + /// changesets (`ATOMIC_CHANGESETS`, bit 0, with the changeset begin and end + /// callbacks wired), so a private contact request is not paid for, nothing + /// sealed or paid. Its recovery + /// marker could not survive a restart, and a process reopening the wallet + /// could then publish the pair while the payment may still execute. Not + /// retryable as it is: a host persisting the scan state declares both. + ErrorPrivateContactRecoveryUnsupported = 73, + + /// Maps `PlatformWalletError::PrivateContactStoreNotRead`: DashPay's + /// private contact request store was not read to its end for the sending + /// identity, with the keys Platform proves it holds, before a contact + /// request or acceptance, public or private, was decided. Nothing was + /// reserved, sealed, paid or broadcast. Calling again continues the read + /// from where it stopped: a node behind the store the wallet already saw, + /// or keys that kept changing, stop it. Not a pending request (71). + ErrorPrivateContactStoreNotRead = 74, + + /// The SDK refused the request without sending it because the SDK itself + /// is pinned below the protocol version the request needs + /// (`dash_sdk::Error::ProtocolVersionNotActive` with `pinned`), whatever + /// the network runs. A network upgrade does not lift it: only raising or + /// removing the pin does. A network proven below the version is + /// [`Self::ErrorProtocolVersionNotActive`] (70). + ErrorSdkPinnedBelowProtocolVersion = 75, + + /// Maps `PlatformWalletError::PublicContactRequestUnconfirmed`: a public + /// contact request to that identity was broadcast and may have been + /// delivered (its own send or accept reported + /// [`Self::ErrorTransactionBroadcastUnconfirmed`] (20)), and no proof + /// settled its outcome yet. Nothing new was signed. Unconfirmed, not + /// failed: do not submit it again. A public contact request sync settles + /// it, recording the request once its document is proved on Platform and + /// freeing the pair once its transition is proved unable to write it. + /// A private request pending to the identity is + /// [`Self::ErrorPrivateContactRequestPending`] (71). + ErrorPublicContactRequestUnconfirmed = 76, + /// The named thing does not exist. /// /// Originally (and still mostly) the code for every `Option` returned as an @@ -922,6 +1056,11 @@ impl From for PlatformWalletFFIResult { PlatformWalletError::WalletAlreadyExists(..) => { PlatformWalletFFIResultCode::ErrorWalletAlreadyExists } + // An identity the wallet does not hold, as a read or a contact + // request names one: its own code, which Swift and Kotlin type. + PlatformWalletError::IdentityNotFound(..) => { + PlatformWalletFFIResultCode::ErrorIdentityNotFound + } // The two shielded broadcast/wait variants. Today nothing routes // them through this blanket impl — the dedicated match in // `platform_wallet_manager_shielded_identity_create_from_pool` @@ -938,7 +1077,11 @@ impl From for PlatformWalletFFIResult { PlatformWalletError::ShieldedBroadcastUnconfirmed { .. } => { PlatformWalletFFIResultCode::ErrorShieldedBroadcastUnconfirmed } - PlatformWalletError::ShieldedSpendUnconfirmed { .. } => { + // A broadcast that may have been delivered may still execute: it + // reads as unconfirmed, never as failed, so a host does not pay + // again with other notes. + PlatformWalletError::ShieldedSpendUnconfirmed { .. } + | PlatformWalletError::ShieldedBroadcastMaybeDelivered(..) => { PlatformWalletFFIResultCode::ErrorShieldedSpendUnconfirmed } PlatformWalletError::ShieldedIdentityDebitPending { .. } => { @@ -1084,6 +1227,38 @@ impl From for PlatformWalletFFIResult { PlatformWalletError::SpvProcessRestartRequired(..) => { PlatformWalletFFIResultCode::ErrorSpvProcessRestartRequired } + // The public send or accept refused a contact whose requests came + // or went privately; the host routes it to the private send or + // accept. + PlatformWalletError::PrivateContactRequestNeedsPrivateReply(..) => { + PlatformWalletFFIResultCode::ErrorPrivateContactRequestNeedsPrivateReply + } + // A private request to the contact is in flight or paid and not + // yet read back: pending, not failed, so the host must not submit + // it again. + PlatformWalletError::PrivateContactRequestPending(..) => { + PlatformWalletFFIResultCode::ErrorPrivateContactRequestPending + } + // A public request to the contact was broadcast and its outcome is + // not proved yet: unconfirmed, not failed, so the host must not + // submit it again. + PlatformWalletError::PublicContactRequestUnconfirmed(..) => { + PlatformWalletFFIResultCode::ErrorPublicContactRequestUnconfirmed + } + // The wallet's private payments from an earlier process are not + // restored yet: wallet readiness, not one contact's pending request. + PlatformWalletError::PrivateContactPaymentsNotRestored => { + PlatformWalletFFIResultCode::ErrorPrivateContactPaymentsNotRestored + } + // The persister cannot keep a private payment's recovery marker. + PlatformWalletError::PrivateContactRecoveryUnsupported => { + PlatformWalletFFIResultCode::ErrorPrivateContactRecoveryUnsupported + } + // The private store read before deciding did not finish: nothing + // reserved or sent, and calling again continues it. + PlatformWalletError::PrivateContactStoreNotRead(..) => { + PlatformWalletFFIResultCode::ErrorPrivateContactStoreNotRead + } // A signer failure can also reach this blanket impl wrapped as // `PlatformWalletError::Sdk(dash_sdk::Error::Protocol(..))` (any // wallet operation that propagates the SDK error via `?`). The @@ -1193,6 +1368,24 @@ impl From for PlatformWalletFFIResult { // `MessageSigningKeyUnavailable` mapped above. By the time a // `MessageSigningFailed` reason exists, any marker in it sits // mid-string and is deliberately not matched. + // The network does not serve the request yet, as its proven + // protocol version shows, or the SDK is pinned below it. A + // refusal whose query for the version failed stays on the + // catch-all, whether that may pass (the network failing) or not + // (a context provider configured so it cannot give quorum keys: + // this SDK's own setup), as neither says the network runs an + // earlier version. + // A pin below the required version is the host's own setting, which + // only it can lift: its own code, whatever the network's query + // showed. + PlatformWalletError::Sdk(dash_sdk::Error::ProtocolVersionNotActive { + pinned: true, + .. + }) => PlatformWalletFFIResultCode::ErrorSdkPinnedBelowProtocolVersion, + PlatformWalletError::Sdk(dash_sdk::Error::ProtocolVersionNotActive { + cause: None, + .. + }) => PlatformWalletFFIResultCode::ErrorProtocolVersionNotActive, _ => PlatformWalletFFIResultCode::ErrorUnknown, }; let result = PlatformWalletFFIResult::err(code, error.to_string()); @@ -2796,3 +2989,282 @@ mod identity_balance_error_tests { assert!(!result.message.is_null()); } } + +#[cfg(test)] +mod private_contact_request_error_tests { + use super::*; + #[cfg(feature = "shielded")] + use crate::shielded_send::map_spend_result; + + /// A store the network does not serve yet (DashPay's private contact + /// requests before protocol version 15) is told apart from a failure, so + /// a host can stay quiet about it; a refusal that may lift soon, because + /// the version could not be confirmed, is still the network failing; and + /// an SDK pinned below the version, which only the host lifts, has its own + /// code. + #[test] + fn should_tell_a_store_the_network_does_not_serve_yet_by_its_own_code() { + let refused = |cause: Option>| { + PlatformWalletFFIResult::from(PlatformWalletError::Sdk( + dash_sdk::Error::ProtocolVersionNotActive { + method: "get_private_document_entries", + required: 15, + feature: None, + network: 14, + pinned: false, + cause, + }, + )) + }; + let lasting = refused(None); + assert_eq!( + lasting.code, + PlatformWalletFFIResultCode::ErrorProtocolVersionNotActive + ); + assert_eq!(lasting.code as u32, 70); + + let transient = refused(Some(Box::new(dash_sdk::Error::Generic( + "no node answered".to_string(), + )))); + assert_eq!(transient.code, PlatformWalletFFIResultCode::ErrorUnknown); + + // A pinned SDK refuses whatever its query for the network's version + // showed, with or without a cause: its own code, which a network + // upgrade does not lift. + for cause in [ + None, + Some(Box::new(dash_sdk::Error::Generic( + "no node answered".to_string(), + ))), + ] { + let pinned = PlatformWalletFFIResult::from(PlatformWalletError::Sdk( + dash_sdk::Error::ProtocolVersionNotActive { + method: "get_private_document_entries", + required: 15, + feature: None, + network: 14, + pinned: true, + cause, + }, + )); + assert_eq!( + pinned.code, + PlatformWalletFFIResultCode::ErrorSdkPinnedBelowProtocolVersion + ); + assert_eq!(pinned.code as u32, 75); + } + + // A provider that cannot give quorum keys at all is this SDK's setup, + // not the network's version: the catch-all too. + let misconfigured = refused(Some(Box::new(dash_sdk::Error::ContextProviderError( + dash_sdk::error::ContextProviderError::Config("no quorum source".to_string()), + )))); + assert_eq!( + misconfigured.code, + PlatformWalletFFIResultCode::ErrorUnknown + ); + } + + #[test] + fn should_tell_a_private_request_from_other_accept_failures_by_code() { + let result = PlatformWalletFFIResult::from( + PlatformWalletError::PrivateContactRequestNeedsPrivateReply([7; 32].into()), + ); + assert_eq!( + result.code, + PlatformWalletFFIResultCode::ErrorPrivateContactRequestNeedsPrivateReply + ); + assert_eq!(result.code as u32, 68); + assert!(!result.message.is_null()); + } + + /// A private request in flight, or paid and not yet read back, is pending + /// rather than failed, whichever path reports it: the blanket conversion, + /// and the shielded spend contract the private send and accepts use. + #[test] + fn should_report_a_pending_private_request_by_its_own_code() { + let pending = || PlatformWalletError::PrivateContactRequestPending([7; 32].into()); + let result = PlatformWalletFFIResult::from(pending()); + assert_eq!( + result.code, + PlatformWalletFFIResultCode::ErrorPrivateContactRequestPending + ); + assert_eq!(result.code as u32, 71); + #[cfg(feature = "shielded")] + assert_eq!( + map_spend_result(Err(pending()), "private contact request").code, + PlatformWalletFFIResultCode::ErrorPrivateContactRequestPending + ); + } + + /// A public request to a contact whose outcome is unconfirmed holds the + /// pair by its own code, not as a private request pending, whichever path + /// reports it: the blanket conversion, and the shielded spend contract the + /// private send and accepts use. + #[test] + fn should_report_an_unconfirmed_public_request_by_its_own_code() { + let unconfirmed = || PlatformWalletError::PublicContactRequestUnconfirmed([7; 32].into()); + let result = PlatformWalletFFIResult::from(unconfirmed()); + assert_eq!( + result.code, + PlatformWalletFFIResultCode::ErrorPublicContactRequestUnconfirmed + ); + assert_eq!(result.code as u32, 76); + #[cfg(feature = "shielded")] + assert_eq!( + map_spend_result(Err(unconfirmed()), "private contact request").code, + PlatformWalletFFIResultCode::ErrorPublicContactRequestUnconfirmed + ); + } + + /// A public contact request a loaded wallet refuses until its private + /// payments are restored reaches the host by its own code, not as a + /// contact's pending request. + #[test] + fn should_report_unrestored_private_payments_by_their_own_code() { + let result = + PlatformWalletFFIResult::from(PlatformWalletError::PrivateContactPaymentsNotRestored); + assert_eq!( + result.code, + PlatformWalletFFIResultCode::ErrorPrivateContactPaymentsNotRestored + ); + assert_eq!(result.code as u32, 72); + #[cfg(feature = "shielded")] + assert_eq!( + map_spend_result( + Err(PlatformWalletError::PrivateContactPaymentsNotRestored), + "private contact request" + ) + .code, + PlatformWalletFFIResultCode::ErrorPrivateContactPaymentsNotRestored + ); + } + + /// A private payment over a persister that cannot keep its recovery marker + /// reaches the host by its own code, as does a spend whose broadcast may + /// have been delivered by the broadcast-failed one. + #[test] + fn should_report_unsupported_private_recovery_by_its_own_code() { + let result = + PlatformWalletFFIResult::from(PlatformWalletError::PrivateContactRecoveryUnsupported); + assert_eq!( + result.code, + PlatformWalletFFIResultCode::ErrorPrivateContactRecoveryUnsupported + ); + assert_eq!(result.code as u32, 73); + // A broadcast that may have been delivered reads as unconfirmed. + let delivered = PlatformWalletFFIResult::from( + PlatformWalletError::ShieldedBroadcastMaybeDelivered("unavailable".to_string()), + ); + assert_eq!( + delivered.code, + PlatformWalletFFIResultCode::ErrorShieldedSpendUnconfirmed + ); + // The explicit private send and accept report them through the spend + // contract alike. + #[cfg(feature = "shielded")] + { + assert_eq!( + map_spend_result( + Err(PlatformWalletError::PrivateContactRecoveryUnsupported), + "private contact request" + ) + .code, + PlatformWalletFFIResultCode::ErrorPrivateContactRecoveryUnsupported + ); + assert_eq!( + map_spend_result( + Err(PlatformWalletError::ShieldedBroadcastMaybeDelivered( + "unavailable".to_string() + )), + "private contact request" + ) + .code, + PlatformWalletFFIResultCode::ErrorShieldedSpendUnconfirmed + ); + } + } + + /// The private store read that did not finish before a contact request + /// was decided reaches the host by its own code, not as a pending request, + /// through the blanket conversion and the spend contract alike; and so + /// does a pair whose requests went privately, which the in-kind accept + /// raises, beside the codes the spend contract already kept. + #[test] + fn should_report_an_unfinished_private_store_read_by_its_own_code() { + let not_read = || PlatformWalletError::PrivateContactStoreNotRead([7; 32].into()); + let result = PlatformWalletFFIResult::from(not_read()); + assert_eq!( + result.code, + PlatformWalletFFIResultCode::ErrorPrivateContactStoreNotRead + ); + assert_eq!(result.code as u32, 74); + #[cfg(feature = "shielded")] + { + let through_spend = |error: PlatformWalletError| { + map_spend_result(Err(error), "private contact request").code as u32 + }; + assert_eq!(through_spend(not_read()), 74); + assert_eq!( + through_spend(PlatformWalletError::PrivateContactRequestNeedsPrivateReply( + [7; 32].into() + )), + 68 + ); + assert_eq!( + through_spend(PlatformWalletError::PrivateContactRequestPending( + [7; 32].into() + )), + 71 + ); + assert_eq!( + through_spend(PlatformWalletError::PrivateContactPaymentsNotRestored), + 72 + ); + assert_eq!( + through_spend(PlatformWalletError::PrivateContactRecoveryUnsupported), + 73 + ); + assert_eq!( + through_spend(PlatformWalletError::WalletRemovedBeforeSend( + "removed".to_string() + )), + 98 + ); + } + } + + /// The SDK's unconfirmed outcome keeps its unconfirmed code (20) through + /// the shielded spend contract, as through the blanket conversion: it may + /// have executed, so it never reads as a failure a host may retry. + #[cfg(feature = "shielded")] + #[test] + fn should_keep_an_unconfirmed_sdk_outcome_unconfirmed_through_the_spend_contract() { + let unconfirmed = || { + PlatformWalletError::Sdk(dash_sdk::Error::StateTransitionResultUnconfirmed(Box::new( + dash_sdk::Error::Generic("the acknowledgement was lost".into()), + ))) + }; + assert_eq!( + map_spend_result(Err(unconfirmed()), "shielded transfer").code, + PlatformWalletFFIResultCode::ErrorTransactionBroadcastUnconfirmed + ); + assert_eq!( + PlatformWalletFFIResult::from(unconfirmed()).code, + PlatformWalletFFIResultCode::ErrorTransactionBroadcastUnconfirmed + ); + } + + /// An identity the wallet does not hold reaches the host by its own code, + /// not the catch-all. + #[test] + fn should_report_an_identity_the_wallet_does_not_hold_by_its_own_code() { + let result = + PlatformWalletFFIResult::from(PlatformWalletError::IdentityNotFound([7; 32].into())); + assert_eq!( + result.code, + PlatformWalletFFIResultCode::ErrorIdentityNotFound + ); + assert_eq!(result.code as u32, 7); + } +} diff --git a/packages/rs-platform-wallet-ffi/src/identity_manager.rs b/packages/rs-platform-wallet-ffi/src/identity_manager.rs index 0fe211ae4bc..3329cb904c8 100644 --- a/packages/rs-platform-wallet-ffi/src/identity_manager.rs +++ b/packages/rs-platform-wallet-ffi/src/identity_manager.rs @@ -4,7 +4,7 @@ use crate::handle::*; use crate::types::*; use crate::{unwrap_option_or_return, unwrap_result_or_return}; use platform_wallet::wallet::persister::{NoPlatformPersistence, WalletPersister}; -use platform_wallet::IdentityManager; +use platform_wallet::{IdentityManager, PlatformWalletError}; use std::sync::Arc; pub(crate) fn ffi_noop_persister() -> WalletPersister { @@ -65,13 +65,20 @@ pub unsafe extern "C" fn identity_manager_remove_identity( manager.remove_identity(&id, &ffi_noop_persister()) }); let result = unwrap_option_or_return!(option); - if result.is_err() { - return PlatformWalletFFIResult::err( + match result { + Ok(_) => PlatformWalletFFIResult::ok(), + // Refused while the identity's contact request channel is held: a + // request in flight or a private payment that may still execute (71), + // or one not restored yet (72). + Err( + error @ (PlatformWalletError::PrivateContactRequestPending(_) + | PlatformWalletError::PrivateContactPaymentsNotRestored), + ) => PlatformWalletFFIResult::from(error), + Err(_) => PlatformWalletFFIResult::err( PlatformWalletFFIResultCode::ErrorIdentityNotFound, "Identity not found", - ); + ), } - PlatformWalletFFIResult::ok() } /// Get an identity by ID. `identity_id` is a `*const u8` to a diff --git a/packages/rs-platform-wallet-ffi/src/masternode_withdrawal.rs b/packages/rs-platform-wallet-ffi/src/masternode_withdrawal.rs index 4b83446381d..f8e10ecc16f 100644 --- a/packages/rs-platform-wallet-ffi/src/masternode_withdrawal.rs +++ b/packages/rs-platform-wallet-ffi/src/masternode_withdrawal.rs @@ -177,12 +177,13 @@ pub unsafe extern "C" fn platform_wallet_manager_masternode_withdrawal_keys( /// invalid. The resolver is invoked exactly once, at signing time; the /// handle-storage guard is not held across it. /// -/// Outcome codes after the transition leaves the wallet: a definitive -/// rejection returns an ordinary error (retryable); an AMBIGUOUS outcome — -/// broadcast accepted (or its ACK lost) and the result wait failed — returns -/// `ErrorMasternodeWithdrawalUnconfirmed` (42): the claim may have executed -/// and the identity nonce was consumed, so the host must NOT retry until it -/// has re-read the claimable balance. +/// Outcome codes of the broadcast: a transition that never left the wallet +/// (refused before anything was sent) returns an ordinary error (retryable). +/// Once a dispatch may have reached a node, anything short of a proved +/// result, an endpoint's refusal or consensus verdict included, returns +/// `ErrorMasternodeWithdrawalUnconfirmed` (42): the claim may have executed, +/// or may still execute, and the identity nonce was taken for it, so the +/// host must NOT retry until it has re-read the claimable balance. /// /// # Safety /// `wallet_id` / `pro_tx_hash` must point at 32 readable bytes; diff --git a/packages/rs-platform-wallet-ffi/src/shielded_send.rs b/packages/rs-platform-wallet-ffi/src/shielded_send.rs index c135350795d..df107b89a24 100644 --- a/packages/rs-platform-wallet-ffi/src/shielded_send.rs +++ b/packages/rs-platform-wallet-ffi/src/shielded_send.rs @@ -596,19 +596,24 @@ fn poke_sync_on_unconfirmed(result: &Result, handle: /// withdraw) to a typed FFI result, mirroring the identity-create sibling's /// code split so hosts can tell "definitively failed, safe to retry" from /// "may have executed, do NOT retry". -fn map_spend_result( +pub(crate) fn map_spend_result( result: Result<(), PlatformWalletError>, operation: &str, ) -> PlatformWalletFFIResult { match result { Ok(()) => PlatformWalletFFIResult::ok(), - // Ambiguous: the broadcast was accepted but its execution result - // couldn't be confirmed — the host must NOT re-submit. For the - // spend-based operations the notes stay reserved wallet-side; a - // shield reserves nothing. Either way the next sync (or an app - // restart) reconciles the outcome; the typed Display already - // carries the operation name and guidance. - Err(e @ PlatformWalletError::ShieldedSpendUnconfirmed { .. }) => { + // Outcome not known: a dispatch may have reached a node and the + // execution result couldn't be confirmed, so the host must NOT + // re-submit. For the spend-based operations the notes stay reserved + // wallet-side, with the recovery record saved before the broadcast; + // a shield from Platform addresses reserves nothing. Either way the + // next sync reconciles a transition that landed; the typed Display + // already carries the operation name and guidance. + // A broadcast that may have been delivered reads the same: it may + // still execute, so its notes and recovery record stay, and a host + // must not pay again. + Err(e @ PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + | Err(e @ PlatformWalletError::ShieldedBroadcastMaybeDelivered(_)) => { PlatformWalletFFIResult::err( PlatformWalletFFIResultCode::ErrorShieldedSpendUnconfirmed, e.to_string(), @@ -620,6 +625,31 @@ fn map_spend_result( Err(e @ PlatformWalletError::ShieldedIdentityDebitPending { .. }) | Err(e @ PlatformWalletError::ShieldedRecoveryCorrupted { .. }) | Err(e @ PlatformWalletError::ShieldedRecoveryKeysRequired { .. }) => e.into(), + // A private contact request in flight, or paid and not yet read back + // from the store: nothing new was paid, and a later private sync + // settles it, so it keeps its own pending code; unrestored private + // payments keep theirs, and so does a persister that cannot keep a + // private payment's recovery marker. A wallet removed before the + // payment started keeps the lifecycle refusal code (`NotFound`) every + // other export gives it. A protocol-version refusal from the store + // read before any payment keeps the blanket conversion's split: a + // lasting refusal is `ErrorProtocolVersionNotActive`, a transient one + // the catch-all. + // So does a public request to the pair whose outcome is unconfirmed, + // which holds the private send and accepts as it holds a public one. + // So does a private store read that did not finish before deciding + // (nothing reserved or sent), and a pair whose requests came or went + // privately, which the in-kind accept can raise. + Err(e @ PlatformWalletError::PrivateContactRequestPending(..)) + | Err(e @ PlatformWalletError::PublicContactRequestUnconfirmed(..)) + | Err(e @ PlatformWalletError::PrivateContactStoreNotRead(..)) + | Err(e @ PlatformWalletError::PrivateContactRequestNeedsPrivateReply(..)) + | Err(e @ PlatformWalletError::PrivateContactPaymentsNotRestored) + | Err(e @ PlatformWalletError::PrivateContactRecoveryUnsupported) + | Err(e @ PlatformWalletError::WalletRemovedBeforeSend(..)) + | Err(e @ PlatformWalletError::Sdk(dash_sdk::Error::ProtocolVersionNotActive { .. })) => { + e.into() + } // Retryable: the wallet couldn't build the spend against any // Platform-recorded anchor yet (its commitment tree is mid-block after // an index-chunk sync). Nothing was broadcast and the notes were @@ -628,17 +658,19 @@ fn map_spend_result( PlatformWalletFFIResultCode::ErrorShieldedNoRecordedAnchor, format!("Wallet is still syncing to a confirmed state — try again shortly. ({e})"), ), - // Definitive failure: the transition was not executed and the notes - // were released; the host may retry. + // Definitive failure: the transition never left the wallet (refused + // before anything was sent); a spend's notes were released and the + // host may retry. Err(e @ PlatformWalletError::ShieldedBroadcastFailed(_)) => PlatformWalletFFIResult::err( PlatformWalletFFIResultCode::ErrorShieldedBroadcastFailed, format!("{operation} failed: {e}"), ), - // Definitively failed on an address-nonce race (a shield spends platform - // address funds; a shield reserves no notes). Its own code carries the - // safe-to-retry contract AND lets the host recognize the self-healing - // nonce mismatch — a plain retry re-fetches the nonce. Without this arm - // it would regress to the generic `ErrorWalletOperation` below. + // An address-nonce race keeps its own code, so the host can recognize + // the self-healing nonce mismatch: a plain retry re-fetches the nonce. + // No operation mapped here reports it today: a shield from Platform + // addresses reads an endpoint's nonce verdict on a dispatched shield + // as unconfirmed, above. The arm keeps the code from regressing to the + // generic `ErrorWalletOperation` below if one does. Err(e @ PlatformWalletError::AddressNonceMismatch { .. }) => PlatformWalletFFIResult::err( PlatformWalletFFIResultCode::ErrorAddressNonceMismatch, format!("{operation} failed: {e}"), @@ -659,6 +691,18 @@ fn map_spend_result( // here as the blanket `From` conversion does, so hosts route to key // repair instead of reading a generic wallet failure. Structural // position-0 check only, never a substring sniff of the rendering. + // The SDK's unconfirmed outcome (`StateTransitionResultUnconfirmed`) + // that reached here unclassified: the transition may have executed, + // so it keeps the blanket conversion's unconfirmed code rather than + // reading as a failure a host may retry. + Err(e) + if matches!( + &e, + PlatformWalletError::Sdk(source) if source.is_state_transition_result_unconfirmed() + ) => + { + e.into() + } Err(e) if is_preserved_signer_key_unavailable(&e) => PlatformWalletFFIResult::err( PlatformWalletFFIResultCode::ErrorSigningKeyUnavailable, format!("{operation} failed: {e}"), @@ -742,7 +786,7 @@ const SPEND_PANIC_GUIDANCE: &str = "The spend may or may not have been broadcast /// a definitive failure code: a panic can strike after the notes were reserved and even after the /// transition was broadcast, so the outcome is genuinely ambiguous. That code's contract is /// exactly the conservative one this needs — the host must not auto-retry, the reservation stays -/// in place, and the next nullifier sync (or an app restart) reconciles whether the spend landed. +/// in place, and the next nullifier sync reconciles whether the spend landed. fn catch_spend_panic( operation: &str, body: impl FnOnce() -> PlatformWalletFFIResult, @@ -2426,6 +2470,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: true, + anchor_height: None, }, ) .expect("seed malformed durable metadata"); @@ -2993,6 +3038,19 @@ mod tests { assert!(message_of(&result).contains("this request was not started")); } + /// A private payment refused because its wallet was removed first keeps + /// the lifecycle refusal code, not the generic operation failure. + #[test] + fn map_spend_result_keeps_a_wallet_removed_before_send_at_not_found() { + let removed: Result<(), PlatformWalletError> = Err( + PlatformWalletError::WalletRemovedBeforeSend("wallet removed".to_string()), + ); + let result = map_spend_result(removed, "private contact request"); + assert_eq!(result.code, PlatformWalletFFIResultCode::NotFound); + assert_eq!(result.code as i32, 98); + assert!(message_of(&result).contains("wallet removed")); + } + /// A key-unavailable signer completion preserved under `Sdk` by the wallet /// layer must keep code 31 through `map_spend_result` (the shield from /// identity path) instead of flattening to `ErrorWalletOperation`; a diff --git a/packages/rs-platform-wallet/Cargo.toml b/packages/rs-platform-wallet/Cargo.toml index b47c5662fa4..4dbe5e97c00 100644 --- a/packages/rs-platform-wallet/Cargo.toml +++ b/packages/rs-platform-wallet/Cargo.toml @@ -61,10 +61,11 @@ grovedb-commitment-tree = { workspace = true, optional = true } # is built against (its `Cargo.lock` resolves rusqlite at this major). rusqlite = { version = "0.41", optional = true } zip32 = { version = "0.2.0", default-features = false, optional = true } -# `StreamExt`/`pin_mut!` to consume the SDK's `sync_shielded_notes_stream` -# in the interleaved fetch/tree-append consumer (shielded sync only). -# Same version as `dash-sdk` so the lockfile resolves a single copy. -futures = { version = "0.3.30", optional = true } +# `StreamExt` to consume the SDK's page streams: the shielded note sync's +# `sync_shielded_notes_stream` and the private contact request sync's +# `private_document_pages`. Same version as `dash-sdk` so the lockfile +# resolves a single copy. +futures = { version = "0.3.30" } # Networked, opt-in example binaries. Each one performs real network I/O # against a live devnet, so they are examples (compiled, never run by @@ -113,8 +114,9 @@ static_assertions = "1.1" tracing-subscriber = { version = "0.3", features = ["env-filter"] } # `test-util` brings `tokio::time::pause` / `tokio::test(start_paused = true)` # so time-driven manager, startup and SPV runtime logic can be tested -# deterministically without sleeping wall-clock seconds. -tokio = { version = "1", features = ["sync", "rt", "time", "macros", "test-util"] } +# deterministically without sleeping wall-clock seconds. `net` gives the +# broadcast tests a loopback port they hold bound and unlistened. +tokio = { version = "1", features = ["sync", "rt", "time", "macros", "test-util", "net"] } # Re-enable the SDK with mocks feature for test-only mock builders; # the non-test build keeps the leaner default-feature SDK above. dash-sdk = { path = "../rs-sdk", default-features = false, features = ["dashpay-contract", "dpns-contract", "wallet", "mocks"] } @@ -129,7 +131,7 @@ default = ["bls", "eddsa"] test-utils = ["key-wallet/test-utils"] bls = ["key-wallet/bls", "key-wallet-manager/bls"] eddsa = ["key-wallet/eddsa", "key-wallet-manager/eddsa"] -shielded = ["dep:grovedb-commitment-tree", "dep:rusqlite", "dep:zip32", "dep:futures", "dash-sdk/shielded", "dpp/shielded-client"] +shielded = ["dep:grovedb-commitment-tree", "dep:rusqlite", "dep:zip32", "dash-sdk/shielded", "dpp/shielded-client"] # Opt-in serde derives on the changeset types in `src/changeset/` plus # the per-identity / DashPay scalar types those changesets carry. # Activates `key-wallet/serde` (which transitively activates diff --git a/packages/rs-platform-wallet/README.md b/packages/rs-platform-wallet/README.md index 1fc475bed45..7e38a91f9f4 100644 --- a/packages/rs-platform-wallet/README.md +++ b/packages/rs-platform-wallet/README.md @@ -121,8 +121,96 @@ Recovery preserves the original signed record with an `Unknown` outcome across r Startup errors distinguish damaged recovery metadata or undecodable signed bytes (`ShieldedRecoveryCorrupted`) from missing/replaced viewing keys (`ShieldedRecoveryKeysRequired`). Failure to recover an output set can also mean damaged ciphertext or output metadata; restore the original keys or a known-good backup before choosing explicit recovery. Invalid SQLite identifiers, nullifiers, and state flags fail startup without deleting their rows. When signed bytes are damaged but the recovery key remains readable, listing retains its account/activity identifiers and leaves the undecodable identity, nonce, and amount absent. +## Private contact request payments after a restart + +Before a private contact request's payment can reach the network, the shielded store saves a record of it in its private payment journal: the sender and recipient identities, the request's account reference, the commitment of the entry it appends, the SHA-256 of the whole entry, the position the sender's read of DashPay's private store rested at when it paid, and the nullifiers its spend consumes. The file store writes the journal, and the payment's redrive record, in one transaction on a connection at `synchronous=FULL` with `fullfsync` (on Apple platforms a plain sync does not flush the drive's own cache), so the record survives a crash or a power loss; a record that cannot be saved refuses the payment before anything is broadcast. The journal is kept apart from the spend's notes and redrive record: no note release, redrive removal, undecodable transition, account rebind or purge removes it. A record is removed only when its entry is read back from DashPay's private store and recorded durably, or when the transition provably never left the wallet (refused before anything was sent: no address to send it to, or the SDK's own refusal). An endpoint's answer, a consensus verdict included, proves nothing: no proof or quorum signature backs it, and an endpoint that kept or forwarded the signed transition can answer with any verdict. A record is also discharged once its payment is proven expired, judged against Platform's recorded anchors fetched before the shielded sync pass and proved at a height H: the spend's anchor, which the record keeps with the proved height of the set it was read from, was read at or below H and is absent from the set at H, the pass's note scan covers H, and its entry is absent from DashPay's private store read from the lowest position the records being judged kept through its end, with every page proved at or above H. An entry counts as the record's only when its whole bytes hash to the hash the record keeps: one that only starts with the commitment, which anyone who saw the commitment can append, does not hold the record. A record journaled before the hash and the position were kept matches by its commitment and is read for from the store's start. Whether its inputs are spent does not matter: the transition appends its entry in the block that spends them. A payment that never lands therefore frees its pair once its anchor ages out (Platform keeps an anchor for `shielded_anchor_retention_blocks`, 1000 blocks, and prunes every `shielded_anchor_pruning_interval`, 100 blocks). A restoration that finds a record whose request the sender's tracked request already records or supersedes, as a private sync read it back in a process that ended before discharging it, discharges it. Once a flush of the wallet's records failed for good in a process, the backend dropping what it buffered, no record is discharged on the strength of a tracked request for the rest of that process: no read-back is noted, a read of the entry again included (it finds the request tracked in memory and stores nothing), and a restoration leaves the records it finds settled. A restoration that finds a record whose request its sender does not track rewinds the sender's read to the position the record kept (the store's start for a record that kept none), so the entry is read again, its request recorded, and the record discharged once that is durable. Nothing else, a relay's refusal or a missing redrive record included, discharges a record. + +Until a payment's reservation is restored from the journal, nothing shows that the pair is taken: the request's entry is not in DashPay's store until the payment executes. So a wallet sends and accepts no contact request, public or private, while such a payment may be unrestored, and returns `PrivateContactPaymentsNotRestored` (FFI code 72) with nothing read, signed or broadcast. The in-kind accept is held the same way. These hold it: + +- In a build with the `shielded` feature, a wallet published, registered or loaded, while no shielded store is configured is held when its persister attests the private scan state: only such a persister lets a private payment be paid, so only its wallet can have journal records that no marker shows, as after the wallet was removed and registered again from the same seed, in this process or a new one. A wallet whose persister does not attest is never held for want of a store. With a store configured, the journal is read as the wallet is published. +- In a build with the `shielded` feature, `load_from_persistor` also holds a wallet that bound a shielded account before (its persisted viewing key shows it). A wallet with no persisted viewing key never bound one, since a bind persists the key before installing anything and refuses when it cannot. +- In a build with the `shielded` feature, a wallet stays held while its last restoration failed, or waits for a busy store. +- In every build, an identity whose private scan state marks a private payment that may be unresolved (`PrivateContactRequestsPosition::private_payments_unresolved`) is held. The wallet stores the marker durably before such a payment may reach the network, flushing a backend that does not commit a store inline, and stores it cleared once the identity holds no private request it is paying for or has not read back. A loaded hold is kept even when the backend no longer attests the scan state. +- In every build, an identity added to a wallet registered or loaded under an id whose record the backend kept marked after removing the wallet (`ClientStartState::retained_private_contact_scan_states`) is held the same way, before it can send or accept, whether it is added from Platform or by discovery. Only the marker is taken: the record's read position covers requests that went with the wallet's other rows, so the store is read for the identity from its start. A backend declaring `PRIVATE_CONTACT_REQUEST_SCAN_STATE` keeps a marked record through the wallet's removal and any purge of its rows, until a record stored cleared for that wallet and owner replaces it; the wallet never asks for one to be deleted, as `remove_wallet` stores nothing and `remove_identity` refuses while the identity's record is marked. + +A private contact request is therefore paid for only over a backend attesting `PRIVATE_CONTACT_REQUEST_SCAN_STATE` (bit 15) together with `ATOMIC_CHANGESETS` (bit 0), the two `PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART` names, as the scan state is written in changesets that must commit whole: any other refuses the private send and the private accept with `PrivateContactRecoveryUnsupported` (FFI code 73) before anything is sealed or paid, and a marker that cannot be stored or flushed refuses the payment too. A payment that may have reached the network keeps its pair held and its marker set whatever its spend's outcome, until its record is removed as above. A pair held so refuses another private payment (`PrivateContactRequestPending`, FFI code 71) and holds public sends and accepts. The wallet holds it, beyond the sender identity, for as long as the journal keeps the payment's record: removing the identity and loading it again does not release it. + +The first `PlatformWalletManager::configure_shielded` restores from the journal, with no keys, the payments of every held wallet and of every wallet the journal may keep payments of; a wallet registered or loaded after it is restored as it is published. A repeat call, as a host makes on every bind, never waits for a store that a scan holds: it restores only the wallets still held, each deferred to a task while the store is busy. Binding a wallet's shielded account restores its own, deferring the same way, the wallet held until it succeeds. A contact request refused as not restored first runs one more restoration, which does not wait on the store. A private sync does not restore. A host whose persister attests the private scan state therefore configures the shielded store when it activates the manager, before loading or creating wallets: until then every such wallet's contact requests are refused with 72, and a configure that fails keeps them refused until one succeeds. A host that opens no shielded store this session keeps those wallets' and identities' contact requests refused, and a build without the `shielded` feature keeps the marked identities' refused: the private payment may still execute, and a public request would publish the pair the private one kept off chain. `DashPayView::private_contact_readiness` (FFI `platform_wallet_get_private_contact_readiness`) reads whether the payments are restored, why the last restoration failed if it did, whether the private store was read to its end, and whether a payment may be unresolved (the marker, or a journal record the wallet holds the pair for), so a host shows the wallet's state rather than inferring it from refusals. `DashPayView::private_pair_held` reads one pair's hold as a send decides it. + +Every contact request and acceptance, public or private, first reads DashPay's private contact request store for the identity from its cursor to the store's end, with the keys Platform proves the identity holds, so a private request that landed since the last read (from another device of the identity, or a contact's request to it) is seen before the request is decided; the claim of a public pair checks again, in its lock, that the read still reaches the end. A read reaches the end only at the largest store size a page proved to the wallet in this process, in any pass or call, as the store only grows, so a later page from a node behind does not end it early, and after a key change rewinds the read, it counts only when the page that reaches the end was proved at or above the height the earlier read had reached. While the read cannot finish, the request is refused with `PrivateContactStoreNotRead` (FFI code 74), nothing reserved, sealed, paid or broadcast; calling again continues the read. On a network proven below the protocol version that serves private documents, nothing is read. An SDK pinned below that version refuses the read (FFI code 75), whatever the network runs. + +A restoration fails closed, every hold staying, when the coordinator is for another network, when a journal record does not read back, when a saved spend's transition does not decode and no journal record accounts for it, when a private contact request payment saved before the journal kept it has no request saved with it, and when an identity is marked as holding an unresolved payment while the wallet's journal is new (the shielded store was deleted or replaced, so it cannot show that payment resolved). The first clears with a store for the wallet's network. A journal record that does not read back is never removed, so it clears only once a known-good store file is restored; one whose wallet id does not read holds every wallet. The undecodable transition and the payment with no request clear once the damaged spend lands or its anchor is pruned, which removes its redrive record, or once a known-good store file is restored; the last one only once a known-good store is restored: removing the wallet and adding it again does not clear it, as the backend keeps the marked record, unless the host discards that record too. The readiness gives the failure's reason while the wallet is held. + +A build without the `shielded` feature keeps no shielded store, journal or restoration. What it protects: an identity whose record is marked, loaded or kept through its wallet's removal, sends and accepts no contact request, public or private (72), and every contact request reads the private store to its end first, so a pair whose private request is in the store is never answered or followed publicly. What it does not: it pays for no private request itself (the private send and accept take the payment as a caller's closure), it never lifts a marker's hold (only a shielded build's restoration can show the payment resolved), and nothing but the marker holds a pair whose payment has not landed: a host that discards a marked record leaves that pair unheld. + +### Shielded spends whose broadcast may have been delivered + +Every shielded spend that consumes notes (shielded transfers, unshields, withdrawals, identity top-ups and creations from the pool, and private document creations) broadcasts in single dispatches and keeps what each one proved: the SDK's own retry loop returns only its last error, which cannot show that an earlier attempt was admitted with its response lost. Any dispatch that reached an endpoint, whatever it answered (a consensus verdict included, which is unauthenticated), or failed in a way that allows delivery, any transport error whatever its gRPC code, makes the whole broadcast possibly delivered. Such a spend waits for its result, and reports `ShieldedSpendUnconfirmed` (FFI code 18) when that wait fails or answers with a verdict, its notes and redrive record kept so the redrive pass resolves it: a host must not pay again with other notes. An identity creation reports `ShieldedBroadcastUnconfirmed` (FFI code 17) instead, carrying the identity's derived id. Earlier versions reported these verdicts and transport failures as `ShieldedBroadcastFailed` (FFI code 16). Only a spend refused before anything was sent reports `ShieldedBroadcastFailed` and releases its notes at once. The dispatches stay within the SDK's configured retry budget: one dispatch and its retries. A re-broadcast refused by a node does not prove that no other node holds the original, so the redrive pass keeps such a spend's notes reserved until it lands or its anchor is pruned. A shield from Platform addresses broadcasts the same way and reports `ShieldedSpendUnconfirmed` (FFI code 18), not `AddressNonceMismatch` (FFI code 21) or `ShieldedBroadcastFailed`, once a dispatch may have reached a node and its result does not read its inputs spent; it consumes no notes and keeps no record of its signed transition, so its activity row stays pending until the scan sees its note: a retry would sign a second shield with the inputs' next nonces. Only a shield from an identity keeps its own handling (see "Identity-funded shield recovery" above). + +### Public contact requests whose broadcast may have been delivered + +Every public `contactRequest` (a send, a public accept, the in-kind accept's public reply, a send from a QR code, an auto-accept and a rotation) is sent by one path, which signs the transition, keeps the signed bytes, and broadcasts them by the rule shielded spends use: only a refusal before anything was sent reports its error with nothing held. Once a dispatch may have reached an endpoint, the send waits for the result (not after an endpoint's verdict, which no proof backs), records the request when its document is confirmed, and otherwise reports the SDK's unconfirmed outcome (`StateTransitionResultUnconfirmed`, FFI code 20) and holds the pair as an unconfirmed public request. Before signing, the send reads the request it would make by DashPay's `ownerIdUserIdAndAccountRef` unique index (the sender, the recipient and the account reference); one found, sent by an earlier process that ended before recording it or by another device of the sender, is adopted as sent, with nothing signed. A read that fails sends on. + +While an unconfirmed public request holds a pair, a public or private request to it, an accept included, is refused with `PublicContactRequestUnconfirmed` (FFI code 76), with nothing signed or paid, and the sender identity cannot be removed. `DashPayView::public_contact_request_unconfirmed` reads one pair's state, beside `DashPayView::private_pair_held`, so a host shows a public request awaiting its outcome apart from a private one pending. The public contact request sync settles it, as does each send or accept to the pair before it decides: `Sdk::state_transition_outcome` reads the transition's identity contract nonce, proved, and then the request is read by the unique index, proved. A request found is recorded as sent, as a confirmed send records it, and frees the pair. With none found, a nonce proved used at a height at or below the height of the read that missed the request shows the transition never wrote it and never will, and frees the pair; a new request may then be sent. Otherwise the transition may still execute: the same signed bytes are broadcast again and the pair stays held. No retry signs a second transition. + +The hold is in memory, bound to the wallet generation that took it: a wallet removed and created again under its id starts with none, and a handle taken before settles nothing of the new wallet's. Nothing about it is persisted. A process that starts afresh reads the sender's DashPay identity contract nonce from Platform, so while the earlier transition has not executed, and no other DashPay transition of the sender has since, a new request takes the same nonce and at most one of the two executes. That alone does not cover a restart after another DashPay transition of the sender executed with a later nonce: Platform then keeps the earlier nonce open as a missing revision (up to 24 back), and the new request takes a later one. What keeps a second request off Platform then is the unique index: a request built from the same recorded requests carries the same account reference (derived from the sender's encryption key, the friendship key, the account index and the version past the last recorded request), so Platform writes at most one of the two, and the read before signing adopts one already written. A restart does not hold back a private request to the pair while the earlier public one may still execute: the private store is not under that index. + ## Shielded balance API migration +Custom `ShieldedStore` implementations must also implement the private +contact payment methods, which have no default: `arm_private_contact_payment`, +`private_contact_redrives_for_wallet`, `retire_undelivered_spend` and the +private payment journal (`private_payment_journal_open`, +`open_private_payment_journal`, `private_payment_journal`, +`journal_private_payments`, `discharge_private_payment`). A store that cannot +keep a payment's records durably returns an error, which refuses the payment; +it must never report success while dropping them. `retire_undelivered_spend` +removes a spend's saved record and its journal records in one durable write, +and refuses, changing nothing, once a re-broadcast of the record was claimed +(`PendingRedrive::attempts` above 0). + +`arm_private_contact_payment` takes the entries a payment appends as +`&[PrivatePaymentEntry]` (each entry's commitment and the SHA-256 of its whole +bytes) and the sender's private store read position when it paid +(`store_position: Option`), and `PrivatePaymentRecord` struct literals +require `entry_hash` and `store_position`. A store keeps both with each journal +record. `FileBackedShieldedStore` writes journal records in format version 4 +and still reads version 3 records, which carry neither: such a record matches +an entry by its commitment and is read for from the store's start. + +Note reservations are owned by the spend attempt that took them: stores must +implement `mark_pending_by(id, nullifier, reservation)`, which reserves a note +for the attempt `reservation`, and `clear_pending_reserved_by(id, nullifier, +reservation)`, which releases it only while that same attempt still holds it, +returning whether it did. Keep the owner with each reservation and compare and +clear it under the store's own lock. Forwarding `clear_pending_reserved_by` to +the unconditional `clear_pending` defeats the protection it gives: a cleanup +that runs after a purge, a rebind or a wallet's replacement would release a +newer attempt's notes or delete its records. + +Anchored note reservations and saved records now keep the proved height of +the anchor set their anchor was read from: `set_pending_spend` takes an +`anchor_height: Option`, `StalePendingSpend` carries it as a fourth +element, `PendingRedrive` struct literals require `anchor_height`, and stores +must implement `note_anchor_recorded`, which gives that height to the +reservations and records of an anchor that carry none, durably for a record. +A store keeps a record's height with it, so a restart restores it. A note +spend's record, or a journal record, saved without a height (one saved before +heights were kept) keeps its height unknown. Its anchor is a root of a tree no +larger than the largest the store has held, so a store can implement +`legacy_anchor_tree_bound` to return that size; the default `None` keeps such +records held until a set is seen holding their anchor. `FileBackedShieldedStore` +keeps the size durably, raised at every open and before every +`reset_commitment_tree`, and reports the size held when it was opened. With a +bound, the sync fetches the pool's proved leaf count before the anchor set, +and such a record is released, or discharged, on a set lacking its anchor only +when that count, proved at or below the set's height, reaches the bound and +one past the position of every note spent on that anchor that the store +holds, the scan covers the set, and, for a journal record, the store read +through its end lacks its entry at that set's height (one hashing to the hash +the record keeps, or, for a record that keeps none, one starting with its +commitment). Otherwise it stays held. + The local shielded balance API introduces three Rust source compatibility changes: - Custom `ShieldedStore` implementations must implement @@ -146,6 +234,12 @@ The local shielded balance API introduces three Rust source compatibility change index is zero. An absent row is different from a recorded empty scan; do not infer presence merely from `last_synced_index > 0`. +## Shielded store lifetime migration + +`ShieldedStore` now requires `Send + Sync + 'static`: a spend dropped before it hands its reserved notes over releases them on a spawned task when the store is locked, and that task owns the store's `Arc`. This is a Rust source compatibility change, not a consensus one. + +A custom `ShieldedStore` that borrows from its embedding application (a `&'a` connection, configuration or buffer held in the store type) no longer satisfies the trait. Move the borrowed resource into the store, by value or behind an `Arc` (an `Arc>` or `Arc>` for one shared with the application), so the store type has no lifetime parameter. The in-repo [InMemoryShieldedStore](src/wallet/shielded/store.rs) and [FileBackedShieldedStore](src/wallet/shielded/file_store.rs) already own what they use and need no change. + ## Dependencies - `key-wallet`: Core wallet functionality diff --git a/packages/rs-platform-wallet/src/broadcast_outcome.rs b/packages/rs-platform-wallet/src/broadcast_outcome.rs index 82648b66799..96b840e8742 100644 --- a/packages/rs-platform-wallet/src/broadcast_outcome.rs +++ b/packages/rs-platform-wallet/src/broadcast_outcome.rs @@ -1,9 +1,16 @@ //! Classifying the outcome of a state-transition broadcast / result wait. //! -//! Shared by every Platform money-moving path that must keep "definitely -//! rejected, safe to retry" apart from "ambiguous, may have executed, do -//! not retry" (shielded spends, masternode credit withdrawals). The shapes -//! are SDK-transport facts, not operation-specific, so they live here +//! Shared by every Platform money-moving path that must keep "never left the +//! wallet, safe to retry" apart from "may have reached a node, may still +//! execute, do not retry". Shielded spends that consume notes, shields from +//! Platform addresses and masternode credit withdrawals broadcast through +//! [`broadcast_tracking_delivery`], which keeps every dispatch's outcome so an +//! earlier dispatch that may have been delivered is never hidden by a later +//! refusal: only a refusal before anything was sent reads as failed. The +//! shield from an identity keeps the SDK's own broadcast and reads its final +//! error with [`broadcast_was_refused`], which is no proof and only decides +//! whether it waits for a result: it reports unconfirmed either way. The +//! shapes are SDK-transport facts, not operation-specific, so they live here //! rather than behind the `shielded` feature. /// Whether an SDK error carries Platform's own consensus verdict on the @@ -21,7 +28,10 @@ /// transition Platform executed and rejected on its merits. /// /// Recurses through a `NoAvailableAddressesToRetry` envelope, mirroring -/// [`crate::error::as_address_invalid_nonce`]. +/// [`crate::error::as_address_invalid_nonce`], and not through the SDK's +/// unconfirmed-outcome envelope (`StateTransitionResultUnconfirmed`): a +/// verdict under it follows an attempt that may have been delivered, so it +/// shows no refusal. /// /// Only these prove the transition was evaluated and REJECTED. Everything /// else — transport errors, timeouts, `AlreadyExists` (which proves the @@ -37,35 +47,37 @@ pub(crate) fn carries_consensus_rejection(err: &dash_sdk::Error) -> bool { } } -/// Whether a failed `broadcast()` call DEFINITIVELY left the transition -/// out of every mempool, so any note reservations may be released and the -/// caller may rebuild and retry: +/// Whether the final error of a failed `broadcast()` call reads as a +/// refusal of the transition, rather than as a call that got no answer: /// /// - a consensus verdict ([`carries_consensus_rejection`]): CheckTx /// evaluated the transition and refused it; /// - a gRPC response whose status code is a server-side rejection or a -/// connection-establishment failure. `Unavailable` is the common shape -/// of a connect-refused/offline attempt — classifying it as definitive -/// keeps the no-network failure's notes immediately re-spendable -/// instead of stranding them until the next restart — and rejection -/// codes (`InvalidArgument`, `ResourceExhausted` = mempool full, …) are -/// verdicts that the tx was refused admission; +/// connection-establishment failure: `Unavailable` is the common shape +/// of a connect-refused/offline attempt, and rejection codes +/// (`InvalidArgument`, `ResourceExhausted` = mempool full, …) say the +/// transition was refused admission; /// - no usable DAPI addresses at all (nothing was ever sent). /// -/// `Unavailable` is NOT an absolute never-delivered guarantee: HTTP/2 -/// stream resets after the request bytes left can surface the same code, -/// and the dapi-client's cross-address retry only retains the LAST +/// This is NOT proof that the transition was left out of every mempool, +/// and it never authorizes a retry, or a release of what the transition +/// spends. An endpoint's answer is unauthenticated, and one that kept or +/// forwarded the signed transition can answer with any verdict. HTTP/2 +/// stream resets after the request bytes left can surface `Unavailable` +/// too, and the dapi-client's cross-address retry only retains the LAST /// transport error, so an earlier-attempt delivery can hide behind a -/// later attempt's `Unavailable`. Releasing the notes in that residual -/// window is still fund-safe — the authoritative no-reuse guarantee is -/// the on-chain nullifier set, so a re-selected note at worst wastes a -/// ~30 s proof on a nullifier-already-used rejection (see the -/// `finalize_pending` downgrade rationale in `unshield`); never fund -/// loss. The trade is deliberate: UX for the dominant offline case over -/// strict conservatism in a rare race. +/// later attempt's final error, whatever its code. A transition reported +/// failed while it may still execute invites a second one, so every path +/// whose retry signs a new transition classifies with +/// [`broadcast_tracking_delivery`] instead: shielded spends, shields from +/// Platform addresses (to the wallet's own notes or to a recipient's) and +/// masternode credit withdrawals. The one caller left here is the shield +/// from an identity, which holds a durable guard on the exact signed +/// transition: a refusal only makes it skip the result wait for a proven +/// read of the identity nonce, and it reports unconfirmed either way. /// -/// Everything else leaves the outcome unknown and the caller must fall -/// through to the result wait instead of failing: `AlreadyExists` proves +/// Everything else reads as no answer, and the caller falls through to the +/// result wait: `AlreadyExists` proves /// the tx IS in the mempool or on chain (a lost-ACK attempt was re-sent /// by the dapi-client retry and hit tenderdash's dedupe), and /// timeout/cancellation/no-response shapes (`TimeoutReached`, @@ -73,7 +85,8 @@ pub(crate) fn carries_consensus_rejection(err: &dash_sdk::Error) -> bool { /// `Internal`/`Unknown`/`Aborted`/`DataLoss`, which DAPI also uses for /// its own tenderdash-side failures that can postdate delivery) allow /// the request to have outlived its lost ACK. -pub(crate) fn broadcast_definitely_failed(e: &dash_sdk::Error) -> bool { +#[cfg(feature = "shielded")] +pub(crate) fn broadcast_was_refused(e: &dash_sdk::Error) -> bool { use dash_sdk::dapi_client::transport::TransportError; use dash_sdk::dapi_client::DapiClientError; use dash_sdk::dapi_grpc::tonic::Code; @@ -101,7 +114,706 @@ pub(crate) fn broadcast_definitely_failed(e: &dash_sdk::Error) -> bool { dash_sdk::Error::DapiClientError(DapiClientError::NoAvailableAddressesToRetry(t)) => { status_is_verdict(t) } - dash_sdk::Error::NoAvailableAddressesToRetry(inner) => broadcast_definitely_failed(inner), + dash_sdk::Error::NoAvailableAddressesToRetry(inner) => broadcast_was_refused(inner), _ => false, } } + +/// What the dispatches of one transition's broadcast proved about its +/// delivery ([`broadcast_tracking_delivery`]). +#[derive(Debug)] +pub(crate) enum BroadcastDelivery { + /// A node admitted the transition, or already held it (`AlreadyExists`). + Admitted, + /// No dispatch proved the transition was left out of every mempool: a + /// dispatch reached an endpoint, which may have kept or forwarded it, + /// whatever it answered (a consensus verdict included, which no proof + /// or quorum signature backs), or failed in a way that allows delivery. + /// It may execute, so the caller waits for its result, and an + /// unconfirmed outcome keeps what the transition spends held (a shielded + /// spend's notes stay reserved). + MaybeDelivered(dash_sdk::Error), + /// The transition never left the wallet: it was refused before its first + /// dispatch was sent, there being no address to send it to or the SDK + /// refusing it, with no dispatch sent before. Nothing holds its bytes but + /// the wallet, so it can never execute. + NeverDelivered(dash_sdk::Error), +} + +/// How many single dispatches [`broadcast_tracking_delivery`] makes at most +/// on `sdk`: its configured overall budget, one dispatch and its effective +/// retries, so a client configured with no retries dispatches once. +pub(crate) fn spend_broadcast_dispatches(sdk: &dash_sdk::Sdk) -> usize { + sdk.query_settings() + .request_settings + .finalize() + .retries + .saturating_add(1) +} + +/// Broadcast `state_transition` (a shielded spend, a shield from Platform +/// addresses, a masternode credit withdrawal) in single dispatches (no +/// SDK retry inside a dispatch), at most the SDK's configured budget +/// ([`spend_broadcast_dispatches`]), keeping what every dispatch proved: the +/// SDK's own retry loop returns only its last error, which cannot show that +/// an earlier attempt was delivered with its response lost. Centralizing that +/// evidence in the SDK is dashpay/platform#5556; what it means for a payment's +/// notes, journal and contact stays with its caller. +/// +/// Any dispatch that reached an endpoint, or failed in a way that allows it +/// (every transport error, whatever its gRPC code, a timeout, a cause-less +/// broadcast envelope, an unknown error), makes the whole broadcast +/// [`BroadcastDelivery::MaybeDelivered`]. So does a consensus verdict: an +/// endpoint's answer is unauthenticated, and one that kept or forwarded the +/// signed transition can answer with any verdict. Only a refusal before +/// anything was sent is [`BroadcastDelivery::NeverDelivered`]. +/// +/// A verdict ends the dispatches, with one exception +/// ([`is_address_nonce_ahead`]): a node that reads an input address's nonce +/// as ahead of its own state is behind the node the nonce was read from, so +/// the same signed bytes go to the next dispatch's node. The SDK's own +/// broadcast ends on every concrete refusal; these single dispatches go on +/// after this one, and they do not step off the answering node, so a later +/// dispatch can reach that node again and spend one of the budget's +/// dispatches on the same answer. The broadcast is maybe delivered either +/// way. +pub(crate) async fn broadcast_tracking_delivery( + sdk: &dash_sdk::Sdk, + state_transition: &dpp::state_transition::StateTransition, +) -> BroadcastDelivery { + use dash_sdk::dapi_client::RequestSettings; + use dash_sdk::platform::transition::broadcast::BroadcastStateTransition; + use dash_sdk::platform::transition::put_settings::PutSettings; + + let single_dispatch = PutSettings { + request_settings: RequestSettings { + retries: Some(0), + ..RequestSettings::default() + }, + ..PutSettings::default() + }; + track_delivery(state_transition, spend_broadcast_dispatches(sdk), || { + state_transition.broadcast(sdk, Some(single_dispatch)) + }) + .await +} + +/// The classification [`broadcast_tracking_delivery`] makes of +/// `state_transition`'s broadcast, over the outcomes `dispatch` returns, one +/// call per single dispatch, at most `dispatches` of them. +async fn track_delivery( + state_transition: &dpp::state_transition::StateTransition, + dispatches: usize, + mut dispatch: F, +) -> BroadcastDelivery +where + F: FnMut() -> Fut, + Fut: std::future::Future>, +{ + use dash_sdk::dapi_client::DapiClientError; + + let mut maybe_delivered: Option = None; + for _ in 0..dispatches.max(1) { + let error = match dispatch().await { + Ok(()) => return BroadcastDelivery::Admitted, + Err(error) if node_holds_transition(&error) => return BroadcastDelivery::Admitted, + Err(error) => error, + }; + // Refused before anything was sent: no address, or the SDK's own + // refusal of a kind the network does not serve yet. + let never_sent = matches!( + error, + dash_sdk::Error::DapiClientError(DapiClientError::NoAvailableAddresses) + | dash_sdk::Error::ProtocolVersionNotActive { .. } + ) || matches!( + &error, + dash_sdk::Error::NoAvailableAddressesToRetry(inner) + if matches!( + **inner, + dash_sdk::Error::DapiClientError(DapiClientError::NoAvailableAddresses) + ) + ); + if never_sent { + return match maybe_delivered { + Some(_) => BroadcastDelivery::MaybeDelivered(error), + None => BroadcastDelivery::NeverDelivered(error), + }; + } + // An endpoint's verdict ends the dispatches, and proves nothing. The + // verdict of a node that is behind does not end them: the same bytes + // go to the next dispatch's node. + if carries_consensus_rejection(&error) && !is_address_nonce_ahead(state_transition, &error) + { + return BroadcastDelivery::MaybeDelivered(error); + } + maybe_delivered = Some(error); + } + match maybe_delivered { + Some(error) => BroadcastDelivery::MaybeDelivered(error), + // Unreachable: every pass sets it or returns. + None => BroadcastDelivery::MaybeDelivered(dash_sdk::Error::Generic( + "no broadcast dispatch was made".to_string(), + )), + } +} + +/// Whether `error` says a node already holds the transition +/// (`AlreadyExists`): bare, or under the SDK's unconfirmed-outcome envelope +/// (`StateTransitionResultUnconfirmed`), which the SDK puts a duplicate +/// answer under as it may follow a delivery, or under its retry envelope. +fn node_holds_transition(error: &dash_sdk::Error) -> bool { + match error { + dash_sdk::Error::AlreadyExists(_) => true, + dash_sdk::Error::StateTransitionResultUnconfirmed(inner) + | dash_sdk::Error::NoAvailableAddressesToRetry(inner) => node_holds_transition(inner), + _ => false, + } +} + +/// Whether `error` is a node refusing `transition` because one of its input +/// addresses' nonces is ahead of what that node has: the answer of a node +/// that is behind the one the nonce was read from, which another node may +/// admit. A nonce the node already passed, one of an address the transition +/// does not spend from, or one other than the transition's, is not. +fn is_address_nonce_ahead( + transition: &dpp::state_transition::StateTransition, + error: &dash_sdk::Error, +) -> bool { + use dpp::consensus::state::state_error::StateError; + use dpp::consensus::ConsensusError; + + let dash_sdk::Error::Protocol(dpp::ProtocolError::ConsensusError(consensus)) = error else { + return false; + }; + matches!(consensus.as_ref(), + ConsensusError::StateError(StateError::AddressInvalidNonceError(nonce_error)) + if nonce_error.provided_nonce() > nonce_error.expected_nonce() + && transition.inputs().and_then(|inputs| inputs.get(nonce_error.address())) + .is_some_and(|(nonce, _)| *nonce == nonce_error.provided_nonce()) + ) +} + +/// Network SDKs for the tests of the flows that broadcast through +/// [`broadcast_tracking_delivery`]. +#[cfg(test)] +pub(crate) mod test_sdks { + use dash_sdk::dpp::dashcore::Network; + use dash_sdk::dpp::prelude::CoreBlockHeight; + use dash_sdk::error::ContextProviderError; + use dash_sdk::platform::ContextProvider; + use dash_sdk::sdk::AddressList; + use dpp::data_contract::{DataContract, TokenConfiguration}; + use dpp::prelude::Identifier; + use dpp::version::PlatformVersion; + use std::str::FromStr; + use std::sync::Arc; + + /// A context provider that knows no contract and no quorum key: the + /// tests' requests fail before a proof is verified. + struct NoKeys; + + impl ContextProvider for NoKeys { + fn get_data_contract( + &self, + _id: &Identifier, + _platform_version: &PlatformVersion, + ) -> Result>, ContextProviderError> { + Ok(None) + } + + fn get_token_configuration( + &self, + _token_id: &Identifier, + ) -> Result, ContextProviderError> { + Ok(None) + } + + fn get_quorum_public_key( + &self, + _quorum_type: u32, + _quorum_hash: [u8; 32], + _core_chain_locked_height: u32, + ) -> Result<[u8; 48], ContextProviderError> { + Err(ContextProviderError::Generic("no quorum keys".to_string())) + } + + fn get_platform_activation_height(&self) -> Result { + Ok(1) + } + } + + fn sdk(addresses: AddressList) -> dash_sdk::Sdk { + dash_sdk::SdkBuilder::new(addresses) + .with_network(Network::Testnet) + .with_version(PlatformVersion::latest()) + .with_context_provider(NoKeys) + .build() + .expect("a network SDK") + } + + /// A network SDK with no address to send to: every dispatch is refused + /// before anything is sent. + pub(crate) fn sdk_without_addresses() -> dash_sdk::Sdk { + sdk(AddressList::new()) + } + + /// A loopback port that refuses every connection for as long as this is + /// held: bound, so nothing else can take it, and never listened on. + pub(crate) struct RefusingPort { + _bound: tokio::net::TcpSocket, + } + + /// A network SDK whose only node refuses the connection, and the port + /// that does so while it is held: every dispatch fails in transport, the + /// way an offline attempt does. + pub(crate) fn sdk_refusing_connections() -> (dash_sdk::Sdk, RefusingPort) { + let bound = tokio::net::TcpSocket::new_v4().expect("a socket"); + bound + .bind(std::net::SocketAddr::from(([127, 0, 0, 1], 0))) + .expect("a loopback port"); + let address = bound.local_addr().expect("its address"); + ( + sdk(AddressList::from_str(&format!("http://{address}")).expect("an address")), + RefusingPort { _bound: bound }, + ) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use dash_sdk::dapi_client::transport::TransportError; + use dash_sdk::dapi_client::DapiClientError; + use dash_sdk::dapi_grpc::tonic::{Code, Status}; + use dpp::address_funds::PlatformAddress; + use dpp::consensus::state::address_funds::AddressInvalidNonceError; + use dpp::consensus::state::state_error::StateError; + use dpp::state_transition::address_funds_transfer_transition::v0::AddressFundsTransferTransitionV0; + use dpp::state_transition::identity_credit_withdrawal_transition::v1::IdentityCreditWithdrawalTransitionV1; + use dpp::state_transition::StateTransition; + use std::collections::BTreeMap; + use std::sync::Mutex; + + /// Another error of the same shape as `error`, which is not `Clone`. + fn copy(error: &dash_sdk::Error) -> dash_sdk::Error { + match error { + dash_sdk::Error::DapiClientError(DapiClientError::Transport(TransportError::Grpc( + status, + ))) => grpc(status.code()), + dash_sdk::Error::DapiClientError(DapiClientError::NoAvailableAddresses) => { + dash_sdk::Error::DapiClientError(DapiClientError::NoAvailableAddresses) + } + dash_sdk::Error::NoAvailableAddressesToRetry(inner) => { + dash_sdk::Error::NoAvailableAddressesToRetry(Box::new(copy(inner))) + } + dash_sdk::Error::Protocol(dpp::ProtocolError::ConsensusError(_)) => rejection(), + dash_sdk::Error::ProtocolVersionNotActive { + method, + required, + feature, + network, + pinned, + .. + } => dash_sdk::Error::ProtocolVersionNotActive { + method, + required: *required, + feature: *feature, + network: *network, + pinned: *pinned, + cause: None, + }, + other => dash_sdk::Error::Generic(other.to_string()), + } + } + + fn grpc(code: Code) -> dash_sdk::Error { + dash_sdk::Error::DapiClientError(DapiClientError::Transport(TransportError::Grpc( + Status::new(code, "test"), + ))) + } + + /// A consensus rejection, as DAPI attaches one to a refused broadcast. + fn rejection() -> dash_sdk::Error { + use dpp::consensus::basic::BasicError; + use dpp::consensus::basic::UnsupportedFeatureError; + dash_sdk::Error::Protocol(dpp::ProtocolError::ConsensusError(Box::new( + dpp::consensus::ConsensusError::BasicError(BasicError::UnsupportedFeatureError( + UnsupportedFeatureError::new("test".to_string(), 1), + )), + ))) + } + + /// What [`track_delivery`] makes of dispatches whose outcome `outcome` + /// gives by dispatch number, from 0, and how many dispatches it made: + /// of a transition with no address input, which no node can be behind on. + async fn tracked( + outcome: impl Fn(usize) -> Result<(), dash_sdk::Error>, + ) -> (BroadcastDelivery, usize) { + tracked_for(&withdrawal(), outcome).await + } + + /// [`tracked`], of `transition`. + async fn tracked_for( + transition: &StateTransition, + outcome: impl Fn(usize) -> Result<(), dash_sdk::Error>, + ) -> (BroadcastDelivery, usize) { + let dispatched = Mutex::new(0usize); + let delivery = track_delivery(transition, BUDGET, || { + let mut count = dispatched.lock().expect("count"); + let result = outcome(*count); + *count += 1; + std::future::ready(result) + }) + .await; + let dispatched = *dispatched.lock().expect("count"); + (delivery, dispatched) + } + + /// An identity credit withdrawal, which is broadcast in every build and + /// spends from no Platform address. + fn withdrawal() -> StateTransition { + IdentityCreditWithdrawalTransitionV1 { + amount: 1_000_000, + nonce: 1, + ..Default::default() + } + .into() + } + + /// The Platform address [`address_spend`] spends from, and the nonce it + /// signed. + const SPENT_FROM: PlatformAddress = PlatformAddress::P2pkh([7; 20]); + const SIGNED_NONCE: u32 = 5; + + /// A transition that spends from a Platform address, as a shield does. + fn address_spend() -> StateTransition { + AddressFundsTransferTransitionV0 { + inputs: BTreeMap::from([(SPENT_FROM, (SIGNED_NONCE, 2_000_000))]), + ..Default::default() + } + .into() + } + + /// A node's verdict that `SPENT_FROM` was spent with `SIGNED_NONCE` where + /// the node expects `expected`. + fn nonce_verdict(expected: u32) -> dash_sdk::Error { + dash_sdk::Error::Protocol(dpp::ProtocolError::ConsensusError(Box::new( + dpp::consensus::ConsensusError::StateError(StateError::AddressInvalidNonceError( + AddressInvalidNonceError::new(SPENT_FROM, SIGNED_NONCE, expected), + )), + ))) + } + + /// The dispatch budget the tests run with. + const BUDGET: usize = 6; + + /// An endpoint that kept or forwarded the transition can answer the + /// first dispatch with a consensus verdict, as serialized metadata the + /// SDK decodes with no proof behind it: the broadcast stays maybe + /// delivered, so its payment stays unconfirmed with its notes, journal + /// record and contact hold, and the dispatches end there. + #[tokio::test] + async fn should_keep_a_broadcast_an_endpoint_refused_maybe_delivered() { + use dash_sdk::dapi_grpc::tonic::metadata::{MetadataMap, MetadataValue}; + use dpp::serialization::PlatformSerializableWithPlatformVersion; + use dpp::version::PlatformVersion; + + let verdict = || { + let bytes = dpp::consensus::ConsensusError::BasicError( + dpp::consensus::basic::BasicError::UnsupportedFeatureError( + dpp::consensus::basic::UnsupportedFeatureError::new("test".to_string(), 1), + ), + ) + .serialize_to_bytes_with_platform_version(PlatformVersion::latest()) + .expect("serialized"); + let mut metadata = MetadataMap::new(); + metadata.insert_bin( + "dash-serialized-consensus-error-bin", + MetadataValue::from_bytes(&bytes), + ); + dash_sdk::Error::from(DapiClientError::Transport(TransportError::Grpc( + Status::with_metadata(Code::InvalidArgument, "rejected", metadata), + ))) + }; + assert!(carries_consensus_rejection(&verdict()), "{:?}", verdict()); + let (delivery, dispatched) = tracked(|_| Err(verdict())).await; + assert!( + matches!(delivery, BroadcastDelivery::MaybeDelivered(_)), + "{delivery:?}" + ); + assert_eq!(dispatched, 1); + } + + /// The tracker keeps the SDK's configured budget: a client configured + /// with no retries dispatches once, one with three retries four times. + #[tokio::test] + async fn should_keep_the_sdk_s_configured_retry_budget() { + use dash_sdk::dapi_client::RequestSettings; + + let no_retries = dash_sdk::SdkBuilder::new_mock() + .with_settings(RequestSettings { + retries: Some(0), + ..RequestSettings::default() + }) + .build() + .expect("an SDK"); + assert_eq!(spend_broadcast_dispatches(&no_retries), 1); + let three_retries = dash_sdk::SdkBuilder::new_mock() + .with_settings(RequestSettings { + retries: Some(3), + ..RequestSettings::default() + }) + .build() + .expect("an SDK"); + assert_eq!(spend_broadcast_dispatches(&three_retries), 4); + + let dispatched = Mutex::new(0usize); + let delivery = track_delivery( + &withdrawal(), + spend_broadcast_dispatches(&no_retries), + || { + *dispatched.lock().expect("count") += 1; + std::future::ready(Err(grpc(Code::Unavailable))) + }, + ) + .await; + assert!(matches!(delivery, BroadcastDelivery::MaybeDelivered(_))); + assert_eq!(*dispatched.lock().expect("count"), 1); + } + + /// An attempt admitted with its response lost, then retries refused for + /// any reason, leaves the broadcast maybe delivered: the last error + /// alone cannot show the transition never left. + #[tokio::test] + async fn should_keep_an_earlier_ambiguous_dispatch_over_later_refusals() { + for lost in [Code::Unavailable, Code::DeadlineExceeded] { + for refusal in [ + grpc(Code::ResourceExhausted), + grpc(Code::Unimplemented), + grpc(Code::InvalidArgument), + rejection(), + ] { + let refusal = &refusal; + let (delivery, _) = tracked(|dispatch| match dispatch { + 0 => Err(grpc(lost)), + _ => Err(copy(refusal)), + }) + .await; + assert!( + matches!(delivery, BroadcastDelivery::MaybeDelivered(_)), + "{lost:?} then a refusal: {delivery:?}" + ); + } + } + } + + /// Every transport-level failure may have delivered the transition, + /// whatever its code, so a broadcast that only ever fails so is maybe + /// delivered after the whole budget. + #[tokio::test] + async fn should_treat_every_transport_failure_as_maybe_delivered() { + for code in [ + Code::Unavailable, + Code::ResourceExhausted, + Code::Unimplemented, + Code::InvalidArgument, + Code::Internal, + ] { + let (delivery, dispatched) = tracked(|_| Err(grpc(code))).await; + assert!( + matches!(delivery, BroadcastDelivery::MaybeDelivered(_)), + "{code:?}: {delivery:?}" + ); + assert_eq!(dispatched, BUDGET, "{code:?}"); + } + } + + /// Only a refusal before anything was sent, nowhere to send the + /// transition or the SDK refusing it, with no dispatch sent before, + /// shows it never left. + #[tokio::test] + async fn should_count_a_broadcast_never_delivered_only_without_an_earlier_ambiguity() { + for first in [ + dash_sdk::Error::ProtocolVersionNotActive { + method: "broadcast_state_transition", + required: 15, + feature: None, + network: 14, + pinned: false, + cause: None, + }, + dash_sdk::Error::DapiClientError(DapiClientError::NoAvailableAddresses), + dash_sdk::Error::NoAvailableAddressesToRetry(Box::new( + dash_sdk::Error::DapiClientError(DapiClientError::NoAvailableAddresses), + )), + ] { + let first = &first; + let (delivery, dispatched) = tracked(|_| Err(copy(first))).await; + assert!( + matches!(delivery, BroadcastDelivery::NeverDelivered(_)), + "{delivery:?}" + ); + assert_eq!(dispatched, 1); + } + } + + /// The broadcast of a signed transition through a network SDK: with no + /// address to send it to it never left, and a node that refuses the + /// connection leaves it maybe delivered, as a transport failure cannot + /// show nothing was sent. Here an identity credit withdrawal, which is + /// broadcast in every build. + #[tokio::test] + async fn should_track_the_delivery_of_a_broadcast_through_a_network_sdk() { + let transition = withdrawal(); + + let delivery = + broadcast_tracking_delivery(&test_sdks::sdk_without_addresses(), &transition).await; + assert!( + matches!(delivery, BroadcastDelivery::NeverDelivered(_)), + "{delivery:?}" + ); + let (refusing, _port) = test_sdks::sdk_refusing_connections(); + let delivery = broadcast_tracking_delivery(&refusing, &transition).await; + assert!( + matches!(delivery, BroadcastDelivery::MaybeDelivered(_)), + "{delivery:?}" + ); + } + + /// A node that reads an input address's nonce as ahead of its own state + /// is behind the node the nonce was read from: the same signed + /// transition goes to the next dispatch's node, as the SDK's own + /// broadcast sends it, and a node that admits it ends the dispatches. + #[tokio::test] + async fn should_send_a_transition_a_node_is_behind_on_to_another_node() { + let behind = SIGNED_NONCE - 1; + let (delivery, dispatched) = tracked_for(&address_spend(), |dispatch| match dispatch { + 0 | 1 => Err(nonce_verdict(behind)), + _ => Ok(()), + }) + .await; + assert!( + matches!(delivery, BroadcastDelivery::Admitted), + "{delivery:?}" + ); + assert_eq!(dispatched, 3); + + // Every node behind: the budget ends the dispatches, and the + // transition stays maybe delivered, as every node that answered holds + // its bytes. + let (delivery, dispatched) = + tracked_for(&address_spend(), |_| Err(nonce_verdict(behind))).await; + assert!( + matches!(delivery, BroadcastDelivery::MaybeDelivered(_)), + "{delivery:?}" + ); + assert_eq!(dispatched, BUDGET); + } + + /// Every other verdict ends the dispatches: a nonce the node has already + /// passed, a nonce of an address the transition does not spend from, and + /// the same verdict on a transition that spends from no address. + #[tokio::test] + async fn should_end_the_dispatches_on_a_verdict_no_other_node_changes() { + let (delivery, dispatched) = + tracked_for(&address_spend(), |_| Err(nonce_verdict(SIGNED_NONCE + 1))).await; + assert!( + matches!(delivery, BroadcastDelivery::MaybeDelivered(_)), + "a nonce the node has passed: {delivery:?}" + ); + assert_eq!(dispatched, 1); + + let another_address = || { + dash_sdk::Error::Protocol(dpp::ProtocolError::ConsensusError(Box::new( + dpp::consensus::ConsensusError::StateError(StateError::AddressInvalidNonceError( + AddressInvalidNonceError::new( + PlatformAddress::P2pkh([8; 20]), + SIGNED_NONCE, + SIGNED_NONCE - 1, + ), + )), + ))) + }; + let (delivery, dispatched) = + tracked_for(&address_spend(), |_| Err(another_address())).await; + assert!( + matches!(delivery, BroadcastDelivery::MaybeDelivered(_)), + "another address: {delivery:?}" + ); + assert_eq!(dispatched, 1); + + let (delivery, dispatched) = tracked(|_| Err(nonce_verdict(SIGNED_NONCE - 1))).await; + assert!( + matches!(delivery, BroadcastDelivery::MaybeDelivered(_)), + "no address input: {delivery:?}" + ); + assert_eq!(dispatched, 1); + } + + /// The SDK puts a dispatch that may have been delivered under its + /// unconfirmed-outcome envelope (`StateTransitionResultUnconfirmed`): it + /// is maybe delivered whatever it wraps, never a refusal before anything + /// was sent, and does not end the dispatches as a verdict would; a node + /// that holds the transition under it is admitted. + #[tokio::test] + async fn should_read_the_sdk_s_unconfirmed_outcome_as_maybe_delivered() { + let unconfirmed = |inner: dash_sdk::Error| { + dash_sdk::Error::StateTransitionResultUnconfirmed(Box::new(inner)) + }; + for inner in [ + grpc(Code::Unavailable), + dash_sdk::Error::DapiClientError(DapiClientError::NoAvailableAddresses), + rejection(), + ] { + let inner = &inner; + let (delivery, dispatched) = tracked(|_| Err(unconfirmed(copy(inner)))).await; + assert!( + matches!(delivery, BroadcastDelivery::MaybeDelivered(_)), + "{inner:?}: {delivery:?}" + ); + assert_eq!(dispatched, BUDGET, "{inner:?}"); + } + let (delivery, dispatched) = tracked(|_| { + Err(unconfirmed(dash_sdk::Error::AlreadyExists( + "state transition already in mempool".to_string(), + ))) + }) + .await; + assert!( + matches!(delivery, BroadcastDelivery::Admitted), + "{delivery:?}" + ); + assert_eq!(dispatched, 1); + #[cfg(feature = "shielded")] + { + assert!(!broadcast_was_refused(&unconfirmed(rejection()))); + assert!(!broadcast_was_refused(&unconfirmed(grpc( + Code::InvalidArgument + )))); + } + } + + /// A dispatch a node admitted, or already holds, is admitted, after any + /// number of failed ones. + #[tokio::test] + async fn should_count_an_admitted_or_known_dispatch_as_admitted() { + let (delivery, _) = tracked(|dispatch| match dispatch { + 0 => Err(grpc(Code::Unavailable)), + _ => Ok(()), + }) + .await; + assert!( + matches!(delivery, BroadcastDelivery::Admitted), + "{delivery:?}" + ); + let (delivery, _) = tracked(|dispatch| match dispatch { + 0 => Err(grpc(Code::DeadlineExceeded)), + _ => Err(dash_sdk::Error::AlreadyExists("in the mempool".to_string())), + }) + .await; + assert!( + matches!(delivery, BroadcastDelivery::Admitted), + "{delivery:?}" + ); + } +} diff --git a/packages/rs-platform-wallet/src/changeset/changeset.rs b/packages/rs-platform-wallet/src/changeset/changeset.rs index 0611158faf1..23d416973a3 100644 --- a/packages/rs-platform-wallet/src/changeset/changeset.rs +++ b/packages/rs-platform-wallet/src/changeset/changeset.rs @@ -1298,9 +1298,11 @@ pub struct ReceivedContactRequestKey { /// (a `sent_requests` insert clears a prior `removed_sent`, an un-ignore /// clears a prior ignore, and vice versa), keeping the two sets /// disjoint. This covers `sent_requests` vs `removed_sent`, -/// `incoming_requests` vs `removed_incoming`, and `ignored` vs -/// `unignored`. `established` has no opposing tombstone set and rides -/// plain last-write-wins. +/// `incoming_requests` vs `removed_incoming`, `ignored` vs +/// `unignored`, and `private_shielded_addresses` vs +/// `removed_private_shielded_addresses`. `established` and +/// `private_contact_requests_positions` have no opposing tombstone set +/// and ride plain last-write-wins. #[derive(Debug, Clone, Default, PartialEq)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct ContactChangeSet { @@ -1330,6 +1332,66 @@ pub struct ContactChangeSet { /// sweep. Kept as a separate set (rather than a shrinking `ignored` /// snapshot) so the changeset's insert-XOR-tombstone discipline holds. pub unignored: BTreeSet<(Identifier, Identifier)>, + /// The position of DashPay's private contact request store each owner + /// identity reads from next, keyed by owner, with the fingerprint of the + /// scanning keys it holds for: every entry before it was read with those + /// keys and what it held for the owner stored. Written only for a backend + /// attesting + /// [`PRIVATE_CONTACT_REQUEST_SCAN_STATE`](crate::changeset::PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE), + /// and only after the stores of what the entries before it held, so a + /// restored position never covers a request that did not reach disk. A + /// rewind (un-ignoring a sender, or the scanning keys changing) writes + /// the lower position. Last write wins. + #[cfg_attr(feature = "serde", serde(default))] + pub private_contact_requests_positions: BTreeMap, + /// The Orchard address each contact's tracked private request to the + /// owner carries, keyed by `(owner, contact)`: 43 bytes, an 11-byte + /// diversifier and a 32-byte transmission key. Written only for a + /// backend attesting + /// [`PRIVATE_CONTACT_REQUEST_SCAN_STATE`](crate::changeset::PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE). + /// Reconciled last-write-wins against + /// [`Self::removed_private_shielded_addresses`] on merge. + #[cfg_attr( + feature = "serde", + serde( + default, + with = "crate::changeset::serde_adapters::private_shielded_addresses" + ) + )] + pub private_shielded_addresses: BTreeMap<(Identifier, Identifier), [u8; 43]>, + /// `(owner, contact)` pairs whose tracked private request carries no + /// shielded address any more: the removal tombstone for + /// [`Self::private_shielded_addresses`]. + #[cfg_attr(feature = "serde", serde(default))] + pub removed_private_shielded_addresses: BTreeSet<(Identifier, Identifier)>, +} + +/// Where an identity reads DashPay's private contact request store from +/// next, and the scanning keys that position holds for. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +pub struct PrivateContactRequestsPosition { + /// The store position read from next. + pub position: u64, + /// SHA-256 over the identity's HD index and each `ECDSA_SECP256K1` + /// `ENCRYPTION` or `DECRYPTION` key (id, purpose and data, in key id + /// order) the entries before `position` were scanned with + /// (`ManagedIdentity::private_scan_key_fingerprint`). A loaded position + /// whose fingerprint is not the identity's is read again from 0. + pub key_fingerprint: [u8; 32], + /// Whether a private contact request this identity paid for may still be + /// unresolved: written set before such a payment may reach the network, + /// and cleared once the identity holds no private request it is paying + /// for or has not read back (each read back, definitively rejected, or + /// released before it was broadcast). Loaded set, it holds the identity's + /// public contact requests, sent or accepted, in every build, until a + /// restoration from the shielded store restores the reservations it + /// stands for (`PlatformWallet::restore_private_contact_payments`). A + /// build without the `shielded` feature never restores them, so it keeps + /// the identity held: its private payment may still execute, and a + /// public request would publish the pair the private one kept off chain. + #[cfg_attr(feature = "serde", serde(default))] + pub private_payments_unresolved: bool, } impl Merge for ContactChangeSet { @@ -1370,6 +1432,20 @@ impl Merge for ContactChangeSet { } self.ignored.extend(other.ignored); self.unignored.extend(other.unignored); + + self.private_contact_requests_positions + .extend(other.private_contact_requests_positions); + + for key in other.removed_private_shielded_addresses.iter() { + self.private_shielded_addresses.remove(key); + } + for key in other.private_shielded_addresses.keys() { + self.removed_private_shielded_addresses.remove(key); + } + self.private_shielded_addresses + .extend(other.private_shielded_addresses); + self.removed_private_shielded_addresses + .extend(other.removed_private_shielded_addresses); } fn is_empty(&self) -> bool { @@ -1380,6 +1456,9 @@ impl Merge for ContactChangeSet { && self.established.is_empty() && self.ignored.is_empty() && self.unignored.is_empty() + && self.private_contact_requests_positions.is_empty() + && self.private_shielded_addresses.is_empty() + && self.removed_private_shielded_addresses.is_empty() } } diff --git a/packages/rs-platform-wallet/src/changeset/client_start_state.rs b/packages/rs-platform-wallet/src/changeset/client_start_state.rs index c63e5a262be..c109e4bba3e 100644 --- a/packages/rs-platform-wallet/src/changeset/client_start_state.rs +++ b/packages/rs-platform-wallet/src/changeset/client_start_state.rs @@ -9,6 +9,9 @@ use std::collections::BTreeMap; +use dpp::prelude::Identifier; + +use crate::changeset::changeset::PrivateContactRequestsPosition; use crate::changeset::client_wallet_start_state::ClientWalletStartState; use crate::changeset::platform_address_sync_start_state::PlatformAddressSyncStartState; #[cfg(feature = "shielded")] @@ -38,11 +41,29 @@ pub struct ClientStartState { /// balance reads work without re-decrypting the chain. #[cfg(feature = "shielded")] pub shielded: ShieldedSyncStartState, + /// The private contact request scan state records + /// (`ContactChangeSet::private_contact_requests_positions`) the backend + /// kept for wallets it does not return in [`Self::wallets`], keyed by + /// wallet id, then owner identity: those of a removed wallet whose + /// marker (`PrivateContactRequestsPosition::private_payments_unresolved`) + /// is set. A backend that removes a wallet keeps each such record until a + /// record stored cleared for that wallet and owner replaces it, as a + /// private payment it stands for may still execute. + /// + /// Only the marker is used: an identity added to a wallet registered or + /// loaded under that id is held, as one loaded with its record marked is, + /// in every build (`PlatformWalletError::PrivateContactPaymentsNotRestored`). + /// The read position is not, as the requests read before it went with the + /// wallet's other rows. + pub retained_private_contact_scan_states: + BTreeMap>, } impl ClientStartState { pub fn is_empty(&self) -> bool { - let core_empty = self.platform_addresses.is_empty() && self.wallets.is_empty(); + let core_empty = self.platform_addresses.is_empty() + && self.wallets.is_empty() + && self.retained_private_contact_scan_states.is_empty(); #[cfg(feature = "shielded")] { core_empty && self.shielded.is_empty() diff --git a/packages/rs-platform-wallet/src/changeset/identity_manager_start_state.rs b/packages/rs-platform-wallet/src/changeset/identity_manager_start_state.rs index a4072b61848..f4f993c3463 100644 --- a/packages/rs-platform-wallet/src/changeset/identity_manager_start_state.rs +++ b/packages/rs-platform-wallet/src/changeset/identity_manager_start_state.rs @@ -37,3 +37,23 @@ pub struct IdentityManagerStartState { /// forces a rescan. See [`IdentityScanStateEntry`]. pub scan_states: BTreeMap, } + +impl IdentityManagerStartState { + /// Drop the private contact request scan state every restored identity + /// carries (its read position and its contacts' shielded addresses), as a + /// load does for a backend that does not attest + /// [`PRIVATE_CONTACT_REQUEST_SCAN_STATE`](crate::changeset::PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE): + /// nothing keeps such a backend's copy current, so the store is read from + /// its start. A restored hold on an unresolved private payment is kept + /// (`ManagedIdentity::forget_private_contact_scan_state`). + pub(crate) fn forget_private_contact_scan_state(&mut self) { + for managed in self + .wallet_identities + .values_mut() + .flat_map(BTreeMap::values_mut) + .chain(self.out_of_wallet_identities.values_mut()) + { + managed.forget_private_contact_scan_state(); + } + } +} diff --git a/packages/rs-platform-wallet/src/changeset/mod.rs b/packages/rs-platform-wallet/src/changeset/mod.rs index 612d81bccaf..266d2d6e2c8 100644 --- a/packages/rs-platform-wallet/src/changeset/mod.rs +++ b/packages/rs-platform-wallet/src/changeset/mod.rs @@ -40,10 +40,10 @@ pub use changeset::{ IdentityKeysChangeSet, InvitationChangeSet, InvitationEntry, InvitationStatus, KeyDerivationBreadcrumb, KeyWithBreadcrumb, PendingContactCrypto, PendingContactCryptoKey, PendingContactCryptoKind, PendingContactCryptoOp, PlatformAddressBalanceEntry, - PlatformAddressChangeSet, PlatformWalletChangeSet, ProviderKeyAccountEntry, - ProviderKeyExtendedPubKey, ProviderPlatformNodePubKey, ReceivedContactRequestKey, - SentContactRequestKey, ShieldedRecipientRaw, TokenBalanceChangeSet, WalletMetadataEntry, - SHIELDED_RECIPIENT_SIZE, + PlatformAddressChangeSet, PlatformWalletChangeSet, PrivateContactRequestsPosition, + ProviderKeyAccountEntry, ProviderKeyExtendedPubKey, ProviderPlatformNodePubKey, + ReceivedContactRequestKey, SentContactRequestKey, ShieldedRecipientRaw, TokenBalanceChangeSet, + WalletMetadataEntry, SHIELDED_RECIPIENT_SIZE, }; pub use client_start_state::ClientStartState; pub use client_wallet_start_state::ClientWalletStartState; diff --git a/packages/rs-platform-wallet/src/changeset/persistence_capabilities.rs b/packages/rs-platform-wallet/src/changeset/persistence_capabilities.rs index afa30546b9a..55c549c015b 100644 --- a/packages/rs-platform-wallet/src/changeset/persistence_capabilities.rs +++ b/packages/rs-platform-wallet/src/changeset/persistence_capabilities.rs @@ -118,13 +118,45 @@ impl PersistenceCapabilities { /// (the pre-recipient behaviour). pub const ASSET_LOCK_SHIELDED_RECIPIENTS: Self = Self(1 << 14); + /// The private contact request sync's scan state round-trips: each + /// identity's read position in DashPay's private contact request store + /// (`ContactChangeSet::private_contact_requests_positions`) and each + /// private contact's shielded address + /// (`ContactChangeSet::private_shielded_addresses`, with its removals) + /// are stored, and loading restores them onto each `ManagedIdentity` + /// (`ManagedIdentity::apply_private_contact_requests_position`, + /// `ManagedIdentity::apply_private_shielded_address`), so a relaunch + /// reads the store from where it stopped. Without this bit nothing of + /// it is written, a restored value is dropped, and each launch reads the + /// store from its start. + /// + /// Honoured only together with [`Self::ATOMIC_CHANGESETS`] + /// ([`Self::PRIVATE_CONTACT_SCAN_STATE_RESTART`]): the scan state is written + /// in changesets that must commit whole, so a backend declaring this bit + /// alone is treated as keeping none of it. + /// + /// A backend declaring it keeps a position record whose + /// `private_payments_unresolved` is set when it removes the record's + /// wallet or purges that wallet's rows, until a record stored cleared for + /// the same wallet and owner replaces it, and returns such records for a + /// wallet it no longer holds in + /// `ClientStartState::retained_private_contact_scan_states`. The marker + /// stands for a private payment that may still execute: a wallet + /// registered again under the id holds the identity it names, in every + /// build, until a restoration from the shielded store's journal shows the + /// payment resolved. The wallet itself never asks for a marked record to + /// be deleted: `PlatformWalletManager::remove_wallet` stores nothing, and + /// `IdentityManager::remove_identity` refuses while the identity's record + /// is marked. + pub const PRIVATE_CONTACT_REQUEST_SCAN_STATE: Self = Self(1 << 15); + /// Index of the highest bit declared above. It lives here, beside the /// constants, so adding a bit and bumping this is one edit in one place /// — and `every_declared_bit_has_a_stable_name` walks up to it, so a new /// bit that never reaches `KNOWN` fails a test instead of gating /// behaviour invisibly. The same test asserts nothing above it is named, /// which is what catches a bit added without bumping this. - const HIGHEST_DECLARED_BIT: u32 = 14; + const HIGHEST_DECLARED_BIT: u32 = 15; /// Capabilities required before exporting and funding an invitation voucher. pub const INVITATION_CREATION: Self = Self( @@ -138,6 +170,16 @@ impl PersistenceCapabilities { pub const SHIELDED_FVK_RESTART: Self = Self(Self::ATOMIC_CHANGESETS.0 | Self::SHIELDED_VIEWING_KEYS.0); + /// Capabilities required for the private contact request scan state to + /// round-trip, and so for a private contact request to be paid for: the + /// state itself, and atomic changesets. An un-ignore stores the sender's + /// removal and the read-position rewind it brings in one changeset; a + /// backend committing the removal without the rewind would, after a + /// restart, read on past the requests passed over while the sender was + /// ignored, and nothing would read them again. + pub const PRIVATE_CONTACT_SCAN_STATE_RESTART: Self = + Self(Self::ATOMIC_CHANGESETS.0 | Self::PRIVATE_CONTACT_REQUEST_SCAN_STATE.0); + /// Capabilities required to durably reconcile an asset-lock status and /// restore that exact row after process restart. pub const ASSET_LOCK_RECONCILIATION: Self = @@ -232,6 +274,10 @@ impl PersistenceCapabilities { PersistenceCapabilities::ASSET_LOCK_SHIELDED_RECIPIENTS, "asset_lock_shielded_recipients", ), + ( + PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE, + "private_contact_request_scan_state", + ), ]; KNOWN @@ -249,7 +295,7 @@ impl PersistenceCapabilities { /// failure the test exists to catch. Written as a module-level `const _` so /// it is evaluated in every build, test or not. const _: () = assert!( - PersistenceCapabilities::ASSET_LOCK_SHIELDED_RECIPIENTS.bits() + PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE.bits() == 1u64 << PersistenceCapabilities::HIGHEST_DECLARED_BIT, "HIGHEST_DECLARED_BIT must name the highest declared capability bit" ); @@ -285,6 +331,10 @@ mod tests { PersistenceCapabilities::ASSET_LOCK_SHIELDED_RECIPIENTS.bits(), 0x4000 ); + assert_eq!( + PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE.bits(), + 0x8000 + ); assert_eq!(PersistenceCapabilities::WALLET_DRAIN.bits(), 0x2285); assert_eq!( PersistenceCapabilities::ASSET_LOCK_RECONCILIATION.bits(), diff --git a/packages/rs-platform-wallet/src/changeset/serde_adapters.rs b/packages/rs-platform-wallet/src/changeset/serde_adapters.rs index d4deed2a0a9..3758c5eb30a 100644 --- a/packages/rs-platform-wallet/src/changeset/serde_adapters.rs +++ b/packages/rs-platform-wallet/src/changeset/serde_adapters.rs @@ -11,6 +11,44 @@ use dpp::prelude::AddressNonce; use key_wallet::wallet::managed_wallet_info::asset_lock_builder::AssetLockFundingType; use serde::{Deserialize, Deserializer, Serialize, Serializer}; +/// Adapter for the private shielded addresses of a contact changeset: +/// serde derives no 43-byte array, so each `(owner, contact)` address rides +/// as an `(owner, contact, bytes)` row, its length checked on the way back. +pub mod private_shielded_addresses { + use super::*; + use dpp::prelude::Identifier; + use serde::de::Error as _; + use std::collections::BTreeMap; + + type Addresses = BTreeMap<(Identifier, Identifier), [u8; 43]>; + + pub fn serialize( + addresses: &Addresses, + serializer: S, + ) -> Result { + serializer.collect_seq( + addresses + .iter() + .map(|((owner, contact), address)| (owner, contact, address.as_slice())), + ) + } + + pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result { + Vec::<(Identifier, Identifier, Vec)>::deserialize(deserializer)? + .into_iter() + .map(|(owner, contact, address)| { + let address: [u8; 43] = address.as_slice().try_into().map_err(|_| { + D::Error::custom(format!( + "a private shielded address is 43 bytes, not {}", + address.len() + )) + })?; + Ok(((owner, contact), address)) + }) + .collect() + } +} + /// Adapter for `AssetLockFundingType` (upstream has no serde derive). /// /// Encodes each variant as a stable u8 tag — same tag space the diff --git a/packages/rs-platform-wallet/src/changeset/traits.rs b/packages/rs-platform-wallet/src/changeset/traits.rs index 11e5d2c58a7..326820934c4 100644 --- a/packages/rs-platform-wallet/src/changeset/traits.rs +++ b/packages/rs-platform-wallet/src/changeset/traits.rs @@ -444,7 +444,12 @@ pub trait PlatformWalletPersistence: Send + Sync { /// Called once at startup — this is a whole-client operation, not a /// per-wallet one, because `ClientStartState::platform_addresses` is /// already keyed by wallet id and the sub-changesets carry their own - /// wallet attribution where needed. + /// wallet attribution where needed. A registration reads it too, for the + /// wallet it registers: the cursors and backfill record of a wallet the + /// backend already holds, and the private contact request scan state + /// records it kept marked for that id + /// (`ClientStartState::retained_private_contact_scan_states`, see + /// [`PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE`]). fn load(&self) -> Result; /// Look up a single core transaction record by `txid` for `wallet_id`. diff --git a/packages/rs-platform-wallet/src/error.rs b/packages/rs-platform-wallet/src/error.rs index e10e2049621..f9ed4a5b60f 100644 --- a/packages/rs-platform-wallet/src/error.rs +++ b/packages/rs-platform-wallet/src/error.rs @@ -678,6 +678,98 @@ pub enum PlatformWalletError { #[error("SDK error: {0}")] Sdk(#[from] dash_sdk::Error), + /// The contact requests with this identity came or went privately + /// (protocol version 15): a `contactRequest` document to it, in reply or + /// as a rotation, would publish the relationship, so it is sent privately. + #[error( + "the contact requests with {0} came or went privately; reply to or rotate with it privately" + )] + PrivateContactRequestNeedsPrivateReply(Identifier), + + /// A private contact request to this identity is being paid for, or was + /// paid for and is not yet read back from DashPay's store, or a private + /// payment the shielded store's journal keeps unresolved holds the pair: + /// no other one is sent, privately or publicly, until the private sync + /// reads it back or its payment provably never executes, as the store + /// keeps every entry appended. Pending, not failed: it is not submitted + /// again. + #[error( + "a private contact request to {0} is in flight or not yet read back from the store; sync \ + private contact requests to settle it" + )] + PrivateContactRequestPending(Identifier), + + /// A public contact request to this identity was broadcast and may have + /// been delivered, and no proof settled its outcome yet: the wallet keeps + /// its signed transition and sends no other contact request to the + /// identity, public or private, until a proved read shows the request on + /// Platform (it is then recorded as sent) or shows the transition can no + /// longer write it. A public contact request sync settles it, broadcasting + /// the same transition again while it may still execute. Unconfirmed, not + /// failed: it is not submitted again. + #[error( + "a public contact request to {0} was broadcast and its outcome is not proved yet; sync \ + contact requests to settle it" + )] + PublicContactRequestUnconfirmed(Identifier), + + /// DashPay's private contact request store was not read to its end for + /// this identity with the keys Platform proves it holds, before a contact + /// request from it, public or private, or an acceptance, was decided: a + /// request in the store unread could hold the pair. Nothing was reserved, + /// sealed, paid or broadcast. Calling again goes on with the read from + /// where it stopped (a node behind the store already seen, or keys that + /// kept changing, stop it). + #[error( + "DashPay's private contact request store was not read to its end for {0}; nothing was \ + sent, and trying again continues the read" + )] + PrivateContactStoreNotRead(Identifier), + + /// The wallet's private contact request payments from an earlier process + /// or wallet generation may hold pairs no reservation shows yet, which + /// only a restoration from the shielded store's journal shows: in a build + /// with the `shielded` feature, the wallet was published with no shielded + /// store configured while its persister keeps the private scan state, it + /// bound a shielded account before this process started, or its last + /// restoration failed or waits for a busy store; in every build, the + /// identity was loaded with its private scan state marking a private + /// payment that may be unresolved + /// (`PrivateContactRequestsPosition::private_payments_unresolved`), or was + /// added to a wallet whose persister kept such a record after an earlier + /// wallet under the id was removed. No contact request, public or + /// private, is sent or accepted, nothing signed or broadcast, until they + /// are restored. Opening the shielded store + /// (`PlatformWalletManager::configure_shielded`) restores them, with no + /// keys; so does binding the wallet's shielded account, and a contact + /// request retries a restoration once. A private sync does not, and a + /// build without the `shielded` feature never does. + #[error( + "this wallet's unconfirmed private contact request payments from an earlier process are \ + not restored yet; configure the shielded store or bind the wallet's shielded account, \ + then try again" + )] + PrivateContactPaymentsNotRestored, + + /// A private contact request is paid for only with a persister that keeps + /// its recovery marker durably + /// (`PrivateContactRequestsPosition::private_payments_unresolved`), which + /// it declares with + /// [`PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART`](crate::changeset::PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART), + /// the scan state and atomic changesets: + /// without it, a process reopening the wallet, in a build without the + /// `shielded` feature or before the shielded store is configured, could + /// not tell that the payment may still execute, and would publish the + /// pair publicly. Refused before anything is sealed or paid. A host + /// persisting the private contact request scan state in changesets it + /// commits whole declares both. + #[error( + "private contact requests are paid for only with a persister that keeps the private \ + contact request scan state; declare PRIVATE_CONTACT_REQUEST_SCAN_STATE and \ + ATOMIC_CHANGESETS" + )] + PrivateContactRecoveryUnsupported, + /// No DPNS `domain` document exists for the requested name (exact /// normalized-label lookup came back empty). Distinct from /// [`Self::InvalidParameter`]: the input was well-formed, the name @@ -981,14 +1073,35 @@ pub enum PlatformWalletError { #[error("Shielded build error: {0}")] ShieldedBuildError(String), + /// A shielded transition (a shield from Platform addresses, or a spend + /// that consumes notes) never left the wallet: its broadcast was refused + /// before anything was sent. It can never execute, so a spend's notes are + /// released, its saved record retired, and the caller may retry. Once a + /// dispatch may have reached a node the outcome is + /// [`Self::ShieldedSpendUnconfirmed`] (or + /// [`Self::ShieldedBroadcastUnconfirmed`]) instead. #[error("Shielded broadcast failed: {0}")] ShieldedBroadcastFailed(String), - /// The shielded identity-create transition was **broadcast and accepted by the relay**, but the - /// SDK could not confirm its execution result (the result-proof fetch/verify failed — e.g. a - /// transient DAPI/proof error, not a platform rejection). The identity with `identity_id` may + /// A shielded spend's broadcast failed in a way that does not prove the + /// transition was never delivered, so it may still execute. None of this + /// crate's spends returns it: a note spend that may have been delivered + /// reports [`Self::ShieldedSpendUnconfirmed`], its notes and redrive record + /// kept. A payment a caller makes for a private contact request (the `pay` + /// a private send or accept takes) may return it, and is then handled as + /// unconfirmed, never as failed: the request stays pending and its pair + /// held, as for one paid for and not read back, and the FFI reports it as + /// `ErrorShieldedSpendUnconfirmed` (18), so a host does not pay again. + #[error("Shielded broadcast failed, but may have been delivered: {0}")] + ShieldedBroadcastMaybeDelivered(String), + + /// The shielded identity-create transition was broadcast and accepted by the relay, or may + /// have been delivered, but the SDK could not confirm its execution result (a broadcast + /// attempt that failed in transport, an endpoint's refusal or verdict, a result-proof + /// fetch/verify failure). The identity with `identity_id` may /// already exist on chain, so the caller must NOT treat it as unregistered: the slot stays held - /// against re-submission and the spent notes' reservations are left in place (the next nullifier + /// against re-submission and the spent notes' reservations are left in place, with the + /// recovery record saved before the broadcast (the next nullifier /// sync reconciles them). `reason` carries the underlying SDK error for diagnostics. #[error( "Shielded broadcast succeeded but its execution result could not be confirmed; \ @@ -1016,16 +1129,19 @@ pub enum PlatformWalletError { #[error("shielded account {account_index} is required for payment recovery: {reason}; restore its original viewing keys or inspect the unresolved payment before choosing recovery")] ShieldedRecoveryKeysRequired { account_index: u32, reason: String }, - /// A shielded transition (`operation` is `"shield"`, `"unshield"`, `"transfer"` or - /// `"withdraw"`) was **broadcast and accepted by the relay**, but the SDK could not confirm - /// its execution result (the result-proof fetch/verify failed — e.g. a transient DAPI/proof - /// error or timeout, not a platform rejection). The operation may already be executed on - /// chain, so re-submitting risks a double-execution. For the spend-based operations the spent + /// A shielded transition (`operation` names it: `"shield"`, `"unshield"`, `"transfer"`, + /// `"withdraw"`, an identity top-up, a private document create) was broadcast and accepted + /// by the relay, or may have been delivered, but the SDK could not confirm its execution + /// result (a broadcast attempt that failed in transport, an endpoint's refusal or consensus + /// verdict, which no proof backs, a result-proof fetch/verify failure or a timeout). The + /// operation may already be executed on chain, or may still execute, so re-submitting risks + /// a double-execution. For the spend-based operations the spent /// notes' reservations are intentionally left in place rather than released — releasing them - /// would invite re-selecting notes whose nullifiers may already be consumed; a shield spends - /// no notes, so it has nothing reserved. The next sync (or an app restart, since reservations - /// are in-memory only) reconciles the outcome either way. `reason` carries the underlying SDK - /// error for diagnostics. + /// would invite re-selecting notes whose nullifiers may already be consumed. Their recovery + /// record is saved before the broadcast, so a restart restores the reservations from it, and + /// the next sync reconciles the outcome. A shield from Platform addresses spends no notes and + /// keeps no record: its activity row stays pending until the scan sees its note. `reason` + /// carries the underlying SDK error for diagnostics. /// /// The identity-create sibling is [`Self::ShieldedBroadcastUnconfirmed`], which additionally /// carries the derived identity id so the caller can hold the registration slot. @@ -1039,11 +1155,13 @@ pub enum PlatformWalletError { reason: String, }, - /// A masternode (evonode) identity credit withdrawal was **broadcast and - /// accepted**, but its execution result could not be confirmed (the - /// result-proof fetch/verify failed — transient DAPI/proof error or - /// timeout, not a Platform rejection). The claim may already have - /// executed, and the SDK's identity-nonce cache was bumped for it, so + /// A masternode (evonode) identity credit withdrawal was broadcast and + /// accepted, or may have been delivered, but its execution result could + /// not be confirmed (a broadcast attempt that failed in transport, an + /// endpoint's refusal or consensus verdict, which no proof backs, a + /// result-proof fetch/verify failure or a timeout). The claim may already + /// have executed, or may still execute, and the SDK's identity-nonce + /// cache was bumped for it, so /// re-submitting could execute a SECOND withdrawal with the next nonce. /// Callers must NOT retry until they have re-read the identity's /// claimable balance (and the payout) and reconciled the outcome. @@ -1265,7 +1383,7 @@ pub fn is_instant_lock_timeout(error: &PlatformWalletError) -> bool { /// Matches the three `dash_sdk::Error` shapes that can carry a consensus /// verdict — `StateTransitionBroadcastError` (wait-stream), `Protocol( /// ConsensusError)` (CheckTx), and a `NoAvailableAddressesToRetry` envelope it -/// recurses into — staying in lockstep with `broadcast_definitely_failed`. +/// recurses into, staying in lockstep with `carries_consensus_rejection`. pub fn as_address_invalid_nonce(error: &dash_sdk::Error) -> Option<&AddressInvalidNonceError> { use dpp::consensus::state::state_error::StateError; @@ -1779,7 +1897,7 @@ mod address_nonce_tests { fn extracts_nonce_error_wrapped_in_no_available_addresses_to_retry() { // The dapi-client wraps the last rejection in `NoAvailableAddressesToRetry` // when every address is exhausted mid-retry; the extractor must recurse - // into it (lockstep with `broadcast_definitely_failed`). + // into it (lockstep with `carries_consensus_rejection`). let inner = Box::new(protocol_shape(9, 10)); let wrapped = dash_sdk::Error::NoAvailableAddressesToRetry(inner); let got = as_address_invalid_nonce(&wrapped).expect("must unwrap the retry envelope"); diff --git a/packages/rs-platform-wallet/src/lib.rs b/packages/rs-platform-wallet/src/lib.rs index 0f4f53b2e4f..70e7cb442f0 100644 --- a/packages/rs-platform-wallet/src/lib.rs +++ b/packages/rs-platform-wallet/src/lib.rs @@ -77,7 +77,8 @@ pub use wallet::core_address_key::{CoreAddressKeyError, CoreAddressPrivateKey}; pub use wallet::identity::network::{ derive_identity_auth_keypair, fetch_identity_public_keys, AutoAcceptProofSource, ContactCryptoProvider, ContactInfoOpened, ContactInfoPublishOutcome, ContactInfoSealed, - FetchedIdentityPublicKeys, PreparedDashPayPayment, SeedBindingVerification, IDENTITY_GAP_LIMIT, + FetchedIdentityPublicKeys, PaymentStarted, PreparedDashPayPayment, PrivateContactReadiness, + PrivateContactSyncReport, PrivateDocumentKeyPaths, SeedBindingVerification, IDENTITY_GAP_LIMIT, MASTER_KEY_INDEX, }; pub use wallet::identity::{ @@ -85,8 +86,8 @@ pub use wallet::identity::{ derive_contact_payment_addresses, derive_contact_xpub, pubkey_binds_expected_key_data, unmask_account_reference, BlockTime, ContactProfileEntry, ContactRequest, ContactXpubData, DashPayProfile, DashPayState, DpnsFetch, DpnsNameInfo, EstablishedContact, IdentityLocation, - IdentityManager, IdentityStatus, KeyStorage, ManagedIdentity, PrivateKeyData, ProfileUpdate, - RegistrationIndex, DEFAULT_CONTACT_GAP_LIMIT, + IdentityManager, IdentityStatus, KeyStorage, ManagedIdentity, PrivateContact, PrivateKeyData, + ProfileUpdate, RegistrationIndex, DEFAULT_CONTACT_GAP_LIMIT, }; pub use wallet::masternode_withdrawal::{ MasternodeWithdrawalKey, MasternodeWithdrawalKeys, MasternodeWithdrawalRequest, @@ -97,7 +98,7 @@ pub use wallet::mnemonic::{ }; pub use wallet::platform_wallet::PlatformWalletInfo; #[cfg(feature = "shielded")] -pub use wallet::platform_wallet::ShieldedShieldPreflight; +pub use wallet::platform_wallet::{PrivateReplyPayment, ShieldedShieldPreflight}; pub use wallet::provider_key_at_index::{ProviderDerivedKey, ProviderKeyKind}; #[cfg(feature = "shielded")] pub use wallet::shielded::operations::shield_fee_reserve_credits; diff --git a/packages/rs-platform-wallet/src/manager/load.rs b/packages/rs-platform-wallet/src/manager/load.rs index 1b612536087..002186924f9 100644 --- a/packages/rs-platform-wallet/src/manager/load.rs +++ b/packages/rs-platform-wallet/src/manager/load.rs @@ -1,9 +1,13 @@ //! Hydrate a [`PlatformWalletManager`] from its persister. use std::collections::BTreeMap; +#[cfg(feature = "shielded")] +use std::collections::BTreeSet; use std::sync::Arc; -use crate::changeset::{ClientStartState, ClientWalletStartState, PlatformWalletPersistence}; +use crate::changeset::{ + ClientStartState, ClientWalletStartState, PersistenceCapabilities, PlatformWalletPersistence, +}; use crate::error::PlatformWalletError; use crate::wallet::core::WalletGeneration; use crate::wallet::identity::IdentityManager; @@ -86,11 +90,22 @@ impl PlatformWalletManager

{ let ClientStartState { mut platform_addresses, wallets, - // Shielded restore happens lazily on `bind_shielded`, - // not here — drop the snapshot at this entry point. #[cfg(feature = "shielded")] - shielded: _, + shielded, + retained_private_contact_scan_states, } = start_state; + // Shielded restore happens lazily on `bind_shielded`, not here: only + // which wallets bound a shielded account is kept from the snapshot. + // A bind persists the account's viewing key before anything is + // installed, and refuses when it cannot, so a wallet with no persisted + // viewing key never bound one, and its shielded store holds no private + // contact request payment of its. A Clear deletes both together. + #[cfg(feature = "shielded")] + let bound_shielded: BTreeSet = shielded + .viewing_keys + .keys() + .map(|id| id.wallet_id) + .collect(); // Tracked (wallet-independent) masternodes ride the same startup // hydration; a failure logs and starts empty rather than failing @@ -143,7 +158,7 @@ impl PlatformWalletManager

{ let ClientWalletStartState { mut wallet, mut wallet_info, - identity_manager, + mut identity_manager, unused_asset_locks, unconfirmed_outgoing_txs, dashpay_backfill, @@ -244,7 +259,33 @@ impl PlatformWalletManager

{ observed_input_conflicts: Default::default(), core_wallet: wallet_info, generation: Arc::clone(&generation), - identity_manager: IdentityManager::from(identity_manager), + identity_manager: { + // A backend that does not attest the private contact + // request scan state, with the atomic changesets it needs, + // keeps no current copy of it: the store is read from its + // start. + if !self + .persister + .persistence_capabilities() + .contains(PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART) + { + identity_manager.forget_private_contact_scan_state(); + } + let mut identity_manager = IdentityManager::from(identity_manager); + // Records the host kept marked for this id after an + // earlier wallet under it was removed hold their + // identities, those loaded now and those added later, as + // a record of their own marked would. + identity_manager.retain_private_payment_markers( + retained_private_contact_scan_states + .get(&expected_wallet_id) + .into_iter() + .flat_map(|records| records.iter()) + .filter(|(_, record)| record.private_payments_unresolved) + .map(|(owner, _)| *owner), + ); + identity_manager + }, tracked_asset_locks, dpns_name_states: std::collections::BTreeMap::new(), dashpay_backfill, @@ -538,6 +579,26 @@ impl PlatformWalletManager

{ platform_wallet.platform().initialize().await; } + // Before the wallet is published: a public contact request it + // sends or accepts waits until the reservations of its unconfirmed + // private payments from an earlier process are restored from the + // shielded store, which only a configured store can show. + // So does one whose persister keeps the private scan state: only it + // lets a private payment be paid, so only its wallet can have one + // the journal keeps that no marker shows. Restored below once the + // load is published when a store is configured, by + // `configure_shielded` otherwise. + #[cfg(feature = "shielded")] + if bound_shielded.contains(&wallet_id) + || platform_wallet + .persister() + .persists_private_contact_scan_state() + { + platform_wallet + .persister() + .hold_until_private_payments_restored(); + } + let platform_wallet = Arc::new(platform_wallet); self.wallets.rcu(|wallets| { let mut wallets = std::collections::BTreeMap::clone(wallets); @@ -656,7 +717,17 @@ impl PlatformWalletManager

{ return Err(err); } - // Past the rollback point: every registration here is one this load + // Past the rollback point. A store configured before this load + // restores the held wallets' private payments now, with no keys and + // without waiting on the store, which a scan may hold; otherwise + // `configure_shielded` does. + #[cfg(feature = "shielded")] + if let Some(coordinator) = self.shielded_coordinator().await { + self.restore_private_payments_without_waiting(&coordinator, true) + .await; + } + + // Every registration here is one this load // actually committed, so the transactions now have a wallet to belong // to for as long as it stays registered. // @@ -1893,3 +1964,235 @@ mod tests { ); } } + +#[cfg(all(test, feature = "shielded"))] +mod private_payment_hold_tests { + use std::collections::BTreeMap; + use std::sync::Arc; + + use key_wallet::test_utils::TestWalletContext; + use key_wallet::wallet::ManagedWalletInfo; + use key_wallet::Wallet; + + use crate::changeset::{ + ClientStartState, ClientWalletStartState, IdentityManagerStartState, PersistenceError, + PlatformWalletChangeSet, PlatformWalletPersistence, ShieldedSyncStartState, + }; + use crate::events::PlatformEventHandler; + use crate::test_support::NoopTestEventHandler; + use crate::wallet::identity::ManagedIdentity; + use crate::wallet::platform_wallet::WalletId; + use crate::wallet::shielded::store::{PendingRedrive, PrivatePaymentEntry}; + use crate::wallet::shielded::{ + FileBackedShieldedStore, PrivateContactPayment, ShieldedStore, SubwalletId, + }; + use crate::PlatformWalletManager; + use dpp::identity::v0::IdentityV0; + use dpp::prelude::Identifier; + + /// The identity the bound wallet manages, which paid for a private + /// contact request to [`RECIPIENT`] in an earlier process. + const SENDER: [u8; 32] = [0xB1; 32]; + /// The identity that private request is to. + const RECIPIENT: [u8; 32] = [0xA1; 32]; + + /// Two wallets, of which only `bound` has a persisted shielded viewing + /// key: it bound a shielded account in an earlier process, and manages + /// [`SENDER`]. + struct ShieldedTracePersister { + wallets: Vec<(Wallet, ManagedWalletInfo)>, + bound: WalletId, + } + + impl PlatformWalletPersistence for ShieldedTracePersister { + fn store( + &self, + _wallet_id: WalletId, + _changeset: PlatformWalletChangeSet, + ) -> Result<(), PersistenceError> { + Ok(()) + } + + fn flush(&self, _wallet_id: WalletId) -> Result<(), PersistenceError> { + Ok(()) + } + + fn load(&self) -> Result { + let wallets = self + .wallets + .iter() + .map(|(wallet, managed)| { + let wallet_id = wallet.compute_wallet_id(); + let mut identity_manager = IdentityManagerStartState::default(); + if wallet_id == self.bound { + let sender = ManagedIdentity::new( + dpp::identity::Identity::V0(IdentityV0 { + id: Identifier::from(SENDER), + public_keys: BTreeMap::new(), + balance: 0, + revision: 1, + }), + 0, + ); + identity_manager + .wallet_identities + .insert(wallet_id, BTreeMap::from([(0, sender)])); + } + ( + wallet_id, + ClientWalletStartState { + wallet: wallet.clone(), + wallet_info: managed.clone(), + identity_manager, + unused_asset_locks: BTreeMap::new(), + unconfirmed_outgoing_txs: Vec::new(), + dashpay_backfill: Default::default(), + }, + ) + }) + .collect(); + let mut shielded = ShieldedSyncStartState::default(); + shielded + .viewing_keys + .insert(SubwalletId::new(self.bound, 0), vec![0; 96]); + Ok(ClientStartState { + wallets, + shielded, + ..Default::default() + }) + } + } + + /// A manager over two wallets, only the first of which bound a shielded + /// account before; with their ids. + fn manager() -> ( + Arc>, + WalletId, + WalletId, + ) { + let bound = TestWalletContext::new_random(); + let unbound = TestWalletContext::new_random(); + let bound_id = bound.wallet.compute_wallet_id(); + let unbound_id = unbound.wallet.compute_wallet_id(); + let persister = ShieldedTracePersister { + wallets: vec![ + (bound.wallet, bound.managed_wallet), + (unbound.wallet, unbound.managed_wallet), + ], + bound: bound_id, + }; + let sdk = Arc::new(dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk")); + let event_handler: Arc = Arc::new(NoopTestEventHandler); + let manager = Arc::new(PlatformWalletManager::new( + sdk, + Arc::new(persister), + event_handler, + )); + (manager, bound_id, unbound_id) + } + + /// Whether `wallet_id`'s public contact requests wait for its private + /// payments to be restored. + async fn held( + manager: &PlatformWalletManager, + wallet_id: WalletId, + ) -> bool { + manager + .get_wallet(&wallet_id) + .await + .expect("loaded") + .persister() + .private_payments_unrestored() + } + + /// Save, in the shielded store at `path`, the bound wallet's payment for a + /// private contact request from [`SENDER`] to [`RECIPIENT`] that may + /// still execute, as an earlier process left it: its redrive record and + /// its journal record. + fn save_payment(path: &std::path::Path, bound: WalletId) { + let mut store = FileBackedShieldedStore::open_path(path, 100).expect("the store"); + store + .arm_private_contact_payment( + SubwalletId::new(bound, 0), + PendingRedrive { + activity_id: [0x21; 32], + anchor: [0x22; 32], + nullifiers: vec![[0x23; 32]], + st_bytes: vec![0xAB; 96], + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }, + PrivateContactPayment { + sender: SENDER, + recipient: RECIPIENT, + account_reference: 0, + }, + &[PrivatePaymentEntry::for_commitment([0xC1; 32])], + 0, + None, + ) + .expect("the payment saved"); + } + + /// Whether `wallet_id`'s [`SENDER`] holds its pair with [`RECIPIENT`], + /// which refuses every request to it, public or private. + async fn pair_held( + manager: &PlatformWalletManager, + wallet_id: WalletId, + ) -> bool { + let wallet = manager.get_wallet(&wallet_id).await.expect("loaded"); + let wm = wallet.wallet_manager().read().await; + wm.get_wallet_info(&wallet_id) + .and_then(|info| { + info.identity_manager + .managed_identity(&Identifier::from(SENDER)) + }) + .is_some_and(|sender| { + sender + .dashpay() + .private_reply_pending(&Identifier::from(RECIPIENT)) + }) + } + + /// A loaded wallet that bound a shielded account before holds its public + /// contact requests until the shielded store is configured, which + /// restores its private payment's pair with no keys and releases the + /// wallet; one that never bound a shielded account is never held. + #[tokio::test] + async fn should_hold_a_loaded_wallet_that_bound_a_shielded_account_until_the_store_opens() { + let (manager, bound, unbound) = manager(); + let dir = tempfile::tempdir().expect("a directory"); + let path = dir.path().join("tree.sqlite"); + save_payment(&path, bound); + manager.load_from_persistor().await.expect("loaded"); + assert!( + held(&manager, bound).await, + "may have an unrestored payment" + ); + assert!(!pair_held(&manager, bound).await, "not restored yet"); + assert!( + !held(&manager, unbound).await, + "never bound a shielded account" + ); + + manager.configure_shielded(&path).await.expect("configured"); + assert!(!held(&manager, bound).await, "restored from the store"); + assert!(pair_held(&manager, bound).await, "the pair is held"); + } + + /// A wallet loaded once the shielded store is configured is restored by + /// the load itself, its private payment's pair held. + #[tokio::test] + async fn should_restore_a_wallet_loaded_once_the_store_is_configured() { + let (manager, bound, _) = manager(); + let dir = tempfile::tempdir().expect("a directory"); + let path = dir.path().join("tree.sqlite"); + save_payment(&path, bound); + manager.configure_shielded(&path).await.expect("configured"); + manager.load_from_persistor().await.expect("loaded"); + assert!(!held(&manager, bound).await, "restored by the load"); + assert!(pair_held(&manager, bound).await, "the pair is held"); + } +} diff --git a/packages/rs-platform-wallet/src/manager/mod.rs b/packages/rs-platform-wallet/src/manager/mod.rs index 63de4e4d49b..83ec1db5b3d 100644 --- a/packages/rs-platform-wallet/src/manager/mod.rs +++ b/packages/rs-platform-wallet/src/manager/mod.rs @@ -47,6 +47,8 @@ use crate::wallet::asset_lock::LockNotifyHandler; use crate::wallet::core::{BalanceUpdateHandler, SpendObservationHandler}; use crate::wallet::identity::network::DashPayPaymentHandler; use crate::wallet::platform_wallet::{PlatformWalletInfo, WalletId}; +#[cfg(feature = "shielded")] +use crate::wallet::shielded::NetworkShieldedCoordinator; use crate::wallet::PlatformWallet; /// Registry key identifying each background worker the manager joins at @@ -900,6 +902,15 @@ impl PlatformWalletManager

{ /// per-wallet bind looks up the coordinator from the manager /// and errors out if it hasn't been configured. /// + /// Once the store is open, restores the reservations of the unconfirmed + /// private contact request payments of every wallet the manager holds + /// whose public contact requests a load or a re-creation held for them, + /// or whose id the store's journal keeps payments of, with no keys + /// ([`Self::restore_private_contact_payment_holds`]). Call it right after + /// [`Self::load_from_persistor`] for a wallet that bound a shielded + /// account before: until then, its public contact requests are refused + /// with [`PlatformWalletError::PrivateContactPaymentsNotRestored`]. + /// /// Subsequent calls with the **same** `db_path` are a no-op /// (configuration is idempotent at the path level). A second /// call with a **different** path returns @@ -918,6 +929,12 @@ impl PlatformWalletManager

{ let mut slot = self.shielded_coordinator.write().await; if let Some(existing) = slot.as_ref() { if existing.db_path() == db_path.as_path() { + let existing = Arc::clone(existing); + drop(slot); + // A repeat call, on the main thread of a host binding again: + // a scan may hold the store, so nothing waits on it. + self.restore_private_payments_without_waiting(&existing, false) + .await; return Ok(()); } return Err(crate::error::PlatformWalletError::ShieldedStoreError( @@ -969,10 +986,115 @@ impl PlatformWalletManager

{ .on_shielded_tree_progress(leaves_committed, total_target); }, ))); - *slot = Some(coordinator); + *slot = Some(Arc::clone(&coordinator)); + drop(slot); + self.restore_private_contact_payment_holds(&coordinator) + .await; Ok(()) } + /// Restore from `coordinator`'s store, just opened, with no keys, the + /// reservations of the unconfirmed private contact request payments of + /// every wallet this manager holds whose contact requests wait for them, + /// or whose id the store's journal keeps payments of + /// ([`PlatformWallet::restore_private_contact_payments`]): a wallet + /// published before the store was configured with a persister that keeps + /// the private scan state, one loaded after binding a shielded account in + /// an earlier process, one with an identity marking a private payment that + /// may be unresolved ([`PlatformWallet::private_payments_held`]), or one + /// whose id another process journaled payments under. Nothing else holds a + /// store just opened, so this waits for nothing long. A wallet whose + /// restoration fails stays held, until a bind, a contact request's own + /// retry or a later call restores it. + #[cfg(feature = "shielded")] + pub(crate) async fn restore_private_contact_payment_holds( + &self, + coordinator: &Arc, + ) { + let wallets: Vec> = self.wallets.load().values().cloned().collect(); + for wallet in wallets { + if !wallet.private_payments_held().await + && !coordinator.may_journal_private_payments_of(wallet.wallet_id()) + { + continue; + } + if let Err(error) = wallet.restore_private_contact_payments(coordinator).await { + tracing::warn!( + wallet_id = %hex::encode(wallet.wallet_id()), + %error, + "unconfirmed private contact request payments not restored; the wallet's \ + contact requests stay held until a restoration succeeds" + ); + } + } + } + + /// [`Self::restore_private_contact_payment_holds`] for a store configured + /// before, which a shielded scan may hold for minutes: none waits on the + /// store ([`PlatformWallet::restore_private_payments_or_defer`]), a busy + /// store deferring it to a task, the wallet held until it runs. The + /// wallets still held are restored, and with `journaled_too` those whose + /// id the journal may keep payments of + /// (`NetworkShieldedCoordinator::may_journal_private_payments_of`, a busy + /// store counting as may): a load passes it, a repeat configure does not, + /// so a configure during a scan holds no wallet that was not held. + #[cfg(feature = "shielded")] + pub(crate) async fn restore_private_payments_without_waiting( + &self, + coordinator: &Arc, + journaled_too: bool, + ) { + let wallets: Vec> = self.wallets.load().values().cloned().collect(); + for wallet in wallets { + if wallet.private_payments_held().await + || (journaled_too + && coordinator.may_journal_private_payments_of(wallet.wallet_id())) + { + wallet.restore_private_payments_or_defer(coordinator).await; + } + } + } + + /// Before `wallet` is published: hold its contact requests until its + /// private payments are restored, or restore them now. The shielded + /// store's journal outlives a wallet's removal and a process's end, so a + /// wallet created or loaded under an id may have payments that may still + /// execute, which no marker shows and only the journal does. With a store + /// configured, the journal is read now, without waiting on the store + /// ([`PlatformWallet::restore_private_payments_or_defer`]): restored, the + /// pairs are held through the wallet's journal mirror whether or not their + /// senders are loaded yet; a busy store or a read that fails holds the + /// wallet until a restoration succeeds. With none, a wallet whose persister + /// keeps the private scan state is held until `configure_shielded` or a + /// bind reads the journal: only such a persister lets a private payment be + /// paid, so only its wallet can have journal records no marker shows. One + /// that does not is never held for want of a store. + #[cfg(feature = "shielded")] + pub(crate) async fn hold_or_restore_private_payments(&self, wallet: &PlatformWallet) { + match self.shielded_coordinator().await { + Some(coordinator) => { + wallet.restore_private_payments_or_defer(&coordinator).await; + } + None if wallet.persister().persists_private_contact_scan_state() => { + wallet.persister().hold_until_private_payments_restored(); + } + None => {} + } + } + + /// After `wallet` is published: a store configured since + /// [`Self::hold_or_restore_private_payments`] found none restored the + /// wallets published then, which this one was not yet, so it is restored + /// here, without waiting on the store, while it is still held. + #[cfg(feature = "shielded")] + pub(crate) async fn restore_private_payments_configured_since(&self, wallet: &PlatformWallet) { + if let Some(coordinator) = self.shielded_coordinator().await { + if wallet.private_payments_held().await { + wallet.restore_private_payments_or_defer(&coordinator).await; + } + } + } + /// Snapshot of the currently-installed shielded coordinator, /// or `None` if `configure_shielded` hasn't run yet on this /// manager. Cloned `Arc` so callers can hold the coordinator diff --git a/packages/rs-platform-wallet/src/manager/wallet_lifecycle.rs b/packages/rs-platform-wallet/src/manager/wallet_lifecycle.rs index 02a91ece586..81b84cee8a5 100644 --- a/packages/rs-platform-wallet/src/manager/wallet_lifecycle.rs +++ b/packages/rs-platform-wallet/src/manager/wallet_lifecycle.rs @@ -1,8 +1,10 @@ //! Wallet creation, registration, and removal on [`PlatformWalletManager`]. +use std::collections::{BTreeMap, BTreeSet}; use std::sync::Arc; use dash_spv::chain::CheckpointManager; +use dpp::prelude::Identifier; use key_wallet::wallet::initialization::WalletAccountCreationOptions; use key_wallet::wallet::managed_wallet_info::ManagedWalletInfo; use key_wallet::wallet::Wallet; @@ -11,8 +13,9 @@ use key_wallet::Network; #[cfg(any(feature = "bls", feature = "eddsa"))] use crate::changeset::ProviderKeyExtendedPubKey; use crate::changeset::{ - AccountAddressPoolEntry, AccountRegistrationEntry, PlatformWalletChangeSet, - PlatformWalletPersistence, ProviderKeyAccountEntry, WalletMetadataEntry, + AccountAddressPoolEntry, AccountRegistrationEntry, ClientWalletStartState, + PlatformWalletChangeSet, PlatformWalletPersistence, PrivateContactRequestsPosition, + ProviderKeyAccountEntry, WalletMetadataEntry, }; use crate::error::PlatformWalletError; use crate::wallet::core::WalletGeneration; @@ -353,7 +356,7 @@ impl PlatformWalletManager

{ .map(|root| Wallet::compute_wallet_id_from_root_extended_pub_key(&root, None)) .unwrap_or(wallet.wallet_id); - let platform_info = PlatformWalletInfo { + let mut platform_info = PlatformWalletInfo { observed_input_conflicts: Default::default(), core_wallet: wallet_info, generation: Arc::clone(&generation), @@ -410,31 +413,47 @@ impl PlatformWalletManager

{ // must measure durable writes against the host's cursor, not the one // it just built, and keeps the host's DashPay backfill record for the // receival accounts it holds (see the seed below). + // + // And the private contact request scan state records the host kept + // marked for this id, its wallet's identities' or those kept after the + // wallet's removal: a private payment one stands for may still + // execute, while the identity is added afresh, with no reservation or + // record of it. Each such identity is held as it is added, before it + // can send or accept, in every build. let load_persister: Arc = Arc::clone(&self.persister) as _; - let (mut persisted_platform_addresses, mut host_wallets) = + let (mut persisted_platform_addresses, mut host_wallets, retained_markers) = match super::run_blocking_load(move || load_persister.load()).await { Ok(crate::changeset::ClientStartState { platform_addresses, wallets, + retained_private_contact_scan_states, .. - }) => ( - platform_addresses, - wallets - .into_iter() - .map(|(id, state)| { - ( - id, + }) => { + let retained_markers = retained_private_payment_markers( + registration_wallet_id, + &wallets, + &retained_private_contact_scan_states, + ); + ( + platform_addresses, + wallets + .into_iter() + .map(|(id, state)| { ( - state.wallet_info.metadata.synced_height, - state.dashpay_backfill, - ), - ) - }) - .collect::>(), - ), + id, + ( + state.wallet_info.metadata.synced_height, + state.dashpay_backfill, + ), + ) + }) + .collect::>(), + retained_markers, + ) + } Err(e) => { tracing::error!( wallet_id = %hex::encode(registration_wallet_id), @@ -502,6 +521,9 @@ impl PlatformWalletManager

{ // runs first, so a wallet still registered under this id never has // its record overwritten; every publisher holds the cursor lock, so // none can appear between that check and the insert. + platform_info + .identity_manager + .retain_private_payment_markers(retained_markers); let created_cursor = platform_info.core_wallet.metadata.synced_height; let (snapshot_cursor, mut host_backfill) = match host_wallets.remove(®istration_wallet_id) { @@ -722,6 +744,12 @@ impl PlatformWalletManager

{ let platform_wallet = Arc::new(platform_wallet); + // Before the wallet is published: hold or restore its private + // payments (`PlatformWalletManager::hold_or_restore_private_payments`). + #[cfg(feature = "shielded")] + self.hold_or_restore_private_payments(&platform_wallet) + .await; + // Register the PlatformWallet handle. `rcu` publishes a new map // snapshot; the closure can rerun under a concurrent-writer // retry, so it must stay pure map manipulation. @@ -730,6 +758,11 @@ impl PlatformWalletManager

{ wallets.insert(wallet_id, Arc::clone(&platform_wallet)); wallets }); + // A store configured since the check above restored the wallets it + // found published, which this one was not yet. + #[cfg(feature = "shielded")] + self.restore_private_payments_configured_since(&platform_wallet) + .await; // Re-seed the lock-free balance atomic from the wallet's inner // balance now that the wallet is in `self.wallets`. @@ -1062,6 +1095,33 @@ impl PlatformWalletManager

{ } } +/// The identities of `wallet_id` whose private contact request scan state +/// record the host kept marked +/// (`PrivateContactRequestsPosition::private_payments_unresolved`): those of +/// its own identities, when the host still holds the wallet, and those it kept +/// after the wallet's removal +/// (`ClientStartState::retained_private_contact_scan_states`). +pub(super) fn retained_private_payment_markers( + wallet_id: WalletId, + wallets: &BTreeMap, + retained: &BTreeMap>, +) -> BTreeSet { + let held = wallets + .get(&wallet_id) + .into_iter() + .flat_map(|state| state.identity_manager.wallet_identities.values()) + .flat_map(|identities| identities.values()) + .filter(|managed| managed.dashpay().private_payments_unresolved()) + .map(|managed| managed.id()); + let kept = retained + .get(&wallet_id) + .into_iter() + .flat_map(|records| records.iter()) + .filter(|(_, record)| record.private_payments_unresolved) + .map(|(owner, _)| *owner); + held.chain(kept).collect() +} + #[cfg(test)] mod scoped_wallet_id_tests { use key_wallet::mnemonic::Mnemonic; diff --git a/packages/rs-platform-wallet/src/wallet/apply.rs b/packages/rs-platform-wallet/src/wallet/apply.rs index f1bccb35b8b..ce89447861c 100644 --- a/packages/rs-platform-wallet/src/wallet/apply.rs +++ b/packages/rs-platform-wallet/src/wallet/apply.rs @@ -234,6 +234,9 @@ impl PlatformWalletInfo { established, ignored, unignored, + private_contact_requests_positions, + private_shielded_addresses, + removed_private_shielded_addresses, } = contact_cs; for (key, entry) in sent_requests { @@ -303,6 +306,23 @@ impl PlatformWalletInfo { managed.apply_unignored_sender(&sender_id); } } + // The private contact request scan state: each owner's read + // position, and its contacts' shielded addresses, removals last. + for (owner_id, position) in private_contact_requests_positions { + if let Some(managed) = self.identity_manager.managed_identity_mut(&owner_id) { + managed.apply_private_contact_requests_position(position); + } + } + for ((owner_id, contact_id), address) in private_shielded_addresses { + if let Some(managed) = self.identity_manager.managed_identity_mut(&owner_id) { + managed.apply_private_shielded_address(contact_id, address); + } + } + for (owner_id, contact_id) in removed_private_shielded_addresses { + if let Some(managed) = self.identity_manager.managed_identity_mut(&owner_id) { + managed.apply_removed_private_shielded_address(&contact_id); + } + } } // 3b. DashPay profile/payment overlays. Applied AFTER identities diff --git a/packages/rs-platform-wallet/src/wallet/core/generation.rs b/packages/rs-platform-wallet/src/wallet/core/generation.rs index b6fc28b1cc8..885dbddd8e9 100644 --- a/packages/rs-platform-wallet/src/wallet/core/generation.rs +++ b/packages/rs-platform-wallet/src/wallet/core/generation.rs @@ -8,7 +8,7 @@ use std::ops::Deref; use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; use dashcore::{OutPoint, Transaction}; -use tokio::sync::{OwnedRwLockWriteGuard, RwLock, RwLockReadGuard}; +use tokio::sync::{OwnedRwLockReadGuard, OwnedRwLockWriteGuard, RwLock, RwLockReadGuard}; use super::balance::WalletBalance; @@ -427,6 +427,15 @@ impl WalletGeneration { self.lifecycle.read().await } + /// [`Self::payment_guard`], owned: for an operation that takes the gate in + /// a callback and holds it past the call, as a contact request send takes + /// it once the host's signature returns and holds it through the + /// broadcast and its bookkeeping. The same lock ordering and reentrancy + /// rules apply. + pub(crate) async fn payment_guard_owned(&self) -> OwnedRwLockReadGuard<()> { + Arc::clone(&self.lifecycle).read_owned().await + } + /// Enter this generation's lifecycle gate as a *teardown*. /// /// Exclusive against every payment operation on this generation. Removal diff --git a/packages/rs-platform-wallet/src/wallet/identity/mod.rs b/packages/rs-platform-wallet/src/wallet/identity/mod.rs index 01079577e1b..37eb12adeff 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/mod.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/mod.rs @@ -31,7 +31,8 @@ pub use crypto::{ }; pub use network::{DashPayView, IdentityWallet}; pub use state::{ - BlockTime, DashPayState, IdentityLocation, IdentityManager, ManagedIdentity, RegistrationIndex, + BlockTime, DashPayState, IdentityLocation, IdentityManager, ManagedIdentity, PrivateContact, + RegistrationIndex, }; pub use types::dashpay::profile::{calculate_avatar_hash, calculate_dhash_fingerprint}; pub use types::{ diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/contact_requests.rs b/packages/rs-platform-wallet/src/wallet/identity/network/contact_requests.rs index 9d7c6664101..eb1f822bbf9 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/contact_requests.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/contact_requests.rs @@ -18,10 +18,32 @@ use super::sdk_writer::SendContactRequestParams; use super::*; use crate::broadcaster::TransactionBroadcaster; use crate::error::PlatformWalletError; +use crate::wallet::core::WalletGeneration; use crate::wallet::identity::types::dashpay::contact_request::ContactRequest; use crate::wallet::identity::types::dashpay::established_contact::EstablishedContact; use crate::wallet::identity::ManagedIdentity; use crate::wallet::persister::WalletPersister; +use crate::wallet::platform_wallet::{PlatformWalletInfo, WalletId}; +use key_wallet_manager::WalletManager; +use std::sync::Arc; +use tokio::sync::RwLock; + +use super::private_contact_requests::{apply_detached, generation_info_mut, with_journaled_marker}; +use crate::broadcast_outcome::{ + broadcast_tracking_delivery, carries_consensus_rejection, BroadcastDelivery, +}; +use dash_sdk::drive::query::{WhereClause, WhereOperator}; +use dash_sdk::platform::dashpay::{PrivateContactRequest, SignedContactRequest}; +use dash_sdk::platform::private_document_entries::PrivateDocumentEntries; +use dash_sdk::platform::private_document_scan::PrivateDocumentScan; +use dash_sdk::platform::transition::outcome::{OutcomeEvidence, TransitionOutcome}; +use dash_sdk::platform::transition::waitable::Waitable; +use dash_sdk::platform::{DocumentQuery, FetchMany}; +use dpp::document::Document; +use dpp::identity::KeyID; +use dpp::platform_value::BinaryData; +use dpp::state_transition::StateTransition; +use key_wallet::bip32::ExtendedPubKey; use std::collections::BTreeMap; // --------------------------------------------------------------------------- @@ -144,6 +166,87 @@ pub trait ContactCryptoProvider { enc_to_user_id: &[u8; 32], private_data_blob: &[u8], ) -> Result; + + /// Sorts `page`, read from `start_position` of the store of the private document type + /// `document_type_name` of `data_contract_id`, with the keys at `keys`: the entries the + /// wallet's identities received, those they sent, and those refused + /// ([`dash_sdk::platform::private_document_scan::PrivateDocumentScanKeys::scan_page`]). + /// The keys stay in the signer. + /// + /// Defaulted to an "unsupported" error so adding this method is not a source-breaking + /// change: a provider that never reads private contact requests needs no override. + async fn scan_private_document_page( + &self, + _keys: &PrivateDocumentKeyPaths, + _data_contract_id: Identifier, + _document_type_name: &str, + _start_position: u64, + _page: &PrivateDocumentEntries, + ) -> Result { + Err(private_documents_unsupported()) + } + + /// Sorts each of `pages`, each read from its start position of the same store, as + /// [`Self::scan_private_document_page`] sorts one: one scan per page, in their order. A + /// provider derives the keys at `keys` once for all of them, rather than once a page. + /// + /// Defaulted to one [`Self::scan_private_document_page`] call per page, so a provider that + /// only implements that one keeps working. + async fn scan_private_document_pages( + &self, + keys: &PrivateDocumentKeyPaths, + data_contract_id: Identifier, + document_type_name: &str, + pages: &[(u64, &PrivateDocumentEntries)], + ) -> Result, PlatformWalletError> { + let mut scans = Vec::with_capacity(pages.len()); + for (start_position, page) in pages { + scans.push( + self.scan_private_document_page( + keys, + data_contract_id, + document_type_name, + *start_position, + page, + ) + .await?, + ); + } + Ok(scans) + } + + /// Seals `request` from `sender`, whose encryption key is the one at + /// `sender_encryption_key_path`, to the key `recipient_key_id` of `recipient`, with + /// `signature`, the signature of the request by the sender's key `signing_key_id` + /// ([`dash_sdk::platform::dashpay::seal_private_contact_request`]). The encryption key's + /// secret key, which the outgoing viewing key is derived from, stays in the signer; the + /// signature comes from the identity signer, as a transition's does. `esk_seed` is 32 + /// fresh random bytes, never reused. + /// + /// Defaulted to an "unsupported" error, as [`Self::scan_private_document_page`]. + #[allow(clippy::too_many_arguments)] + async fn seal_private_contact_request( + &self, + _sender_encryption_key_path: &key_wallet::bip32::DerivationPath, + _dashpay_contract: &dpp::prelude::DataContract, + _sender: &Identity, + _sender_encryption_key_id: KeyID, + _signing_key_id: KeyID, + _signature: &[u8; 65], + _recipient: &Identity, + _recipient_key_id: KeyID, + _request: &PrivateContactRequest, + _esk_seed: &[u8; 32], + _platform_version: &dpp::version::PlatformVersion, + ) -> Result { + Err(private_documents_unsupported()) + } +} + +fn private_documents_unsupported() -> PlatformWalletError { + PlatformWalletError::InvalidIdentityData( + "private contact requests are not supported by this crypto provider".to_string(), + ) } /// Result of [`ContactCryptoProvider::contact_info_seal`] — the two DIP-15 @@ -175,6 +278,9 @@ pub struct ContactInfoOpened { #[cfg(test)] pub(crate) struct SeedCryptoProvider { wallet: key_wallet::wallet::Wallet, + /// How many times the private document scan keys were derived: once per scan call, a + /// page's or a batch's. + pub(crate) scan_key_derivations: std::sync::atomic::AtomicUsize, } #[cfg(test)] @@ -185,6 +291,7 @@ impl SeedCryptoProvider { Self { wallet: Wallet::from_seed_bytes(seed, network, WalletAccountCreationOptions::None) .expect("test seed wallet"), + scan_key_derivations: std::sync::atomic::AtomicUsize::new(0), } } } @@ -312,6 +419,96 @@ impl ContactCryptoProvider for SeedCryptoProvider { private_data, }) } + + async fn scan_private_document_page( + &self, + keys: &PrivateDocumentKeyPaths, + data_contract_id: Identifier, + document_type_name: &str, + start_position: u64, + page: &PrivateDocumentEntries, + ) -> Result { + self.scan_private_document_pages( + keys, + data_contract_id, + document_type_name, + &[(start_position, page)], + ) + .await? + .pop() + .ok_or_else(|| PlatformWalletError::InvalidIdentityData("no scan".to_string())) + } + + async fn scan_private_document_pages( + &self, + keys: &PrivateDocumentKeyPaths, + data_contract_id: Identifier, + document_type_name: &str, + pages: &[(u64, &PrivateDocumentEntries)], + ) -> Result, PlatformWalletError> { + // Once for the batch, as a signer-backed provider resolves its seed once. + self.scan_key_derivations + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); + let keys = keys.scan_keys(|path| self.secret_key_at(path))?; + let target = platform_encryption::PrivateDocumentTarget { + contract_id: data_contract_id.to_buffer(), + document_type_name, + }; + Ok(pages + .iter() + .map(|(start_position, page)| keys.scan_page(&target, *start_position, page)) + .collect()) + } + + async fn seal_private_contact_request( + &self, + sender_encryption_key_path: &key_wallet::bip32::DerivationPath, + dashpay_contract: &dpp::prelude::DataContract, + sender: &Identity, + sender_encryption_key_id: KeyID, + signing_key_id: KeyID, + signature: &[u8; 65], + recipient: &Identity, + recipient_key_id: KeyID, + request: &PrivateContactRequest, + esk_seed: &[u8; 32], + platform_version: &dpp::version::PlatformVersion, + ) -> Result { + let mut encryption_secret_key = self.secret_key_at(sender_encryption_key_path)?; + let sealed = dash_sdk::platform::dashpay::seal_private_contact_request( + dashpay_contract, + &dash_sdk::platform::dashpay::PrivateContactRequestSender { + identity: sender, + encryption_key_id: sender_encryption_key_id, + encryption_secret_key: &encryption_secret_key, + signing_key_id, + signature, + }, + recipient, + recipient_key_id, + request, + esk_seed, + platform_version, + ); + encryption_secret_key.non_secure_erase(); + Ok(sealed?) + } +} + +#[cfg(test)] +impl SeedCryptoProvider { + /// The secret key at `path` of the test seed. + fn secret_key_at( + &self, + path: &key_wallet::bip32::DerivationPath, + ) -> Result { + let xprv = self + .wallet + .derive_extended_private_key(path) + .map_err(|e| PlatformWalletError::InvalidIdentityData(format!("test derive: {e}")))?; + dpp::secp256k1::SecretKey::from_secret_bytes(*xprv.private_key.to_bytes()) + .map_err(|e| PlatformWalletError::KeyDerivation(e.to_string())) + } } #[cfg(test)] @@ -378,6 +575,152 @@ pub enum AutoAcceptProofSource { }, } +/// What sending a reply to a contact request came to. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum ReplyOutcome { + /// The reply was sent. + Sent, + /// A reply to the request's sender was already tracked by the time the + /// pair was claimed or reserved: nothing was sent, and it is adopted. + AlreadyReplied, +} + +/// The proved query for the `contactRequest` from `sender` to `recipient` +/// carrying `account_reference`: equality on every property of DashPay's +/// `ownerIdUserIdAndAccountRef` unique index, as DPNS reads a preorder. +pub(super) fn sent_contact_request_query( + sender: &Identifier, + recipient: &Identifier, + account_reference: u32, +) -> Result { + let mut query = DocumentQuery::new(dashpay_contract()?, "contactRequest").map_err(|e| { + PlatformWalletError::InvalidIdentityData(format!( + "Failed to build the contact request query: {e}" + )) + })?; + query.where_clauses = vec![ + WhereClause { + field: "$ownerId".to_string(), + operator: WhereOperator::Equal, + value: Value::Identifier(sender.to_buffer()), + }, + WhereClause { + field: "toUserId".to_string(), + operator: WhereOperator::Equal, + value: Value::Identifier(recipient.to_buffer()), + }, + WhereClause { + field: "accountReference".to_string(), + operator: WhereOperator::Equal, + value: Value::U32(account_reference), + }, + ]; + query.limit = 1; + Ok(query) +} + +/// `error` under the SDK's unconfirmed-outcome envelope +/// (`StateTransitionResultUnconfirmed`), once: the transition it reports on +/// may have been delivered. +fn unconfirmed(error: dash_sdk::Error) -> dash_sdk::Error { + if error.is_state_transition_result_unconfirmed() { + error + } else { + dash_sdk::Error::StateTransitionResultUnconfirmed(Box::new(error)) + } +} + +/// The claim a public request holds on its pair from before its channel is +/// decided until it is submitted and recorded +/// (`DashPayView::claim_public_pair`): while it is held no private request to +/// the recipient is reserved. Released by [`Self::release`] or on drop. +pub(super) struct PublicContactClaim { + wallet_manager: Arc>>, + wallet_id: WalletId, + /// The wallet generation the claim was taken on: its release acts only + /// on that generation, so a wallet removed and re-created under its id + /// since is left alone. + generation: Arc, + sender: Identifier, + recipient: Identifier, + /// The attempt the claim was taken under: only it releases the claim. + attempt: u64, + held: bool, +} + +impl PublicContactClaim { + /// Release the claim now. Dropped while it waits for the wallet lock, + /// the guard releases it. + pub(super) async fn release(mut self) { + let mut wm = self.wallet_manager.write().await; + release_public_claim( + &mut wm, + &self.wallet_id, + &self.generation, + &self.sender, + &self.recipient, + self.attempt, + ); + self.held = false; + } +} + +impl Drop for PublicContactClaim { + fn drop(&mut self) { + if !self.held { + return; + } + let (wallet_id, sender, recipient, attempt) = + (self.wallet_id, self.sender, self.recipient, self.attempt); + let generation = Arc::clone(&self.generation); + apply_detached( + &self.wallet_manager, + "a dropped public contact request's claim", + move |wm| { + release_public_claim(wm, &wallet_id, &generation, &sender, &recipient, attempt) + }, + ); + } +} + +/// Release the claim `attempt` holds on `sender`'s pair with `recipient`, on +/// the wallet generation `generation` only. +fn release_public_claim( + wm: &mut WalletManager, + wallet_id: &WalletId, + generation: &Arc, + sender: &Identifier, + recipient: &Identifier, + attempt: u64, +) { + if let Some(managed) = generation_info_mut(wm, wallet_id, generation) + .and_then(|info| info.identity_manager.managed_identity_mut(sender)) + { + managed.release_public_contact_request(recipient, attempt); + } +} + +/// What a contact request to send is built from, whether it is published as a +/// `contactRequest` document or sealed privately: see +/// `DashPayView::prepare_contact_request`. +pub(super) struct PreparedContactRequest { + pub(super) sender_identity: Identity, + pub(super) sender_key_index: u32, + /// The path of the sender's encryption key, whose scalar keys the ECDH and + /// the account reference mask in the signer. + pub(super) sender_enc_path: key_wallet::bip32::DerivationPath, + pub(super) recipient_identity: Identity, + pub(super) recipient_key_index: u32, + pub(super) recipient_enc_pubkey: dpp::secp256k1::PublicKey, + pub(super) account_index: u32, + /// Our receiving (friendship) xpub for the pair. + pub(super) contact_xpub_ext: key_wallet::bip32::ExtendedPubKey, + /// Its DIP-15 69-byte compact form, which the request carries. + pub(super) xpub_bytes: Vec, + pub(super) account_reference: u32, + pub(super) auto_accept_proof: Option>, +} + impl AutoAcceptProofSource { /// Map a pre-built optional proof (the FFI / legacy shape) into a source. pub fn from_option(proof: Option>) -> Self { @@ -415,6 +758,31 @@ impl DashPayView<'_, B> { /// for seedless / external-signable wallets: the raw ECDH scalar stays in /// the signer and only the (public) xpub, the shared secret, and the masked /// reference cross back. + /// + /// A broadcast that may have been delivered and is not confirmed reports + /// the SDK's unconfirmed outcome (`StateTransitionResultUnconfirmed`) and + /// leaves the pair held as an unconfirmed public request, its signed + /// transition kept, until a proved read settles it + /// (`DashPayView::settle_unconfirmed_public_request`): until then a request + /// to the recipient is refused + /// ([`PlatformWalletError::PublicContactRequestUnconfirmed`]). A request + /// already on Platform that this one would repeat is adopted as sent, + /// with nothing signed. + /// + /// A recipient whose requests with this identity came or went privately is + /// refused ([`PlatformWalletError::PrivateContactRequestNeedsPrivateReply`]). + /// So is one a private request is pending to + /// ([`PlatformWalletError::PrivateContactRequestPending`]), until its + /// payment fails for good or a private sync reads it back: it may already + /// be on chain. Before the pair is claimed, DashPay's private store is + /// read to its end when it was not since load, so a request sent + /// privately in an earlier process or on another device is tracked first; + /// while that read cannot finish the send is refused with + /// [`PlatformWalletError::PrivateContactRequestPending`], and on a network + /// that serves no private documents yet nothing is read. A request whose + /// payment is unconfirmed since before a restart holds the pair from the + /// moment the wallet binds to its shielded coordinator + /// (`PlatformWallet::restore_private_contact_payments`). #[allow(clippy::type_complexity)] pub async fn send_contact_request_with_external_signer( &self, @@ -428,6 +796,744 @@ impl DashPayView<'_, B> { where S: Signer + Send + Sync, C: ContactCryptoProvider + Sync, + { + // The pair is claimed before its channel is decided and held until + // the request is submitted and recorded, so a private request cannot + // be reserved and paid for in between; the claim is released when + // the send ends, however it ends, a request that may have been + // delivered holding the pair from then on as unconfirmed. + self.send_public_contact_request( + sender_identity_id, + recipient_identity_id, + account_label, + auto_accept_proof, + signer, + crypto, + false, + ) + .await? + .ok_or_else(|| { + PlatformWalletError::InvalidParameter( + "no contact request was sent: only a reply adopts one already sent".to_string(), + ) + }) + } + + /// [`Self::send_contact_request_with_external_signer`], for a reply when + /// `adopt_reply`: then a request to the recipient tracked by the time + /// the pair is claimed (another accept's reply) is adopted rather than + /// rotated past, and `None` comes back with nothing sent. + #[allow(clippy::too_many_arguments)] + pub(super) async fn send_public_contact_request( + &self, + sender_identity_id: &Identifier, + recipient_identity_id: &Identifier, + account_label: Option, + auto_accept_proof: AutoAcceptProofSource, + signer: &S, + crypto: &C, + adopt_reply: bool, + ) -> Result, PlatformWalletError> + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + { + // Bound to this handle's wallet generation, under its lifecycle gate + // while the pair is claimed, and again from the moment the host's + // signature returns through the submission and its bookkeeping + // (`GatedSigner`): a removal cannot complete in either section, and a + // send started on a wallet since removed and re-created under the same + // id publishes nothing and records nothing on the replacement. + // + // The private store read runs before the gate: its network reads and + // the host's key resolution (a keychain or biometric prompt) never hold + // a removal back. It writes the wallet's state only through steps + // fenced to this handle's generation (`current_wallet_info_mut`), so a + // replacement never receives it, and a read that ran on a wallet + // removed meanwhile is refused at the gate. + // Boxed: the read's future (a private sync) is large, and the send's + // callers nest it in their own. + let read = + Box::pin(self.read_private_store_before_deciding(sender_identity_id, crypto)).await; + // A public request to the recipient whose outcome is unconfirmed is + // settled first where proof allows; while it stands the claim refuses. + Box::pin( + self.settle_unconfirmed_public_request_logged( + sender_identity_id, + recipient_identity_id, + ), + ) + .await; + let claim = { + let _lifecycle = self.generation.payment_guard().await; + if !self.is_current_generation().await { + return Err(PlatformWalletError::WalletRemovedBeforeSend(hex::encode( + self.wallet_id, + ))); + } + let store_read = read?; + self.release_discharged_private_requests().await?; + match self + .claim_public_pair( + sender_identity_id, + recipient_identity_id, + adopt_reply, + store_read, + ) + .await? + { + Some(claim) => claim, + None => return Ok(None), + } + }; + // Boxed: the send's future (its reads, the broadcast and the result + // wait) is large, and its callers nest it in their own. + let sent = Box::pin(self.send_claimed_contact_request( + sender_identity_id, + recipient_identity_id, + account_label, + auto_accept_proof, + signer, + crypto, + )) + .await; + claim.release().await; + sent.map(Some) + } + + /// Whether this handle's wallet generation is the one the manager holds: + /// not removed, nor re-created under its id since the handle was taken. + async fn is_current_generation(&self) -> bool { + self.wallet_manager + .read() + .await + .get_wallet_info(&self.wallet_id) + .is_some_and(|info| Arc::ptr_eq(&info.generation, &self.generation)) + } + + /// Claim the pair `sender`, `recipient` for a public request: refused, + /// in the same lock, while a private request to the recipient is + /// reserved, or a private payment the shielded store's journal keeps + /// unresolved holds the pair, whether or not the sender identity was + /// removed and added again since + /// (`WalletPersister::private_pair_journaled`), or once their requests + /// came or went privately, as a `contactRequest` document would publish + /// the relationship (replies and rotations go privately instead). The + /// refusal reads what the wallet tracks, which the store read before the + /// send brought up to date (`DashPayView::read_private_store_before_deciding`). + /// When that read applied (`store_read`), the sender's read must still be + /// to the store's end here, in the same lock: a rewind since (keys that + /// changed, a sender unignored) refuses with + /// [`PlatformWalletError::PrivateContactStoreNotRead`]. + pub(super) async fn claim_public_pair( + &self, + sender: &Identifier, + recipient: &Identifier, + adopt_reply: bool, + store_read: bool, + ) -> Result, PlatformWalletError> { + let mut wm = self.wallet_manager.write().await; + // A handle whose wallet was removed, or re-created under its id, since + // claims nothing on the replacement. + let managed = generation_info_mut(&mut wm, &self.wallet_id, &self.generation) + .ok_or_else(|| { + PlatformWalletError::WalletRemovedBeforeSend(hex::encode(self.wallet_id)) + })? + .identity_manager + .managed_identity_mut(sender) + .ok_or(PlatformWalletError::IdentityNotFound(*sender))?; + // A reply finds the one another accept recorded, in the same lock. + if adopt_reply && managed.dashpay().outgoing_request(recipient).is_some() { + return Ok(None); + } + if store_read && !managed.dashpay().private_contact_requests_read() { + return Err(PlatformWalletError::PrivateContactStoreNotRead(*sender)); + } + if managed + .dashpay() + .public_contact_request_unconfirmed(recipient) + { + return Err(PlatformWalletError::PublicContactRequestUnconfirmed( + *recipient, + )); + } + if managed.dashpay().private_reply_pending(recipient) + || self.persister.private_pair_journaled(sender, recipient) + { + return Err(PlatformWalletError::PrivateContactRequestPending( + *recipient, + )); + } + if managed.dashpay().private_contact(recipient).is_some() { + return Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply( + *recipient, + )); + } + let attempt = managed.claim_public_contact_request(*recipient); + Ok(Some(PublicContactClaim { + wallet_manager: Arc::clone(&self.wallet_manager), + wallet_id: self.wallet_id, + generation: Arc::clone(&self.generation), + sender: *sender, + recipient: *recipient, + attempt, + held: true, + })) + } + + /// The body of [`Self::send_contact_request_with_external_signer`], once + /// the pair is claimed. + async fn send_claimed_contact_request( + &self, + sender_identity_id: &Identifier, + recipient_identity_id: &Identifier, + account_label: Option, + auto_accept_proof: AutoAcceptProofSource, + signer: &S, + crypto: &C, + ) -> Result + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + { + // 1-4c. The keys, the receiving xpub, the masked account reference and + // the auto-accept proof, as a private request is built from them too. + let PreparedContactRequest { + sender_identity, + sender_key_index, + sender_enc_path, + recipient_identity, + recipient_key_index, + recipient_enc_pubkey, + account_index, + contact_xpub_ext, + xpub_bytes, + account_reference, + auto_accept_proof, + } = self + .prepare_contact_request( + sender_identity_id, + recipient_identity_id, + auto_accept_proof, + crypto, + ) + .await?; + + // 4d. A request this one repeats may be on Platform already: DashPay's + // unique index keys a request by its sender, recipient and account + // reference, which a request built from the same tracked requests + // repeats. One this wallet signed in a process that ended before + // recording it, or one another device of the sender sent, is + // adopted: recorded as sent, with nothing signed. A read that fails + // sends on: the unique index refuses this request if that one is + // there, and the refused request is held as unconfirmed until a read + // finds the one on Platform. + match self + .find_sent_contact_request(sender_identity_id, recipient_identity_id, account_reference) + .await + { + Ok((Some(request), _)) => { + let _lifecycle = self.generation.payment_guard().await; + if !self.is_current_generation().await { + return Err(PlatformWalletError::WalletRemovedBeforeSend(hex::encode( + self.wallet_id, + ))); + } + tracing::info!( + sender = %sender_identity_id, + recipient = %recipient_identity_id, + account_reference, + "contact request already on Platform; adopting it instead of sending another" + ); + return self + .record_sent_contact_request( + sender_identity_id, + recipient_identity_id, + request, + None, + account_index, + contact_xpub_ext, + ) + .await; + } + Ok((None, _)) => {} + Err(error) => tracing::warn!( + sender = %sender_identity_id, + recipient = %recipient_identity_id, + %error, + "could not read whether the contact request is on Platform already; sending it" + ), + } + + // 5. Build the signing key reference for document signing. + let identity_public_key = sender_identity + // Contact-request send writes a document state transition, + // which DPP requires to be signed by a HIGH-or-stricter + // authentication key. MASTER is rejected on document writes. + .available_signing_key( + signer, + Purpose::AUTHENTICATION, + &[SecurityLevel::HIGH, SecurityLevel::CRITICAL], + &[KeyType::ECDSA_SECP256K1], + false, + )? + .cloned() + .ok_or_else(|| { + PlatformWalletError::InvalidIdentityData( + "Sender identity has no HIGH or CRITICAL authentication key \ + (required for document state transitions)" + .to_string(), + ) + })?; + + // 6. Client-side ECDH via the signer: the shared secret is derived in + // the signer (scalar at `sender_enc_path`) against the recipient's + // encryption key, so the SDK write helper receives the finished secret + // (`EcdhProvider::ClientSide`) and no private key is ever materialized + // here. The recipient key is resolved exactly as the SDK would + // (`recipientKeyIndex` on the recipient identity); the helper re-checks + // the SDK asks for this same key before using the secret. + let shared_secret = crypto + .ecdh_shared_secret(&sender_enc_path, &recipient_enc_pubkey) + .await?; + + // 7. Sign through the write helper. All inputs are resolved above; the + // helper assembles the SDK `EcdhProvider` + xpub closure and calls + // `Sdk::sign_contact_request`, keeping the seven-generic SDK + // signature out of this call site (see `sdk_writer.rs`). The host + // signs through `GatedSigner`, which takes the wallet generation's + // lifecycle gate once the signature returns and keeps it, to the end + // of this call, through the broadcast right after and the + // bookkeeping below. + let gated = GatedSigner { + signer, + wallet: self, + gate: std::sync::Mutex::new(SigningGate::Unsigned), + }; + let signed = self + .sdk_writer + .sign_contact_request(SendContactRequestParams { + sender_identity: sender_identity.clone(), + recipient_identity, + sender_key_index, + recipient_key_index, + account_reference, + account_label, + auto_accept_proof, + shared_secret, + expected_recipient_pubkey: recipient_enc_pubkey, + xpub_bytes, + signing_public_key: identity_public_key, + signer: &gated as &(dyn Signer + Send + Sync), + }) + .await + .map_err(|error| match gated.removed() { + true => PlatformWalletError::WalletRemovedBeforeSend(hex::encode(self.wallet_id)), + false => error, + })?; + + // 8. Broadcast the signed bytes, keeping what every dispatch proved, + // by the rule shielded spends use (`broadcast_tracking_delivery`): + // only a refusal before anything was sent shows the request can + // never execute. A dispatch that reached an endpoint may have + // delivered it whatever the endpoint answered, as no proof backs + // the answer, and the request may execute later under its identity + // contract nonce, while a second request would take the next one. + // So the request is then held as unconfirmed, the pair with it, + // until a proved read settles it + // (`DashPayView::settle_unconfirmed_public_request`), and the host + // gets the SDK's unconfirmed outcome. An endpoint's verdict skips + // the wait for a result that would only time out. + let SignedContactRequest { + state_transition, .. + } = signed; + let delivery = Box::pin(broadcast_tracking_delivery(&self.sdk, &state_transition)).await; + let confirmed = match delivery { + BroadcastDelivery::NeverDelivered(error) => { + return Err(PlatformWalletError::Sdk(error)) + } + BroadcastDelivery::MaybeDelivered(error) if carries_consensus_rejection(&error) => { + Err(error) + } + BroadcastDelivery::Admitted | BroadcastDelivery::MaybeDelivered(_) => { + Box::pin(::wait_for_response( + &self.sdk, + state_transition.clone(), + None, + )) + .await + } + }; + let document = match confirmed { + Ok(document) => document, + Err(error) => { + self.hold_unconfirmed_public_request( + sender_identity_id, + recipient_identity_id, + state_transition, + account_reference, + account_index, + contact_xpub_ext, + ) + .await; + return Err(PlatformWalletError::Sdk(unconfirmed(error))); + } + }; + + // 9. Record the request as a confirmed send records it. + // + // Store the REAL 96-byte ciphertext off the broadcast + // document (not a zero placeholder) so the persisted / + // SwiftData row matches what landed on Platform — a restored + // device comparing local rows against chain sees identity, + // and the sent-side re-ingest doesn't "upgrade" the row. + // Hard error rather than a zero-fill fallback: persisting a 96-byte + // all-zero "valid-looking" ciphertext would poison the local row + // (a restored device compares it to chain and mismatches; anything + // treating it as the contact's xpub source decrypts garbage). The + // broadcast already landed on-chain, so the sweep re-ingests + // the real document on the next pass — returning an error here is + // strictly safer than silently storing poison in release builds. + let encrypted_public_key = document + .properties() + .get("encryptedPublicKey") + .and_then(|v: &Value| v.to_binary_bytes().ok()) + .ok_or_else(|| { + PlatformWalletError::InvalidIdentityData( + "broadcast contactRequest lacks a readable encryptedPublicKey; \ + the on-chain doc will reconcile on the next sync" + .to_string(), + ) + })?; + let mut contact_request = ContactRequest::new( + *sender_identity_id, + *recipient_identity_id, + sender_key_index, + recipient_key_index, + account_reference, + encrypted_public_key, + document.created_at_core_block_height().unwrap_or(0), + document.created_at().unwrap_or(0), + ); + // Mirror the broadcast doc's optional `encryptedAccountLabel` onto the + // local outgoing row so it matches what landed on Platform (same reason + // the 96-byte ciphertext is read off the doc above). Without this the + // sender's own row never reflects the label it just sent. + contact_request.encrypted_account_label = document + .properties() + .get("encryptedAccountLabel") + .and_then(|v: &Value| v.to_binary_bytes().ok()); + + // Register our receiving (friendship) account from the xpub the signer + // already derived above: same friendship key, no second derivation and + // no resident seed. + self.record_sent_contact_request( + sender_identity_id, + recipient_identity_id, + contact_request, + None, + account_index, + contact_xpub_ext, + ) + .await + } + + /// Record `request` as sent from `sender` to `recipient` and register our + /// receiving (friendship) account for the pair from `contact_xpub`, as a + /// send that saw its document confirmed does. `settles` is the attempt of + /// the unconfirmed public request to the recipient this request settles, + /// released in the same lock it is recorded in. Only on this handle's + /// wallet generation: the caller holds the generation's lifecycle gate. + async fn record_sent_contact_request( + &self, + sender: &Identifier, + recipient: &Identifier, + request: ContactRequest, + settles: Option, + account_index: u32, + contact_xpub: ExtendedPubKey, + ) -> Result { + { + let mut wm = self.wallet_manager.write().await; + let managed = generation_info_mut(&mut wm, &self.wallet_id, &self.generation) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))? + .identity_manager + .managed_identity_mut(sender) + .ok_or(PlatformWalletError::IdentityNotFound(*sender))?; + managed + .add_sent_contact_request(request.clone(), &self.persister) + .map_err(|e| { + PlatformWalletError::Persistence(format!( + "sent contact request not persisted: {e}" + )) + })?; + if let Some(attempt) = settles { + managed.settle_unconfirmed_public_request(recipient, attempt); + } + } + self.register_contact_account(sender, recipient, account_index, contact_xpub) + .await?; + Ok(request) + } + + /// Hold the pair `sender`, `recipient` for the public request + /// `transition` signs, whose broadcast may have been delivered + /// (`ManagedIdentity::hold_unconfirmed_public_request`). Only on this + /// handle's wallet generation: a wallet removed, or re-created under its + /// id, since is left alone. + #[allow(clippy::too_many_arguments)] + async fn hold_unconfirmed_public_request( + &self, + sender: &Identifier, + recipient: &Identifier, + transition: StateTransition, + account_reference: u32, + account_index: u32, + contact_xpub: ExtendedPubKey, + ) { + let mut wm = self.wallet_manager.write().await; + if let Some(managed) = generation_info_mut(&mut wm, &self.wallet_id, &self.generation) + .and_then(|info| info.identity_manager.managed_identity_mut(sender)) + { + managed.hold_unconfirmed_public_request( + *recipient, + transition, + account_reference, + account_index, + contact_xpub, + ); + } + } + + /// The `contactRequest` from `sender` to `recipient` carrying + /// `account_reference`, as a proved read shows it, and the height the read + /// was proved at: `None` when the read proves there is none. DashPay's + /// `ownerIdUserIdAndAccountRef` unique index keys it, so there is at most + /// one, and as the type's documents are neither mutable nor deletable, + /// one found stays. + pub(super) async fn find_sent_contact_request( + &self, + sender: &Identifier, + recipient: &Identifier, + account_reference: u32, + ) -> Result<(Option, u64), PlatformWalletError> { + let query = sent_contact_request_query(sender, recipient, account_reference)?; + let (documents, metadata) = Document::fetch_many_with_metadata(&self.sdk, query, None) + .await + .map_err(PlatformWalletError::Sdk)?; + let request = documents + .values() + .flatten() + .filter(|document| { + document.owner_id() == *sender + && document + .properties() + .get("toUserId") + .and_then(|value: &Value| value.to_identifier().ok()) + == Some(*recipient) + }) + .find_map(|document| { + Self::parse_sent_contact_request_doc(document, *sender, *recipient) + }) + .filter(|request| request.account_reference == account_reference); + Ok((request, metadata.height)) + } + + /// Whether a public contact request from `sender` to `recipient` was + /// broadcast and may have been delivered, with no proof settling its + /// outcome yet: until one does, no other contact request to the recipient + /// is sent, public or private + /// ([`PlatformWalletError::PublicContactRequestUnconfirmed`]). A public + /// contact request sync settles it. The per-contact read a host shows next + /// to `DashPayView::private_pair_held`, so it tells a public request + /// awaiting its outcome from a private one pending. + pub async fn public_contact_request_unconfirmed( + &self, + sender: &Identifier, + recipient: &Identifier, + ) -> Result { + let wm = self.wallet_manager.read().await; + Ok(wm + .get_wallet_info(&self.wallet_id) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))? + .identity_manager + .managed_identity(sender) + .ok_or(PlatformWalletError::IdentityNotFound(*sender))? + .dashpay() + .public_contact_request_unconfirmed(recipient)) + } + + /// Settle the unconfirmed public request from `sender` to `recipient`, + /// if this handle's wallet generation holds one, as far as proved reads + /// allow: + /// + /// - its document found by a proved read (the sender, the recipient and + /// its account reference, DashPay's unique index): recorded as sent, as + /// a send that saw it confirmed records it, and the pair released; + /// - otherwise, the transition proved unable to execute + /// (`TransitionOutcome::CannotExecute`), or its identity contract nonce + /// proved used at a height the read that missed the document was proved + /// at or above (`TransitionOutcome::ExecutedOrSuperseded`): it never + /// wrote the document and never will, so the pair is released and a new + /// request may be sent; + /// - otherwise it may still execute: the same signed bytes are broadcast + /// again, whatever that answers, and the pair stays held. + /// + /// The nonce is read before the document: a nonce used at height `h` + /// proves the transition cannot execute after `h`, so only a document + /// read at or above `h` that misses it shows it never wrote it. + pub(super) async fn settle_unconfirmed_public_request( + &self, + sender: &Identifier, + recipient: &Identifier, + ) -> Result<(), PlatformWalletError> { + let held = { + let wm = self.wallet_manager.read().await; + wm.get_wallet_info(&self.wallet_id) + .filter(|info| Arc::ptr_eq(&info.generation, &self.generation)) + .and_then(|info| info.identity_manager.managed_identity(sender)) + .and_then(|managed| { + managed + .dashpay() + .unconfirmed_public_request(recipient) + .cloned() + }) + }; + let Some(held) = held else { + return Ok(()); + }; + let outcome = self + .sdk + .state_transition_outcome(&held.transition, OutcomeEvidence::default()) + .await + .map_err(PlatformWalletError::Sdk)?; + let (found, read_at) = self + .find_sent_contact_request(sender, recipient, held.account_reference) + .await?; + let settled = match outcome { + TransitionOutcome::CannotExecute(_) => true, + TransitionOutcome::ExecutedOrSuperseded { consumed_by_height } => { + read_at >= consumed_by_height + } + TransitionOutcome::StillPossible { .. } => false, + }; + if found.is_none() && !settled { + if matches!(outcome, TransitionOutcome::StillPossible { .. }) { + // The same bytes, so never a second request; an endpoint's + // answer proves nothing either way. + let delivery = broadcast_tracking_delivery(&self.sdk, &held.transition).await; + tracing::debug!( + sender = %sender, + recipient = %recipient, + ?delivery, + "unconfirmed public contact request broadcast again" + ); + } + return Ok(()); + } + let _lifecycle = self.generation.payment_guard().await; + if !self.is_current_generation().await { + return Ok(()); + } + match found { + Some(request) => { + self.record_sent_contact_request( + sender, + recipient, + request, + Some(held.attempt), + held.account_index, + held.contact_xpub, + ) + .await?; + } + None => { + let mut wm = self.wallet_manager.write().await; + if let Some(managed) = + generation_info_mut(&mut wm, &self.wallet_id, &self.generation) + .and_then(|info| info.identity_manager.managed_identity_mut(sender)) + { + managed.settle_unconfirmed_public_request(recipient, held.attempt); + } + } + } + Ok(()) + } + + /// [`Self::settle_unconfirmed_public_request`], logging a read that could + /// not settle it: the request stays held. + pub(super) async fn settle_unconfirmed_public_request_logged( + &self, + sender: &Identifier, + recipient: &Identifier, + ) { + // Boxed: its reads and broadcast make a large future, which sends and + // syncs nest in their own. + if let Err(error) = + Box::pin(self.settle_unconfirmed_public_request(sender, recipient)).await + { + tracing::warn!( + sender = %sender, + recipient = %recipient, + %error, + "an unconfirmed public contact request could not be settled; it stays held" + ); + } + } + + /// Settle every unconfirmed public request this handle's wallet + /// generation holds ([`Self::settle_unconfirmed_public_request`]). + async fn settle_unconfirmed_public_requests(&self) { + let pairs: Vec<(Identifier, Identifier)> = { + let wm = self.wallet_manager.read().await; + wm.get_wallet_info(&self.wallet_id) + .filter(|info| Arc::ptr_eq(&info.generation, &self.generation)) + .map(|info| { + info.identity_manager + .all_identities() + .iter() + .filter_map(|identity| { + info.identity_manager.managed_identity(&identity.id()) + }) + .flat_map(|managed| { + let sender = managed.identity.id(); + managed + .dashpay() + .unconfirmed_public_request_recipients() + .into_iter() + .map(move |recipient| (sender, recipient)) + }) + .collect() + }) + .unwrap_or_default() + }; + for (sender, recipient) in pairs { + self.settle_unconfirmed_public_request_logged(&sender, &recipient) + .await; + } + } + + /// Steps 1 to 4c of a contact request send, shared by the document send + /// ([`Self::send_contact_request_with_external_signer`]) and the private one + /// (`send_private_contact_request`): the sender's identity, encryption key + /// and its path, the recipient's identity and key, our receiving xpub for + /// the pair, the DIP-15 masked account reference (its version bumped past + /// the previous request to the recipient, public or private) and the + /// auto-accept proof over it. + /// + /// Once the version is at its last, 15, a request with the same xpub and + /// key would repeat the previous one: it is refused with + /// [`PlatformWalletError::InvalidParameter`], before anything is signed, + /// sealed or paid. + pub(super) async fn prepare_contact_request( + &self, + sender_identity_id: &Identifier, + recipient_identity_id: &Identifier, + auto_accept_proof: AutoAcceptProofSource, + crypto: &C, + ) -> Result + where + C: ContactCryptoProvider + Sync, { // 1. Retrieve the sender identity and its HD index from the // local manager. @@ -558,17 +1664,17 @@ impl DashPayView<'_, B> { // identical resend, so the bump is what makes a superseding // (rotation) request broadcastable. The HMAC+mask runs in the // signer (keyed by the raw scalar at `sender_enc_path`). + let prior_reference = { + let wm = self.wallet_manager.read().await; + wm.get_wallet_info(&self.wallet_id) + .and_then(|info| info.identity_manager.managed_identity(sender_identity_id)) + // Checks both the pending sent map AND the established + // contact's outgoing request: see the method doc for + // why consulting only the pending map breaks rotation + // on established contacts. + .and_then(|managed| managed.prior_sent_account_reference(recipient_identity_id)) + }; let account_reference = { - let prior_reference = { - let wm = self.wallet_manager.read().await; - wm.get_wallet_info(&self.wallet_id) - .and_then(|info| info.identity_manager.managed_identity(sender_identity_id)) - // Checks both the pending sent map AND the established - // contact's outgoing request — see the method doc for - // why consulting only the pending map breaks rotation - // on established contacts. - .and_then(|managed| managed.prior_sent_account_reference(recipient_identity_id)) - }; let previous_version = match prior_reference { Some(prior) => Some( crypto @@ -580,8 +1686,8 @@ impl DashPayView<'_, B> { }; let version = match previous_version { // 4-bit field; saturate rather than wrap so a 16th - // rotation fails loudly at the unique index instead of - // silently colliding with version 0. + // rotation is refused below instead of silently colliding + // with version 0. Some(v) if v >= 15 => { tracing::warn!( recipient = %recipient_identity_id, @@ -596,6 +1702,16 @@ impl DashPayView<'_, B> { .account_reference(&sender_enc_path, &xpub_bytes, account_index, version) .await? }; + // Saturated, with the same xpub and key: the request would repeat the + // tracked one. A document send would fail at the unique index; a + // private one would be paid for and then ignored as already tracked. + if prior_reference == Some(account_reference) { + return Err(PlatformWalletError::InvalidParameter(format!( + "no account reference version is left for another contact request to \ + {recipient_identity_id}: version 15 is used, and this request would repeat the \ + one already sent" + ))); + } // 4c. Resolve the auto-accept proof now that `account_reference` is // known. The QR-scanner variant signs `(sender, recipient, @@ -611,157 +1727,39 @@ impl DashPayView<'_, B> { recipient_identity_id, account_reference, expiry, - ), - ), - }; - - // 5. Build the signing key reference for document signing. - let identity_public_key = sender_identity - // Contact-request send writes a document state transition, - // which DPP requires to be signed by a HIGH-or-stricter - // authentication key. MASTER is rejected on document writes. - .available_signing_key( - signer, - Purpose::AUTHENTICATION, - &[SecurityLevel::HIGH, SecurityLevel::CRITICAL], - &[KeyType::ECDSA_SECP256K1], - false, - )? - .cloned() - .ok_or_else(|| { - PlatformWalletError::InvalidIdentityData( - "Sender identity has no HIGH or CRITICAL authentication key \ - (required for document state transitions)" - .to_string(), - ) - })?; - - // 6. Client-side ECDH via the signer: the shared secret is derived in - // the signer (scalar at `sender_enc_path`) against the recipient's - // encryption key, so the SDK write helper receives the finished secret - // (`EcdhProvider::ClientSide`) and no private key is ever materialized - // here. The recipient key is resolved exactly as the SDK would - // (`recipientKeyIndex` on the recipient identity); the helper re-checks - // the SDK asks for this same key before using the secret. - let recipient_enc_pubkey = { - use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; - let key = recipient_identity - .public_keys() - .get(&recipient_key_index) - .ok_or_else(|| { - PlatformWalletError::InvalidIdentityData(format!( - "Recipient identity has no key at index {recipient_key_index}" - )) - })?; - dpp::secp256k1::PublicKey::from_slice(key.data().as_slice()).map_err(|e| { - PlatformWalletError::InvalidIdentityData(format!( - "Recipient encryption public key is invalid: {e}" - )) - })? - }; - let shared_secret = crypto - .ecdh_shared_secret(&sender_enc_path, &recipient_enc_pubkey) - .await?; - - // 7. Broadcast through the write helper. All inputs are resolved - // above; the helper assembles the SDK `EcdhProvider` + xpub - // closure and dispatches `Sdk::send_contact_request`, keeping - // the seven-generic SDK signature out of this call site — see - // `sdk_writer.rs`. - let result = self - .sdk_writer - .send_contact_request(SendContactRequestParams { - sender_identity: sender_identity.clone(), - recipient_identity, - sender_key_index, - recipient_key_index, - account_reference, - account_label, - auto_accept_proof, - shared_secret, - expected_recipient_pubkey: recipient_enc_pubkey, - xpub_bytes, - signing_public_key: identity_public_key, - signer: signer as &(dyn Signer + Send + Sync), - }) - .await?; - - // 8. Mirror the local-state bookkeeping in `send_contact_request`. - // - // Store the REAL 96-byte ciphertext off the broadcast - // document (not a zero placeholder) so the persisted / - // SwiftData row matches what landed on Platform — a restored - // device comparing local rows against chain sees identity, - // and the sent-side re-ingest doesn't "upgrade" the row. - // Hard error rather than a zero-fill fallback: persisting a 96-byte - // all-zero "valid-looking" ciphertext would poison the local row - // (a restored device compares it to chain and mismatches; anything - // treating it as the contact's xpub source decrypts garbage). The - // broadcast already landed on-chain, so the sweep re-ingests - // the real document on the next pass — returning an error here is - // strictly safer than silently storing poison in release builds. - let encrypted_public_key = result - .document - .properties() - .get("encryptedPublicKey") - .and_then(|v: &Value| v.to_binary_bytes().ok()) - .ok_or_else(|| { - PlatformWalletError::InvalidIdentityData( - "broadcast contactRequest lacks a readable encryptedPublicKey; \ - the on-chain doc will reconcile on the next sync" - .to_string(), - ) - })?; - let mut contact_request = ContactRequest::new( - *sender_identity_id, - result.recipient_id, - sender_key_index, - recipient_key_index, - result.account_reference, - encrypted_public_key, - result.document.created_at_core_block_height().unwrap_or(0), - result.document.created_at().unwrap_or(0), - ); - // Mirror the broadcast doc's optional `encryptedAccountLabel` onto the - // local outgoing row so it matches what landed on Platform (same reason - // the 96-byte ciphertext is read off the doc above). Without this the - // sender's own row never reflects the label it just sent. - contact_request.encrypted_account_label = result - .document - .properties() - .get("encryptedAccountLabel") - .and_then(|v: &Value| v.to_binary_bytes().ok()); + ), + ), + }; - { - let mut wm = self.wallet_manager.write().await; - let info = wm - .get_wallet_info_mut(&self.wallet_id) - .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))?; - let managed = info - .identity_manager - .managed_identity_mut(sender_identity_id) - .ok_or(PlatformWalletError::IdentityNotFound(*sender_identity_id))?; - managed - .add_sent_contact_request(contact_request.clone(), &self.persister) - .map_err(|e| { - PlatformWalletError::Persistence(format!( - "sent contact request not persisted: {e}" + let recipient_enc_pubkey = { + use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; + let key = recipient_identity + .public_keys() + .get(&recipient_key_index) + .ok_or_else(|| { + PlatformWalletError::InvalidIdentityData(format!( + "Recipient identity has no key at index {recipient_key_index}" )) })?; - } - - // Register our receiving (friendship) account from the xpub the signer - // already derived above — same friendship key, no second derivation and - // no resident seed. - self.register_contact_account( - sender_identity_id, - recipient_identity_id, + dpp::secp256k1::PublicKey::from_slice(key.data().as_slice()).map_err(|e| { + PlatformWalletError::InvalidIdentityData(format!( + "Recipient encryption public key is invalid: {e}" + )) + })? + }; + Ok(PreparedContactRequest { + sender_identity, + sender_key_index, + sender_enc_path, + recipient_identity, + recipient_key_index, + recipient_enc_pubkey, account_index, contact_xpub_ext, - ) - .await?; - - Ok(contact_request) + xpub_bytes, + account_reference, + auto_accept_proof, + }) } } @@ -826,10 +1824,11 @@ fn query_lower_bound(high_water: Option) -> Option { /// Collapse a stream of parsed received contact requests to the single /// newest request per sender, keyed by `sender_id`. /// -/// "Newest" is the lexicographic max of `(created_at, account_reference)` -/// — created_at is the primary signal (a rotation request is broadcast -/// later), with account_reference as a deterministic tiebreak for the -/// degenerate same-timestamp case. +/// "Newest" is the lexicographic max of the account reference's version, +/// `created_at`, then `account_reference` ([`freshness`]): a rotation bumps +/// the version and is broadcast later, and a replay of an older request +/// appended again later keeps its older version. The reference is a +/// deterministic tiebreak for the degenerate same-timestamp case. /// /// This is the idempotency keystone of the recurring sync: on-chain /// `contactRequest` docs are immutable and never deleted, so a sender who @@ -861,7 +1860,7 @@ fn query_lower_bound(high_water: Option) -> Option { /// /// DIP-15 section 8.4 allows ignoring additional requests, which is what the /// collapse does. -fn newest_received_per_sender( +pub(super) fn newest_received_per_sender( requests: impl IntoIterator, ) -> std::collections::BTreeMap { let mut newest: std::collections::BTreeMap = @@ -870,9 +1869,7 @@ fn newest_received_per_sender( let sender = req.sender_id; let replace = newest .get(&sender) - .map(|cur| { - (req.created_at, req.account_reference) > (cur.created_at, cur.account_reference) - }) + .map(|cur| freshness(&req) > freshness(cur)) .unwrap_or(true); if replace { newest.insert(sender, req); @@ -894,7 +1891,7 @@ fn newest_received_per_sender( /// with the freshest outgoing reference — otherwise the next rotation /// collides on the contract's `($ownerId, toUserId, accountReference)` unique /// index. -fn newest_sent_per_recipient( +pub(super) fn newest_sent_per_recipient( requests: impl IntoIterator, ) -> std::collections::BTreeMap { let mut newest: std::collections::BTreeMap = @@ -903,9 +1900,7 @@ fn newest_sent_per_recipient( let recipient = req.recipient_id; let replace = newest .get(&recipient) - .map(|cur| { - (req.created_at, req.account_reference) > (cur.created_at, cur.account_reference) - }) + .map(|cur| freshness(&req) > freshness(cur)) .unwrap_or(true); if replace { newest.insert(recipient, req); @@ -929,7 +1924,13 @@ pub(super) fn ingest_sent_sweep( fetch_ok: bool, ) -> bool { let newest_by_recipient = record_and_collapse_sent_requests(managed, requests); - let persisted = ingest_sent_requests(managed, persister, identity_id, newest_by_recipient); + let persisted = ingest_sent_requests( + managed, + persister, + identity_id, + newest_by_recipient, + &mut Vec::new(), + ); if fetch_ok && persisted { managed.mark_sent_sweep_completed(); } @@ -963,6 +1964,38 @@ fn record_and_collapse_sent_requests( newest_sent_per_recipient(requests) } +/// Whether `candidate` is older than `tracked`, a request between the same +/// pair: by its account reference's version, which a rotation bumps, then by +/// its creation time. A replay of an older request appended again later has a +/// newer time but an older version. +pub(super) fn predates(candidate: &ContactRequest, tracked: &ContactRequest) -> bool { + freshness(candidate) < freshness(tracked) +} + +/// Whether `tracked`, a request between one pair, is an unconfirmed request +/// carrying `account_reference` or supersedes it in the order [`predates`] +/// reads: the same reference, or a later version. The unconfirmed request is +/// not in the store yet, so it has no creation time; appended, it would be +/// the newest of its version. +pub(super) fn records_or_supersedes(tracked: &ContactRequest, account_reference: u32) -> bool { + tracked.account_reference == account_reference + || platform_encryption::account_reference_version(account_reference) + < platform_encryption::account_reference_version(tracked.account_reference) +} + +/// How fresh a request between one pair is, for collapsing a sweep's requests +/// and for passing over older ones alike: by its account reference's version, +/// which a rotation bumps, then by its creation time, then by the reference +/// itself so that equal times order deterministically. A replay of an older +/// request appended again later has a newer time but an older version. +fn freshness(request: &ContactRequest) -> (u32, u64, u32) { + ( + platform_encryption::account_reference_version(request.account_reference), + request.created_at, + request.account_reference, + ) +} + /// Ingest one identity's collapsed **received** contact requests into local /// state, returning whether every write reached disk. /// @@ -978,7 +2011,7 @@ fn record_and_collapse_sent_requests( /// /// Split out of the sweep so the persist-failure branches are reachable in a /// test without standing up a Platform that answers document queries. -fn ingest_received_requests( +pub(super) fn ingest_received_requests( managed: &mut crate::wallet::identity::ManagedIdentity, persister: &crate::wallet::persister::WalletPersister, identity_id: Identifier, @@ -1008,21 +2041,18 @@ fn ingest_received_requests( // tracked incoming/established state is a re-ingest of a known doc; a // DIFFERENT reference from a known sender is a rotation request // (receive side) and must get through. - let tracked_reference = managed - .dashpay() - .incoming_contact_requests() - .get(&sender_id) - .map(|r| r.account_reference) - .or_else(|| { - managed - .dashpay() - .established_contacts() - .get(&sender_id) - .map(|c| c.incoming_request.account_reference) - }); + let tracked = managed.dashpay().incoming_request(&sender_id); + let tracked_reference = tracked.map(|r| r.account_reference); if tracked_reference == Some(contact_request.account_reference) { continue; } + // An older request than the tracked one is no rotation: one channel's + // sweep can replay a request the other channel already superseded (a + // cold start scans the private store from its start), and taking it + // would roll the contact back to a retired xpub. + if tracked.is_some_and(|tracked| predates(&contact_request, tracked)) { + continue; + } if tracked_reference.is_some() { // Rotation: supersede the tracked request. When an established @@ -1062,20 +2092,43 @@ fn ingest_received_requests( /// /// `add_sent_contact_request` carries its own duplicate / metadata-loss guard, /// so re-ingesting the same range on the next sweep is safe. -fn ingest_sent_requests( +/// +/// `recorded` gets each request this recorded: not one already tracked with +/// the same account reference, a replay, or one whose store failed. +pub(super) fn ingest_sent_requests( managed: &mut ManagedIdentity, persister: &WalletPersister, identity_id: Identifier, newest_by_recipient: std::collections::BTreeMap, + recorded: &mut Vec, ) -> bool { - for (_recipient_id, contact_request) in newest_by_recipient { - if let Err(e) = managed.add_sent_contact_request(contact_request, persister) { + for (recipient_id, contact_request) in newest_by_recipient { + // An older request than the tracked one is a replay, as on the + // received side: superseding with it would re-derive the next rotation + // from a retired reference. + let (replay, tracked) = + managed + .dashpay() + .outgoing_request(&recipient_id) + .map_or((false, false), |tracked| { + ( + predates(&contact_request, tracked), + tracked.account_reference == contact_request.account_reference, + ) + }); + if replay { + continue; + } + if let Err(e) = managed.add_sent_contact_request(contact_request.clone(), persister) { tracing::error!( owner = %identity_id, error = %e, "sent-request ingest persist failed; leaving sent cursor for retry" ); return false; } + if !tracked { + recorded.push(contact_request); + } } true } @@ -1149,6 +2202,61 @@ pub(crate) fn budget_spent(deadline: Option) -> bool { deadline.is_some_and(|d| std::time::Instant::now() >= d) } +/// Tears down the external (sending) accounts of `identity_id`'s contacts that +/// must be rebuilt: those `rotated` this pass, re-keyed by a rotation request, +/// and any registered account not built from its contact's current incoming +/// request. Removes both the immutable `Account` (old xpub, `send_payment`'s +/// derivation source) and the managed wrapper (old address pool); the account +/// build sweep then re-queues them and re-registers from the current xpub, and +/// the persisted account row is upserted (same unique key) when that round +/// lands. +/// +/// The second case is the rotation self-heal across a restart: an external +/// account rebuilt from the persisted (tombstone-less) registration row can +/// carry the STALE xpub while the established contact already tracks the new +/// incoming reference (the deferred rebuild was lost with the in-memory queue +/// at load). Such an account exists but was not built from the current +/// reference, so the plain "has an external account" gate would skip it +/// forever: a recorded `external_account_reference` that does not match the +/// contact's current `incoming_request.account_reference`, including a `None` +/// marker from a cold restore that did not carry it, queues it here. +/// Idempotent: once rebuilt the marker is stamped and the next sweep skips it. +pub(super) fn tear_down_stale_external_accounts( + wallet: &mut key_wallet::wallet::Wallet, + info: &mut PlatformWalletInfo, + identity_id: &Identifier, + mut rotated: Vec, +) { + use key_wallet::account::account_collection::DashpayAccountKey; + let key_for = |contact_id: &Identifier| DashpayAccountKey { + index: 0, + user_identity_id: identity_id.to_buffer(), + friend_identity_id: contact_id.to_buffer(), + }; + if let Some(managed) = info.identity_manager.managed_identity(identity_id) { + for (contact_id, contact) in managed.dashpay().established_contacts().iter() { + let has_external = info + .core_wallet + .accounts + .dashpay_external_accounts + .contains_key(&key_for(contact_id)); + if external_account_needs_rebuild(contact, has_external) + && !rotated.contains(contact_id) + { + rotated.push(*contact_id); + } + } + } + for contact_id in &rotated { + let key = key_for(contact_id); + wallet.accounts.dashpay_external_accounts.remove(&key); + info.core_wallet + .accounts + .dashpay_external_accounts + .remove(&key); + } +} + /// Whether a registered outbound `DashpayExternalAccount` for `contact` /// must be torn down + rebuilt because it was NOT built from the contact's /// current `incoming_request.account_reference`. @@ -1438,6 +2546,10 @@ impl DashPayView<'_, B> { pub async fn sync_contact_requests_reporting( &self, ) -> Result { + // Public requests whose outcome is unconfirmed are settled first, so + // one proved on Platform is recorded, and one that can no longer + // execute frees its pair, before anything is decided from this pass. + self.settle_unconfirmed_public_requests().await; // Snapshot each identity's high-water cursors up front so the // incremental query bound is read before any mutation this sweep. let identities: Vec<(Identifier, Option, Option)> = { @@ -1623,69 +2735,6 @@ impl DashPayView<'_, B> { let sent_persist_ok = ingest_sent_sweep(managed, &self.persister, identity_id, parsed_sent, sent_ok); - // (2a') Rotation self-heal across restart: an external account - // rebuilt from the persisted (tombstone-less) registration - // row after a restart can carry the STALE xpub while the - // established contact already tracks the new incoming - // reference (the deferred rebuild was lost with the - // in-memory queue at load). Such an account exists but was - // NOT built from the current reference, so the plain - // `has_external` gate would skip it forever. Detect a - // registered external account whose recorded - // `external_account_reference` does not match the contact's - // current `incoming_request.account_reference` (including a - // `None` marker from a cold restore that didn't carry it), - // and enqueue it for teardown + rebuild alongside the - // in-pass rotations. Idempotent: once rebuilt the marker is - // stamped, so the next sweep sees a match and skips it. - // Accesses the managed identity's established contacts and - // `info.core_wallet` as DISJOINT fields of `info` via a - // plain `for` loop (the same split the teardown loop below - // relies on) — a closure capturing whole `info` would - // collide with the mutable `managed` reborrow. - { - use key_wallet::account::account_collection::DashpayAccountKey; - for (contact_id, contact) in managed.dashpay().established_contacts().iter() { - let key = DashpayAccountKey { - index: 0, - user_identity_id: identity_id.to_buffer(), - friend_identity_id: contact_id.to_buffer(), - }; - let has_external = info - .core_wallet - .accounts - .dashpay_external_accounts - .contains_key(&key); - if external_account_needs_rebuild(contact, has_external) - && !rotated_contacts.contains(contact_id) - { - rotated_contacts.push(*contact_id); - } - } - } - - // (2b) Tear down stale external accounts for contacts that - // rotated in this pass: both the immutable Account - // (old xpub — `send_payment`'s derivation source) and - // the managed wrapper (old address pool). The - // candidate collection below then re-queues them and - // the build step re-registers from the NEW encrypted - // xpub. The persisted account row is upserted (same - // unique key) when the re-registration round lands. - for contact_id in &rotated_contacts { - use key_wallet::account::account_collection::DashpayAccountKey; - let key = DashpayAccountKey { - index: 0, - user_identity_id: identity_id.to_buffer(), - friend_identity_id: contact_id.to_buffer(), - }; - wallet.accounts.dashpay_external_accounts.remove(&key); - info.core_wallet - .accounts - .dashpay_external_accounts - .remove(&key); - } - // Advance the high-water cursors to the max `$createdAt` // fetched this sweep, never below the current value. Advance a // direction's cursor only when BOTH its fetch succeeded AND @@ -1716,6 +2765,11 @@ impl DashPayView<'_, B> { report.unpersisted_identities.push(identity_id); } + // (2a', 2b) Tear down the external accounts of contacts re-keyed + // this pass, or rebuilt after a restart from a stale + // xpub, so the build below re-registers them. + tear_down_stale_external_accounts(wallet, info, &identity_id, rotated_contacts); + // (3) Collect missing receiving accounts for sent-only // requests and account pairs for established contacts. Self::collect_account_build_candidates(info, &identity_id) @@ -1888,9 +2942,10 @@ impl DashPayView<'_, B> { }) .collect(); - // Serialize the queue write with identity removal under the same guard. + // Serialize the queue write with identity removal under the same guard, + // and fence it to this handle's generation. let mut wm = self.wallet_manager.write().await; - let Some(info) = wm.get_wallet_info_mut(&self.wallet_id) else { + let Ok(info) = self.current_wallet_info_mut(&mut wm) else { return; }; let Some(managed) = info.identity_manager.managed_identity_mut(identity_id) else { @@ -2005,7 +3060,7 @@ impl DashPayView<'_, B> { /// /// Called **after** the sync write guard is dropped: this re-acquires /// the non-reentrant wallet-manager lock. - async fn build_contact_accounts( + pub(super) async fn build_contact_accounts( &self, identity_id: &Identifier, candidate: AccountBuildCandidate, @@ -2086,9 +3141,10 @@ impl DashPayView<'_, B> { }); } - // Serialize the queue write with identity removal under the same guard. + // Serialize the queue write with identity removal under the same guard, + // and fence it to this handle's generation. let mut wm = self.wallet_manager.write().await; - let Some(info) = wm.get_wallet_info_mut(&self.wallet_id) else { + let Ok(info) = self.current_wallet_info_mut(&mut wm) else { return; }; let Some(managed) = info.identity_manager.managed_identity_mut(identity_id) else { @@ -3496,6 +4552,14 @@ impl DashPayView<'_, B> { /// [`Self::send_contact_request_with_external_signer`] so signing /// crosses the FFI via the supplied `&S: Signer`. /// Same ECDH caveat applies — see that method's docstring. + /// + /// A request that came privately is refused with + /// [`PlatformWalletError::PrivateContactRequestNeedsPrivateReply`]: a + /// `contactRequest` document in reply would publish the relationship the + /// sender kept off chain. It is accepted with + /// `accept_private_contact_request`. The store is read first as the send + /// reads it, so the refusal and the reply it adopts see a private reply + /// sent in an earlier process. pub async fn accept_contact_request_with_external_signer( &self, request: &ContactRequest, @@ -3505,13 +4569,80 @@ impl DashPayView<'_, B> { where S: Signer + Send + Sync, C: ContactCryptoProvider + Sync, + { + Box::pin(self.read_private_store_before_deciding(&request.recipient_id, crypto)).await?; + if self.needs_private_reply(request).await { + return Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply( + request.sender_id, + )); + } + self.accept_contact_request_replying_with(request, crypto, || async { + Ok( + match self + .send_public_contact_request( + &request.recipient_id, + &request.sender_id, + None, + AutoAcceptProofSource::None, + signer, + crypto, + true, + ) + .await? + { + Some(_) => ReplyOutcome::Sent, + None => ReplyOutcome::AlreadyReplied, + }, + ) + }) + .await + } + + /// Whether accepting `request` takes a private reply: it, or the request + /// tracked from its sender, came privately, and we have sent the sender + /// no request yet. A reply already sent, either way, is adopted without a + /// broadcast, so only a reply still to send would publish anything. + pub(super) async fn needs_private_reply(&self, request: &ContactRequest) -> bool { + let wm = self.wallet_manager.read().await; + wm.get_wallet_info(&self.wallet_id) + .and_then(|info| { + info.identity_manager + .managed_identity(&request.recipient_id) + }) + .is_some_and(|managed| { + let dashpay = managed.dashpay(); + (request.came_privately() + || dashpay + .incoming_request(&request.sender_id) + .is_some_and(ContactRequest::came_privately)) + && dashpay.outgoing_request(&request.sender_id).is_none() + }) + } + + /// Accept `request`, with `send_reply` sending our reciprocal request to + /// its sender unless one already exists: the body of + /// [`Self::accept_contact_request_with_external_signer`], shared with the + /// private accept, which replies privately. `send_reply` reports a reply + /// tracked by the time it claimed or reserved the pair (another accept's, + /// recorded in between) as [`ReplyOutcome::AlreadyReplied`], and that + /// reply is adopted as one found here first is: nothing is sent or paid. + pub(super) async fn accept_contact_request_replying_with( + &self, + request: &ContactRequest, + crypto: &C, + send_reply: R, + ) -> Result + where + C: ContactCryptoProvider + Sync, + R: FnOnce() -> Fut, + Fut: std::future::Future>, { let our_identity_id = request.recipient_id; let sender_id = request.sender_id; // 1. Verify the incoming request is known, and detect whether an // on-platform reciprocal already exists for this pair. - let (already_established, already_reciprocated) = { + let (_, already_reciprocated) = { let wm = self.wallet_manager.read().await; let info = wm .get_wallet_info(&self.wallet_id) @@ -3559,7 +4690,9 @@ impl DashPayView<'_, B> { // fresh-send local registrations below (receiving account + // validate→decrypt→register external), so the contact becomes // payable without a duplicate broadcast. - if already_reciprocated { + let adopt = + already_reciprocated || matches!(send_reply().await?, ReplyOutcome::AlreadyReplied); + if adopt { tracing::info!( our_identity = %our_identity_id, contact = %sender_id, @@ -3579,19 +4712,27 @@ impl DashPayView<'_, B> { // path the normal flow and the sync sweep use), so the final lookup // is guaranteed non-`None`. Idempotent: `add_incoming_contact_request` // preserves metadata on an already-established pair. - if !already_established { + { let mut wm = self.wallet_manager.write().await; let managed = wm .get_wallet_info_mut(&self.wallet_id) .and_then(|info| info.identity_manager.managed_identity_mut(&our_identity_id)) .ok_or(PlatformWalletError::IdentityNotFound(our_identity_id))?; - managed - .add_incoming_contact_request(request.clone(), &self.persister) - .map_err(|e| { - PlatformWalletError::Persistence(format!( - "accept-adopt: incoming request not persisted: {e}" - )) - })?; + // Read now: a reply adopted after `send_reply` may have + // established the pair since step 1. + if !managed + .dashpay() + .established_contacts() + .contains_key(&sender_id) + { + managed + .add_incoming_contact_request(request.clone(), &self.persister) + .map_err(|e| { + PlatformWalletError::Persistence(format!( + "accept-adopt: incoming request not persisted: {e}" + )) + })?; + } } // Adopt: register the receiving (friendship) account, derived via // the signer (no resident seed), matching the fresh-send path. @@ -3619,16 +4760,6 @@ impl DashPayView<'_, B> { "Accept-adopt: failed to derive receiving xpub via signer; will retry on next sweep" ), } - } else { - self.send_contact_request_with_external_signer( - &our_identity_id, - &sender_id, - None, - AutoAcceptProofSource::None, - signer, - crypto, - ) - .await?; } // 4. Validate key indices (same gate as the sync sweep and the @@ -4043,11 +5174,24 @@ impl DashPayView<'_, B> { // `unignore_sender` removes the sender + rewinds the cursor and // returns the removal changeset (empty if the sender wasn't // ignored). Persist it so the ignored-sender row is deleted. - let cs = managed.unignore_sender(contact_identity_id); + let mut cs = managed.unignore_sender(contact_identity_id); if ::is_empty(&cs) { // Not ignored — nothing to persist, but not an error. return Ok(()); } + // The private read position was rewound with the received cursor: a + // backend that keeps it stores the rewind, so a relaunch reads the + // un-ignored sender's private requests again too. + if self.persister.persists_private_contact_scan_state() { + cs.private_contact_requests_positions.insert( + *identity_id, + with_journaled_marker( + &self.persister, + *identity_id, + managed.private_contact_requests_position_record(), + ), + ); + } self.persister.store(cs.into()).map_err(|e| { PlatformWalletError::Persistence(format!("un-ignore not persisted: {e}")) })?; @@ -4410,6 +5554,137 @@ mod sweep_tests { assert_eq!(managed.dashpay().incoming_contact_requests().len(), 1); } + /// A request older than the tracked one, by its reference's version and + /// then its time, is passed over on both sides: one channel's sweep can + /// replay a request the other already superseded, and a replay appended + /// again later has a newer time but an older version. + #[test] + fn an_older_request_than_the_tracked_one_is_no_rotation() { + let our = 1u8; + let contact = 2u8; + let our_id = Identifier::from([our; 32]); + let contact_id = Identifier::from([contact; 32]); + let mut info = info_with_bare_identity(our); + let managed = info + .identity_manager + .managed_identity_mut(&our_id) + .expect("managed identity"); + let at = |sender: u8, recipient: u8, version: u32, account: u32, created_at: u64| { + let mut request = test_request( + sender, + recipient, + (version << ACCOUNT_REFERENCE_VERSION_SHIFT) | account, + ); + request.created_at = created_at; + request + }; + let tracked_incoming = |managed: &ManagedIdentity| { + managed + .dashpay() + .incoming_request(&contact_id) + .map(|request| request.account_reference) + }; + + let rotated = at(contact, our, 1, 5, 100); + for (case, candidate, expected) in [ + ( + "the rotated request", + rotated.clone(), + rotated.account_reference, + ), + ( + "a replay of the request it rotated past, appended later", + at(contact, our, 0, 4, 200), + rotated.account_reference, + ), + ( + "an earlier request of the same version", + at(contact, our, 1, 6, 50), + rotated.account_reference, + ), + ] { + assert!(ingest_received_requests( + managed, + &noop_persister(), + our_id, + newest_received_per_sender([candidate]), + &mut Vec::new(), + &mut Vec::new(), + )); + assert_eq!(tracked_incoming(managed), Some(expected), "{case}"); + } + let newer = at(contact, our, 2, 7, 300); + assert!(ingest_received_requests( + managed, + &noop_persister(), + our_id, + newest_received_per_sender([newer.clone()]), + &mut Vec::new(), + &mut Vec::new(), + )); + assert_eq!( + tracked_incoming(managed), + Some(newer.account_reference), + "a newer rotation is still taken" + ); + + let sent = at(our, contact, 1, 5, 100); + assert!(ingest_sent_requests( + managed, + &noop_persister(), + our_id, + newest_sent_per_recipient([sent.clone()]), + &mut Vec::new(), + )); + assert!(ingest_sent_requests( + managed, + &noop_persister(), + our_id, + newest_sent_per_recipient([at(our, contact, 0, 4, 200)]), + &mut Vec::new(), + )); + assert_eq!( + managed + .dashpay() + .outgoing_request(&contact_id) + .map(|request| request.account_reference), + Some(sent.account_reference), + "a replay of an older sent request does not supersede the tracked one" + ); + } + + /// Collapsing a sweep's requests orders them by version first, as ingest + /// passes over older ones: a rotation and a replay of the request it + /// rotated past, appended later, collapse to the rotation, both ways. + #[test] + fn a_sweep_collapses_to_the_highest_version_before_the_latest_time() { + let at = |sender: u8, recipient: u8, version: u32, account: u32, created_at: u64| { + let mut request = test_request( + sender, + recipient, + (version << ACCOUNT_REFERENCE_VERSION_SHIFT) | account, + ); + request.created_at = created_at; + request + }; + let rotation = at(2, 1, 1, 5, 200); + let replay = at(2, 1, 0, 4, 300); + assert_eq!( + newest_received_per_sender([rotation.clone(), replay.clone()]) + .get(&Identifier::from([2u8; 32])) + .map(|request| request.account_reference), + Some(rotation.account_reference) + ); + let sent_rotation = at(1, 2, 1, 5, 200); + let sent_replay = at(1, 2, 0, 4, 300); + assert_eq!( + newest_sent_per_recipient([sent_replay, sent_rotation.clone()]) + .get(&Identifier::from([2u8; 32])) + .map(|request| request.account_reference), + Some(sent_rotation.account_reference) + ); + } + /// The first-ingest persist failure (`add_incoming_contact_request`). /// The request is not tracked and must not be reported as newly /// discovered — a caller that took it as real would act on a request that @@ -4502,7 +5777,8 @@ mod sweep_tests { managed, &failing_persister(), our_id, - newest + newest, + &mut Vec::new() )); // Control on the same fixture: the write succeeds, so the ingest @@ -4512,7 +5788,8 @@ mod sweep_tests { managed, &noop_persister(), our_id, - newest + newest, + &mut Vec::new() )); } @@ -4607,6 +5884,11 @@ mod sweep_tests { ), "precondition: the failed write must report the pass incomplete" ); + assert_eq!( + all_requests, + vec![], + "a request whose store failed is not reported" + ); assert!( managed.dashpay().incoming_contact_requests().is_empty(), "a request that never reached disk must not be tracked in memory, or the \ @@ -4721,6 +6003,49 @@ mod sweep_tests { ); } + /// The sent ingest reports what it recorded: a new request, not one whose + /// store failed nor one already tracked. + #[test] + fn should_report_only_what_a_sent_ingest_recorded() { + let our = 1u8; + let our_id = Identifier::from([our; 32]); + let mut info = info_with_bare_identity(our); + let managed = info + .identity_manager + .managed_identity_mut(&our_id) + .expect("managed identity"); + let request = test_request(our, 2, 0); + + let mut recorded = Vec::new(); + assert!(!ingest_sent_requests( + managed, + &failing_persister(), + our_id, + newest_sent_per_recipient([request.clone()]), + &mut recorded, + )); + assert_eq!(recorded, vec![], "a request whose store failed"); + + assert!(ingest_sent_requests( + managed, + &noop_persister(), + our_id, + newest_sent_per_recipient([request.clone()]), + &mut recorded, + )); + assert_eq!(recorded, vec![request.clone()], "a new request"); + + let mut again = Vec::new(); + assert!(ingest_sent_requests( + managed, + &noop_persister(), + our_id, + newest_sent_per_recipient([request]), + &mut again, + )); + assert_eq!(again, vec![], "a request already tracked"); + } + /// Branch 3, the fresh sent request (`add_sent_contact_request`). Its /// same-reference no-op guard returns `Ok(())`, so a memory-committed /// failed write makes the retry report success without storing anything. @@ -4737,7 +6062,13 @@ mod sweep_tests { // Sweep 1: the write fails. let newest = newest_sent_per_recipient([test_request(our, 2, 0)]); assert!( - !ingest_sent_requests(managed, &failing_persister(), our_id, newest), + !ingest_sent_requests( + managed, + &failing_persister(), + our_id, + newest, + &mut Vec::new() + ), "precondition: the failed write must report the pass incomplete" ); assert!( @@ -4750,7 +6081,7 @@ mod sweep_tests { let (persister, backend) = counting_persister(); let newest = newest_sent_per_recipient([test_request(our, 2, 0)]); assert!( - ingest_sent_requests(managed, &persister, our_id, newest), + ingest_sent_requests(managed, &persister, our_id, newest, &mut Vec::new()), "the retry must complete the pass" ); @@ -6112,6 +7443,108 @@ mod stamp_race_tests { } } +/// Where a contact request send's signing stands, for [`GatedSigner`]. +enum SigningGate { + /// The host has not signed yet: no gate is held. + Unsigned, + /// Signed, and the wallet generation's lifecycle gate is held from then + /// on, until the send ends: kept for its drop. + Gated { + _gate: tokio::sync::OwnedRwLockReadGuard<()>, + }, + /// Signed after the wallet was removed or replaced: nothing goes out. + Removed, +} + +/// The host's signer for a contact request send, taking the wallet +/// generation's lifecycle gate once a signature returns and before it can +/// leave: the SDK broadcasts right after signing, so the broadcast and the +/// send's bookkeeping run under the gate, while the host's signing prompt +/// does not. A signature made after the wallet was removed, or re-created +/// under its id, is refused, so nothing is published. +struct GatedSigner<'a, S: ?Sized, B: TransactionBroadcaster + ?Sized> { + signer: &'a S, + wallet: &'a IdentityWallet, + gate: std::sync::Mutex, +} + +impl GatedSigner<'_, S, B> { + fn gate(&self) -> std::sync::MutexGuard<'_, SigningGate> { + self.gate + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + } + + /// Whether a signature was refused because the wallet was removed or + /// replaced while the host signed. + fn removed(&self) -> bool { + matches!(*self.gate(), SigningGate::Removed) + } + + /// Take the lifecycle gate after a signature, unless held already, and + /// check the wallet is still current under it. The gate is taken before + /// the wallet manager's lock, as the lock ordering requires. + async fn hold_gate_after_signing(&self) -> Result<(), dpp::ProtocolError> { + if matches!(*self.gate(), SigningGate::Gated { .. }) { + return Ok(()); + } + let guard = self.wallet.generation.payment_guard_owned().await; + let current = self + .wallet + .wallet_manager + .read() + .await + .get_wallet_info(&self.wallet.wallet_id) + .is_some_and(|info| Arc::ptr_eq(&info.generation, &self.wallet.generation)); + if current { + *self.gate() = SigningGate::Gated { _gate: guard }; + Ok(()) + } else { + *self.gate() = SigningGate::Removed; + Err(dpp::ProtocolError::Generic( + "the wallet was removed while the host signed: nothing is sent".to_string(), + )) + } + } +} + +impl std::fmt::Debug for GatedSigner<'_, S, B> { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str("GatedSigner") + } +} + +#[async_trait::async_trait] +impl Signer for GatedSigner<'_, S, B> +where + S: Signer + ?Sized + Send + Sync, + B: TransactionBroadcaster + ?Sized + Send + Sync, +{ + async fn sign( + &self, + key: &IdentityPublicKey, + data: &[u8], + ) -> Result { + let signature = self.signer.sign(key, data).await?; + self.hold_gate_after_signing().await?; + Ok(signature) + } + + async fn sign_create_witness( + &self, + key: &IdentityPublicKey, + data: &[u8], + ) -> Result { + let witness = self.signer.sign_create_witness(key, data).await?; + self.hold_gate_after_signing().await?; + Ok(witness) + } + + fn can_sign_with(&self, key: &IdentityPublicKey) -> bool { + self.signer.can_sign_with(key) + } +} + #[cfg(test)] mod drain_budget_tests { use super::{bounded, budget_spent}; diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/dpns_marketplace.rs b/packages/rs-platform-wallet/src/wallet/identity/network/dpns_marketplace.rs index a448db29490..f54f1791730 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/dpns_marketplace.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/dpns_marketplace.rs @@ -3910,6 +3910,12 @@ mod tests { let wallet_id = wm .create_wallet_with_random_mnemonic(WalletAccountCreationOptions::None) .expect("create wallet"); + // The live generation, as `PlatformWallet::new` takes it. + let generation = Arc::clone( + &wm.get_wallet_info(&wallet_id) + .expect("the wallet's info") + .generation, + ); let wallet_manager = Arc::new(RwLock::new(wm)); let persister = WalletPersister::new(wallet_id, mirror); @@ -3934,6 +3940,7 @@ mod tests { persister, sync_fault: Arc::new(std::sync::atomic::AtomicBool::new(false)), durable_cursors: crate::changeset::DurableCursors::default(), + generation, broadcaster, sdk_writer: Arc::new(super::super::sdk_writer::SdkWriter::new(sdk)), dpns_operation_gate: Arc::new(tokio::sync::Mutex::new(())), diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/identity_handle.rs b/packages/rs-platform-wallet/src/wallet/identity/network/identity_handle.rs index 76634be498f..c8e7937b2e6 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/identity_handle.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/identity_handle.rs @@ -45,6 +45,7 @@ use zeroize::Zeroizing; use crate::broadcaster::{SpvBroadcaster, TransactionBroadcaster}; use crate::error::PlatformWalletError; use crate::wallet::asset_lock::manager::AssetLockManager; +use crate::wallet::core::WalletGeneration; use crate::wallet::platform_wallet::{PlatformWalletInfo, WalletId}; /// Default gap limit for identity discovery scanning. @@ -508,6 +509,11 @@ pub struct IdentityWallet { /// adapter and the DashPay rescan reconcile. See /// [`DurableCursors`](crate::changeset::DurableCursors). pub(crate) durable_cursors: crate::changeset::DurableCursors, + /// The wallet generation this handle belongs to: a public contact + /// request is sent only while it is the live one, under its lifecycle + /// gate, so a send started on a wallet since removed and re-created under + /// the same id never publishes or records on the replacement. + pub(crate) generation: Arc, /// Broadcaster for DashPay payment transactions. Distinct from the /// asset-lock broadcaster — the asset-lock manager is always /// `SpvBroadcaster`-pinned, while this one picks the broadcaster @@ -551,6 +557,7 @@ impl Clone for IdentityWallet { persister: self.persister.clone(), sync_fault: Arc::clone(&self.sync_fault), durable_cursors: Arc::clone(&self.durable_cursors), + generation: Arc::clone(&self.generation), broadcaster: Arc::clone(&self.broadcaster), sdk_writer: Arc::clone(&self.sdk_writer), dpns_operation_gate: Arc::clone(&self.dpns_operation_gate), @@ -560,6 +567,32 @@ impl Clone for IdentityWallet { } impl IdentityWallet { + /// This handle's wallet in `wm`, the wallet manager under its write lock, + /// while it is still this handle's generation: refused, as not found, once + /// the wallet was removed, or re-created under its id, since the handle + /// was taken. Work that ran without the wallet's lifecycle gate (network + /// reads, host key resolution) applies its results through this, so a + /// replacement never receives a stale handle's state: the check and the + /// write are under the one lock a removal takes. + pub(crate) fn current_wallet_info_mut<'w>( + &self, + wm: &'w mut WalletManager, + ) -> Result<&'w mut PlatformWalletInfo, PlatformWalletError> { + wm.get_wallet_info_mut(&self.wallet_id) + .filter(|info| Arc::ptr_eq(&info.generation, &self.generation)) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id))) + } + + /// [`Self::current_wallet_info_mut`], with the wallet itself. + pub(crate) fn current_wallet_and_info_mut<'w>( + &self, + wm: &'w mut WalletManager, + ) -> Result<(&'w mut Wallet, &'w mut PlatformWalletInfo), PlatformWalletError> { + wm.get_wallet_mut_and_info_mut(&self.wallet_id) + .filter(|(_, info)| Arc::ptr_eq(&info.generation, &self.generation)) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id))) + } + /// Build the DIP-9 identity authentication derivation path. /// /// Path format: `m/9'/coin_type'/5'/0'/key_type'/identity_index'/key_id'` diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/loading.rs b/packages/rs-platform-wallet/src/wallet/identity/network/loading.rs index 19e591bbe2e..c0d63b5afe3 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/loading.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/loading.rs @@ -6,8 +6,11 @@ use dpp::identity::Identity; use dpp::prelude::Identifier; use key_wallet::bip32::ExtendedPrivKey; +use crate::broadcaster::TransactionBroadcaster; use crate::error::PlatformWalletError; +use crate::wallet::identity::state::managed_identity::key_storage::IdentityStatus; use crate::BlockTime; +use dash_sdk::platform::Fetch; use super::*; @@ -345,60 +348,16 @@ impl IdentityWallet { &self, identity_id: &Identifier, ) -> Result { - use crate::wallet::identity::state::managed_identity::key_storage::IdentityStatus; - use dash_sdk::platform::Fetch; - - // Verify identity exists in the manager. - { - let wm = self.wallet_manager.read().await; - let info = wm.get_wallet_info(&self.wallet_id).ok_or_else(|| { - crate::error::PlatformWalletError::WalletNotFound( - "Wallet info not found in wallet manager".to_string(), - ) - })?; - if info.identity_manager.identity(identity_id).is_none() { - return Err(PlatformWalletError::IdentityNotFound(*identity_id)); - } - } - - // Fetch the latest state from Platform. - let (identity, metadata) = Identity::fetch_with_metadata(&self.sdk, *identity_id, None) + self.fetch_and_fold_identity(identity_id) .await - .map_err(|e| { - PlatformWalletError::InvalidIdentityData(format!( + .map(|(identity, _)| identity) + .map_err(|error| match error { + PlatformWalletError::Sdk(e) => PlatformWalletError::InvalidIdentityData(format!( "Failed to fetch identity {} from Platform: {}", identity_id, e - )) - })?; - let mut identity = identity.ok_or_else(|| { - PlatformWalletError::InvalidIdentityData(format!( - "Identity {} not found on Platform", - identity_id - )) - })?; - let block_time = BlockTime::from(metadata); - - // Update the managed identity. - { - let mut wm = self.wallet_manager.write().await; - let info = wm.get_wallet_info_mut(&self.wallet_id).ok_or_else(|| { - crate::error::PlatformWalletError::WalletNotFound( - "Wallet info not found in wallet manager".to_string(), - ) - })?; - if let Some(managed) = info.identity_manager.managed_identity_mut(identity_id) { - managed.status = IdentityStatus::Active; - if let Err(e) = - managed.store_fetched_identity(&identity, block_time, &self.persister) - { - tracing::error!("Failed to persist changeset: {}", e); - } - // The cache as folded. - identity = managed.identity.clone(); - } - } - - Ok(identity) + )), + other => other, + }) } /// Refresh an identity using an externally-provided identity ID. @@ -531,6 +490,63 @@ impl IdentityWallet { } } +impl IdentityWallet { + /// [`IdentityWallet::refresh_identity`]'s fetch and fold, generic over the + /// broadcaster, with a fetch that fails coming back as the SDK reported it + /// ([`PlatformWalletError::Sdk`]): the fetch is proved, a stale node + /// included (`dash_sdk::Error::StaleNode`). Applied only while the wallet + /// is still this handle's generation (`current_wallet_info_mut`). Returns + /// the identity the cache holds afterwards, and the height the fetch was + /// proved at. + pub(crate) async fn fetch_and_fold_identity( + &self, + identity_id: &Identifier, + ) -> Result<(Identity, u64), PlatformWalletError> { + // Verify identity exists in the manager. + { + let wm = self.wallet_manager.read().await; + let info = wm.get_wallet_info(&self.wallet_id).ok_or_else(|| { + PlatformWalletError::WalletNotFound( + "Wallet info not found in wallet manager".to_string(), + ) + })?; + if info.identity_manager.identity(identity_id).is_none() { + return Err(PlatformWalletError::IdentityNotFound(*identity_id)); + } + } + + // Fetch the latest state from Platform. + let (identity, metadata) = + Identity::fetch_with_metadata(&self.sdk, *identity_id, None).await?; + let mut identity = identity.ok_or_else(|| { + PlatformWalletError::InvalidIdentityData(format!( + "Identity {} not found on Platform", + identity_id + )) + })?; + let proved_at = metadata.height; + let block_time = BlockTime::from(metadata); + + // Update the managed identity. + { + let mut wm = self.wallet_manager.write().await; + let info = self.current_wallet_info_mut(&mut wm)?; + if let Some(managed) = info.identity_manager.managed_identity_mut(identity_id) { + managed.status = IdentityStatus::Active; + if let Err(e) = + managed.store_fetched_identity(&identity, block_time, &self.persister) + { + tracing::error!("Failed to persist changeset: {}", e); + } + // The cache as folded. + identity = managed.identity.clone(); + } + } + + Ok((identity, proved_at)) + } +} + #[cfg(test)] mod tests { use super::super::identity_handle::{ diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/mod.rs b/packages/rs-platform-wallet/src/wallet/identity/network/mod.rs index d431d449039..babb0e9fee1 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/mod.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/mod.rs @@ -75,6 +75,14 @@ mod payments; pub(crate) use payments::{record_incoming_dashpay_payments, sent_payment_status_for_record}; mod prepared_payment; pub use prepared_payment::PreparedDashPayPayment; +mod private_contact_requests; +#[cfg(feature = "shielded")] +pub(crate) use private_contact_requests::{ + restore_journaled_private_payments, JournaledPrivatePayment, +}; +pub use private_contact_requests::{ + PaymentStarted, PrivateContactReadiness, PrivateContactSyncReport, PrivateDocumentKeyPaths, +}; mod profile; mod public_keys; pub use public_keys::{fetch_identity_public_keys, FetchedIdentityPublicKeys}; diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/payments.rs b/packages/rs-platform-wallet/src/wallet/identity/network/payments.rs index 757b71290a6..5060aa6295d 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/payments.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/payments.rs @@ -13429,6 +13429,7 @@ mod tests { persister: real.persister.clone(), sync_fault: Arc::clone(&real.sync_fault), durable_cursors: Arc::clone(&real.durable_cursors), + generation: Arc::clone(&real.generation), broadcaster: Arc::new(GatedRejectingBroadcaster { entered, release }), sdk_writer: Arc::clone(&real.sdk_writer), dpns_operation_gate: Arc::clone(&real.dpns_operation_gate), @@ -13470,6 +13471,7 @@ mod tests { persister: real.persister.clone(), sync_fault: Arc::clone(&real.sync_fault), durable_cursors: Arc::clone(&real.durable_cursors), + generation: Arc::clone(&real.generation), broadcaster: Arc::new(GatedBroadcaster { entered, release }), sdk_writer: Arc::clone(&real.sdk_writer), dpns_operation_gate: Arc::clone(&real.dpns_operation_gate), @@ -13525,6 +13527,7 @@ mod tests { persister: real.persister.clone(), sync_fault: Arc::clone(&real.sync_fault), durable_cursors: Arc::clone(&real.durable_cursors), + generation: Arc::clone(&real.generation), broadcaster: Arc::new(broadcaster), sdk_writer: Arc::clone(&real.sdk_writer), dpns_operation_gate: Arc::clone(&real.dpns_operation_gate), diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/private_contact_requests.rs b/packages/rs-platform-wallet/src/wallet/identity/network/private_contact_requests.rs new file mode 100644 index 00000000000..3425470a24a --- /dev/null +++ b/packages/rs-platform-wallet/src/wallet/identity/network/private_contact_requests.rs @@ -0,0 +1,13640 @@ +//! DashPay private contact requests (protocol version 15): send, sync, accept. +//! +//! A private contact request is an entry of DashPay's `privateContactRequest` +//! store, sealed to one of the recipient's DashPay keys and appended by a +//! transition paid from the shielded pool, so nothing on chain names either +//! side. The sender names itself and its encryption key inside, signs it with +//! the identity signer it signs transitions with, and seals with the outgoing +//! viewing key of the encryption key, so a wallet restored from seed recovers +//! what it sent. +//! +//! The wallet keeps a private request as it keeps a public one, a +//! [`ContactRequest`], so contacts establish, rotate and get their DashPay +//! accounts the same way whichever way a request came. The entry carries the +//! compact xpub and the label in the clear; the wallet encrypts them under the +//! pair's DIP-15 shared key, as a `contactRequest` document carries them, with +//! IVs from the entry's commitment so a rescan rebuilds the same record, and at +//! core height 0, which no `contactRequest` document has: that a request came +//! privately is the record's own ([`ContactRequest::came_privately`]), so it +//! holds across restarts. The contact's shielded address, which a +//! `ContactRequest` has no field for, is kept in memory and read with +//! [`PrivateContact`]. +//! +//! The store is opened and requests are sealed inside the +//! [`ContactCryptoProvider`], which keeps the key material; requests are signed +//! by the identity signer. Checking an entry needs no secret key. +//! +//! [`PrivateContact`]: crate::wallet::identity::PrivateContact + +use std::collections::{BTreeMap, BTreeSet}; +use std::future::Future; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::Arc; + +use dash_sdk::dapi_grpc::platform::v0::ResponseMetadata; +use dash_sdk::error::StaleNodeError; +use dash_sdk::platform::dashpay::{ + private_contact_request_identities, private_contact_request_signature, + private_contact_request_signing_data, private_contact_request_signing_keys, + private_contact_requests_from_scan, recipient_key_purpose_is_valid, PrivateContactRequest, + ProvedIdentity, RejectedPrivateContactRequest, PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, +}; +use dash_sdk::platform::private_document_entries::{PrivateDocumentEntries, PrivateDocumentEntry}; +use dash_sdk::platform::private_document_scan::{ + PrivateDocumentPageHeights, PrivateDocumentScanKeys, + MAX_CONCURRENT_PRIVATE_DOCUMENT_PAGE_FETCHES, +}; +use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::document_type::decode_private_document_payload; +use dpp::identity::accessors::IdentityGettersV0; +use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; +use dpp::identity::identity_public_key::Purpose; +use dpp::identity::signer::Signer; +use dpp::identity::{Identity, IdentityPublicKey, KeyID, KeyType}; +use dpp::platform_value::BinaryData; +use dpp::prelude::Identifier; +use dpp::secp256k1::rand::rngs::StdRng; +use dpp::secp256k1::rand::{RngCore, SeedableRng}; +use dpp::secp256k1::{PublicKey, SecretKey}; +use futures::StreamExt; +use key_wallet::bip32::{DerivationPath, KeyDerivationType}; +use key_wallet_manager::WalletManager; +use platform_encryption::{encrypt_account_label, encrypt_extended_public_key, COMPACT_XPUB_LEN}; +use tokio::sync::RwLock; +use zeroize::Zeroizing; + +use super::contact_requests::{ + ingest_received_requests, ingest_sent_requests, newest_received_per_sender, + newest_sent_per_recipient, predates, records_or_supersedes, tear_down_stale_external_accounts, + AutoAcceptProofSource, ContactCryptoProvider, PreparedContactRequest, ReplyOutcome, +}; +use super::signing_key::first_available; +use super::{dashpay_contract, DashPayView, IdentityWallet}; +use crate::broadcaster::TransactionBroadcaster; +use crate::changeset::{ContactChangeSet, PersistenceError, PrivateContactRequestsPosition}; +use crate::error::PlatformWalletError; +use crate::wallet::core::WalletGeneration; +use crate::wallet::identity::types::dashpay::contact_request::ContactRequest; +use crate::wallet::identity::types::dashpay::established_contact::EstablishedContact; +use crate::wallet::identity::ManagedIdentity; +use crate::wallet::persister::WalletPersister; +use crate::wallet::platform_wallet::{PlatformWalletInfo, WalletId}; + +/// The paths of the keys a wallet's identities read DashPay's private contact +/// request store with, for a [`ContactCryptoProvider`] to derive inside the +/// signer. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct PrivateDocumentKeyPaths { + /// Each identity entries may be sealed to, with the path of each of its + /// keys an entry may be sealed to, by key id. + pub recipients: Vec<(Identifier, Vec<(KeyID, DerivationPath)>)>, + /// Each identity that may have sealed entries, with the id and path of + /// each of its encryption keys: one outgoing viewing key each. + pub senders: Vec<(Identifier, KeyID, DerivationPath)>, +} + +impl PrivateDocumentKeyPaths { + /// The scan keys these paths derive to, `derive` deriving the secret key at + /// a path: for a provider implementation to build inside the signer and + /// drop there. + pub fn scan_keys( + &self, + derive: impl FnMut(&DerivationPath) -> Result, + ) -> Result { + PrivateDocumentScanKeys::derive(&self.recipients, &self.senders, derive) + } +} + +/// What a contact request from one of the wallet's identities waits for, as +/// the wallet decides it ([`DashPayView::private_contact_readiness`]), so a +/// host shows it rather than inferring it from the refusals it got. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct PrivateContactReadiness { + /// Whether the reservations of the wallet's private payments are restored + /// for the identity. While false, its contact requests, sent or accepted, + /// public or private, are refused with + /// [`PlatformWalletError::PrivateContactPaymentsNotRestored`]: in a build + /// with the `shielded` feature, the wallet was published with no shielded + /// store configured while its persister keeps the private scan state, it + /// bound a shielded account before it was loaded, or its last restoration + /// failed or waits for a busy store; in every build, the identity was + /// loaded marking a private payment that may be unresolved. Configuring + /// the shielded store, or binding the wallet's shielded account, restores + /// them, and a contact request retries a failed restoration once; no + /// private sync does. A build without the `shielded` feature never does. + pub private_payments_restored: bool, + /// Whether a private sync read DashPay's private contact request store to + /// its end for the identity with its current keys. Every contact request + /// and acceptance reads it again from the cursor before it is decided, and + /// is refused with [`PlatformWalletError::PrivateContactStoreNotRead`] + /// while that read cannot finish. + pub private_store_read: bool, + /// Whether a private contact request the identity paid for may still be + /// unresolved: the marker its position record stores + /// (`PrivateContactRequestsPosition::private_payments_unresolved`), set + /// while it holds a private request it is paying for or has not read back. + /// A contact's own pending request is + /// [`DashPayState::private_reply_pending`](crate::wallet::identity::DashPayState::private_reply_pending). + /// A payment the shielded store's journal keeps unresolved counts too, as + /// a send holds its pair (`DashPayView::private_pair_held`). + pub unresolved_private_payment: bool, + /// Why the last restoration of the wallet's private payments failed, while + /// `private_payments_restored` is false for it and none succeeded since: + /// `None` when none failed, so the payments are only not restored yet. + pub private_payments_restore_failure: Option, +} + +/// What a pass over DashPay's private contact request store did. +#[derive(Clone, Debug, Default)] +pub struct PrivateContactSyncReport { + /// The store pages read. + pub pages_read: usize, + /// The requests this pass recorded, received and sent, as the wallet + /// records them: new ones and rotations. Not one already tracked, an + /// ignored sender's, a replay older than the tracked one, or one whose + /// store failed. + pub requests: Vec, + /// Entries that opened for one of the wallet's identities but were + /// refused. + pub rejected: Vec, + /// The store position the pass stopped at. + pub next_position: u64, + /// Whether the pass read to the store's last entry. + pub complete: bool, + /// Identities whose ingest did not reach disk, or one of whose sent + /// requests could not be rebuilt for want of its recipient: their cursor + /// stays where it was, so the next pass reads their entries again. + pub unpersisted_identities: Vec, + /// Identities this pass read the store to its end for, with their current + /// keys and nothing held back + /// (`DashPayState::private_contact_requests_read`). One read to the end + /// by an earlier pass is not listed. + pub read_to_end: Vec, +} + +/// How many pages of the store a send reads back after paying: one window of +/// pages fetched at once, enough for an identity that synced recently, whose +/// new entry is in the last page or two. A request not read back within them +/// stays pending for a later sync. +const POST_SEND_SYNC_PAGES: usize = MAX_CONCURRENT_PRIVATE_DOCUMENT_PAGE_FETCHES; + +/// How many pages of the store each private sync reads that a contact +/// request or acceptance runs before it is decided +/// ([`DashPayView::read_private_store_before_deciding`]): sixteen windows of +/// pages fetched at once, from the identity's cursor. With the read position +/// kept across restarts, the read is from there to the end. +const PRIVATE_STORE_READ_PAGES: usize = 16 * MAX_CONCURRENT_PRIVATE_DOCUMENT_PAGE_FETCHES; + +/// How many fetched pages a sync scans at once, one key derivation for them +/// all: at most the pages in flight. +const PRIVATE_SCAN_BATCH_PAGES: usize = MAX_CONCURRENT_PRIVATE_DOCUMENT_PAGE_FETCHES; + +/// How many such syncs a contact request or acceptance runs before it +/// refuses with [`PlatformWalletError::PrivateContactStoreNotRead`]: a later +/// call goes on from where they stopped. +const PRIVATE_STORE_READ_PASSES: usize = 4; + +/// How many rounds of a store read and a proved fetch of the sender identity +/// a public request or acceptance runs to show the read covers the identity's +/// keys before it refuses +/// ([`DashPayView::read_private_store_before_deciding`]): one when the fetch +/// is proved at or above the pages read and the keys did not change. +const PRIVATE_KEY_COVERAGE_ATTEMPTS: usize = 3; + +/// Whether the private store read an identity's decisions rest on covers its +/// keys as a proved fetch shows them. +enum PrivateStoreCoverage { + /// Read to its end with the keys the fetch shows, every page proved at or + /// below the fetch; or an identity the private sync does not read for. + Covered, + /// Not read to its end with those keys: they changed, or no read finished. + Unread, + /// Read with them, but the fetch was proved below a page the read rests + /// on: a key added in between could have a request sealed to it there. + IdentityBelow { + identity_height: u64, + store_height: u64, + }, +} + +/// One of the wallet's identities, as a pass reads the store for it. +struct ScannedIdentity { + identity_id: Identifier, + identity_index: u32, + /// Its cursor when the pass last advanced it; a change under the pass is a + /// rewind, which the pass leaves alone. + position: u64, + /// Its ingest failed this pass: it is not advanced again until the next. + failed: bool, + /// Its cursor was rewound under the pass (unignoring a sender, or its + /// scanning keys changing): it is not advanced again this pass, so the + /// next reads from the rewound position. + rewound: bool, + /// The fingerprint of the keys the pass scans with for it + /// (`ManagedIdentity::private_scan_key_fingerprint`): progress made + /// with them holds only while they are still the identity's. + key_fingerprint: [u8; 32], +} + +impl ScannedIdentity { + /// Advance `managed`'s cursor to `next_position` once a page's ingest for + /// it reached disk: unless it was rewound under the pass, which stops it + /// advancing for the rest of the pass, as a later page's advance would + /// otherwise overwrite the rewind. + fn advance(&mut self, managed: &mut ManagedIdentity, next_position: u64) { + if self.failed || self.rewound { + return; + } + // Keys added under the pass opened nothing it read. + if !self.keys_current(managed) { + self.rewound = true; + return; + } + if managed.dashpay().private_contact_requests_position() != self.position { + self.rewound = true; + return; + } + managed.advance_private_contact_requests_position(self.position, next_position); + self.position = managed.dashpay().private_contact_requests_position(); + } + + /// Whether the keys the pass scans with are still the identity's, and + /// the ones its read position holds for. + fn keys_current(&self, managed: &ManagedIdentity) -> bool { + managed.private_scan_key_fingerprint() == self.key_fingerprint + && managed + .private_contact_requests_position_record() + .key_fingerprint + == self.key_fingerprint + } +} + +/// Handed to a private request's `pay`, which marks it right before anything +/// it does may reach the network. Until it is marked, a send dropped (a +/// cancelled accept, a timeout) releases its reservation, as nothing was paid +/// and no sync could settle it; once marked, the reservation stays for a +/// sync to settle. A `pay` that awaits anything first, such as resolving its +/// payment source, a spend key or a proof, marks it only after those. +/// +/// It also names the request it pays for ([`Self::account_reference`]), so +/// the payment's record can be saved with it and a restart restores the +/// reservation without opening the entry. +/// +/// A payment that marked it and then failed keeps the reservation too: its +/// transition may still execute. Only one whose transition provably never +/// left the wallet ([`Self::note_never_delivered`]) releases it. +#[derive(Clone, Debug, Default)] +pub struct PaymentStarted { + marked: Arc, + never_delivered: Arc, + account_reference: Option, + store_position: Option, +} + +impl PaymentStarted { + /// The payment may reach the network from now on. + pub fn mark(&self) { + self.marked.store(true, Ordering::Release); + } + + /// Whether [`Self::mark`] was called. + pub fn is_marked(&self) -> bool { + self.marked.load(Ordering::Acquire) + } + + /// The payment's transition provably never left the wallet, and the + /// shielded store's journal record of it is discharged: nothing can + /// execute it, so its reservation may be released. + #[cfg(feature = "shielded")] + pub(crate) fn note_never_delivered(&self) { + self.never_delivered.store(true, Ordering::Release); + } + + /// Whether the payment may have reached the network: it was marked + /// started, and its transition was not shown never to have left. + pub(crate) fn may_have_reached_network(&self) -> bool { + self.is_marked() && !self.never_delivered.load(Ordering::Acquire) + } + + /// The account reference of the private request this payment is for, + /// when the send handed it over. + pub fn account_reference(&self) -> Option { + self.account_reference + } + + /// The sender identity's private store read position when the send paid: + /// its entry is appended at or after it, so the payment's journal record + /// keeps it for the expiry's read of the store to start there + /// (`PrivatePaymentRecord::store_position`). + pub fn store_position(&self) -> Option { + self.store_position + } + + /// The same token, naming the request with `account_reference`, sent from + /// `store_position`. + fn for_request(&self, account_reference: u32, store_position: u64) -> Self { + Self { + marked: Arc::clone(&self.marked), + never_delivered: Arc::clone(&self.never_delivered), + account_reference: Some(account_reference), + store_position: Some(store_position), + } + } +} + +/// The reservation one send attempt holds on the private request to a +/// recipient that may be in flight. Dropped before its payment is marked +/// started ([`PaymentStarted`]), it releases the reservation: a send +/// cancelled before it pays leaves nothing pending. Once the payment may +/// have started, or the send kept it, the reservation stays for the sync. +struct PrivateReplyReservation { + wallet_manager: Arc>>, + persister: WalletPersister, + wallet_id: WalletId, + /// The wallet generation the reservation was taken on: its release acts + /// only on that generation, so a wallet removed and re-created under its + /// id since is left alone. + generation: Arc, + sender: Identifier, + recipient: Identifier, + attempt: u64, + payment_started: PaymentStarted, + /// Whether the payment may have reached the network when it returned: + /// marked by the payment itself and not shown never to have left + /// ([`PaymentStarted::may_have_reached_network`]). + payment_may_have_executed: bool, + kept: bool, +} + +impl PrivateReplyReservation { + /// Leave the reservation for the private sync to settle. + fn keep(&mut self) { + self.kept = true; + } + + /// Release the reservation now, kept or not. Dropped while it waits for + /// the wallet lock, the guard releases it. + async fn release(mut self) { + self.kept = false; + self.payment_started = PaymentStarted::default(); + let mut wm = self.wallet_manager.write().await; + release_reservation( + &mut wm, + &self.wallet_id, + &self.generation, + &self.sender, + &self.recipient, + self.attempt, + ); + store_private_payment_marker( + &self.persister, + &wm, + &self.wallet_id, + &self.generation, + &self.sender, + ); + self.kept = true; + } +} + +impl Drop for PrivateReplyReservation { + fn drop(&mut self) { + if self.kept || self.payment_started.is_marked() { + return; + } + let (wallet_id, sender, recipient, attempt) = + (self.wallet_id, self.sender, self.recipient, self.attempt); + let persister = self.persister.clone(); + let generation = Arc::clone(&self.generation); + apply_detached( + &self.wallet_manager, + "a cancelled private contact request's reservation", + move |wm| { + release_reservation(wm, &wallet_id, &generation, &sender, &recipient, attempt); + store_private_payment_marker(&persister, wm, &wallet_id, &generation, &sender); + }, + ); + } +} + +/// A stale handle's refusal before anything was paid: its wallet was removed, +/// or re-created under its id, since the handle was taken +/// (`DashPayView::with_managed` reports it as not found). +fn removed_before_send(error: PlatformWalletError) -> PlatformWalletError { + match error { + PlatformWalletError::WalletNotFound(wallet_id) => { + PlatformWalletError::WalletRemovedBeforeSend(wallet_id) + } + other => other, + } +} + +/// Run `apply` on the wallet manager, for a guard released on drop, which +/// cannot wait for the lock: now when the lock is free, otherwise on a +/// spawned task. Outside a runtime it is logged, and `what` stays until +/// restart. +pub(super) fn apply_detached( + wallet_manager: &Arc>>, + what: &'static str, + apply: impl FnOnce(&mut WalletManager) + Send + 'static, +) { + if let Ok(mut wm) = wallet_manager.try_write() { + apply(&mut wm); + return; + } + let Ok(runtime) = tokio::runtime::Handle::try_current() else { + tracing::warn!( + what, + "released on drop outside a runtime; it stays until restart" + ); + return; + }; + let wallet_manager = Arc::clone(wallet_manager); + runtime.spawn(async move { + let mut wm = wallet_manager.write().await; + apply(&mut wm); + }); +} + +/// `wallet_id`'s wallet in `wm` while it is still `generation`: `None` once +/// the wallet was removed, or re-created under its id, since. A guard that +/// releases what one generation took acts only through this, so it never +/// touches a replacement's state. +pub(super) fn generation_info_mut<'w>( + wm: &'w mut WalletManager, + wallet_id: &WalletId, + generation: &Arc, +) -> Option<&'w mut PlatformWalletInfo> { + wm.get_wallet_info_mut(wallet_id) + .filter(|info| Arc::ptr_eq(&info.generation, generation)) +} + +/// Release the reservation `attempt` holds on `sender`'s private request to +/// `recipient`, on the wallet generation `generation` only. +fn release_reservation( + wm: &mut WalletManager, + wallet_id: &WalletId, + generation: &Arc, + sender: &Identifier, + recipient: &Identifier, + attempt: u64, +) { + if let Some(managed) = generation_info_mut(wm, wallet_id, generation) + .and_then(|info| info.identity_manager.managed_identity_mut(sender)) + { + managed.release_private_reply(recipient, attempt); + } +} + +/// A private contact request payment a restoration reads, from the shielded +/// store's journal or from the redrive record of its spend: (sender, +/// recipient, account reference, the entry's commitment, the sender's read +/// position of the store when it paid, when the journal record kept it). +pub(crate) type JournaledPrivatePayment = (Identifier, Identifier, u32, [u8; 32], Option); + +/// What [`reserve_unresolved_private_payments`] reserved. +#[derive(Debug, Default)] +pub(crate) struct ReservedPrivatePayments { + /// The (sender, recipient) pairs reserved, each once, in the payments' + /// order. + pub(crate) restored: Vec<(Identifier, Identifier)>, + /// Every payment left unresolved, reserved or with its sender not managed + /// by the wallet, as (entry commitment, sender, recipient): the wallet's + /// hold on each pair until its record is discharged. + #[cfg_attr(not(feature = "shielded"), allow(dead_code))] + pub(crate) unresolved: Vec<([u8; 32], Identifier, Identifier)>, + /// The commitments of the payments whose request the sender's tracked + /// request to its recipient records or supersedes, as a private sync that + /// read the entry back settled it: their journal records are discharged, + /// rather than read for again on every launch. + #[cfg_attr(not(feature = "shielded"), allow(dead_code))] + pub(crate) settled: Vec<[u8; 32]>, +} + +/// The one step every restoration of a private contact request payment's +/// reservation takes, and every retarget of one: reserve the recipient of each +/// of `payments` that may still execute, in `info`, which the caller holds +/// under the wallet manager's write lock. +/// +/// Fenced to `generation`, the wallet generation the caller's handle belongs +/// to: a wallet removed, or re-created under its id, since then is refused +/// with [`PlatformWalletError::WalletNotFound`] and nothing is reserved. The +/// check and the reservations are under the one lock a removal takes. +/// +/// Left alone: +/// - a payment whose journal record was discharged in this session +/// ([`WalletPersister::private_entry_discharged`]): a restoration that read +/// it before the discharge, and reserves after the reservation was released, +/// would hold a pair no entry ever settles; +/// - one whose request the sender's tracked request to its recipient records +/// or supersedes, as a private sync that recorded it settled it, returned in +/// [`ReservedPrivatePayments::settled`] for its journal record to be +/// discharged; +/// - one whose sender the wallet does not manage, returned in +/// [`ReservedPrivatePayments::unresolved`] for the wallet to hold its pair. +/// +/// The pair `paying` is retargeted to the entry of its first payment left to +/// reserve, as the entry about to be paid is not paid for; every other pair +/// keeps the entry it is reserved for, and gets one only when it has none. +pub(crate) fn reserve_unresolved_private_payments( + info: &mut PlatformWalletInfo, + generation: &Arc, + wallet_id: WalletId, + persister: &WalletPersister, + payments: &[JournaledPrivatePayment], + paying: Option<(Identifier, Identifier)>, +) -> Result { + if !Arc::ptr_eq(&info.generation, generation) { + return Err(PlatformWalletError::WalletNotFound(hex::encode(wallet_id))); + } + let mut reserved = ReservedPrivatePayments::default(); + for &(sender, recipient, account_reference, commitment, _) in payments { + if persister.private_entry_discharged(&commitment) { + continue; + } + let Some(managed) = info.identity_manager.managed_identity_mut(&sender) else { + reserved.unresolved.push((commitment, sender, recipient)); + continue; + }; + if managed + .dashpay() + .outgoing_request(&recipient) + .is_some_and(|tracked| records_or_supersedes(tracked, account_reference)) + { + reserved.settled.push(commitment); + continue; + } + reserved.unresolved.push((commitment, sender, recipient)); + let first = !reserved.restored.contains(&(sender, recipient)); + if paying == Some((sender, recipient)) { + if first { + managed.retarget_private_reply(recipient, commitment); + } + } else { + managed.restore_private_reply(recipient, commitment); + } + if first { + reserved.restored.push((sender, recipient)); + } + } + Ok(reserved) +} + +/// The body of [`DashPayView::restore_private_payments`], over the wallet's +/// state alone, so a restoration deferred to a task while the shielded store +/// is busy runs it too. +#[cfg(feature = "shielded")] +pub(crate) async fn restore_journaled_private_payments( + wallet_manager: &Arc>>, + generation: &Arc, + persister: &WalletPersister, + wallet_id: WalletId, + payments: &[JournaledPrivatePayment], + journal_authoritative: bool, +) -> Result<(Vec<(Identifier, Identifier)>, Vec<[u8; 32]>), PlatformWalletError> { + let mut wm = wallet_manager.write().await; + let info = wm + .get_wallet_info_mut(&wallet_id) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(wallet_id)))?; + let ReservedPrivatePayments { + restored, + unresolved, + settled, + } = reserve_unresolved_private_payments( + info, generation, wallet_id, persister, payments, None, + )?; + // A payment whose request its sender does not track may have had its + // entry read past while what recorded it was lost (a flush the backend + // failed for good): the sender's read goes back to where it was when it + // paid, so the entry is read again, its request recorded, and the record + // discharged once that is durable. A sender's read already before it + // stays. + let untracked: BTreeSet<[u8; 32]> = unresolved + .iter() + .map(|(commitment, _, _)| *commitment) + .collect(); + for &(sender, _, _, commitment, store_position) in payments { + if !untracked.contains(&commitment) { + continue; + } + if let Some(managed) = info.identity_manager.managed_identity_mut(&sender) { + managed.rewind_private_store_read_to(store_position.unwrap_or(0)); + } + } + // The wallet holds each unresolved payment's pair too, beyond its sender + // identity, and whether or not it manages the sender, until its record is + // discharged. + persister.note_journaled_private_payments(unresolved); + // Under the same lock, after the reservations: a send that sees an + // identity's hold gone sees them. + let identity_ids: Vec = info + .identity_manager + .all_identities() + .iter() + .map(|identity| identity.id()) + .collect(); + let mut unaccounted = 0usize; + for identity_id in identity_ids { + let Some(managed) = info.identity_manager.managed_identity_mut(&identity_id) else { + continue; + }; + if !managed.dashpay().private_payments_unrestored() { + continue; + } + if !journal_authoritative && !managed.dashpay().private_replies_pending() { + unaccounted += 1; + continue; + } + if managed.note_private_payments_restored() + && persister.persists_private_contact_scan_state() + { + store_private_position( + persister, + identity_id, + managed.private_contact_requests_position_record(), + ); + } + } + if unaccounted > 0 { + return Err(PlatformWalletError::ShieldedRecoveryCorrupted { + account_index: None, + reason: format!( + "{unaccounted} of the wallet's identities were loaded marking a private contact \ + request payment that may be unresolved, and the shielded store's private \ + payment journal for the wallet is new, so it cannot show that payment \ + resolved: their contact requests stay held" + ), + }); + } + Ok((restored, settled)) +} + +/// Store `owner`'s private read position record again, for a backend that +/// keeps it, as whether a private payment of `owner` may be unresolved +/// (`PrivateContactRequestsPosition::private_payments_unresolved`) may have +/// changed: a reservation was released or settled. Flushed when the backend +/// does not commit a store inline, so a cleared marker does not hold the +/// identity after a restart. A store or flush that fails is logged and +/// leaves the marker set, which holds the identity after a restart only +/// until the next restoration: that one clears it, the shielded store's +/// journal being open by then and showing the payment resolved. Never the +/// other way round. +/// +/// Only while the wallet is still `generation`: a replacement under the id +/// stores its own records. +fn store_private_payment_marker( + persister: &WalletPersister, + wm: &WalletManager, + wallet_id: &WalletId, + generation: &Arc, + owner: &Identifier, +) { + if !persister.persists_private_contact_scan_state() { + return; + } + if let Some(managed) = wm + .get_wallet_info(wallet_id) + .filter(|info| Arc::ptr_eq(&info.generation, generation)) + .and_then(|info| info.identity_manager.managed_identity(owner)) + { + store_private_position( + persister, + *owner, + managed.private_contact_requests_position_record(), + ); + if !persister.store_commits_inline() { + if let Err(error) = persister.flush() { + // Not known to be stored: the next comparison stores it again. + persister.note_private_marker_stored(*owner, None); + tracing::warn!( + owner = %owner, + %error, + "a private payment marker change is not flushed; the next restoration \ + clears a stale one" + ); + } + } + } +} + +/// The changeset recording, for each contact one of `addresses` came from, the +/// shielded address `owner` keeps for it now, or its removal. +fn shielded_address_changeset( + managed: &ManagedIdentity, + owner: Identifier, + addresses: &[(ContactRequest, Option<[u8; 43]>)], +) -> ContactChangeSet { + let mut changeset = ContactChangeSet::default(); + for (record, _) in addresses { + let key = (owner, record.sender_id); + match managed + .dashpay() + .private_shielded_address(&record.sender_id) + { + Some(address) => { + changeset.private_shielded_addresses.insert(key, address); + } + None => { + changeset.removed_private_shielded_addresses.insert(key); + } + } + } + changeset +} + +/// `position`, `owner`'s record, marked as holding a private payment that may +/// be unresolved while the wallet's journal keeps one of `owner`'s +/// (`WalletPersister::private_sender_journaled`): a marker is never stored +/// cleared while a payment the identity's own state no longer shows may still +/// execute. +pub(super) fn with_journaled_marker( + persister: &WalletPersister, + owner: Identifier, + mut position: PrivateContactRequestsPosition, +) -> PrivateContactRequestsPosition { + position.private_payments_unresolved |= persister.private_sender_journaled(&owner).is_some(); + position +} + +/// Store `owner`'s private read position. A failed store leaves the cursor +/// advanced in memory: the next launch reads from the last position stored, +/// and ingest is a fixpoint. +fn store_private_position( + persister: &WalletPersister, + owner: Identifier, + position: PrivateContactRequestsPosition, +) { + let position = with_journaled_marker(persister, owner, position); + let mut changeset = ContactChangeSet::default(); + changeset + .private_contact_requests_positions + .insert(owner, position); + match persister.store(changeset.into()) { + Ok(()) => { + persister.note_private_marker_stored(owner, Some(position.private_payments_unresolved)) + } + Err(error) => { + persister.note_private_marker_stored(owner, None); + tracing::warn!( + owner = %owner, position = position.position, %error, + "private read position not stored; the next launch reads from the last one stored" + ); + } + } +} + +/// Whether `managed`'s position record, stored now, would carry another +/// marker than the one `owner`'s record was last stored with in this session +/// (`WalletPersister::private_marker_stored`), for a backend that keeps it: +/// its identity's part and the journal's (`with_journaled_marker`) together, +/// so a journal record discharged after the identity's own reservation +/// settled clears it too. None stored this session counts as another. +fn private_marker_stale( + persister: &WalletPersister, + owner: Identifier, + managed: &ManagedIdentity, +) -> bool { + persister.persists_private_contact_scan_state() + && persister.private_marker_stored(&owner) + != Some( + with_journaled_marker( + persister, + owner, + managed.private_contact_requests_position_record(), + ) + .private_payments_unresolved, + ) +} + +/// The local record of a private request: a [`ContactRequest`] carrying the +/// request's compact xpub and label encrypted under `shared_key`, the pair's +/// DIP-15 shared key, as a `contactRequest` document carries them. The IVs are +/// the two halves of the entry's `commitment`, so a rescan of the entry +/// rebuilds the same record, and the wallet's comparisons of a contact's +/// encrypted xpub hold across passes. Its core height is 0, which marks it +/// private ([`ContactRequest::came_privately`]); our receiving account for the +/// contact is then scanned from the wallet's birth. +#[allow(clippy::too_many_arguments)] +pub(super) fn private_request_record( + sender_id: Identifier, + recipient_id: Identifier, + sender_key_index: KeyID, + recipient_key_index: KeyID, + request: &PrivateContactRequest, + commitment: &[u8; 32], + shared_key: &[u8; 32], + created_at: u64, +) -> ContactRequest { + let mut xpub_iv = [0u8; 16]; + let mut label_iv = [0u8; 16]; + xpub_iv.copy_from_slice(&commitment[..16]); + label_iv.copy_from_slice(&commitment[16..]); + let mut record = ContactRequest::new( + sender_id, + recipient_id, + sender_key_index, + recipient_key_index, + request.account_reference, + encrypt_extended_public_key(shared_key, &xpub_iv, &request.extended_public_key), + 0, + created_at, + ); + record.encrypted_account_label = request + .account_label + .as_deref() + .map(|label| encrypt_account_label(shared_key, &label_iv, label)); + record.auto_accept_proof = request.auto_accept_proof.clone(); + record +} + +/// Whether `key` is one a private contact request entry can be sealed to, +/// which a private sync scans the store with. +fn scanning_key(key: &IdentityPublicKey) -> bool { + key.key_type() == KeyType::ECDSA_SECP256K1 && recipient_key_purpose_is_valid(key.purpose()) +} + +/// Whether a private sync reads DashPay's private contact request store for +/// `managed`: it has an HD index the wallet derives its keys at, and a key an +/// entry can be sealed to (`DashPayView::private_scan_identities`). +fn scans_private_store(managed: &ManagedIdentity) -> bool { + managed.identity_index.is_some() && managed.identity.public_keys().values().any(scanning_key) +} + +/// The public key of `identity`'s key `key_id`. +fn identity_public_key( + identity: &Identity, + key_id: KeyID, +) -> Result { + let key = identity.public_keys().get(&key_id).ok_or_else(|| { + PlatformWalletError::InvalidIdentityData(format!( + "identity {} has no key {key_id}", + identity.id() + )) + })?; + PublicKey::from_slice(key.data().as_slice()).map_err(|e| { + PlatformWalletError::InvalidIdentityData(format!( + "key {key_id} of identity {} is not a secp256k1 key: {e}", + identity.id() + )) + }) +} + +impl DashPayView<'_, B> { + /// Send a private contact request from `sender_identity_id` to + /// `recipient_identity_id`: the request a `contactRequest` document would + /// carry (our receiving xpub for the pair, the masked account reference, + /// the label and the auto-accept proof) plus our `shielded_address`, + /// signed by `signer` with one of the sender's signing keys, sealed in the + /// crypto provider to the recipient's DashPay key, then appended by `pay`, + /// which pays for it from the shielded pool and returns the metadata of + /// the proof that it was appended + /// (`PlatformWallet::send_private_contact_request`). + /// + /// The keys and the account reference are chosen as for a document send, + /// so a later private request to the same recipient rotates past this + /// one; a later public one is refused + /// ([`PlatformWalletError::PrivateContactRequestNeedsPrivateReply`]). + /// + /// One private request to a recipient is in flight at a time: it is + /// reserved before sealing, and while it is pending another is refused + /// with [`PlatformWalletError::PrivateContactRequestPending`], as the store + /// keeps every entry appended and a second payment could execute too. A + /// public request to the recipient is refused the same way. While a public + /// request to the recipient is unconfirmed (its broadcast may have been + /// delivered, and no proof settled it yet), the send is refused with + /// [`PlatformWalletError::PublicContactRequestUnconfirmed`] before anything + /// is reserved or paid. + /// + /// The proof `pay` waits for shows the notes spent, not the entry + /// appended, so a paid request is recorded only once read back: a private + /// sync of a few pages follows the payment, and records the request from + /// the store as it records any request the identity sent. If it is not + /// read back yet, the send returns `PrivateContactRequestPending` and the + /// request stays pending until a later sync reads it. Any outcome of the + /// payment keeps it pending the same way, unless its transition provably + /// never left the wallet, which releases it, as does a send dropped before + /// its payment started: `pay` gets a [`PaymentStarted`] it marks right + /// before anything it does may reach the network, after any resolving it + /// awaits first. `pay` itself may return `PrivateContactRequestPending` to + /// keep the request pending unpaid. The reservation is in memory; a + /// payment that may reach the network is first journaled in the shielded + /// store, whose restoration after a restart holds its pair again + /// (`PlatformWallet::restore_private_contact_payments`). + /// + /// Every contact request reads the store from the identity's cursor to its + /// end first, with the keys Platform proves the identity holds, which + /// records a request paid for in an earlier process or on another device; + /// while that read cannot finish, the send is refused with + /// [`PlatformWalletError::PrivateContactStoreNotRead`], nothing sealed or + /// paid. + #[allow(clippy::too_many_arguments)] + pub async fn send_private_contact_request( + &self, + sender_identity_id: &Identifier, + recipient_identity_id: &Identifier, + account_label: Option, + auto_accept_proof: AutoAcceptProofSource, + shielded_address: Option<[u8; 43]>, + signer: &S, + crypto: &C, + pay: F, + ) -> Result + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + F: FnOnce(BinaryData, PaymentStarted) -> Fut + Send, + Fut: Future> + Send, + { + self.send_private_request( + sender_identity_id, + recipient_identity_id, + account_label, + auto_accept_proof, + shielded_address, + signer, + crypto, + false, + pay, + ) + .await? + .ok_or_else(|| { + PlatformWalletError::InvalidParameter( + "no private contact request was sent: only a reply adopts one already sent" + .to_string(), + ) + }) + } + + /// Reply privately to `request`, paid by `pay`: `AlreadyReplied`, with + /// nothing sealed or paid, when a request to its sender is tracked by the + /// time the pair is reserved (another accept's reply, recorded in + /// between), which the accept then adopts. + pub(super) async fn send_private_reply( + &self, + request: &ContactRequest, + shielded_address: Option<[u8; 43]>, + signer: &S, + crypto: &C, + pay: F, + ) -> Result + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + F: FnOnce(BinaryData, PaymentStarted) -> Fut + Send, + Fut: Future> + Send, + { + Ok( + match self + .send_private_request( + &request.recipient_id, + &request.sender_id, + None, + AutoAcceptProofSource::None, + shielded_address, + signer, + crypto, + true, + pay, + ) + .await? + { + Some(_) => ReplyOutcome::Sent, + None => ReplyOutcome::AlreadyReplied, + }, + ) + } + + /// [`Self::send_private_contact_request`], for a reply when + /// `adopt_reply`: then a request to the recipient tracked once the store + /// was read and the pair is reserved, in the same lock, is adopted + /// rather than rotated past, and `None` comes back with nothing paid. + #[allow(clippy::too_many_arguments)] + async fn send_private_request( + &self, + sender_identity_id: &Identifier, + recipient_identity_id: &Identifier, + account_label: Option, + auto_accept_proof: AutoAcceptProofSource, + shielded_address: Option<[u8; 43]>, + signer: &S, + crypto: &C, + adopt_reply: bool, + pay: F, + ) -> Result, PlatformWalletError> + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + F: FnOnce(BinaryData, PaymentStarted) -> Fut + Send, + Fut: Future> + Send, + { + // Before anything is read, sealed or paid: a payment no restart could + // see would leave its pair unheld. + if !self.persister.persists_private_contact_scan_state() { + return Err(PlatformWalletError::PrivateContactRecoveryUnsupported); + } + // A private payment from an earlier process may hold this pair, which + // only a restoration from the shielded store's journal shows: until + // one succeeds, no private request is paid for either. + if self + .private_payments_still_unrestored(sender_identity_id) + .await? + { + return Err(PlatformWalletError::PrivateContactPaymentsNotRestored); + } + Box::pin(self.read_private_store_and_keys(sender_identity_id, crypto)).await?; + self.release_discharged_private_requests().await?; + // A public request to the recipient whose outcome is unconfirmed is + // settled first where proof allows; while it stands nothing is + // reserved. + Box::pin( + self.settle_unconfirmed_public_request_logged( + sender_identity_id, + recipient_identity_id, + ), + ) + .await; + // Held beyond the sender identity: a journaled payment's pair outlives + // the identity's removal, and holds for a sender loaded after it was + // restored, until its record is discharged. + let held_by_wallet = self + .persister + .private_pair_journaled(sender_identity_id, recipient_identity_id); + let reserved = self + .with_managed(sender_identity_id, |managed| { + if adopt_reply + && managed + .dashpay() + .outgoing_request(recipient_identity_id) + .is_some() + { + return None; + } + if managed + .dashpay() + .public_contact_request_unconfirmed(recipient_identity_id) + { + return Some(Err(PlatformWalletError::PublicContactRequestUnconfirmed( + *recipient_identity_id, + ))); + } + if held_by_wallet { + return Some(Ok(None)); + } + Some(Ok(managed.reserve_private_reply(*recipient_identity_id))) + }) + .await + .map_err(removed_before_send)?; + let Some(reserved) = reserved else { + return Ok(None); + }; + let attempt = reserved?.ok_or(PlatformWalletError::PrivateContactRequestPending( + *recipient_identity_id, + ))?; + let mut reservation = PrivateReplyReservation { + wallet_manager: Arc::clone(&self.wallet_manager), + persister: self.persister.clone(), + wallet_id: self.wallet_id, + generation: Arc::clone(&self.generation), + sender: *sender_identity_id, + recipient: *recipient_identity_id, + attempt, + payment_started: PaymentStarted::default(), + payment_may_have_executed: false, + kept: false, + }; + let sent = self + .send_reserved_private_contact_request( + sender_identity_id, + recipient_identity_id, + account_label, + auto_accept_proof, + shielded_address, + signer, + crypto, + &mut reservation, + pay, + ) + .await; + // A payment that may have executed keeps the request pending, its + // marker set: one that reached the network and then failed too, as + // its entry may still be appended, unless its transition provably + // never left the wallet. + let keep_pending = reservation.payment_may_have_executed + || matches!( + &sent, + Err(PlatformWalletError::PrivateContactRequestPending(_) + | PlatformWalletError::ShieldedSpendUnconfirmed { .. } + | PlatformWalletError::ShieldedBroadcastMaybeDelivered(_)) + ); + if keep_pending { + reservation.keep(); + } else { + reservation.release().await; + } + sent.map(Some) + } + + /// Read DashPay's private contact request store for `identity_id` from its + /// cursor until a pass of this call reaches the store's end, with its + /// current keys and nothing held back (one proved page at the end when the + /// cursor is there), before a contact request from it, public or private, + /// or an acceptance, is decided: a request that landed since the last read, + /// from another device of the identity or from a contact, then holds the + /// pair here too. A request that lands after this read is not seen. Runs + /// private syncs of [`PRIVATE_STORE_READ_PAGES`] pages, at most + /// [`PRIVATE_STORE_READ_PASSES`] of them, and refuses with + /// [`PlatformWalletError::PrivateContactStoreNotRead`] when they stop + /// advancing or run out first. A sync error comes back as it is. Returns + /// whether the store was read for the identity: one the private sync does + /// not read, with no HD index or no key an entry can be sealed to or from, + /// sends no private request and reads nothing, so it is not held. + async fn read_private_store_to_end( + &self, + identity_id: &Identifier, + crypto: &C, + ) -> Result + where + C: ContactCryptoProvider + Sync, + { + // Keys added since the store was read rewind it first. + self.reconcile_private_scan_keys().await?; + let (identities, _) = self.private_scan_identities().await?; + if !identities + .iter() + .any(|identity| identity.identity_id == *identity_id) + { + return Ok(false); + } + let mut position = identities + .iter() + .map(|identity| identity.position) + .min() + .unwrap_or_default(); + for _ in 0..PRIVATE_STORE_READ_PASSES { + let report = self + .sync_private_contact_requests(crypto, PRIVATE_STORE_READ_PAGES) + .await?; + if report.read_to_end.contains(identity_id) { + return Ok(true); + } + if report.next_position <= position { + break; + } + position = report.next_position; + } + Err(PlatformWalletError::PrivateContactStoreNotRead( + *identity_id, + )) + } + + /// [`Self::read_private_store_to_end`], shown to cover the identity's keys: + /// after the read, `identity_id` is fetched from Platform, proved, and its + /// keys folded into the cached identity (`IdentityWallet::refresh_identity`'s + /// fold). A DashPay encryption or decryption key another device added, to + /// which a request in the store may be sealed, changes the identity's + /// scanning keys, which rewinds its read (`Self::reconcile_private_scan_keys`), + /// and the store is read again with it. A key added at a height is in no + /// request in a page proved below it, so the read covers the keys once the + /// fetch is proved at or above every page it read + /// (`DashPayState::private_store_read_height`); a fetch proved below them, + /// from a node behind, is made again. Up to [`PRIVATE_KEY_COVERAGE_ATTEMPTS`] + /// rounds, then refused: with the SDK's stale node error + /// (`StaleNodeError::Height`) when the fetch stayed below the pages, and + /// with [`PlatformWalletError::PrivateContactStoreNotRead`] when the keys + /// kept changing so the read never finished with them. A fetch that fails + /// refuses as the SDK reported it. Nothing is reserved or sent before. One + /// proved identity fetch when the first round covers it. Returns whether + /// the store was read for the identity ([`Self::read_private_store_to_end`]). + /// + /// Run before every contact request and acceptance, public or private, so + /// a reply another device sealed under a key this device had not folded in + /// yet is adopted rather than paid for again. + async fn read_private_store_and_keys( + &self, + identity_id: &Identifier, + crypto: &C, + ) -> Result + where + C: ContactCryptoProvider + Sync, + { + let mut uncovered = PrivateStoreCoverage::Unread; + for _ in 0..PRIVATE_KEY_COVERAGE_ATTEMPTS { + let read = self.read_private_store_to_end(identity_id, crypto).await?; + let (_, identity_height) = self.fetch_and_fold_identity(identity_id).await?; + self.reconcile_private_scan_keys().await?; + match self + .private_store_coverage(identity_id, identity_height) + .await? + { + PrivateStoreCoverage::Covered => return Ok(read), + coverage => uncovered = coverage, + } + } + Err(match uncovered { + PrivateStoreCoverage::IdentityBelow { + identity_height, + store_height, + } => PlatformWalletError::Sdk(dash_sdk::Error::StaleNode(StaleNodeError::Height { + expected_height: store_height, + received_height: identity_height, + tolerance_blocks: 0, + })), + PrivateStoreCoverage::Covered | PrivateStoreCoverage::Unread => { + PlatformWalletError::PrivateContactStoreNotRead(*identity_id) + } + }) + } + + /// [`Self::read_private_store_and_keys`], before a public request or reply + /// from `identity_id` is chosen or sent, so a private request, whether paid + /// for in an earlier process, on another device, or by a contact, holds the + /// pair here too. Returns whether the store was read for the identity: the + /// claim of the pair checks, under the wallet's lifecycle gate, that the + /// read is still to the end then (a rewind in between refuses). + /// + /// A network that serves no private documents yet holds none, so the SDK's + /// refusal of the read reads as nothing to read, but only once a verified + /// answer shows the network below the protocol version that serves them + /// (`Sdk::network_proven_below`): a refusal alone does not say whether the + /// network or this SDK is below it, and an SDK pinned below it refuses a + /// store the network has. Without that evidence the refusal comes back as + /// it is, and nothing is sent. + /// + /// Refused first, with nothing read, while the wallet's unconfirmed + /// private payments may be unrestored + /// ([`PlatformWalletError::PrivateContactPaymentsNotRestored`]): such a + /// payment's entry is not in the store until it executes, so no read + /// shows the pair it holds; only the shielded store's record of it does. + /// That is so for a wallet a shielded build publishes with no shielded + /// store configured when its persister keeps the private scan state, for + /// one it loads with a persisted viewing key, for one whose restoration + /// failed, and, in every build, for an identity loaded with its position + /// record marking a private payment that may be unresolved + /// (`PrivateContactRequestsPosition::private_payments_unresolved`). + pub(super) async fn read_private_store_before_deciding( + &self, + identity_id: &Identifier, + crypto: &C, + ) -> Result + where + C: ContactCryptoProvider + Sync, + { + if self.private_payments_still_unrestored(identity_id).await? { + return Err(PlatformWalletError::PrivateContactPaymentsNotRestored); + } + match Box::pin(self.read_private_store_and_keys(identity_id, crypto)).await { + Err(PlatformWalletError::Sdk( + refusal @ dash_sdk::Error::ProtocolVersionNotActive { required, .. }, + )) => match self.sdk.network_proven_below(required).await { + Ok(true) => Ok(false), + Ok(false) => Err(PlatformWalletError::Sdk(refusal)), + Err(error) => { + tracing::warn!( + %error, + "the network's protocol version could not be verified; the private \ + store is not taken as empty" + ); + Err(PlatformWalletError::Sdk(refusal)) + } + }, + read => read, + } + } + + /// Whether the private store read `identity_id`'s decisions rest on + /// covers its keys as the fetch proved at `identity_height` shows them + /// ([`Self::read_private_store_before_deciding`]). + async fn private_store_coverage( + &self, + identity_id: &Identifier, + identity_height: u64, + ) -> Result { + let wm = self.wallet_manager.read().await; + let managed = wm + .get_wallet_info(&self.wallet_id) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))? + .identity_manager + .managed_identity(identity_id) + .ok_or(PlatformWalletError::IdentityNotFound(*identity_id))?; + // No key a request can be sealed to that the wallet derives: the + // private sync does not read for it, and nothing holds it. + if !scans_private_store(managed) { + return Ok(PrivateStoreCoverage::Covered); + } + let dashpay = managed.dashpay(); + if !dashpay.private_contact_requests_read() { + return Ok(PrivateStoreCoverage::Unread); + } + Ok(match dashpay.private_store_read_height() { + Some(store_height) if store_height <= identity_height => PrivateStoreCoverage::Covered, + Some(store_height) => PrivateStoreCoverage::IdentityBelow { + identity_height, + store_height, + }, + None => PrivateStoreCoverage::Unread, + }) + } + + /// Rewind the private read position and the read flag of each of the + /// wallet's identities whose scanning keys changed since they were set + /// (`ManagedIdentity::reconcile_private_scan_keys`), storing the rewind + /// for a backend that keeps the position. A refresh that folds in a key + /// another device added is caught here, before the next scan or send. + pub(crate) async fn reconcile_private_scan_keys(&self) -> Result<(), PlatformWalletError> { + let persists_scan_state = self.persister.persists_private_contact_scan_state(); + let mut wm = self.wallet_manager.write().await; + let info = self.current_wallet_info_mut(&mut wm)?; + let identity_ids: Vec = info + .identity_manager + .all_identities() + .iter() + .map(|identity| identity.id()) + .collect(); + for identity_id in identity_ids { + let Some(managed) = info.identity_manager.managed_identity_mut(&identity_id) else { + continue; + }; + if let Some(position) = managed.reconcile_private_scan_keys() { + if persists_scan_state { + store_private_position(&self.persister, identity_id, position); + } + } + } + Ok(()) + } + + /// Store `owner`'s position record, marking it as holding a private payment + /// that may be unresolved, durably, before anything is paid: flushed when + /// the backend does not commit a store inline. A backend that does not + /// keep the marker refuses the payment + /// ([`PlatformWalletError::PrivateContactRecoveryUnsupported`]), and a + /// failed store or flush refuses it too, with nothing paid: a payment a + /// restart could not see would leave the pair unheld. + /// + /// Clearing the marker once the payment resolves is not flushed: a clear + /// that is lost only holds the identity after a restart until a + /// restoration clears it, which fails closed. + /// + /// Stored only while the wallet is still this handle's generation, under + /// the wallet lock a removal takes: a handle whose wallet was removed, or + /// re-created under its id, since is refused with + /// [`PlatformWalletError::WalletRemovedBeforeSend`], nothing stored or + /// paid. + async fn store_private_payment_marker_before_paying( + &self, + owner: &Identifier, + marker: PrivateContactRequestsPosition, + ) -> Result<(), PlatformWalletError> { + if !self.persister.persists_private_contact_scan_state() { + return Err(PlatformWalletError::PrivateContactRecoveryUnsupported); + } + let wm = self.wallet_manager.read().await; + if !wm + .get_wallet_info(&self.wallet_id) + .is_some_and(|info| Arc::ptr_eq(&info.generation, &self.generation)) + { + return Err(PlatformWalletError::WalletRemovedBeforeSend(hex::encode( + self.wallet_id, + ))); + } + let mut changeset = ContactChangeSet::default(); + changeset + .private_contact_requests_positions + .insert(*owner, marker); + let not_kept = |error: PersistenceError| { + PlatformWalletError::Persistence(format!( + "the private contact request's unresolved payment was not stored durably, so it \ + is not paid for: {error}" + )) + }; + // Not known to be stored until both succeed. + self.persister.note_private_marker_stored(*owner, None); + self.persister.store(changeset.into()).map_err(not_kept)?; + if !self.persister.store_commits_inline() { + self.persister.flush().map_err(not_kept)?; + } + self.persister + .note_private_marker_stored(*owner, Some(marker.private_payments_unresolved)); + drop(wm); + Ok(()) + } + + /// Whether a contact request from `identity_id` waits for the wallet's + /// private payments to be restored: the wallet is held + /// (`WalletPersister::private_payments_unrestored`), or the identity was + /// loaded marking a private payment no restoration has restored since + /// ([`Self::private_payments_unrestored`]). When it is, one more + /// restoration runs first, without waiting on the shielded store, once the + /// wallet built one with a shielded coordinator + /// (`WalletPersister::retry_private_payment_restore`): a restoration that + /// failed, or was deferred, lifts at the next send rather than only at a + /// later configure or bind. + pub(crate) async fn private_payments_still_unrestored( + &self, + identity_id: &Identifier, + ) -> Result { + let held = self.persister.private_payments_unrestored() + || self.private_payments_unrestored(identity_id).await?; + #[cfg(feature = "shielded")] + if held && self.persister.retry_private_payment_restore().await { + return Ok(self.persister.private_payments_unrestored() + || self.private_payments_unrestored(identity_id).await?); + } + Ok(held) + } + + /// Whether `identity_id` was loaded with a private contact request payment + /// that may be unresolved and no restoration has restored it since + /// ([`DashPayState::private_payments_unrestored`]). + /// + /// [`DashPayState::private_payments_unrestored`]: crate::wallet::identity::DashPayState::private_payments_unrestored + pub(crate) async fn private_payments_unrestored( + &self, + identity_id: &Identifier, + ) -> Result { + let wm = self.wallet_manager.read().await; + let managed = wm + .get_wallet_info(&self.wallet_id) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))? + .identity_manager + .managed_identity(identity_id) + .ok_or(PlatformWalletError::IdentityNotFound(*identity_id))?; + Ok(managed.dashpay().private_payments_unrestored()) + } + + /// What a contact request from `identity_id` waits for, as the wallet + /// decides it ([`PrivateContactReadiness`]). Not a pure read: a journal + /// record discharged since is applied first, under the wallet's write + /// lock, as a send would see it; then it reads live wallet state. + pub async fn private_contact_readiness( + &self, + identity_id: &Identifier, + ) -> Result { + // A discharge reads as a send would see it. + self.release_discharged_private_requests().await?; + let wallet_held = self.persister.private_payments_unrestored(); + let journaled = self + .persister + .private_sender_journaled(identity_id) + .is_some(); + let wm = self.wallet_manager.read().await; + let dashpay = wm + .get_wallet_info(&self.wallet_id) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))? + .identity_manager + .managed_identity(identity_id) + .ok_or(PlatformWalletError::IdentityNotFound(*identity_id))? + .dashpay(); + let private_payments_restored = !wallet_held && !dashpay.private_payments_unrestored(); + Ok(PrivateContactReadiness { + private_payments_restored, + private_store_read: dashpay.private_contact_requests_read(), + unresolved_private_payment: dashpay.private_payments_unresolved() || journaled, + private_payments_restore_failure: self + .persister + .private_payment_restore_failure() + .filter(|_| !private_payments_restored), + }) + } + + /// Whether a contact request from `sender` to `recipient`, public or + /// private, is held for a private one, as a send decides it: a private + /// request to the recipient is reserved (being paid for, or paid and not + /// read back), or a private payment the shielded store's journal keeps + /// unresolved holds the pair, whether or not the sender identity was + /// removed and added again since (`WalletPersister::private_pair_journaled`). + /// A journal record discharged since is applied first, so a discharge reads + /// as freed with no send or sync in between. The per-contact read a host + /// shows; `DashPayState::private_reply_pending` reads only the identity's + /// own reservation. + pub async fn private_pair_held( + &self, + sender: &Identifier, + recipient: &Identifier, + ) -> Result { + self.release_discharged_private_requests().await?; + let journaled = self.persister.private_pair_journaled(sender, recipient); + let wm = self.wallet_manager.read().await; + let reserved = wm + .get_wallet_info(&self.wallet_id) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))? + .identity_manager + .managed_identity(sender) + .ok_or(PlatformWalletError::IdentityNotFound(*sender))? + .dashpay() + .private_reply_pending(recipient); + Ok(reserved || journaled) + } + + /// Whether any of the wallet's identities was loaded with a private + /// contact request payment that may be unresolved and no restoration has + /// restored it since. + pub(crate) async fn any_private_payments_unrestored(&self) -> bool { + let wm = self.wallet_manager.read().await; + wm.get_wallet_info(&self.wallet_id).is_some_and(|info| { + info.identity_manager + .all_identities() + .iter() + .filter_map(|identity| info.identity_manager.managed_identity(&identity.id())) + .any(|managed| managed.dashpay().private_payments_unrestored()) + }) + } + + /// Release the pending private requests whose payment's journal record + /// was discharged (`WalletPersister::note_discharged_private_entries`): + /// one proven expired, its anchor pruned with an input still unspent, can + /// never be read back. Run before a private request is reserved, before a + /// public one claims its pair, and by the private sync, so a retry needs + /// no restart. Each identity's marker, its own part and the journal's, is + /// stored again when it differs from the one last stored + /// (`private_marker_stale`): a discharge clears the journal's part also + /// for an identity whose own reservation a read-back already settled, so + /// a reload does not hold it on a marker no payment backs. First, the + /// read-back notices a failed flush kept are retried + /// (`WalletPersister::note_read_back_once_durable`). + pub(crate) async fn release_discharged_private_requests( + &self, + ) -> Result<(), PlatformWalletError> { + // Read-back notices a failed flush kept, retried first: their journal + // records are discharged once noted. + #[cfg(feature = "shielded")] + self.persister.note_read_back_once_durable([]); + if !self.persister.has_unreleased_discharged_private_entries() { + return Ok(()); + } + // Taken only once the wallet is locked and found, this handle's + // generation, and applied with nothing awaited in between. + let mut wm = self.wallet_manager.write().await; + let info = self.current_wallet_info_mut(&mut wm)?; + let discharged = self.persister.take_unreleased_discharged_private_entries(); + let identity_ids: Vec = info + .identity_manager + .all_identities() + .iter() + .map(|identity| identity.id()) + .collect(); + let mut changed = Vec::new(); + for identity_id in identity_ids { + if let Some(managed) = info.identity_manager.managed_identity_mut(&identity_id) { + managed.release_discharged_private_replies(&discharged); + if private_marker_stale(&self.persister, identity_id, managed) { + changed.push(identity_id); + } + } + } + for identity_id in changed { + store_private_payment_marker( + &self.persister, + &wm, + &self.wallet_id, + &self.generation, + &identity_id, + ); + } + Ok(()) + } + + /// Run `f` on the managed identity `identity_id` under the wallet lock. + async fn with_managed( + &self, + identity_id: &Identifier, + f: impl FnOnce(&mut ManagedIdentity) -> R, + ) -> Result { + let mut wm = self.wallet_manager.write().await; + let managed = self + .current_wallet_info_mut(&mut wm)? + .identity_manager + .managed_identity_mut(identity_id) + .ok_or(PlatformWalletError::IdentityNotFound(*identity_id))?; + Ok(f(managed)) + } + + /// The body of [`Self::send_private_contact_request`], once the request + /// to the recipient is reserved by `reservation`, which it keeps right + /// before paying. + #[allow(clippy::too_many_arguments)] + async fn send_reserved_private_contact_request( + &self, + sender_identity_id: &Identifier, + recipient_identity_id: &Identifier, + account_label: Option, + auto_accept_proof: AutoAcceptProofSource, + shielded_address: Option<[u8; 43]>, + signer: &S, + crypto: &C, + reservation: &mut PrivateReplyReservation, + pay: F, + ) -> Result + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + F: FnOnce(BinaryData, PaymentStarted) -> Fut + Send, + Fut: Future> + Send, + { + let PreparedContactRequest { + sender_identity, + sender_key_index, + sender_enc_path, + recipient_identity, + recipient_key_index, + recipient_enc_pubkey, + account_index, + contact_xpub_ext, + xpub_bytes, + account_reference, + auto_accept_proof, + } = self + .prepare_contact_request( + sender_identity_id, + recipient_identity_id, + auto_accept_proof, + crypto, + ) + .await?; + let extended_public_key: [u8; COMPACT_XPUB_LEN] = + xpub_bytes.as_slice().try_into().map_err(|_| { + PlatformWalletError::InvalidIdentityData(format!( + "the receiving xpub is {} bytes, not the {COMPACT_XPUB_LEN}-byte compact form", + xpub_bytes.len() + )) + })?; + let request = PrivateContactRequest { + account_reference, + extended_public_key, + account_label, + auto_accept_proof, + shielded_address, + }; + + // The request is signed as a public request's transition is: by the + // first signing key of the sender the signer holds, of those the SDK + // lets sign it (level, type, contract bounds). + let contract = dashpay_contract()?; + let signing_key = first_available( + private_contact_request_signing_keys(&contract, &sender_identity)?.into_iter(), + signer, + )? + .cloned() + .ok_or_else(|| { + PlatformWalletError::InvalidIdentityData( + "the sender identity has no enabled AUTHENTICATION key at HIGH or CRITICAL, \ + bound to no other contract, to sign a private contact request with" + .to_string(), + ) + })?; + let signing_data = private_contact_request_signing_data( + &contract, + &sender_identity, + sender_key_index, + &recipient_identity, + recipient_key_index, + &request, + self.sdk.version(), + )?; + let signature = + private_contact_request_signature(signer, &signing_key, &signing_data).await?; + + // Wiped on drop, so a send dropped while the seal is awaited wipes it too. + let mut esk_seed = Zeroizing::new([0u8; 32]); + StdRng::try_from_os_rng() + .map_err(|error| { + PlatformWalletError::InvalidIdentityData(format!( + "the OS RNG failed while sealing a private contact request: {error}" + )) + })? + .fill_bytes(&mut *esk_seed); + let sealed = crypto + .seal_private_contact_request( + &sender_enc_path, + &contract, + &sender_identity, + sender_key_index, + signing_key.id(), + &signature, + &recipient_identity, + recipient_key_index, + &request, + &esk_seed, + self.sdk.version(), + ) + .await; + drop(esk_seed); + let entry = sealed?; + // An entry starts with its 32-byte commitment. + let commitment: [u8; 32] = entry + .as_slice() + .get(..32) + .and_then(|commitment| commitment.try_into().ok()) + .ok_or_else(|| { + PlatformWalletError::InvalidIdentityData( + "the provider sealed an entry shorter than its commitment".to_string(), + ) + })?; + let marker = self + .with_managed(sender_identity_id, |managed| { + managed.note_private_reply_commitment( + *recipient_identity_id, + reservation.attempt, + commitment, + ); + managed.private_contact_requests_position_record() + }) + .await + .map_err(removed_before_send)?; + // Before anything is paid, the identity is marked as holding a private + // payment that may be unresolved: a process reopening the wallet before + // the payment's reservation is restored, or in a build that cannot + // restore it, holds its public requests until then. + self.store_private_payment_marker_before_paying(sender_identity_id, marker) + .await?; + // What the record read back must carry, computed before paying. + let shared_secret = crypto + .ecdh_shared_secret(&sender_enc_path, &recipient_enc_pubkey) + .await?; + let expected = private_request_record( + *sender_identity_id, + *recipient_identity_id, + sender_key_index, + recipient_key_index, + &request, + &commitment, + &shared_secret, + 0, + ); + + // `pay` marks the payment started right before it may reach the + // network: from then on the reservation is the sync's to settle, + // whatever happens to this send. + let paid = pay( + entry, + reservation + .payment_started + .for_request(account_reference, marker.position), + ) + .await; + reservation.payment_may_have_executed = + reservation.payment_started.may_have_reached_network(); + reservation.payment_started.mark(); + paid?; + + // Recorded only as the store proves it: read it back. + if let Err(error) = self + .sync_private_contact_requests(crypto, POST_SEND_SYNC_PAGES) + .await + { + tracing::warn!( + sender = %sender_identity_id, + recipient = %recipient_identity_id, + %error, + "private contact request paid for; reading it back failed, a later sync reads it" + ); + } + let recorded = self + .with_managed(sender_identity_id, |managed| { + managed + .dashpay() + .outgoing_request(recipient_identity_id) + .filter(|tracked| { + tracked.account_reference == expected.account_reference + && tracked.encrypted_public_key == expected.encrypted_public_key + }) + .cloned() + }) + .await?; + let Some(contact_request) = recorded else { + return Err(PlatformWalletError::PrivateContactRequestPending( + *recipient_identity_id, + )); + }; + if let Err(e) = self + .register_contact_account( + sender_identity_id, + recipient_identity_id, + account_index, + contact_xpub_ext, + ) + .await + { + tracing::warn!( + sender = %sender_identity_id, + recipient = %recipient_identity_id, + error = %e, + "private contact request sent; its receiving account is not registered yet, the \ + next sync registers it" + ); + } + Ok(contact_request) + } + + /// Accept a contact request that came privately, replying privately: as + /// [`Self::accept_contact_request_with_external_signer`], with the reply + /// sent by [`Self::send_private_contact_request`], signed by `signer`, + /// `pay` paying for it and `shielded_address` the address the contact may + /// pay us at privately. + /// + /// As for the send, refused first for a persister that cannot keep a + /// private payment's recovery marker + /// ([`PlatformWalletError::PrivateContactRecoveryUnsupported`]) and while + /// the wallet's private payments are not restored + /// ([`PlatformWalletError::PrivateContactPaymentsNotRestored`]); then the + /// store is read from the cursor to its end with the keys Platform proves + /// the identity holds (`Self::read_private_store_and_keys`), so a reply + /// paid for in an earlier process or on another device is adopted rather + /// than paid for again; while that read cannot finish, the accept is + /// refused with [`PlatformWalletError::PrivateContactStoreNotRead`]. A + /// reply whose payment is unconfirmed since before a restart holds the + /// pair from the moment the wallet's private payments are restored. + pub async fn accept_private_contact_request( + &self, + request: &ContactRequest, + shielded_address: Option<[u8; 43]>, + signer: &S, + crypto: &C, + pay: F, + ) -> Result + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + F: FnOnce(BinaryData, PaymentStarted) -> Fut + Send, + Fut: Future> + Send, + { + if !self.persister.persists_private_contact_scan_state() { + return Err(PlatformWalletError::PrivateContactRecoveryUnsupported); + } + if self + .private_payments_still_unrestored(&request.recipient_id) + .await? + { + return Err(PlatformWalletError::PrivateContactPaymentsNotRestored); + } + Box::pin(self.read_private_store_and_keys(&request.recipient_id, crypto)).await?; + Box::pin( + self.accept_contact_request_replying_with(request, crypto, || { + self.send_private_reply(request, shielded_address, signer, crypto, pay) + }), + ) + .await + } + + /// Accept `request` replying the way it came: privately, paid by `pay`, + /// when it came privately and we have sent its sender no request yet + /// ([`Self::accept_private_contact_request`]); otherwise with a + /// `contactRequest` document, or by adopting the reply already sent + /// ([`Self::accept_contact_request_with_external_signer`]). The one accept + /// a host calls: which reply a request takes is the wallet's decision. + /// `pay` runs only for a private reply. + /// + /// The store is read from the cursor to its end first, before the reply + /// is chosen, whatever the request: a reply paid for in an earlier process + /// or on another device, to a public request too, is then adopted, with no + /// payment and no public reply. While that read cannot finish, the accept + /// is refused with [`PlatformWalletError::PrivateContactStoreNotRead`]. + /// On a network that serves no private documents yet, nothing is read. + pub async fn accept_contact_request_replying_in_kind( + &self, + request: &ContactRequest, + shielded_address: Option<[u8; 43]>, + signer: &S, + crypto: &C, + pay: F, + ) -> Result + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + F: FnOnce(BinaryData, PaymentStarted) -> Fut + Send, + Fut: Future> + Send, + { + Box::pin(self.read_private_store_before_deciding(&request.recipient_id, crypto)).await?; + // Boxed: each accept's future holds a store read and a payment. + if self.needs_private_reply(request).await { + Box::pin(self.accept_private_contact_request( + request, + shielded_address, + signer, + crypto, + pay, + )) + .await + } else { + Box::pin(self.accept_contact_request_with_external_signer(request, signer, crypto)) + .await + } + } + + /// The wallet's identities a pass reads the store for (those with an HD + /// index, whose keys the signer can derive) and the paths of their keys: + /// every `ECDSA_SECP256K1` decryption or encryption key, disabled ones + /// included, as an entry sealed before a key was disabled still opens with + /// it, and every such encryption key as a sender. + async fn private_scan_identities( + &self, + ) -> Result<(Vec, PrivateDocumentKeyPaths), PlatformWalletError> { + let wm = self.wallet_manager.read().await; + let info = wm + .get_wallet_info(&self.wallet_id) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))?; + let mut identities = Vec::new(); + let mut paths = PrivateDocumentKeyPaths::default(); + for identity in info.identity_manager.all_identities() { + let identity_id = identity.id(); + let Some(managed) = info.identity_manager.managed_identity(&identity_id) else { + continue; + }; + let Some(identity_index) = managed.identity_index else { + continue; + }; + let path = |key_id| { + IdentityWallet::::identity_auth_derivation_path( + self.sdk.network, + KeyDerivationType::ECDSA, + identity_index, + key_id, + ) + }; + let mut recipient_paths = Vec::new(); + for (key_id, key) in managed.identity.public_keys() { + if !scanning_key(key) { + continue; + } + recipient_paths.push((*key_id, path(*key_id)?)); + if key.purpose() == Purpose::ENCRYPTION { + paths.senders.push((identity_id, *key_id, path(*key_id)?)); + } + } + if recipient_paths.is_empty() { + continue; + } + paths.recipients.push((identity_id, recipient_paths)); + identities.push(ScannedIdentity { + identity_id, + identity_index, + position: managed.dashpay().private_contact_requests_position(), + failed: false, + rewound: false, + key_fingerprint: managed.private_scan_key_fingerprint(), + }); + } + Ok((identities, paths)) + } + + /// Read DashPay's private contact request store for the wallet's + /// identities, at most `max_pages` pages from the earliest of their + /// cursors, and ingest what it holds for them: requests to them, each + /// checked against the keys of its sender and of the identity it is to, + /// and requests they sent, recovered from the store alone and checked to + /// be theirs. Contacts establish, and their DashPay accounts are queued, + /// as the document sync does. A request older than the one tracked with + /// the same contact, either way and from either channel, is passed over. + /// + /// A request that came privately carries no auto-accept proof into the + /// wallet: accepting it replies privately, which pays from the shielded + /// pool, so it is accepted by hand + /// ([`Self::accept_private_contact_request`]). + /// + /// Refused with [`PlatformWalletError::SeedMismatch`], before any page + /// is read and with no position moved, when `crypto` does not resolve + /// this wallet's seed ([`IdentityWallet::verify_seed_binds`]): another + /// seed derives valid but unrelated keys, which open nothing, so its pass + /// would record as read pages holding requests it never saw, and nothing + /// rewinds them once the provider is fixed. + pub async fn sync_private_contact_requests( + &self, + crypto: &C, + max_pages: usize, + ) -> Result + where + C: ContactCryptoProvider + Sync, + { + self.release_discharged_private_requests().await?; + self.reconcile_private_scan_keys().await?; + let (mut identities, paths) = self.private_scan_identities().await?; + let mut report = PrivateContactSyncReport::default(); + let Some(start) = identities.iter().map(|identity| identity.position).min() else { + report.complete = true; + return Ok(report); + }; + // Before anything is read or recorded: once a pass, as the keys it + // scans with all come from the same provider. + self.verify_seed_binds(crypto).await?; + let identity_indexes: BTreeMap = identities + .iter() + .map(|identity| (identity.identity_id, identity.identity_index)) + .collect(); + let key_path = |identity_id: &Identifier, key_id: KeyID| { + let identity_index = identity_indexes + .get(identity_id) + .copied() + .ok_or_else(|| PlatformWalletError::IdentityNotFound(*identity_id))?; + IdentityWallet::::identity_auth_derivation_path( + self.sdk.network, + KeyDerivationType::ECDSA, + identity_index, + key_id, + ) + }; + let contract = dashpay_contract()?; + // Fetched once a pass, and again when a later page's entries are newer + // than the proof: the senders and the wallet's own identities, whose + // keys a request is checked against as they were when it was appended. + let mut proved_identities: BTreeMap = BTreeMap::new(); + // The recipients of the requests the wallet's identities sent, read for + // the key id of the key a request is sealed to, as they were when it + // was appended or later. + let mut recipients: BTreeMap = BTreeMap::new(); + report.next_position = start; + // The largest store size a page proved, in this pass or an earlier + // pass or call (`WalletPersister::private_store_size_proved`): the pass + // reaches the store's end only there. A later page from a node behind, + // its store ending at that page's end, shows an older end. + let mut pass_total: u64 = self.persister.private_store_size_proved(); + let persists_scan_state = self.persister.persists_private_contact_scan_state(); + + // The pages are fetched many at once while earlier ones are processed, + // and scanned in batches of those ready, one key derivation a batch. + let mut batches = std::pin::pin!(self + .sdk + .private_document_pages_with_heights( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + start, + MAX_CONCURRENT_PRIVATE_DOCUMENT_PAGE_FETCHES, + ) + .take(max_pages) + .ready_chunks(PRIVATE_SCAN_BATCH_PAGES)); + while let Some(batch) = batches.next().await { + // The pages before a failed fetch are processed, then the error + // ends the pass. + let mut fetched = Vec::with_capacity(batch.len()); + let mut failure = None; + for page in batch { + match page { + Ok(page) => fetched.push(page), + Err(error) => { + failure = Some(error); + break; + } + } + } + let scans = if fetched.is_empty() { + Vec::new() + } else { + let pages: Vec<(u64, &PrivateDocumentEntries)> = fetched + .iter() + .map(|(page, _)| (page.start_position, &page.entries)) + .collect(); + crypto + .scan_private_document_pages( + &paths, + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + &pages, + ) + .await? + }; + if scans.len() != fetched.len() { + return Err(PlatformWalletError::InvalidIdentityData(format!( + "the crypto provider sorted {} pages into {} scans", + fetched.len(), + scans.len() + ))); + } + let mut reached_end = false; + // The heights each page's reads were proved at, in the scans' order: no entry a + // page holds was appended above the highest, nor sealed to a key added above it, + // and the page shows the store at least as of the lowest. + let page_heights: Vec = + fetched.iter().map(|(_, heights)| *heights).collect(); + for (scan, heights) in scans.into_iter().zip(page_heights) { + report.pages_read += 1; + let stale: BTreeMap = private_contact_request_identities(&scan) + .into_iter() + .filter(|(identity_id, height)| { + proved_identities + .get(identity_id) + .is_none_or(|proved| proved.proved_at_height < *height) + }) + .collect(); + proved_identities.extend( + self.sdk + .fetch_private_contact_request_identities(&stale) + .await?, + ); + let read = private_contact_requests_from_scan( + &contract, + scan, + &proved_identities, + self.sdk.version(), + )?; + pass_total = pass_total.max(read.total_count); + self.persister + .note_private_store_size_proved(read.total_count); + let reaches_end = read.next_position >= pass_total; + // Each recipient is fetched on its own, so one that cannot be read + // holds back only the identities whose sent requests it is for. + let mut stale_recipients: BTreeMap = BTreeMap::new(); + for sent in &read.sent { + let height = stale_recipients.entry(sent.recipient_id).or_default(); + *height = (*height).max(sent.block_height); + } + stale_recipients.retain(|recipient_id, height| { + recipients + .get(recipient_id) + .is_none_or(|proved| proved.proved_at_height < *height) + }); + let mut unreadable_recipients = BTreeSet::new(); + for (recipient_id, height) in stale_recipients { + match self + .sdk + .fetch_private_contact_request_identities(&BTreeMap::from([( + recipient_id, + height, + )])) + .await + { + Ok(fetched) => recipients.extend(fetched), + Err(error) => { + tracing::warn!( + recipient = %recipient_id, + %error, + "the recipient of a sent private contact request could not be read; \ + its sender's cursor is held" + ); + unreadable_recipients.insert(recipient_id); + } + } + } + let held: BTreeSet = read + .sent + .iter() + .filter(|sent| unreadable_recipients.contains(&sent.recipient_id)) + .map(|sent| sent.sender_id) + .collect(); + + // The wallet's records of the page's requests, under the shared + // keys the signer computes. + let mut records: Vec<(Identifier, ContactRequest, bool, Option<[u8; 43]>)> = + Vec::new(); + // The entry commitment of each sent request's record: a pending + // request is settled by it once that record is reconciled. + let mut sent_commitments: Vec<([u8; 32], ContactRequest)> = Vec::new(); + for received in &read.received { + let Some(sender) = proved_identities + .get(&received.sender_id) + .and_then(|proved| proved.identity.as_ref()) + else { + continue; + }; + let sender_key = identity_public_key(sender, received.sender_key_id)?; + let shared_secret = crypto + .ecdh_shared_secret( + &key_path(&received.recipient_id, received.recipient_key_id)?, + &sender_key, + ) + .await?; + // Accepting replies privately, by hand: no auto-accept. + let mut record = private_request_record( + received.sender_id, + received.recipient_id, + received.sender_key_id, + received.recipient_key_id, + &received.request, + &received.commitment, + &shared_secret, + received.block_time_ms, + ); + record.auto_accept_proof = None; + records.push(( + received.recipient_id, + record, + true, + received.request.shielded_address, + )); + } + for sent in &read.sent { + if unreadable_recipients.contains(&sent.recipient_id) { + continue; + } + // The recipient's key the entry was sealed to, compared as + // a curve point: a key may hold the point compressed or + // uncompressed, and the sealer reads both. Only the keys an + // entry can be sealed to are matched. + let recipient_key_id = recipients + .get(&sent.recipient_id) + .and_then(|proved| proved.identity.as_ref()) + .and_then(|recipient| { + recipient + .public_keys() + .iter() + .find(|(_, key)| { + key.key_type() == KeyType::ECDSA_SECP256K1 + && recipient_key_purpose_is_valid(key.purpose()) + && PublicKey::from_slice(key.data().as_slice()) + .is_ok_and(|point| point == sent.recipient_public_key) + }) + .map(|(key_id, _)| *key_id) + }); + let Some(recipient_key_id) = recipient_key_id else { + tracing::warn!( + sender = %sent.sender_id, + recipient = %sent.recipient_id, + position = sent.position, + "sent private contact request is sealed to a key its recipient does not \ + hold; not recorded" + ); + continue; + }; + let shared_secret = crypto + .ecdh_shared_secret( + &key_path(&sent.sender_id, sent.sender_key_id)?, + &sent.recipient_public_key, + ) + .await?; + let record = private_request_record( + sent.sender_id, + sent.recipient_id, + sent.sender_key_id, + recipient_key_id, + &sent.request, + &sent.commitment, + &shared_secret, + sent.block_time_ms, + ); + sent_commitments.push((sent.commitment, record.clone())); + records.push((sent.sender_id, record, false, None)); + } + for rejected in &read.rejected { + tracing::debug!( + position = rejected.position, + reason = ?rejected.reason, + "private contact request refused" + ); + } + report.rejected.extend(read.rejected.iter().cloned()); + + // Ingest what the page held for each identity, then advance its + // cursor past the page if that reached disk. + let mut candidates = Vec::new(); + { + // Fenced to this handle's generation: what the pass read + // never lands on a wallet re-created under its id. + let mut wm = self.wallet_manager.write().await; + let (wallet, info) = self.current_wallet_and_info_mut(&mut wm)?; + for identity in identities.iter_mut() { + let identity_id = identity.identity_id; + let Some(managed) = + info.identity_manager.managed_identity_mut(&identity_id) + else { + continue; + }; + if held.contains(&identity_id) && !identity.failed { + identity.failed = true; + report.unpersisted_identities.push(identity_id); + } + let mut received = Vec::new(); + let mut addresses = Vec::new(); + let mut sent = Vec::new(); + for (owner, record, is_received, shielded_address) in &records { + if *owner != identity_id { + continue; + } + if *is_received { + addresses.push((record.clone(), *shielded_address)); + received.push(record.clone()); + } else { + // Our receiving account for the contact is + // scanned from the wallet's birth. + managed.note_sent_request_core_height(record.recipient_id, 0); + sent.push(record.clone()); + } + } + let mut rotated = Vec::new(); + let mut ingested = Vec::new(); + let received_ok = ingest_received_requests( + managed, + &self.persister, + identity_id, + newest_received_per_sender(received), + &mut rotated, + &mut ingested, + ); + let sent_ok = ingest_sent_requests( + managed, + &self.persister, + identity_id, + newest_sent_per_recipient(sent), + &mut ingested, + ); + report.requests.extend(ingested); + // The address of the request tracked from each contact, + // once ingest decided which that is. + for (record, shielded_address) in &addresses { + managed.note_private_shielded_address(record, *shielded_address); + } + // The addresses are stored before the read position + // that covers the entries they came from. + let mut stored = received_ok && sent_ok; + if stored && persists_scan_state && !addresses.is_empty() { + let addresses_changeset = + shielded_address_changeset(managed, identity_id, &addresses); + if let Err(error) = self.persister.store(addresses_changeset.into()) { + tracing::error!( + owner = %identity_id, %error, + "private contacts' shielded addresses not stored; leaving \ + the private cursor for retry" + ); + stored = false; + } + } + if stored { + let unresolved = managed.dashpay().private_payments_unresolved(); + // A pending private request is settled once its + // entry's record is reconciled: the request tracked + // to the recipient is that record, carries its + // account reference (another copy of it), or is + // newer. An entry whose record was not built, its + // recipient unreadable, settles nothing. + #[cfg(feature = "shielded")] + let mut read_back: Vec<[u8; 32]> = Vec::new(); + for (commitment, record) in sent_commitments + .iter() + .filter(|(_, record)| record.sender_id == identity_id) + { + let reconciled = managed + .dashpay() + .outgoing_request(&record.recipient_id) + .is_some_and(|tracked| { + tracked.account_reference == record.account_reference + || predates(record, tracked) + }); + if reconciled { + managed.settle_private_reply(&record.recipient_id, commitment); + #[cfg(feature = "shielded")] + read_back.push(*commitment); + } + } + let before = managed.dashpay().private_contact_requests_position(); + identity.advance(managed, read.next_position); + // Read with its keys, from its own cursor: the + // height its read rests on rises. Not by a page of + // a pass whose keys changed under it, or whose + // cursor was rewound under it, which counts for + // nothing: the rewind kept the height the read + // rested on as the floor a read since must reach + // (`ManagedIdentity::rewind_private_store_read`), + // and such a page would pass it. + if !identity.failed && !identity.rewound { + managed.note_private_store_page_read(heights.max); + } + let after = managed.dashpay().private_contact_requests_position(); + // Stored once it moved, once the last private + // payment it held settled, or once its marker + // differs from the one last stored. + if persists_scan_state + && (after != before + || managed.dashpay().private_payments_unresolved() + != unresolved + || private_marker_stale(&self.persister, identity_id, managed)) + { + store_private_position( + &self.persister, + identity_id, + managed.private_contact_requests_position_record(), + ); + } + // The shielded store's journal records of the entries + // read back are discharged once what records them is + // durable: a record lost with them would leave the + // pair unheld while no request of it is recorded. + #[cfg(feature = "shielded")] + if !read_back.is_empty() { + self.persister.note_read_back_once_durable(read_back); + } + } else if !identity.failed { + identity.failed = true; + report.unpersisted_identities.push(identity_id); + } + // Read to the store's end with nothing held back this + // pass: every entry was ingested for this identity. + // Not once its cursor was rewound under the pass (a + // sender unignored): the entries before it were read + // with the sender ignored, and the next pass reads + // them again. + if reaches_end + && !identity.failed + && !identity.rewound + && identity.keys_current(managed) + && managed.note_private_contact_requests_read(heights.min) + { + report.read_to_end.push(identity_id); + } + tear_down_stale_external_accounts(wallet, info, &identity_id, rotated); + candidates.push(( + identity_id, + Self::collect_account_build_candidates(info, &identity_id), + )); + } + } + for (identity_id, identity_candidates) in candidates { + for candidate in identity_candidates { + self.build_contact_accounts(&identity_id, candidate).await; + } + } + + report.next_position = read.next_position; + if reaches_end { + // A pass whose ingest did not reach disk for an identity is + // not complete: that identity reads its entries again. + report.complete = report.unpersisted_identities.is_empty(); + reached_end = true; + break; + } + } + if let Some(error) = failure { + return Err(error.into()); + } + if reached_end { + break; + } + } + Ok(report) + } + + /// Restore, after a restart, the pending private requests whose payment + /// is unconfirmed: `entries` are those of the signed transitions the + /// shielded store keeps for unconfirmed spends to DashPay's + /// `privateContactRequest` store + /// (`PlatformWallet::restore_pending_private_contact_requests` reads + /// them). Each opens with the keys of the wallet's identities, and every + /// one an identity sent reserves its recipient again under the entry's + /// commitment, so no second request to it is sent, privately or + /// publicly, until a private sync reads the entry back and settles it. + /// A recipient already reserved keeps its reservation, which gets the + /// entry's commitment only when it has none yet. Returns the (sender, + /// recipient) pairs restored. + /// + /// An entry is discharged once its own request or a superseding one is + /// recorded: it is left alone when the request the sender tracks to its + /// recipient has the entry's account reference, or a later version. So an + /// unconfirmed rotation is restored over the request it rotates, and an + /// entry read back while its spend still waits for confirmation is not. + /// + /// An entry whose request does not decode is left alone: no sync could + /// record it, so its reservation would never settle. A record saved with + /// the request it pays for is restored without this call when the wallet + /// binds to its shielded coordinator + /// (`PlatformWallet::restore_private_contact_payments`); this call stays + /// for records saved before that. + pub async fn restore_pending_private_contact_requests( + &self, + entries: &[BinaryData], + crypto: &C, + ) -> Result, PlatformWalletError> + where + C: ContactCryptoProvider + Sync, + { + self.restore_private_reservations(entries, crypto, None) + .await + } + + /// Restore, after a restart or a bind, the reservations of the private + /// contact request payments the shielded store's private payment journal + /// keeps for this wallet, `payments` being each record's (sender, + /// recipient, account reference, the entry's commitment), and release the + /// holds a load set on the wallet's identities, all under one wallet + /// lock: an identity added in between is either restored and released or + /// neither. Nothing is opened, so no keys are needed. + /// + /// A payment whose request the sender's tracked request to that recipient + /// records or supersedes is resolved and left alone, as + /// [`Self::restore_pending_private_contact_requests`] leaves it. One + /// whose sender the wallet does not manage holds its pair for the sends + /// of an identity added later, until its record is discharged + /// (`WalletPersister::private_pair_journaled`). + /// + /// An identity loaded marking a private payment that may be unresolved + /// is released when the journal is authoritative (`journal_authoritative`: + /// open before this bind, so it keeps every payment the wallet made since) + /// or holds a restored reservation now. Otherwise the journal cannot + /// account for its payment, the store being new or replaced: it stays + /// held, and the restoration fails with + /// [`PlatformWalletError::ShieldedRecoveryCorrupted`]. Returns the + /// (sender, recipient) pairs restored. + #[cfg(all(test, feature = "shielded"))] + pub(crate) async fn restore_private_payments( + &self, + payments: &[JournaledPrivatePayment], + journal_authoritative: bool, + ) -> Result, PlatformWalletError> { + restore_journaled_private_payments( + &self.wallet_manager, + &self.generation, + &self.persister, + self.wallet_id, + payments, + journal_authoritative, + ) + .await + .map(|(restored, _)| restored) + } + + /// Whether an earlier private payment from `sender` to `recipient` that + /// the shielded store's journal keeps, `journaled` being each one's + /// (account reference, entry commitment), may still execute, neither its + /// request nor a later one being recorded: then the recipient stays + /// reserved for that entry instead of the one about to be paid, which + /// must not be. + #[cfg(feature = "shielded")] + pub(crate) async fn hold_for_journaled_private_payment( + &self, + sender: &Identifier, + recipient: &Identifier, + journaled: &[(u32, [u8; 32])], + ) -> Result { + if journaled.is_empty() { + return Ok(false); + } + let payments: Vec = journaled + .iter() + .map(|&(account_reference, commitment)| { + (*sender, *recipient, account_reference, commitment, None) + }) + .collect(); + let mut wm = self.wallet_manager.write().await; + let info = wm + .get_wallet_info_mut(&self.wallet_id) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))?; + if info.identity_manager.managed_identity(sender).is_none() { + return Err(PlatformWalletError::IdentityNotFound(*sender)); + } + let reserved = reserve_unresolved_private_payments( + info, + &self.generation, + self.wallet_id, + &self.persister, + &payments, + Some((*sender, *recipient)), + )?; + Ok(!reserved.restored.is_empty()) + } + + /// Whether a request from `sender` to `recipient` among `entries`, paid + /// for before a restart and unconfirmed, may still execute, neither it nor + /// a later request being recorded (a rotation over the tracked request + /// counts): then the recipient stays reserved for that entry instead of + /// the one about to be paid, which must not be. The other entries are + /// restored as [`Self::restore_pending_private_contact_requests`] restores + /// them. + #[cfg(test)] + pub(crate) async fn hold_for_restored_private_contact_request( + &self, + entries: &[BinaryData], + crypto: &C, + sender: &Identifier, + recipient: &Identifier, + ) -> Result + where + C: ContactCryptoProvider + Sync, + { + let pair = (*sender, *recipient); + Ok(self + .restore_private_reservations(entries, crypto, Some(pair)) + .await? + .contains(&pair)) + } + + /// Open `entries` as one page of the store and reserve the recipient of + /// each the wallet's identities sent whose request is neither recorded + /// nor superseded yet; the pair `paying` is retargeted to its restored + /// entry instead. Reserved through [`reserve_unresolved_private_payments`], + /// as a journal restoration reserves: fenced to this handle's wallet + /// generation, and leaving alone an entry whose payment's journal record + /// was discharged in this session, though the discharge came while the + /// entries were opened (checked under the wallet lock). + async fn restore_private_reservations( + &self, + entries: &[BinaryData], + crypto: &C, + paying: Option<(Identifier, Identifier)>, + ) -> Result, PlatformWalletError> + where + C: ContactCryptoProvider + Sync, + { + if entries.is_empty() { + return Ok(Vec::new()); + } + let (_, paths) = self.private_scan_identities().await?; + if paths.senders.is_empty() { + return Ok(Vec::new()); + } + let contract = dashpay_contract()?; + let document_type = contract + .document_type_for_name(PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME) + .map_err(|error| { + PlatformWalletError::InvalidIdentityData(format!( + "the bundled DashPay has no {PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME} type: \ + {error}" + )) + })?; + let page = PrivateDocumentEntries { + chunk_power: None, + entries: entries + .iter() + .zip(0u64..) + .map(|(data, position)| PrivateDocumentEntry { + position, + block_height: 0, + block_time_ms: 0, + data: data.to_vec(), + }) + .collect(), + total_count: entries.len() as u64, + }; + let scan = crypto + .scan_private_document_page( + &paths, + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + 0, + &page, + ) + .await?; + + let mut payments: Vec = Vec::new(); + for sent in scan.sent { + let sender = sent.sender_identity_id; + // The wallet's own entries name the identity that sealed them. + if Identifier::from(*sent.entry.sender_identity_id()) != sender { + continue; + } + let recipient = Identifier::from(*sent.entry.recipient_identity_id()); + let request = decode_private_document_payload( + document_type, + sent.entry.payload(), + self.sdk.version(), + ) + .map_err(|error| error.to_string()) + .and_then(|properties| { + PrivateContactRequest::from_properties(properties) + .map_err(|error| error.to_string()) + }); + let request = match request { + Ok(request) => request, + Err(error) => { + tracing::warn!( + sender = %sender, + recipient = %recipient, + %error, + "an unconfirmed private contact request does not decode; not restored" + ); + continue; + } + }; + payments.push(( + sender, + recipient, + request.account_reference, + *sent.entry.commitment(), + None, + )); + } + let mut wm = self.wallet_manager.write().await; + let info = wm + .get_wallet_info_mut(&self.wallet_id) + .ok_or_else(|| PlatformWalletError::WalletNotFound(hex::encode(self.wallet_id)))?; + // A sender the wallet does not manage is not held here: the journal + // restoration holds those. + let reserved = reserve_unresolved_private_payments( + info, + &self.generation, + self.wallet_id, + &self.persister, + &payments, + paying, + )?; + Ok(reserved.restored) + } +} + +#[cfg(test)] +mod tests { + use super::super::contact_requests::sent_contact_request_query; + use super::*; + use crate::changeset::{ + ClientStartState, ClientWalletStartState, IdentityManagerStartState, + PersistenceCapabilities, PersistenceError, PersistenceErrorKind, PlatformWalletChangeSet, + PlatformWalletPersistence, + }; + use crate::events::{EventHandler, PlatformEventHandler}; + use crate::wallet::identity::network::identity_auth_derivation_path_for_type; + use crate::wallet::identity::network::SeedCryptoProvider; + use crate::wallet::platform_wallet::{PlatformWallet, WalletId}; + #[cfg(feature = "shielded")] + use crate::wallet::shielded::coordinator::{ + heightless_tree_bounds, private_payment_journal_snapshot, HeightlessAnchorEvidence, + PrunedAnchorEvidence, + }; + #[cfg(feature = "shielded")] + use crate::wallet::shielded::operations::{ + arm_redrive_before_broadcast, pay_private_document_with_outcome, TestBroadcastOutcome, + }; + #[cfg(feature = "shielded")] + use crate::wallet::shielded::{ + FileBackedShieldedStore, NetworkShieldedCoordinator, OrchardKeySet, PrivateContactPayment, + PrivatePaymentRecord, ShieldedNote, ShieldedStore, SubwalletId, + }; + use crate::PlatformWalletManager; + use dash_sdk::error::ContextProviderError; + use dash_sdk::platform::private_document_entries::{ + PrivateDocumentEntriesQuery, PrivateDocumentEntry, + }; + use dash_sdk::platform::private_document_scan::PrivateDocumentScan; + use dash_sdk::platform::ContextProvider; + use dpp::address_funds::AddressWitness; + use dpp::data_contract::{DataContract, TokenConfiguration}; + use dpp::document::{Document, DocumentV0}; + use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeySettersV0; + use dpp::identity::identity_public_key::v0::IdentityPublicKeyV0; + use dpp::identity::v0::IdentityV0; + use dpp::identity::{IdentityPublicKey, SecurityLevel}; + use dpp::platform_value::Value; + use dpp::state_transition::batch_transition::BatchTransition; + use dpp::state_transition::StateTransition; + use dpp::version::PlatformVersion; + use dpp::ProtocolError; + use key_wallet::account::account_collection::DashpayAccountKey; + use key_wallet::bip32::DerivationPath; + use key_wallet::mnemonic::Mnemonic; + use key_wallet::wallet::initialization::WalletAccountCreationOptions; + use key_wallet::Network; + use platform_encryption::{ + account_reference_version, decrypt_account_label, decrypt_extended_public_key, + }; + #[cfg(feature = "shielded")] + use std::collections::HashSet; + use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; + use std::sync::Mutex; + use std::time::Duration; + #[cfg(feature = "shielded")] + use tokio_util::sync::CancellationToken; + + const ALICE_PHRASE: &str = "abandon abandon abandon abandon abandon abandon abandon abandon \ + abandon abandon abandon about"; + const BOB_PHRASE: &str = + "legal winner thank year wave sausage worth useful legal winner thank yellow"; + const ALICE: [u8; 32] = [0xA1; 32]; + const BOB: [u8; 32] = [0xB1; 32]; + const CAROL_PHRASE: &str = + "letter advice cage absurd amount doctor acoustic avoid letter advice cage above"; + const CAROL: [u8; 32] = [0xC2; 32]; + /// The time of the block that appends the test entries. + const BLOCK_TIME_MS: u64 = 1_700_000_000_000; + /// The key ids of each test identity's signing key and DashPay keys. + const SIGNING_KEY_ID: KeyID = 0; + const ENCRYPTION_KEY_ID: KeyID = 1; + const DECRYPTION_KEY_ID: KeyID = 2; + + #[derive(Default)] + /// A backend that keeps nothing, declaring that it keeps the private + /// contact request scan state and commits each store inline, so private + /// payments, which need their recovery marker kept, run over it. The tests + /// using it never reload what it kept. + struct NoPersistence; + + impl PlatformWalletPersistence for NoPersistence { + fn persistence_capabilities(&self) -> PersistenceCapabilities { + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART + } + + fn store_commits_inline(&self) -> bool { + true + } + + fn store( + &self, + _wallet_id: WalletId, + _changeset: PlatformWalletChangeSet, + ) -> Result<(), PersistenceError> { + Ok(()) + } + + fn flush(&self, _wallet_id: WalletId) -> Result<(), PersistenceError> { + Ok(()) + } + + fn load(&self) -> Result { + Ok(ClientStartState::default()) + } + } + + struct NoopEventHandler; + impl EventHandler for NoopEventHandler {} + impl PlatformEventHandler for NoopEventHandler {} + + /// A context provider holding the bundled DashPay contract. + struct DashpayContractProvider(Arc); + + impl ContextProvider for DashpayContractProvider { + fn get_data_contract( + &self, + id: &Identifier, + _platform_version: &PlatformVersion, + ) -> Result>, ContextProviderError> { + Ok((*id == self.0.id()).then(|| Arc::clone(&self.0))) + } + + fn get_token_configuration( + &self, + _token_id: &Identifier, + ) -> Result, ContextProviderError> { + Ok(None) + } + + fn get_quorum_public_key( + &self, + _quorum_type: u32, + _quorum_hash: [u8; 32], + _core_chain_locked_height: u32, + ) -> Result<[u8; 48], ContextProviderError> { + Err(ContextProviderError::Config( + "no quorum keys in this test".into(), + )) + } + + fn get_platform_activation_height(&self) -> Result { + Ok(1) + } + } + + fn seed(phrase: &str) -> [u8; 64] { + *Mnemonic::from_phrase(phrase) + .expect("test mnemonic") + .to_seed("") + } + + /// The secret key `key_id` of identity index 0 of `phrase`'s seed. + fn identity_secret_key(phrase: &str, key_id: KeyID) -> SecretKey { + let wallet = key_wallet::wallet::Wallet::from_seed_bytes( + seed(phrase), + Network::Testnet, + WalletAccountCreationOptions::None, + ) + .expect("test wallet"); + let path = identity_auth_derivation_path_for_type( + Network::Testnet, + KeyDerivationType::ECDSA, + 0, + key_id, + ) + .expect("identity key path"); + let xprv = wallet + .derive_extended_private_key(&path) + .expect("identity key"); + SecretKey::from_secret_bytes(*xprv.private_key.to_bytes()).expect("secret key") + } + + /// The identity `id` whose keys are those of identity index 0 of + /// `phrase`'s seed: its HIGH signing key 0, encryption key 1 and + /// decryption key 2. + fn identity(phrase: &str, id: [u8; 32]) -> Identity { + let key = |key_id: KeyID, purpose: Purpose, security_level: SecurityLevel| { + IdentityPublicKey::V0(IdentityPublicKeyV0 { + id: key_id, + purpose, + security_level, + contract_bounds: None, + key_type: KeyType::ECDSA_SECP256K1, + read_only: false, + data: BinaryData::new( + PublicKey::from_secret_key(&identity_secret_key(phrase, key_id)) + .serialize() + .to_vec(), + ), + disabled_at: None, + }) + }; + let keys = [ + key(SIGNING_KEY_ID, Purpose::AUTHENTICATION, SecurityLevel::HIGH), + key( + ENCRYPTION_KEY_ID, + Purpose::ENCRYPTION, + SecurityLevel::MEDIUM, + ), + key( + DECRYPTION_KEY_ID, + Purpose::DECRYPTION, + SecurityLevel::MEDIUM, + ), + ]; + Identity::V0(IdentityV0 { + id: Identifier::from(id), + public_keys: keys.into_iter().map(|key| (key.id(), key)).collect(), + balance: 0, + revision: 0, + }) + } + + /// The signer holding `identity`'s signing key, as a host's signer holds + /// the keys it signs transitions with. + fn signer(phrase: &str, identity: &Identity) -> simple_signer::signer::SimpleSigner { + let mut signer = simple_signer::signer::SimpleSigner::default(); + signer.add_identity_public_key( + identity + .get_public_key_by_id(SIGNING_KEY_ID) + .expect("the signing key") + .clone(), + identity_secret_key(phrase, SIGNING_KEY_ID).to_secret_bytes(), + ); + signer + } + + /// A backend recording every changeset stored, attesting `capabilities`. + #[derive(Default)] + struct RecordingPersistence { + capabilities: PersistenceCapabilities, + stored: Mutex>, + /// While set, a store carrying a private read position record fails + /// and keeps nothing. + positions_fail: AtomicBool, + /// While set, a flush fails, transiently: the backend keeps what it + /// buffered. + flush_fails: AtomicBool, + /// While set, a flush fails fatally: the backend drops what it + /// buffered. + flush_fails_fatally: AtomicBool, + } + + impl RecordingPersistence { + fn attesting(capabilities: PersistenceCapabilities) -> Arc { + Arc::new(Self { + capabilities, + stored: Mutex::new(Vec::new()), + positions_fail: AtomicBool::new(false), + flush_fails: AtomicBool::new(false), + flush_fails_fatally: AtomicBool::new(false), + }) + } + + /// The contact changesets stored, in order. + fn contacts(&self) -> Vec { + self.stored + .lock() + .expect("stored") + .iter() + .filter_map(|changeset| changeset.contacts.clone()) + .collect() + } + } + + impl PlatformWalletPersistence for RecordingPersistence { + fn store( + &self, + _wallet_id: WalletId, + changeset: PlatformWalletChangeSet, + ) -> Result<(), PersistenceError> { + if self.positions_fail.load(Ordering::SeqCst) + && changeset + .contacts + .as_ref() + .is_some_and(|contacts| !contacts.private_contact_requests_positions.is_empty()) + { + return Err(PersistenceError::backend("the disk is full")); + } + self.stored.lock().expect("stored").push(changeset); + Ok(()) + } + + fn flush(&self, _wallet_id: WalletId) -> Result<(), PersistenceError> { + if self.flush_fails.load(Ordering::SeqCst) { + return Err(PersistenceError::backend_with_kind( + PersistenceErrorKind::Transient, + "the disk is busy", + )); + } + if self.flush_fails_fatally.load(Ordering::SeqCst) { + return Err(PersistenceError::backend("the database is corrupt")); + } + Ok(()) + } + + fn load(&self) -> Result { + Ok(ClientStartState::default()) + } + + fn persistence_capabilities(&self) -> PersistenceCapabilities { + self.capabilities + } + } + + /// A wallet of `phrase` holding `own` at identity index 0, on a mock SDK that + /// answers identity fetches with `known` and page 0 of DashPay's private + /// contact request store with `entries`. + async fn wallet( + phrase: &str, + own: &Identity, + known: &[&Identity], + entries: Vec>, + ) -> (PlatformWalletManager, Arc) { + wallet_on(Arc::new(NoPersistence), phrase, own, known, entries).await + } + + /// [`wallet`] on the backend `persistence`. + async fn wallet_on( + persistence: Arc

, + phrase: &str, + own: &Identity, + known: &[&Identity], + entries: Vec>, + ) -> (PlatformWalletManager

, Arc) { + wallet_at( + persistence, + phrase, + own, + known, + entries, + PlatformVersion::latest(), + None, + ) + .await + } + + /// [`wallet_on`], with its SDK pinned to `platform_version` and holding + /// DashPay as that version bundles it, which a DashPay fetch also + /// answers; `verified_network` is the network's version a verified + /// answer showed, when one did. + async fn wallet_at( + persistence: Arc

, + phrase: &str, + own: &Identity, + known: &[&Identity], + entries: Vec>, + platform_version: &'static PlatformVersion, + verified_network: Option, + ) -> (PlatformWalletManager

, Arc) { + let sdk = dashpay_sdk(known, entries, platform_version, verified_network).await; + let manager = + PlatformWalletManager::new(Arc::new(sdk), persistence, Arc::new(NoopEventHandler)); + let wallet = manager + .create_wallet_from_seed_bytes( + Network::Testnet, + &seed(phrase), + WalletAccountCreationOptions::Default, + Some(0), + ) + .await + .expect("wallet"); + { + let iw = wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let info = wm + .get_wallet_info_mut(&wallet.wallet_id()) + .expect("wallet info"); + info.identity_manager + .add_identity(own.clone(), 0, wallet.wallet_id(), &iw.persister) + .expect("own identity"); + } + // As a host that configured an empty shielded store before creating + // the wallet: a wallet published with none, its persister keeping the + // private scan state, is otherwise held until one is. The tests of + // that hold build their wallets without this. + #[cfg(feature = "shielded")] + wallet.persister().private_payments_restored(); + (manager, wallet) + } + + /// The mock SDK of [`wallet_at`]: pinned to `platform_version`, holding + /// DashPay as that version bundles it, answering fetches of `known` and + /// of the private store's first page, holding `entries`. + async fn dashpay_sdk( + known: &[&Identity], + entries: Vec>, + platform_version: &'static PlatformVersion, + verified_network: Option, + ) -> dash_sdk::Sdk { + let contract = Arc::new( + dpp::system_data_contracts::load_system_data_contract( + dpp::data_contracts::SystemDataContract::Dashpay, + platform_version, + ) + .expect("bundled DashPay"), + ); + let mut sdk = dash_sdk::SdkBuilder::new_mock() + .with_network(Network::Testnet) + .with_version(platform_version) + .with_context_provider(DashpayContractProvider(Arc::clone(&contract))) + .build() + .expect("mock sdk"); + if let Some(verified) = verified_network { + sdk.mock_verified_protocol_version(verified) + .expect("a mock SDK"); + } + sdk.mock() + .expect_fetch(contract.id(), Some((*contract).clone())) + .await + .expect("DashPay expectation"); + for identity in known { + sdk.mock() + .expect_fetch(identity.id(), Some((*identity).clone())) + .await + .expect("identity expectation"); + } + // The mock proves identities at height 0, which an entry's identities + // must be proved at or after: every entry is at height 0. + expect_store_from(&mut sdk, 0, entries).await; + sdk + } + + /// A backend handing back, on every load, a wallet as [`snapshot`] or + /// [`scan_state_snapshot`] took it: the relaunch of a wallet from an + /// earlier process, with the viewing key its shielded account 0 bound + /// with, when it bound one. It keeps what the relaunched wallet stores. + struct SnapshotPersistence { + wallet: key_wallet::Wallet, + core: key_wallet::wallet::ManagedWalletInfo, + identities: BTreeMap, + capabilities: PersistenceCapabilities, + #[cfg(feature = "shielded")] + viewing_key: Option<[u8; 96]>, + stored: Mutex>, + retained: BTreeMap>, + } + + impl SnapshotPersistence { + /// Whether the last position record stored for `owner` marks a private + /// payment that may be unresolved, if one was stored. + #[cfg(feature = "shielded")] + fn last_marker(&self, owner: &Identifier) -> Option { + last_marker(&self.stored.lock().expect("stored"), owner) + } + } + + /// Whether the last of `stored` to carry `owner`'s position record marks a + /// private payment that may be unresolved. + fn last_marker(stored: &[PlatformWalletChangeSet], owner: &Identifier) -> Option { + stored + .iter() + .rev() + .filter_map(|changeset| changeset.contacts.as_ref()) + .find_map(|contacts| contacts.private_contact_requests_positions.get(owner)) + .map(|position| position.private_payments_unresolved) + } + + impl PlatformWalletPersistence for SnapshotPersistence { + fn persistence_capabilities(&self) -> PersistenceCapabilities { + self.capabilities + } + + fn store( + &self, + _wallet_id: WalletId, + changeset: PlatformWalletChangeSet, + ) -> Result<(), PersistenceError> { + self.stored.lock().expect("stored").push(changeset); + Ok(()) + } + + fn flush(&self, _wallet_id: WalletId) -> Result<(), PersistenceError> { + Ok(()) + } + + fn load(&self) -> Result { + let wallet_id = self.wallet.compute_wallet_id(); + let mut wallet_identities = BTreeMap::new(); + wallet_identities.insert(wallet_id, self.identities.clone()); + let mut wallets = BTreeMap::new(); + wallets.insert( + wallet_id, + ClientWalletStartState { + wallet: self.wallet.clone(), + wallet_info: self.core.clone(), + identity_manager: IdentityManagerStartState { + wallet_identities, + ..Default::default() + }, + unused_asset_locks: BTreeMap::new(), + unconfirmed_outgoing_txs: Vec::new(), + dashpay_backfill: Default::default(), + }, + ); + #[allow(unused_mut)] + let mut state = ClientStartState { + wallets, + retained_private_contact_scan_states: self.retained.clone(), + ..Default::default() + }; + #[cfg(feature = "shielded")] + if let Some(viewing_key) = self.viewing_key { + state + .shielded + .viewing_keys + .insert(SubwalletId::new(wallet_id, 0), viewing_key.to_vec()); + } + Ok(state) + } + } + + /// `wallet`, from `phrase`, with its identity `owner`, as a backend keeps + /// it once its shielded account 0 is bound. + #[cfg(feature = "shielded")] + async fn snapshot( + wallet: &PlatformWallet, + owner: &Identifier, + phrase: &str, + ) -> SnapshotPersistence { + let iw = wallet.identity(); + let wm = iw.wallet_manager.read().await; + let wallet_id = wallet.wallet_id(); + let info = wm.get_wallet_info(&wallet_id).expect("wallet info"); + let mut identities = BTreeMap::new(); + identities.insert( + 0, + info.identity_manager + .managed_identity(owner) + .expect("the owner") + .clone(), + ); + SnapshotPersistence { + wallet: wm.get_wallet(&wallet_id).expect("the wallet").clone(), + core: info.core_wallet.clone(), + identities, + capabilities: PersistenceCapabilities::SHIELDED_FVK_RESTART, + viewing_key: Some( + OrchardKeySet::from_seed(&seed(phrase), Network::Testnet, 0) + .expect("shielded keys") + .viewing_keys() + .to_fvk_bytes(), + ), + stored: Mutex::default(), + retained: BTreeMap::new(), + } + } + + /// `wallet`, with its identity `owner`, as a backend keeping the private + /// contact request scan state keeps it, with no shielded viewing key: the + /// identity's position record marks a private payment that may be + /// unresolved when `unresolved`, as a process that paid for one and ended + /// before it resolved stored it. + async fn scan_state_snapshot( + wallet: &PlatformWallet, + owner: &Identifier, + unresolved: bool, + ) -> SnapshotPersistence { + let iw = wallet.identity(); + let wm = iw.wallet_manager.read().await; + let wallet_id = wallet.wallet_id(); + let info = wm.get_wallet_info(&wallet_id).expect("wallet info"); + let mut managed = info + .identity_manager + .managed_identity(owner) + .expect("the owner") + .clone(); + managed.apply_private_contact_requests_position(PrivateContactRequestsPosition { + private_payments_unresolved: unresolved, + ..managed.private_contact_requests_position_record() + }); + SnapshotPersistence { + wallet: wm.get_wallet(&wallet_id).expect("the wallet").clone(), + core: info.core_wallet.clone(), + identities: BTreeMap::from([(0, managed)]), + capabilities: PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + #[cfg(feature = "shielded")] + viewing_key: None, + stored: Mutex::default(), + retained: BTreeMap::new(), + } + } + + /// A process that paid for a private contact request and ended before the + /// payment resolved stored the identity's position record marking it, in a + /// build with the `shielded` feature: reloaded, in any build, the identity + /// sends and accepts no public contact request, with nothing read, signed + /// or sent, as no reservation holds the pair the payment is for. A build + /// with the `shielded` feature releases it once the shielded store is + /// configured, which restores the reservations and stores the record + /// unmarked, when the store's journal was open before, so it accounts for + /// the payment: one opened only now (a deleted or replaced store) keeps + /// the identity held. No private sync releases it, and a build without + /// the `shielded` feature keeps it. + #[tokio::test] + async fn should_hold_an_identity_reloaded_marking_an_unresolved_private_payment() { + for journal_open_before in [false, true] { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let incoming = public_request(&bob, &alice, 3); + let (_before_manager, before) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + add_incoming(&before, ALICE, &incoming).await; + let kept = Arc::new(scan_state_snapshot(&before, &alice.id(), true).await); + + let manager = PlatformWalletManager::new( + Arc::new( + dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await, + ), + Arc::clone(&kept), + Arc::new(NoopEventHandler), + ); + manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + let restarted = manager + .get_wallet(&before.wallet_id()) + .await + .expect("the relaunched wallet"); + assert!(restarted.private_payments_held().await); + + let public = restarted + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{public:?}" + ); + let accepted = restarted + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &incoming, + None, + &alice_signer, + &alice_crypto, + no_payment, + ) + .await; + assert!( + matches!( + accepted, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{accepted:?}" + ); + + // No private request is paid for either. + let private = restarted + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + no_payment, + ) + .await; + assert!( + matches!( + private, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{private:?}" + ); + // A private sync reads the store, and restores nothing. + let view = restarted.identity().dashpay(); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the private sync"); + assert_eq!( + view.private_contact_readiness(&alice.id()) + .await + .expect("the readiness"), + PrivateContactReadiness { + private_payments_restored: false, + private_store_read: true, + unresolved_private_payment: true, + private_payments_restore_failure: None, + } + ); + assert!(restarted.private_payments_held().await, "still held"); + + #[cfg(feature = "shielded")] + { + let dir = tempfile::tempdir().expect("temporary shielded store"); + let path = dir.path().join("tree.sqlite"); + if journal_open_before { + // An earlier bind's restoration opened the wallet's journal. + let mut store = + FileBackedShieldedStore::open_path(&path, 100).expect("the store"); + store + .open_private_payment_journal(before.wallet_id()) + .expect("opened"); + } + manager + .configure_shielded(path) + .await + .expect("the shielded store is configured"); + if journal_open_before { + assert!(!restarted.private_payments_held().await, "restored"); + assert_eq!(kept.last_marker(&alice.id()), Some(false)); + assert_eq!( + view.private_contact_readiness(&alice.id()) + .await + .expect("the readiness"), + PrivateContactReadiness { + private_payments_restored: true, + private_store_read: true, + unresolved_private_payment: false, + private_payments_restore_failure: None, + } + ); + } else { + // A journal opened only now, as in a deleted or replaced + // store, cannot show the marked payment resolved. + assert!(restarted.private_payments_held().await, "still held"); + assert_ne!(kept.last_marker(&alice.id()), Some(false), "never cleared"); + let public = restarted + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{public:?}" + ); + } + } + #[cfg(not(feature = "shielded"))] + assert!( + restarted.private_payments_held().await, + "no shielded store restores it here, journal open before: {journal_open_before}" + ); + } + } + + /// A private sync stores an identity's position record whenever its + /// marker differs from the one last stored in this session, though + /// nothing moved: one whose store failed is stored by the next sync, and + /// not again while it is unchanged. + #[tokio::test] + async fn should_store_a_marker_that_differs_from_the_one_last_stored() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let persistence = RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ); + let (_manager, alice_wallet) = wallet_on( + Arc::clone(&persistence), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + let records = || { + persistence + .stored + .lock() + .expect("stored") + .iter() + .filter_map(|changeset| changeset.contacts.as_ref()) + .filter(|contacts| { + contacts + .private_contact_requests_positions + .contains_key(&alice.id()) + }) + .count() + }; + let view = alice_wallet.identity().dashpay(); + let before = records(); + persistence.positions_fail.store(true, Ordering::SeqCst); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("a private sync whose position stores fail"); + assert_eq!(records(), before, "nothing kept"); + persistence.positions_fail.store(false, Ordering::SeqCst); + + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the next private sync"); + assert_eq!(records(), before + 1, "stored, though nothing moved"); + assert_eq!( + last_marker(&persistence.stored.lock().expect("stored"), &alice.id()), + Some(false) + ); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("another private sync"); + assert_eq!(records(), before + 1, "unchanged: not stored again"); + } + + /// A read-back whose records' flush fails keeps its notice: the pair stays + /// held, as the journal record does, and a retry pays nothing. The next + /// step's flush succeeds and notes it, the coordinator discharges the + /// record, the pair is freed, and a retry pays. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_keep_a_read_back_notice_whose_flush_failed_until_a_flush_succeeds() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let fixture = ExpiryFixture::new().await; + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + let persister = fixture.wallet.persister(); + assert!(persister.private_pair_journaled(&alice.id(), &bob.id())); + + // Read back while flushes fail: nothing is noted. + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + publish(&fixture.wallet, 1, vec![]).await; + fixture + .persistence + .flush_fails + .store(true, Ordering::SeqCst); + let view = fixture.wallet.identity().dashpay(); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read back"); + assert!( + !persister.has_read_back_private_entries(), + "not durable yet" + ); + fixture + .coordinator + .discharge_read_back_private_payments() + .await; + assert_eq!(fixture.journaled().await, 1, "kept"); + assert!(persister.private_pair_journaled(&alice.id(), &bob.id())); + // A retry, its flush failing again, pays nothing. + let retry = Arc::new(Mutex::new(Vec::new())); + let held = fixture.send_again(keep_entry(&retry)).await; + assert!( + matches!( + held, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{held:?}" + ); + assert!(retry.lock().expect("retry").is_empty(), "nothing paid"); + + // The next step's flush succeeds: noted, discharged, freed. + fixture + .persistence + .flush_fails + .store(false, Ordering::SeqCst); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the next private sync"); + assert!(persister.has_read_back_private_entries(), "noted"); + fixture + .coordinator + .discharge_read_back_private_payments() + .await; + assert_eq!(fixture.journaled().await, 0, "discharged"); + assert!(!persister.private_pair_journaled(&alice.id(), &bob.id())); + let paid = fixture.send_again(keep_entry(&retry)).await; + assert!( + matches!( + paid, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {paid:?}" + ); + assert_eq!(retry.lock().expect("retry").len(), 1, "the retry pays"); + } + + /// A read-back whose records' flush fails for good, the backend dropping + /// what it buffered, drops its notice: the journal record stays, the pair + /// held, and a later flush that succeeds notes nothing; a restoration in + /// the same process leaves the record too, the request it finds tracked + /// being in memory only. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_drop_a_read_back_notice_whose_records_the_backend_dropped() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let fixture = ExpiryFixture::new().await; + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + let persister = fixture.wallet.persister(); + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + fixture + .persistence + .flush_fails_fatally + .store(true, Ordering::SeqCst); + let view = fixture.wallet.identity().dashpay(); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read back"); + fixture + .persistence + .flush_fails_fatally + .store(false, Ordering::SeqCst); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the next private sync"); + assert!(!persister.has_read_back_private_entries(), "dropped"); + fixture + .coordinator + .discharge_read_back_private_payments() + .await; + assert_eq!(fixture.journaled().await, 1, "the record stays"); + assert!(persister.private_pair_journaled(&alice.id(), &bob.id())); + // Nor does a restoration in this process discharge it, though the + // request is tracked: in memory only, as its flush was lost. + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + assert_eq!(fixture.journaled().await, 1, "kept for the next process"); + } + + /// After a flush failed for good, a rewind that reads the entry again in + /// the same process finds the request already tracked and notes no + /// read-back, so the journal record stays. The next process, whose disk + /// kept a read position past the entry and no record of the request (a + /// later flush stored the one, the lost flush held the other), restores + /// the pair, rewinds the sender's read to where the record says it was + /// when it paid, reads the entry again, records the request durably and + /// discharges the record. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_hold_a_record_whose_request_a_lost_flush_dropped_until_a_restart_reads_it_again( + ) { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let fixture = ExpiryFixture::new().await; + let wallet_id = fixture.wallet.wallet_id(); + // What the disk keeps of Alice: no request to Bob, read past it. + let mut disk = scan_state_snapshot(&fixture.wallet, &alice.id(), false).await; + if let Some(managed) = disk.identities.get_mut(&0) { + let record = managed.private_contact_requests_position_record(); + managed.apply_private_contact_requests_position(PrivateContactRequestsPosition { + position: 1, + ..record + }); + } + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + let view = fixture.wallet.identity().dashpay(); + fixture + .persistence + .flush_fails_fatally + .store(true, Ordering::SeqCst); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read back"); + fixture + .persistence + .flush_fails_fatally + .store(false, Ordering::SeqCst); + // A rewind reads the entry again, its request already tracked. + { + let iw = fixture.wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let managed = wm + .get_wallet_info_mut(&wallet_id) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("Alice"); + let carol = Identifier::from([0xCC; 32]); + let _ = managed.ignore_sender(&carol); + let _ = managed.unignore_sender(&carol); + assert_eq!(managed.dashpay().private_contact_requests_position(), 0); + } + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read again"); + fixture + .coordinator + .discharge_read_back_private_payments() + .await; + assert_eq!(fixture.journaled().await, 1, "the record stays"); + + // The next process. + let manager = PlatformWalletManager::new( + Arc::new( + dashpay_sdk( + &[&alice, &bob], + vec![entry.to_vec()], + PlatformVersion::latest(), + None, + ) + .await, + ), + Arc::new(disk), + Arc::new(NoopEventHandler), + ); + manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + manager + .configure_shielded(&fixture.db_path) + .await + .expect("the shielded store is configured"); + let restarted = manager + .get_wallet(&wallet_id) + .await + .expect("the relaunched wallet"); + managed(&restarted, ALICE, |managed| { + assert_eq!( + managed.dashpay().private_contact_requests_position(), + 0, + "rewound to where Alice paid from" + ); + }) + .await; + let restarted_view = restarted.identity().dashpay(); + assert!(restarted_view + .private_pair_held(&alice.id(), &bob.id()) + .await + .expect("the hold")); + restarted_view + .sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read again"); + managed(&restarted, ALICE, |managed| { + assert!(managed.dashpay().outgoing_request(&bob.id()).is_some()); + }) + .await; + let coordinator = manager.shielded_coordinator().await.expect("configured"); + restarted + .restore_private_contact_payments(&coordinator) + .await + .expect("restored again"); + assert!( + coordinator + .store() + .read() + .await + .private_payment_journal(wallet_id) + .expect("the journal") + .is_empty(), + "discharged" + ); + assert!(!restarted_view + .private_pair_held(&alice.id(), &bob.id()) + .await + .expect("the hold")); + } + + /// An entry that only starts with a journal record's commitment, as anyone + /// who saw the commitment can append, does not show the record's payment + /// executed: the record expires once its anchor is proven pruned. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_not_take_an_entry_starting_with_a_commitment_as_its_payment() { + let fixture = ExpiryFixture::new().await; + let height = ExpiryFixture::ANCHOR_SET_HEIGHT; + fixture.prove_at(height); + let entry = fixture.pay_unconfirmed(ExpiryFixture::ANCHOR, height).await; + let mut forged = entry.to_vec()[..32].to_vec(); + forged.extend_from_slice(&[0xEE; 64]); + publish(&fixture.wallet, 0, vec![forged]).await; + let journal = fixture.journal_snapshot().await; + assert!( + journal[0].1.entry_hash.is_some(), + "a new record keeps the hash" + ); + fixture + .discharge(&journal, &HashSet::new(), Some(height)) + .await; + fixture.assert_discharged("forged entry").await; + } + + /// The expiry's read of the store starts at the sender's read position the + /// record kept: a store whose earlier pages no longer answer is read from + /// there, and the record discharged. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_read_the_store_for_an_expiry_from_the_position_the_record_kept() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let fixture = ExpiryFixture::new().await; + let height = ExpiryFixture::ANCHOR_SET_HEIGHT; + fixture.prove_at(height); + let wallet_id = fixture.wallet.wallet_id(); + let record = PrivatePaymentRecord { + account_index: 0, + activity_id: [0x71; 32], + anchor: ExpiryFixture::ANCHOR, + anchor_height: Some(height), + commitment: [0x72; 32], + payment: PrivateContactPayment { + sender: alice.id().to_buffer(), + recipient: bob.id().to_buffer(), + account_reference: 1, + }, + nullifiers: vec![fixture.input.nullifier], + entry_hash: Some([0x73; 32]), + store_position: Some(2), + }; + fixture + .coordinator + .store() + .write() + .await + .journal_private_payments(wallet_id, std::slice::from_ref(&record)) + .expect("journaled"); + let contract = dashpay_contract().expect("bundled DashPay"); + { + let mut sdk = (*fixture.wallet.identity().sdk).clone(); + sdk.mock() + .remove_fetch_expectation::( + PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + 0, + ), + ) + .await; + } + publish(&fixture.wallet, 2, vec![]).await; + let journal = fixture.journal_snapshot().await; + fixture + .discharge(&journal, &HashSet::new(), Some(height)) + .await; + assert_eq!( + fixture.journaled().await, + 0, + "read from position 2, discharged" + ); + } + + /// A private request read back while its journal record waits for the + /// shielded sync to discharge it still counts as unresolved, in the + /// readiness and the pair's hold alike, as a send holds the pair until + /// the discharge; both clear with it. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_report_a_journaled_payment_unresolved_until_its_record_is_discharged() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let fixture = ExpiryFixture::new().await; + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + let view = fixture.wallet.identity().dashpay(); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read back"); + let readiness = view + .private_contact_readiness(&alice.id()) + .await + .expect("the readiness"); + assert!( + readiness.unresolved_private_payment, + "its record is not discharged yet" + ); + assert!(view + .private_pair_held(&alice.id(), &bob.id()) + .await + .expect("the hold")); + fixture + .coordinator + .discharge_read_back_private_payments() + .await; + let readiness = view + .private_contact_readiness(&alice.id()) + .await + .expect("the readiness"); + assert!(!readiness.unresolved_private_payment, "discharged"); + assert!(!view + .private_pair_held(&alice.id(), &bob.id()) + .await + .expect("the hold")); + } + + /// A restoration discharges a record its sender's tracked request settles + /// only once what records that request is durable. A newer request to the + /// pair, stored but not flushed as a flush fails transiently, leaves the + /// record; once a flush succeeds the next restoration discharges it. A + /// read-back whose flush failed transiently is left to its own path, and a + /// flush that then fails for good leaves the record journaled after a + /// restart. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_discharge_a_settled_record_only_once_its_request_is_durable() { + use platform_encryption::ACCOUNT_REFERENCE_VERSION_SHIFT; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + + // A newer request to the pair, buffered. + let fixture = ExpiryFixture::new().await; + fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + let journal = fixture.journal_snapshot().await; + let reference = journal[0].1.payment.account_reference; + assert_eq!(platform_encryption::account_reference_version(reference), 0); + fixture + .persistence + .flush_fails + .store(true, Ordering::SeqCst); + { + let iw = fixture.wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&fixture.wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("Alice") + .add_sent_contact_request( + public_request( + &alice, + &bob, + reference + (1 << ACCOUNT_REFERENCE_VERSION_SHIFT), + ), + &iw.persister, + ) + .expect("stored, not flushed"); + } + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + assert_eq!( + fixture.journaled().await, + 1, + "kept while the request is buffered" + ); + fixture + .persistence + .flush_fails + .store(false, Ordering::SeqCst); + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + assert_eq!(fixture.journaled().await, 0, "discharged once flushed"); + + // A read-back awaiting its flush, which then succeeds. + let fixture = ExpiryFixture::new().await; + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + fixture + .persistence + .flush_fails + .store(true, Ordering::SeqCst); + fixture + .wallet + .identity() + .dashpay() + .sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read back"); + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + assert_eq!( + fixture.journaled().await, + 1, + "its read-back waits for a flush" + ); + fixture + .persistence + .flush_fails + .store(false, Ordering::SeqCst); + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + assert_eq!( + fixture.journaled().await, + 0, + "discharged once its read-back is flushed" + ); + + // A read-back awaiting its flush, which then fails for good. + let fixture = ExpiryFixture::new().await; + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + fixture + .persistence + .flush_fails + .store(true, Ordering::SeqCst); + fixture + .wallet + .identity() + .dashpay() + .sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read back"); + assert!(fixture + .wallet + .persister() + .read_back_awaiting_flush(&journal_commitment(&fixture).await)); + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + assert_eq!( + fixture.journaled().await, + 1, + "its read-back waits for a flush" + ); + fixture + .persistence + .flush_fails + .store(false, Ordering::SeqCst); + fixture + .persistence + .flush_fails_fatally + .store(true, Ordering::SeqCst); + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + assert_eq!(fixture.journaled().await, 1, "the buffer was lost"); + let wallet_id = fixture.wallet.wallet_id(); + assert_eq!( + FileBackedShieldedStore::open_path(&fixture.db_path, 100) + .expect("reopened") + .private_payment_journal(wallet_id) + .expect("the journal") + .len(), + 1, + "still journaled after a restart" + ); + } + + /// The commitment of `fixture`'s one journal record. + #[cfg(feature = "shielded")] + async fn journal_commitment(fixture: &ExpiryFixture) -> [u8; 32] { + fixture.journal_snapshot().await[0].1.commitment + } + + /// A restoration that finds a journal record its sender's tracked request + /// already records, as a private sync read it back in a process that ended + /// before the shielded sync discharged it, discharges the record. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_discharge_a_journal_record_a_restoration_finds_settled() { + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let fixture = ExpiryFixture::new().await; + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + fixture + .wallet + .identity() + .dashpay() + .sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read back"); + // The process ends before the shielded sync discharges it. + let _ = fixture.wallet.persister().take_read_back_private_entries(); + assert_eq!(fixture.journaled().await, 1); + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + assert_eq!( + fixture.journaled().await, + 0, + "discharged by the restoration" + ); + } + + /// A public pair's claim checks again, in its lock, that the read the send + /// made before it still reaches the store's end: one rewound since, as + /// keys that changed or a sender unignored leave it, refuses it as not + /// read; one that still stands claims it. + #[tokio::test] + async fn should_refuse_claiming_a_public_pair_once_the_read_before_it_is_rewound() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (_manager, wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = wallet.identity().dashpay(); + let refused = view + .claim_public_pair(&alice.id(), &bob.id(), false, true) + .await; + assert!( + matches!( + refused, + Err(PlatformWalletError::PrivateContactStoreNotRead(sender)) + if sender == alice.id() + ), + "{:?}", + refused.err() + ); + { + let iw = wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("managed identity") + .note_private_contact_requests_read_for_tests(); + } + let claimed = view + .claim_public_pair(&alice.id(), &bob.id(), false, true) + .await; + assert!(matches!(claimed, Ok(Some(_))), "{:?}", claimed.err()); + } + + /// The store's end as the pass's highest proved total: with chunks of two, + /// the first page proves five entries at H, and the full second page, from + /// a node a block behind, proves only four and its own end. The public + /// request reads on to position 4, where Alice's private request is, and is + /// refused. + #[tokio::test] + async fn should_read_past_a_full_page_from_a_node_behind_before_a_public_request() { + const H: u64 = 20; + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + serve_pages( + &bob_wallet, + H, + vec![ + (0, vec![vec![0xA0; 589], vec![0xA1; 589]], 5, H), + (2, vec![vec![0xA2; 589], vec![0xA3; 589]], 4, H - 1), + (4, vec![entry], 5, H), + ], + ) + .await; + let public = bob_wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(sender)) + if sender == alice.id() + ), + "{public:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert!(managed.dashpay().incoming_request(&alice.id()).is_some()); + }) + .await; + } + + /// After a key rewind with floor H, with chunks of two: a first page at + /// H - 1 proving six entries, a middle page at H proving seven and a third + /// page at H - 1 proving six. The read goes on past the third page to the + /// seven the middle page proved, and position 6 holds Alice's private + /// request to Bob's new key: the public request is refused. A pass ending + /// at the third page would not count either, its height below the floor + /// though the middle page reached it. + #[tokio::test] + async fn should_not_end_a_rewound_read_at_an_older_walk_target_before_a_public_request() { + const H: u64 = 20; + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &stale, &[&alice, &bob], vec![]).await; + let filler = |byte: u8| vec![vec![byte; 589], vec![byte + 1; 589]]; + serve_pages( + &bob_wallet, + H, + vec![ + (0, filler(0xA0), 7, H), + (2, filler(0xA2), 7, H), + (4, filler(0xA4), 7, H), + (6, vec![entry.clone()], 7, H), + (7, vec![], 7, H), + ], + ) + .await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 16) + .await + .expect("Bob reads the store at H with his older keys"); + assert!(store_read(&bob_wallet, BOB).await); + + // The key reaches Bob's identity at the send, which rewinds his read. + set_identity_known(&bob_wallet, &bob, true).await; + serve_pages( + &bob_wallet, + H, + vec![ + (0, filler(0xA0), 6, H - 1), + (2, filler(0xA2), 7, H), + (4, filler(0xA4), 6, H - 1), + (6, vec![entry], 7, H), + ], + ) + .await; + let public = view + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(sender)) + if sender == alice.id() + ), + "{public:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert!(managed.dashpay().incoming_request(&alice.id()).is_some()); + }) + .await; + } + + /// The largest store size a page proved survives the pass it was read in: + /// with chunks of two, a first pass bounded to one page proves five + /// entries at H; a second pass, its page from a node at H - 1 proving + /// four, stops at four and leaves the store not read to its end; a third + /// reads position 4, Alice's private request, and the store is read. + #[tokio::test] + async fn should_carry_the_largest_proved_store_size_across_bounded_passes() { + const H: u64 = 20; + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + serve_pages( + &bob_wallet, + H, + vec![ + (0, vec![vec![0xA0; 589], vec![0xA1; 589]], 5, H), + (2, vec![vec![0xA2; 589], vec![0xA3; 589]], 4, H - 1), + (4, vec![entry], 5, H), + ], + ) + .await; + let view = bob_wallet.identity().dashpay(); + let first = view + .sync_private_contact_requests(&bob_crypto, 1) + .await + .expect("the first pass"); + assert_eq!(first.next_position, 2, "its page budget"); + let second = view + .sync_private_contact_requests(&bob_crypto, 16) + .await + .expect("the second pass"); + assert_eq!(second.next_position, 4); + assert!(!second.complete, "short of the five the first pass proved"); + assert!(!store_read(&bob_wallet, BOB).await); + view.sync_private_contact_requests(&bob_crypto, 16) + .await + .expect("the third pass"); + assert!(store_read(&bob_wallet, BOB).await); + managed(&bob_wallet, BOB, |managed| { + assert!(managed.dashpay().incoming_request(&alice.id()).is_some()); + }) + .await; + } + + /// A store size an earlier call proved bounds the read a public request + /// makes: after a sync bounded to one page proved five entries at H, Bob's + /// public request to Alice, whose pages from 2 come from a node at H - 1 + /// proving four, reads on to position 4, Alice's private request, and is + /// refused. + #[tokio::test] + async fn should_not_end_a_public_request_s_read_below_a_size_an_earlier_call_proved() { + const H: u64 = 20; + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + serve_pages( + &bob_wallet, + H, + vec![ + (0, vec![vec![0xA0; 589], vec![0xA1; 589]], 5, H), + (2, vec![vec![0xA2; 589], vec![0xA3; 589]], 4, H - 1), + (4, vec![entry], 5, H), + ], + ) + .await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 1) + .await + .expect("a sync bounded to one page"); + let public = view + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(sender)) + if sender == alice.id() + ), + "{public:?}" + ); + } + + /// `wallet`'s mock answers each page `(start, entries, total, height)` with + /// those entries, in chunks of two, showing `total` and proved at + /// `height`; every other response is proved at `base`. + async fn serve_pages( + wallet: &PlatformWallet, + base: u64, + pages: Vec<(u64, Vec>, u64, u64)>, + ) { + let contract = dashpay_contract().expect("bundled DashPay"); + let mut sdk = (*wallet.identity().sdk).clone(); + let mut mock = sdk.mock(); + mock.set_response_height(base); + for (start, entries, total, height) in pages { + let query = PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + start, + ); + let mut page = store_page(start, entries); + page.chunk_power = Some(1); + page.total_count = total; + mock.remove_fetch_expectation::(query.clone()) + .await; + mock.expect_fetch(query.clone(), Some(page)) + .await + .expect("page expectation"); + mock.set_response_height_for::(query, height); + } + } + + /// An identity reloaded from a position record stored with its marker + /// cleared, as a discharge leaves it, is not held, in any build (in one + /// with the `shielded` feature once the store is configured, which an + /// empty journal releases): its public request goes on to be built. + #[tokio::test] + async fn should_not_hold_an_identity_reloaded_with_its_marker_cleared() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_before_manager, before) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(scan_state_snapshot(&before, &alice.id(), false).await); + let manager = PlatformWalletManager::new( + Arc::new(dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await), + Arc::clone(&kept), + Arc::new(NoopEventHandler), + ); + manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + // A host keeping the private scan state configures the shielded store + // at activation: until then, a loaded wallet is held. + #[cfg(feature = "shielded")] + assert!( + manager + .get_wallet(&before.wallet_id()) + .await + .expect("the relaunched wallet") + .private_payments_held() + .await, + "held until the store is configured" + ); + #[cfg(feature = "shielded")] + let _store = { + let dir = tempfile::tempdir().expect("temporary shielded store"); + manager + .configure_shielded(dir.path().join("tree.sqlite")) + .await + .expect("the shielded store is configured"); + dir + }; + let restarted = manager + .get_wallet(&before.wallet_id()) + .await + .expect("the relaunched wallet"); + assert!(!restarted.private_payments_held().await); + assert!( + restarted + .identity() + .dashpay() + .private_contact_readiness(&alice.id()) + .await + .expect("the readiness") + .private_payments_restored + ); + // Past the hold, the store read and the claim, the request is built + // (the mock answers no nonce, which ends it there). + let public = restarted + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + !matches!( + public, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored + | PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{public:?}" + ); + } + + /// A private payment is marked unresolved in its identity's position + /// record before it is paid, for a backend keeping the scan state, and + /// unmarked once its entry is read back; one released before anything was + /// paid is unmarked too. + #[tokio::test] + async fn should_mark_a_private_payment_unresolved_until_it_resolves() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let attesting = || { + RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ) + }; + let marker = |persistence: &RecordingPersistence| { + last_marker(&persistence.stored.lock().expect("stored"), &alice.id()) + }; + + let persistence = attesting(); + let (_manager, alice_wallet) = wallet_on( + Arc::clone(&persistence), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + let marked_when_paid = Arc::new(AtomicBool::new(false)); + let kept = Arc::new(Mutex::new(Vec::new())); + let pay = { + let paying = append_entry(&alice_wallet, 0, vec![], &kept); + let (persistence, marked, alice_id) = ( + Arc::clone(&persistence), + Arc::clone(&marked_when_paid), + alice.id(), + ); + move |entry: BinaryData, started: PaymentStarted| { + let unresolved = + last_marker(&persistence.stored.lock().expect("stored"), &alice_id); + marked.store(unresolved == Some(true), Ordering::SeqCst); + paying(entry, started) + } + }; + alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + pay, + ) + .await + .expect("paid and read back"); + assert!( + marked_when_paid.load(Ordering::SeqCst), + "marked before paying" + ); + assert_eq!(marker(&persistence), Some(false), "unmarked once read back"); + + let persistence = attesting(); + let (_manager, alice_wallet) = wallet_on( + Arc::clone(&persistence), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + let marked_when_paid = Arc::new(AtomicBool::new(false)); + let failing = { + let (persistence, marked, alice_id) = ( + Arc::clone(&persistence), + Arc::clone(&marked_when_paid), + alice.id(), + ); + move |_: BinaryData, _: PaymentStarted| { + let unresolved = + last_marker(&persistence.stored.lock().expect("stored"), &alice_id); + marked.store(unresolved == Some(true), Ordering::SeqCst); + std::future::ready(Err::( + PlatformWalletError::InvalidParameter("no notes to pay with".to_string()), + )) + } + }; + let refused = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + failing, + ) + .await; + assert!(refused.is_err(), "{refused:?}"); + assert!( + marked_when_paid.load(Ordering::SeqCst), + "marked before paying" + ); + assert_eq!(marker(&persistence), Some(false), "unmarked once released"); + } + + /// A backend that buffers what is stored until a flush makes it durable, + /// declaring the private contact request scan state. Its flushes fail + /// once `flush_fails` is set. + #[derive(Default)] + struct BufferedPersistence { + buffered: Mutex>, + durable: Mutex>, + flush_fails: AtomicBool, + } + + impl PlatformWalletPersistence for BufferedPersistence { + fn persistence_capabilities(&self) -> PersistenceCapabilities { + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART + } + + fn store( + &self, + _wallet_id: WalletId, + changeset: PlatformWalletChangeSet, + ) -> Result<(), PersistenceError> { + self.buffered.lock().expect("buffered").push(changeset); + Ok(()) + } + + fn flush(&self, _wallet_id: WalletId) -> Result<(), PersistenceError> { + if self.flush_fails.load(Ordering::SeqCst) { + return Err(PersistenceError::backend("the disk is full")); + } + let mut buffered = self.buffered.lock().expect("buffered"); + self.durable + .lock() + .expect("durable") + .extend(buffered.drain(..)); + Ok(()) + } + + fn load(&self) -> Result { + Ok(ClientStartState::default()) + } + } + + /// A backend that hands back an identity's position record marking an + /// unresolved private payment without attesting the scan state any more, + /// as one whose host stopped declaring it, has its scan state read again + /// from the start, and keeps the hold: the payment may still execute. + #[tokio::test] + async fn should_keep_a_restored_hold_for_a_backend_that_no_longer_attests_the_scan_state() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (_before_manager, before) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let mut kept = scan_state_snapshot(&before, &alice.id(), true).await; + kept.capabilities = PersistenceCapabilities::NONE; + let manager = PlatformWalletManager::new( + Arc::new(dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await), + Arc::new(kept), + Arc::new(NoopEventHandler), + ); + manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + let restarted = manager + .get_wallet(&before.wallet_id()) + .await + .expect("the relaunched wallet"); + assert!(restarted.private_payments_held().await, "held"); + managed(&restarted, ALICE, |managed| { + assert_eq!( + managed.dashpay().private_contact_requests_position(), + 0, + "read again from the start" + ); + }) + .await; + } + + /// A private payment is refused before anything is sealed or paid over a + /// backend that does not keep the private contact request scan state, as + /// its recovery marker could not survive a restart; nothing stays + /// reserved. + #[tokio::test] + async fn should_refuse_a_private_payment_over_a_backend_that_keeps_no_marker() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet_on( + RecordingPersistence::attesting(PersistenceCapabilities::NONE), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + let refused = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + no_payment, + ) + .await; + assert!( + matches!( + refused, + Err(PlatformWalletError::PrivateContactRecoveryUnsupported) + ), + "{refused:?}" + ); + assert!(!pending_to(&alice_wallet, ALICE, &bob).await); + } + + /// Over a backend that buffers its stores, a private payment's marker is + /// flushed before it is paid: a flush that fails refuses the payment, with + /// nothing paid, and one that succeeds leaves the marker durable before + /// `pay` runs, so a process reopening the wallet, in a build without the + /// `shielded` feature too, holds the identity. + #[tokio::test] + async fn should_make_a_private_payment_s_marker_durable_before_paying() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + + let failing = Arc::new(BufferedPersistence::default()); + let (_manager, alice_wallet) = wallet_on( + Arc::clone(&failing), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + failing.flush_fails.store(true, Ordering::SeqCst); + let refused = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + no_payment, + ) + .await; + assert!( + matches!(&refused, Err(PlatformWalletError::Persistence(message)) + if message.contains("not stored durably")), + "{refused:?}" + ); + assert!(!pending_to(&alice_wallet, ALICE, &bob).await); + + let buffered = Arc::new(BufferedPersistence::default()); + let (_manager, alice_wallet) = wallet_on( + Arc::clone(&buffered), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + let durable_when_paid = Arc::new(AtomicBool::new(false)); + let unconfirmed = { + let (buffered, durable, alice_id) = ( + Arc::clone(&buffered), + Arc::clone(&durable_when_paid), + alice.id(), + ); + move |_: BinaryData, started: PaymentStarted| { + let marker = last_marker(&buffered.durable.lock().expect("durable"), &alice_id); + durable.store(marker == Some(true), Ordering::SeqCst); + started.mark(); + std::future::ready(Err::( + PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create", + reason: "the process ends here".to_string(), + }, + )) + } + }; + let sent = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + unconfirmed, + ) + .await; + assert!( + matches!( + sent, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{sent:?}" + ); + assert!( + durable_when_paid.load(Ordering::SeqCst), + "durable before paying" + ); + + // The process ends with only what was flushed: reopened from it. + let unresolved = + last_marker(&buffered.durable.lock().expect("durable"), &alice.id()) == Some(true); + let kept = Arc::new(scan_state_snapshot(&alice_wallet, &alice.id(), unresolved).await); + let manager = PlatformWalletManager::new( + Arc::new(dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await), + kept, + Arc::new(NoopEventHandler), + ); + manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + let reopened = manager + .get_wallet(&alice_wallet.wallet_id()) + .await + .expect("the relaunched wallet"); + assert!(reopened.private_payments_held().await, "held"); + let public = reopened + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{public:?}" + ); + } + + /// A private payment whose broadcast may have been delivered, an + /// `Unavailable` answer after the node may have admitted it, keeps its + /// pair held and its marker set, though its notes are released: its entry + /// may still be appended. A public send to that recipient is refused. + #[tokio::test] + async fn should_keep_the_pair_held_when_a_payment_may_have_been_delivered() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let persistence = RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ); + let (_manager, alice_wallet) = wallet_on( + Arc::clone(&persistence), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + let view = alice_wallet.identity().dashpay(); + let delivered = |_: BinaryData, started: PaymentStarted| { + started.mark(); + std::future::ready(Err::( + PlatformWalletError::ShieldedBroadcastMaybeDelivered( + "status: Unavailable".to_string(), + ), + )) + }; + let sent = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + delivered, + ) + .await; + assert!( + matches!( + sent, + Err(PlatformWalletError::ShieldedBroadcastMaybeDelivered(_)) + ), + "{sent:?}" + ); + assert!(pending_to(&alice_wallet, ALICE, &bob).await, "held"); + assert_eq!( + last_marker(&persistence.stored.lock().expect("stored"), &alice.id()), + Some(true), + "marked" + ); + let public = view + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob.id() + ), + "{public:?}" + ); + } + + /// `identity` with each of its `ECDSA_SECP256K1` keys holding its point + /// uncompressed, a 65-byte encoding DPP accepts and the sealer reads. + fn with_uncompressed_keys(identity: &Identity) -> Identity { + Identity::V0(IdentityV0 { + id: identity.id(), + public_keys: identity + .public_keys() + .iter() + .map(|(id, key)| { + let mut key = key.clone(); + if key.key_type() == KeyType::ECDSA_SECP256K1 { + let point = + PublicKey::from_slice(key.data().as_slice()).expect("a valid point"); + key.set_data(BinaryData::new(point.serialize_uncompressed().to_vec())); + } + (*id, key) + }) + .collect(), + balance: identity.balance(), + revision: identity.revision(), + }) + } + + /// A request sealed to a recipient key holding its point uncompressed is + /// recovered from the store by its sender restored from seed, as one sealed + /// to a compressed key is: the key is matched as a curve point. A public + /// send to that recipient is then refused, the requests having gone + /// privately. + #[tokio::test] + async fn should_recover_a_request_sealed_to_an_uncompressed_recipient_key() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = with_uncompressed_keys(&identity(BOB_PHRASE, BOB)); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + let sent = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&kept), + ) + .await; + assert!( + matches!( + sent, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {sent:?}" + ); + let entry = kept.lock().expect("kept").remove(0); + + let (_restored_manager, restored) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![entry.to_vec()]).await; + let view = restored.identity().dashpay(); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the store is read"); + managed(&restored, ALICE, |managed| { + assert!( + managed.dashpay().outgoing_request(&bob.id()).is_some(), + "recovered" + ); + }) + .await; + let public = view + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(recipient)) + if recipient == bob.id() + ), + "{public:?}" + ); + } + + /// A saved private payment whose redrive record does not read back, its + /// association with the request it pays for or its signed transition, or + /// was lost, still holds its pair after a relaunch: the shielded store's + /// private payment journal restores it. Through a coordinator sync pass, a second + /// restoration and another relaunch, a private and a public request to + /// that recipient are refused, while one to anyone else is not held. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_hold_a_pair_from_its_journal_when_its_saved_payment_does_not_read() { + for damage in [ + "UPDATE shielded_pending_spends SET private_contact_payment = x'01'", + "UPDATE shielded_pending_spends SET st_bytes = x'0102'", + // The redrive record lost after the broadcast. + "DELETE FROM shielded_pending_spends", + ] { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let incoming = public_request(&alice, &bob, 3); + let dir = tempfile::tempdir().expect("temporary shielded store"); + let db_path = dir.path().join("tree.sqlite"); + + let store = FileBackedShieldedStore::open_path(&db_path, 100).expect("open the store"); + let before_coordinator = Arc::new(NetworkShieldedCoordinator::new( + Arc::new(dash_sdk::Sdk::new_mock()), + Network::Testnet, + db_path.clone(), + store, + )); + let (_before_manager, before) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + add_incoming(&before, BOB, &incoming).await; + // A backend keeping the viewing key and the private scan state, so a + // private send reaches the pair's hold. + let mut kept = snapshot(&before, &bob.id(), BOB_PHRASE).await; + kept.capabilities = kept + .capabilities + .union(PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART); + let kept = Arc::new(kept); + let subwallet = SubwalletId::new(before.wallet_id(), 0); + let pay = { + let store = Arc::clone(before_coordinator.store()); + let (sender, recipient) = (bob.id(), alice.id()); + move |entry: BinaryData, started: PaymentStarted| async move { + let transition = private_contact_request_payment(entry); + let payment = PrivateContactPayment { + sender: sender.to_buffer(), + recipient: recipient.to_buffer(), + account_reference: started + .account_reference() + .expect("the send names its request"), + }; + arm_redrive_before_broadcast( + &store, + subwallet, + Some([0x77; 32]), + [7; 32], + vec![[1; 32]], + &transition, + "private document create from shielded pool", + Some(payment), + Some(&started), + 0, + ) + .await?; + Err::(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create", + reason: "the result wait timed out".to_string(), + }) + } + }; + let paid = before + .identity() + .dashpay() + .accept_private_contact_request(&incoming, None, &bob_signer, &bob_crypto, pay) + .await; + assert!( + matches!( + paid, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{paid:?}" + ); + drop(before_coordinator); + rusqlite::Connection::open(&db_path) + .expect("the store's file") + .execute(damage, []) + .expect("the saved payment is damaged"); + + for relaunch in 0..2 { + let restarted_manager = PlatformWalletManager::new( + Arc::new( + dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await, + ), + Arc::clone(&kept), + Arc::new(NoopEventHandler), + ); + restarted_manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + restarted_manager + .configure_shielded(&db_path) + .await + .expect("the shielded store opens"); + let restarted = restarted_manager + .get_wallet(&before.wallet_id()) + .await + .expect("the relaunched wallet"); + let coordinator = restarted_manager + .shielded_coordinator() + .await + .expect("the coordinator"); + for pass in 0..2 { + if pass == 1 { + // A coordinator pass, whose redrive keeps an undecodable + // record, then a second restoration. + coordinator.sync(true, &CancellationToken::new()).await; + restarted + .restore_private_contact_payments(&coordinator) + .await + .expect("restored again from the journal"); + } + let context = format!("{damage}, relaunch {relaunch}, pass {pass}"); + assert!(!restarted.private_payments_held().await, "{context}"); + let view = restarted.identity().dashpay(); + let public = view + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{context}: {public:?}" + ); + let private = view + .send_private_contact_request( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + None, + &bob_signer, + &bob_crypto, + no_payment, + ) + .await; + assert!( + matches!( + private, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{context}: {private:?}" + ); + let elsewhere = view + .send_contact_request_with_external_signer( + &bob.id(), + &Identifier::from([0xCC; 32]), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + !matches!( + elsewhere, + Err(PlatformWalletError::PrivateContactRequestPending(_) + | PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{context}: {elsewhere:?}" + ); + } + } + } + } + + /// The page of DashPay's private store from `start`, holding `entries`. + fn store_page(start: u64, entries: Vec>) -> PrivateDocumentEntries { + let total_count = start + entries.len() as u64; + PrivateDocumentEntries { + chunk_power: None, + entries: entries + .into_iter() + .zip(start..) + .map(|(data, position)| PrivateDocumentEntry { + position, + block_height: 0, + block_time_ms: BLOCK_TIME_MS, + data, + }) + .collect(), + total_count, + } + } + + /// From now on, `wallet`'s mock SDK answers the page from `start`, and + /// from every position after it to the store's end, with `entries` from + /// there: the store as it is once they are appended, read from any cursor + /// in it, its end included (every contact request reads the store from + /// its cursor first). + async fn publish(wallet: &PlatformWallet, start: u64, entries: Vec>) { + let mut sdk = (*wallet.identity().sdk).clone(); + expect_store_from(&mut sdk, start, entries).await; + } + + /// `sdk`'s mock answers the page from `start`, and from every position + /// after it to the store's end, with `entries` from there + /// ([`publish`]). + async fn expect_store_from(sdk: &mut dash_sdk::Sdk, start: u64, entries: Vec>) { + let contract = dashpay_contract().expect("bundled DashPay"); + let mut mock = sdk.mock(); + for offset in 0..=entries.len() { + let from = start + offset as u64; + let query = PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + from, + ); + mock.remove_fetch_expectation::(query.clone()) + .await; + mock.expect_fetch(query, Some(store_page(from, entries[offset..].to_vec()))) + .await + .expect("page expectation"); + } + } + + /// A `pay` that appends the entry to the store `wallet` reads, after + /// `before` from `start`, and keeps it. + fn append_entry( + wallet: &Arc, + start: u64, + before: Vec>, + kept: &Arc>>, + ) -> impl FnOnce( + BinaryData, + PaymentStarted, + ) -> std::pin::Pin< + Box> + Send>, + > + Send { + let wallet = Arc::clone(wallet); + let kept = Arc::clone(kept); + move |entry, started| { + started.mark(); + Box::pin(async move { + let mut entries = before; + entries.push(entry.to_vec()); + publish(&wallet, start, entries).await; + kept.lock().expect("kept entries").push(entry); + Ok(ResponseMetadata { + time_ms: BLOCK_TIME_MS, + ..Default::default() + }) + }) + } + } + + /// A `pay` that keeps the entry instead of paying for it, and answers as + /// the proof of a block at `BLOCK_TIME_MS` would: the entry never reaches + /// the store. + fn keep_entry( + kept: &Arc>>, + ) -> impl FnOnce( + BinaryData, + PaymentStarted, + ) -> std::future::Ready> + + Send { + let kept = Arc::clone(kept); + move |entry, started| { + started.mark(); + kept.lock().expect("kept entries").push(entry); + std::future::ready(Ok(ResponseMetadata { + time_ms: BLOCK_TIME_MS, + ..Default::default() + })) + } + } + + async fn managed( + wallet: &PlatformWallet, + identity_id: [u8; 32], + read: impl FnOnce(&crate::wallet::identity::ManagedIdentity) -> R, + ) -> R { + let iw = wallet.identity(); + let wm = iw.wallet_manager.read().await; + let managed = wm + .get_wallet_info(&wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity(&Identifier::from(identity_id)) + .expect("managed identity"); + read(managed) + } + + /// Alice sends Bob a private request; Bob reads it from the store with + /// Alice checked as its sender, refuses to accept it with a public reply, + /// and accepts it with a private one, which establishes the contact. The + /// request Bob records carries Alice's receiving xpub and label as a + /// document would, under the pair's shared key. + #[tokio::test] + async fn should_send_read_and_accept_a_private_contact_request() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let bob_signer = signer(BOB_PHRASE, &bob); + let shielded_address = [0x55; 43]; + + let (_alice_manager, alice_wallet) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + let sent = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + Some("Alice".to_string()), + AutoAcceptProofSource::None, + Some(shielded_address), + &alice_signer, + &alice_crypto, + append_entry(&alice_wallet, 0, vec![], &kept), + ) + .await + .expect("Alice sends the request, read back from the store"); + let entry = kept.lock().expect("kept entries").remove(0); + assert_eq!(entry.len(), 589, "the entry takes DashPay's entry size"); + assert_eq!(sent.sender_key_index, ENCRYPTION_KEY_ID); + assert_eq!(sent.recipient_key_index, DECRYPTION_KEY_ID); + assert_eq!(sent.created_at, BLOCK_TIME_MS); + assert!(sent.came_privately(), "recorded at core height 0"); + managed(&alice_wallet, ALICE, |managed| { + assert_eq!( + managed.dashpay().sent_contact_requests().get(&bob.id()), + Some(&sent) + ); + assert!( + managed + .dashpay() + .private_contact(&bob.id()) + .expect("the request went privately") + .sent_privately + ); + }) + .await; + // Alice's public request to Bob would publish what she sent privately. + assert!(matches!( + alice_wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(recipient)) + if recipient == bob.id() + )); + + let (_bob_manager, bob_wallet) = + wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![entry.to_vec()]).await; + let bob_view = bob_wallet.identity().dashpay(); + let report = bob_view + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store"); + assert_eq!(report.pages_read, 1); + assert!(report.complete); + assert_eq!(report.next_position, 1); + assert_eq!(report.rejected, vec![]); + let received = managed(&bob_wallet, BOB, |managed| { + assert_eq!(managed.dashpay().private_contact_requests_position(), 1); + let private = managed + .dashpay() + .private_contact(&alice.id()) + .expect("noted"); + assert!(private.received_privately); + assert_eq!(private.shielded_address, Some(shielded_address)); + managed + .dashpay() + .incoming_contact_requests() + .get(&alice.id()) + .cloned() + .expect("Bob holds Alice's request") + }) + .await; + assert_eq!(received.sender_key_index, ENCRYPTION_KEY_ID); + assert_eq!(received.recipient_key_index, DECRYPTION_KEY_ID); + assert_eq!(received.account_reference, sent.account_reference); + assert_eq!(received.created_at, BLOCK_TIME_MS); + assert!(received.came_privately(), "recorded at core height 0"); + assert_eq!(received.auto_accept_proof, None); + // The shared key Bob's decryption key and Alice's encryption key agree + // on opens the xpub and label, as it opens a document's. + let bob_key_path = identity_auth_derivation_path_for_type( + Network::Testnet, + KeyDerivationType::ECDSA, + 0, + DECRYPTION_KEY_ID, + ) + .expect("Bob's decryption key path"); + let shared_key = bob_crypto + .ecdh_shared_secret( + &bob_key_path, + &identity_public_key(&alice, ENCRYPTION_KEY_ID).expect("Alice's key"), + ) + .await + .expect("shared key"); + assert_eq!( + decrypt_extended_public_key(&shared_key, &received.encrypted_public_key) + .expect("the xpub opens"), + decrypt_extended_public_key(&shared_key, &sent.encrypted_public_key) + .expect("Alice's record opens with the same key"), + ); + assert_eq!( + received.encrypted_public_key, sent.encrypted_public_key, + "both sides record the same ciphertext" + ); + assert_eq!( + decrypt_account_label( + &shared_key, + received + .encrypted_account_label + .as_deref() + .expect("a label") + ) + .expect("the label opens"), + "Alice" + ); + + // A public reply would publish the relationship. + assert!(matches!( + bob_view + .accept_contact_request_with_external_signer(&received, &bob_signer, &bob_crypto) + .await, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(sender)) + if sender == alice.id() + )); + + // The accept a host calls replies the way the request came. + let reply = Arc::new(Mutex::new(Vec::new())); + let established = bob_view + .accept_contact_request_replying_in_kind( + &received, + None, + &bob_signer, + &bob_crypto, + append_entry(&bob_wallet, 1, vec![], &reply), + ) + .await + .expect("Bob accepts privately"); + assert_eq!(established.contact_identity_id, alice.id()); + assert_eq!(established.incoming_request, received); + assert_eq!( + reply.lock().expect("reply").len(), + 1, + "the reply is a private entry" + ); + managed(&bob_wallet, BOB, |managed| { + let private = managed + .dashpay() + .private_contact(&alice.id()) + .expect("noted"); + assert!(private.received_privately && private.sent_privately); + }) + .await; + // Bob can pay Alice: her sending account is registered from the xpub. + { + let iw = bob_wallet.identity(); + let wm = iw.wallet_manager.read().await; + let info = wm + .get_wallet_info(&bob_wallet.wallet_id()) + .expect("wallet info"); + assert!(info + .core_wallet + .accounts + .dashpay_external_accounts + .contains_key(&DashpayAccountKey { + index: 0, + user_identity_id: BOB, + friend_identity_id: ALICE, + })); + } + + // Un-ignoring a sender reads the store again from its start, where the + // requests skipped while it was ignored are. + { + let iw = bob_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let managed = wm + .get_wallet_info_mut(&bob_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&bob.id()) + .expect("Bob"); + managed.ignore_sender(&alice.id()); + // Past Alice's request and Bob's reply, which the accept read back. + assert_eq!(managed.dashpay().private_contact_requests_position(), 2); + managed.unignore_sender(&alice.id()); + assert_eq!(managed.dashpay().private_contact_requests_position(), 0); + } + } + + /// A public request from `sender` to `recipient` for `account_reference`, + /// as a `contactRequest` document is recorded: with its core height. + fn public_request( + sender: &Identity, + recipient: &Identity, + account_reference: u32, + ) -> ContactRequest { + ContactRequest::new( + sender.id(), + recipient.id(), + ENCRYPTION_KEY_ID, + DECRYPTION_KEY_ID, + account_reference, + vec![7; 96], + 100, + BLOCK_TIME_MS, + ) + } + + /// The accept a host calls replies to a public request publicly, without + /// paying: by adopting the reply already sent, or with a document whose + /// broadcast error comes back as it is. A request the wallet does not + /// hold is refused either way, and nothing is paid. + #[tokio::test] + async fn should_accept_a_public_request_replying_in_kind() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let incoming = public_request(&alice, &bob, 3); + let add = |wallet: Arc, requests: Vec<(bool, ContactRequest)>| async move { + let iw = wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let managed = wm + .get_wallet_info_mut(&wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&Identifier::from(BOB)) + .expect("Bob"); + for (incoming, request) in requests { + if incoming { + managed + .add_incoming_contact_request(request, &iw.persister) + .expect("incoming request"); + } else { + managed + .add_sent_contact_request(request, &iw.persister) + .expect("sent request"); + } + } + }; + + // Already reciprocated: adopted, no broadcast and no payment. + let (_manager, reciprocated) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + add( + Arc::clone(&reciprocated), + vec![ + (true, incoming.clone()), + (false, public_request(&bob, &alice, 4)), + ], + ) + .await; + let paid = Arc::new(Mutex::new(Vec::new())); + let established = reciprocated + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &incoming, + None, + &bob_signer, + &bob_crypto, + keep_entry(&paid), + ) + .await + .expect("the reply already sent is adopted"); + assert_eq!(established.contact_identity_id, alice.id()); + assert!(paid.lock().expect("paid").is_empty(), "nothing is paid"); + + // Not reciprocated: a public reply, whose broadcast this mock refuses. + let (_manager, fresh) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + add(Arc::clone(&fresh), vec![(true, incoming.clone())]).await; + let paid = Arc::new(Mutex::new(Vec::new())); + let result = fresh + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &incoming, + None, + &bob_signer, + &bob_crypto, + keep_entry(&paid), + ) + .await; + assert!( + matches!(&result, Err(error) + if !matches!(error, PlatformWalletError::PrivateContactRequestNeedsPrivateReply(_))), + "the public reply's error comes back: {result:?}" + ); + assert!(paid.lock().expect("paid").is_empty(), "nothing is paid"); + + // A private request from a sender the wallet holds no request from. + let carol = identity(ALICE_PHRASE, [0xC1; 32]); + let mut unknown = public_request(&carol, &bob, 5); + unknown.core_height_created_at = 0; + let paid = Arc::new(Mutex::new(Vec::new())); + assert!(matches!( + fresh + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &unknown, + None, + &bob_signer, + &bob_crypto, + keep_entry(&paid), + ) + .await, + Err(PlatformWalletError::ContactRequestNotFound(sender)) if sender == carol.id() + )); + assert!(paid.lock().expect("paid").is_empty(), "nothing is paid"); + } + + /// A wallet restored from seed recovers the private requests it sent from + /// the store alone, recording each as it recorded it when sending. + #[tokio::test] + async fn should_recover_a_sent_private_contact_request_from_the_store() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + let sent = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + append_entry(&alice_wallet, 0, vec![], &kept), + ) + .await + .expect("Alice sends the request"); + let entry = kept.lock().expect("kept entries").remove(0); + + // The restored wallet checks its own identity's keys as on chain. + let (_restored_manager, restored) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![entry.to_vec()]).await; + let report = restored + .identity() + .dashpay() + .sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the restored wallet reads the store"); + assert_eq!(report.requests, vec![sent.clone()]); + managed(&restored, ALICE, |managed| { + assert_eq!( + managed.dashpay().sent_contact_requests().get(&bob.id()), + Some(&sent) + ); + }) + .await; + } + + /// A sync reports the requests it recorded: an ignored sender's request is + /// opened but not recorded, so not reported; once the sender is no longer + /// ignored, the store is read again and the request is. + #[tokio::test] + async fn should_report_only_the_requests_a_sync_recorded() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + append_entry(&alice_wallet, 0, vec![], &kept), + ) + .await + .expect("Alice sends the request"); + let entry = kept.lock().expect("kept entries").remove(0); + + let (_bob_manager, bob_wallet) = + wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![entry.to_vec()]).await; + let set_ignored = |ignored: bool| { + let bob_wallet = Arc::clone(&bob_wallet); + let alice_id = alice.id(); + let bob_id = bob.id(); + async move { + let iw = bob_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let managed = wm + .get_wallet_info_mut(&bob_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&bob_id) + .expect("Bob"); + if ignored { + managed.ignore_sender(&alice_id); + } else { + managed.unignore_sender(&alice_id); + } + } + }; + + set_ignored(true).await; + let report = bob_wallet + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store"); + assert_eq!(report.requests, vec![], "an ignored sender's request"); + assert_eq!(report.rejected, vec![]); + + set_ignored(false).await; + let report = bob_wallet + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store again"); + assert_eq!(report.requests.len(), 1, "{:?}", report.requests); + assert_eq!(report.requests[0].sender_id, alice.id()); + managed(&bob_wallet, BOB, |managed| { + assert_eq!( + managed.dashpay().incoming_request(&alice.id()), + Some(&report.requests[0]) + ); + }) + .await; + } + + /// One private request to a recipient is in flight at a time: one paid + /// for but not read back, or whose payment is unconfirmed, keeps the next + /// from being sent, until a sync reads it back; one whose payment failed + /// does not. + #[tokio::test] + async fn should_send_one_private_request_to_a_recipient_at_a_time() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = alice_wallet.identity().dashpay(); + macro_rules! send { + ($pay:expr) => { + view.send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + $pay, + ) + .await + }; + } + let pending = |result: &Result| matches!(result, Err(PlatformWalletError::PrivateContactRequestPending(id)) if *id == bob.id()); + + // A payment that definitely failed releases the recipient. + let failed = send!(|_, _| std::future::ready(Err( + PlatformWalletError::InvalidIdentityData("no notes".to_string()) + ))); + assert!(!pending(&failed), "{failed:?}"); + + // Paid for, but the entry is not in the store yet: pending. + let kept = Arc::new(Mutex::new(Vec::new())); + let first = send!(keep_entry(&kept)); + assert!(pending(&first), "{first:?}"); + let entry = kept.lock().expect("kept").remove(0); + + // A second request is refused before anything is paid. + let paid_again = Arc::new(Mutex::new(Vec::new())); + let second = send!(keep_entry(&paid_again)); + assert!(pending(&second), "{second:?}"); + assert!( + paid_again.lock().expect("paid").is_empty(), + "nothing is paid twice" + ); + + // The store reads the entry back: settled and recorded. + publish(&alice_wallet, 0, vec![entry.to_vec()]).await; + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("Alice reads the store"); + managed(&alice_wallet, ALICE, |managed| { + assert!(!managed.dashpay().private_reply_pending(&bob.id())); + assert!(managed.dashpay().outgoing_request(&bob.id()).is_some()); + }) + .await; + } + + /// A payment whose execution is unconfirmed keeps the request pending. + #[tokio::test] + async fn should_keep_an_unconfirmed_private_request_pending() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let result = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + |_, started: PaymentStarted| { + started.mark(); + std::future::ready(Err(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create", + reason: "the proof fetch timed out".to_string(), + })) + }, + ) + .await; + assert!(matches!( + result, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + )); + managed(&alice_wallet, ALICE, |managed| { + assert!(managed.dashpay().private_reply_pending(&bob.id())); + }) + .await; + // A public request now would publish the pair, whose private one may + // already be on chain. + assert!(matches!( + alice_wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await, + Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob.id() + )); + } + + /// A signer whose signatures never come, as a host's prompt the user never + /// answers: it notes that it was asked. + #[derive(Debug)] + struct StalledSigner { + inner: simple_signer::signer::SimpleSigner, + asked: Arc, + } + + #[async_trait::async_trait] + impl Signer for StalledSigner { + async fn sign( + &self, + _key: &IdentityPublicKey, + _data: &[u8], + ) -> Result { + self.asked.store(true, Ordering::SeqCst); + std::future::pending().await + } + + async fn sign_create_witness( + &self, + key: &IdentityPublicKey, + data: &[u8], + ) -> Result { + self.inner.sign_create_witness(key, data).await + } + + fn can_sign_with(&self, key: &IdentityPublicKey) -> bool { + self.inner.can_sign_with(key) + } + } + + /// From now on, `wallet`'s mock SDK answers a fetch of `identity` with it + /// when `known`, and fails it otherwise. + async fn set_identity_known(wallet: &PlatformWallet, identity: &Identity, known: bool) { + let mut sdk = (*wallet.identity().sdk).clone(); + let mut mock = sdk.mock(); + mock.remove_fetch_expectation::(identity.id()) + .await; + if known { + mock.expect_fetch(identity.id(), Some(identity.clone())) + .await + .expect("identity expectation"); + } + } + + /// Whether `wallet`'s identity `identity_id` holds a private request to + /// `recipient` pending. + async fn pending_to( + wallet: &PlatformWallet, + identity_id: [u8; 32], + recipient: &Identity, + ) -> bool { + managed(wallet, identity_id, |managed| { + managed.dashpay().private_reply_pending(&recipient.id()) + }) + .await + } + + /// A signer counting the signatures it makes. + #[derive(Debug)] + struct CountingSigner { + inner: simple_signer::signer::SimpleSigner, + signed: Arc, + } + + #[async_trait::async_trait] + impl Signer for CountingSigner { + async fn sign( + &self, + key: &IdentityPublicKey, + data: &[u8], + ) -> Result { + self.signed.fetch_add(1, Ordering::SeqCst); + self.inner.sign(key, data).await + } + async fn sign_create_witness( + &self, + key: &IdentityPublicKey, + data: &[u8], + ) -> Result { + self.inner.sign_create_witness(key, data).await + } + fn can_sign_with(&self, key: &IdentityPublicKey) -> bool { + self.inner.can_sign_with(key) + } + } + + /// Answer `sender`'s DashPay identity contract nonce reads on `wallet`'s + /// SDK with `nonce`, in place of an earlier answer. + async fn expect_dashpay_nonce(wallet: &PlatformWallet, sender: &Identity, nonce: u64) { + use dash_sdk::query_types::IdentityContractNonceFetcher; + + let mut sdk = (*wallet.identity().sdk).clone(); + let key = ( + sender.id(), + dashpay_contract().expect("bundled DashPay").id(), + ); + sdk.mock() + .remove_fetch_expectation::(key) + .await; + sdk.mock() + .expect_fetch(key, Some(IdentityContractNonceFetcher(nonce))) + .await + .expect("the nonce read"); + } + + /// Answer the read of the request from `sender` to `recipient` carrying + /// `account_reference` on `wallet`'s SDK with `document`, `None` proving + /// there is none. + async fn expect_sent_request( + wallet: &PlatformWallet, + sender: &Identity, + recipient: &Identity, + account_reference: u32, + document: Option, + ) { + use dash_sdk::query_types::Documents; + use dpp::document::DocumentV0Getters; + + let mut sdk = (*wallet.identity().sdk).clone(); + let mut documents = Documents::new(); + if let Some(document) = document { + documents.insert(document.id(), Some(document)); + } + sdk.mock() + .expect_fetch_many::( + sent_contact_request_query(&sender.id(), &recipient.id(), account_reference) + .expect("the query"), + Some(documents), + ) + .await + .expect("the request read"); + } + + /// `sender`'s `contactRequest` document to `recipient` carrying + /// `account_reference`, as Platform holds it. + fn sent_request_document( + sender: &Identity, + recipient: &Identity, + account_reference: u32, + ) -> Document { + Document::V0(DocumentV0 { + id: Identifier::from([0x5E; 32]), + owner_id: sender.id(), + properties: BTreeMap::from([ + ( + "toUserId".to_string(), + Value::Identifier(recipient.id().to_buffer()), + ), + ("senderKeyIndex".to_string(), Value::U32(ENCRYPTION_KEY_ID)), + ( + "recipientKeyIndex".to_string(), + Value::U32(DECRYPTION_KEY_ID), + ), + ( + "accountReference".to_string(), + Value::U32(account_reference), + ), + ("encryptedPublicKey".to_string(), Value::Bytes(vec![7; 96])), + ]), + created_at: Some(BLOCK_TIME_MS), + created_at_core_block_height: Some(100), + ..Default::default() + }) + } + + /// The unconfirmed public request from `sender` to `recipient` on + /// `wallet`: its transition and account reference. + async fn unconfirmed_to( + wallet: &PlatformWallet, + sender: [u8; 32], + recipient: &Identity, + ) -> Option<(StateTransition, u32)> { + managed(wallet, sender, |managed| { + managed + .dashpay() + .unconfirmed_public_request(&recipient.id()) + .map(|held| (held.transition.clone(), held.account_reference)) + }) + .await + } + + /// How many times `transition`'s own bytes were broadcast on `wallet`'s + /// SDK. + async fn broadcasts_of(wallet: &PlatformWallet, transition: &StateTransition) -> usize { + use dash_sdk::platform::transition::broadcast_request::BroadcastRequestForStateTransition; + + let mut sdk = (*wallet.identity().sdk).clone(); + let request = transition + .broadcast_request_for_state_transition() + .expect("encodes"); + let count = sdk.mock().request_count(&request).await; + count + } + + /// Track `request` as received by its recipient on `wallet`. + async fn track_incoming(wallet: &PlatformWallet, request: &ContactRequest) { + let iw = wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&request.recipient_id) + .expect("the recipient") + .add_incoming_contact_request(request.clone(), &iw.persister) + .expect("the incoming request"); + } + + /// A public accept whose broadcast may have been delivered reports the + /// SDK's unconfirmed outcome (FFI code 20) and leaves its pair held as an + /// unconfirmed public request, which the per-pair read reports apart from + /// a private request pending. A public sync that cannot read the request + /// leaves it held, and a second accept is refused with nothing signed. + /// Proof ends it: the request proved on Platform is recorded as sent and + /// the pair released; its nonce proved used, with no request on Platform + /// at or above that height, releases the pair, and a fresh accept signs + /// and submits again. + #[tokio::test] + async fn should_hold_an_unconfirmed_public_accept_until_proof_settles_it() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let signed = Arc::new(AtomicUsize::new(0)); + let alice_signer = CountingSigner { + inner: signer(ALICE_PHRASE, &alice), + signed: Arc::clone(&signed), + }; + let request = public_request(&bob, &alice, 0); + + for recorded in [true, false] { + let (_manager, alice_wallet) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + track_incoming(&alice_wallet, &request).await; + expect_dashpay_nonce(&alice_wallet, &alice, 3).await; + let view = alice_wallet.identity().dashpay(); + + let accepted = view + .accept_contact_request_with_external_signer(&request, &alice_signer, &alice_crypto) + .await; + assert!( + matches!(&accepted, Err(PlatformWalletError::Sdk(error)) + if error.is_state_transition_result_unconfirmed()), + "{accepted:?}" + ); + assert!(view + .public_contact_request_unconfirmed(&alice.id(), &bob.id()) + .await + .expect("the read")); + assert!( + !view + .private_pair_held(&alice.id(), &bob.id()) + .await + .expect("the read"), + "no private request is pending" + ); + let (_, reference) = unconfirmed_to(&alice_wallet, ALICE, &bob) + .await + .expect("held"); + + // The sync cannot read the request: still held. + let _ = view.sync_contact_requests_reporting().await; + assert!(view + .public_contact_request_unconfirmed(&alice.id(), &bob.id()) + .await + .expect("the read")); + let signatures = signed.load(Ordering::SeqCst); + let again = view + .accept_contact_request_with_external_signer(&request, &alice_signer, &alice_crypto) + .await; + assert!( + matches!(&again, Err(PlatformWalletError::PublicContactRequestUnconfirmed(recipient)) + if *recipient == bob.id()), + "{again:?}" + ); + assert_eq!( + signed.load(Ordering::SeqCst), + signatures, + "nothing is signed" + ); + + if recorded { + expect_sent_request( + &alice_wallet, + &alice, + &bob, + reference, + Some(sent_request_document(&alice, &bob, reference)), + ) + .await; + let _ = view.sync_contact_requests_reporting().await; + assert!(!view + .public_contact_request_unconfirmed(&alice.id(), &bob.id()) + .await + .expect("the read")); + managed(&alice_wallet, ALICE, |managed| { + assert_eq!( + managed + .dashpay() + .outgoing_request(&bob.id()) + .map(|request| request.account_reference), + Some(reference), + "recorded as sent" + ); + }) + .await; + } else { + // The nonce it took (4) is used, and no request is on Platform. + expect_dashpay_nonce(&alice_wallet, &alice, 4).await; + expect_sent_request(&alice_wallet, &alice, &bob, reference, None).await; + let _ = view.sync_contact_requests_reporting().await; + assert!(!view + .public_contact_request_unconfirmed(&alice.id(), &bob.id()) + .await + .expect("the read")); + managed(&alice_wallet, ALICE, |managed| { + assert!(managed.dashpay().outgoing_request(&bob.id()).is_none()); + }) + .await; + let fresh = view + .accept_contact_request_with_external_signer( + &request, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + signed.load(Ordering::SeqCst) > signatures, + "a fresh accept signs: {fresh:?}" + ); + assert!( + matches!(&fresh, Err(PlatformWalletError::Sdk(error)) + if error.is_state_transition_result_unconfirmed()), + "this mock answers no broadcast: {fresh:?}" + ); + } + } + } + + /// While an unconfirmed public request may still execute, a sync + /// broadcasts its own signed bytes again and signs nothing. A nonce proved + /// used above the height the read that missed its document was proved at + /// does not release it: the request may have executed in between. Once + /// that read is at or above the nonce's height, it does. + #[tokio::test] + async fn should_broadcast_an_unconfirmed_public_request_again_as_its_own_bytes() { + use dash_sdk::query_types::{Documents, IdentityContractNonceFetcher}; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let signed = Arc::new(AtomicUsize::new(0)); + let alice_signer = CountingSigner { + inner: signer(ALICE_PHRASE, &alice), + signed: Arc::clone(&signed), + }; + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + expect_dashpay_nonce(&alice_wallet, &alice, 3).await; + let view = alice_wallet.identity().dashpay(); + let sent = view + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!(&sent, Err(PlatformWalletError::Sdk(error)) + if error.is_state_transition_result_unconfirmed()), + "{sent:?}" + ); + let signatures = signed.load(Ordering::SeqCst); + let (transition, reference) = unconfirmed_to(&alice_wallet, ALICE, &bob) + .await + .expect("held"); + expect_sent_request(&alice_wallet, &alice, &bob, reference, None).await; + + let before = broadcasts_of(&alice_wallet, &transition).await; + assert!(before > 0, "the send broadcast it"); + let _ = view.sync_contact_requests_reporting().await; + let after = broadcasts_of(&alice_wallet, &transition).await; + assert!(after > before, "broadcast again"); + assert_eq!(signed.load(Ordering::SeqCst), signatures, "nothing signed"); + assert_eq!( + unconfirmed_to(&alice_wallet, ALICE, &bob).await, + Some((transition.clone(), reference)), + "the same request stays held" + ); + + // Its nonce used at 10, the request read missing at 9 (within the + // SDK's one-block tolerance, so not refused as stale): held, as the + // request may have executed at 10, and as the nonce is used, not + // broadcast again. + expect_dashpay_nonce(&alice_wallet, &alice, 4).await; + let mut sdk = (*alice_wallet.identity().sdk).clone(); + sdk.mock() + .set_response_height_of::(10) + .set_response_height_of::(9); + let _ = view.sync_contact_requests_reporting().await; + assert!(view + .public_contact_request_unconfirmed(&alice.id(), &bob.id()) + .await + .expect("the read")); + assert_eq!(broadcasts_of(&alice_wallet, &transition).await, after); + + sdk.mock().set_response_height_of::(10); + let _ = view.sync_contact_requests_reporting().await; + assert!(!view + .public_contact_request_unconfirmed(&alice.id(), &bob.id()) + .await + .expect("the read")); + } + + /// A handle taken before its wallet was removed and created again under + /// its id settles nothing of the replacement's unconfirmed public request, + /// whatever the proofs show, and claims nothing on its pair. + #[tokio::test] + async fn should_leave_a_replacement_s_unconfirmed_public_request_to_it() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let manager = manager_on(Arc::new(NoPersistence)).await; + #[cfg(feature = "shielded")] + let _store = { + let dir = tempfile::tempdir().expect("temporary shielded store"); + manager + .configure_shielded(dir.path().join("tree.sqlite")) + .await + .expect("the shielded store is configured"); + dir + }; + let first = create_holding(&manager, ALICE_PHRASE, &alice).await; + let wallet_id = first.wallet_id(); + let stale = first.identity().dashpay(); + manager.remove_wallet(&wallet_id).await.expect("removed"); + let again = create_holding(&manager, ALICE_PHRASE, &alice).await; + assert_eq!(again.wallet_id(), wallet_id); + expect_dashpay_nonce(&again, &alice, 3).await; + let sent = again + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!(&sent, Err(PlatformWalletError::Sdk(error)) + if error.is_state_transition_result_unconfirmed()), + "{sent:?}" + ); + let (transition, reference) = unconfirmed_to(&again, ALICE, &bob).await.expect("held"); + + // Proofs that would settle it, as recorded: the stale handle acts on + // none of it. + expect_sent_request( + &again, + &alice, + &bob, + reference, + Some(sent_request_document(&alice, &bob, reference)), + ) + .await; + stale + .settle_unconfirmed_public_request(&alice.id(), &bob.id()) + .await + .expect("nothing to settle"); + assert_eq!( + unconfirmed_to(&again, ALICE, &bob).await, + Some((transition, reference)), + "the replacement's request stays held" + ); + managed(&again, ALICE, |managed| { + assert!(managed.dashpay().outgoing_request(&bob.id()).is_none()); + }) + .await; + let claimed = stale + .claim_public_pair(&alice.id(), &bob.id(), false, false) + .await; + assert!( + matches!( + claimed, + Err(PlatformWalletError::WalletRemovedBeforeSend(_)) + ), + "{:?}", + claimed.err() + ); + + // The replacement's own handle settles it. + again + .identity() + .dashpay() + .settle_unconfirmed_public_request(&alice.id(), &bob.id()) + .await + .expect("settled"); + assert!(unconfirmed_to(&again, ALICE, &bob).await.is_none()); + } + + /// A process that starts afresh holds no unconfirmed public request: a + /// request the earlier process broadcast, and that executed after it + /// ended, is found by the proved read before a new one is signed, and + /// adopted as sent with nothing signed or broadcast. + #[tokio::test] + async fn should_adopt_a_request_already_on_platform_instead_of_sending_another() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let signed = Arc::new(AtomicUsize::new(0)); + let alice_signer = CountingSigner { + inner: signer(ALICE_PHRASE, &alice), + signed: Arc::clone(&signed), + }; + // The earlier process: its request is unconfirmed when it ends. + let reference = { + let (_manager, earlier) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + expect_dashpay_nonce(&earlier, &alice, 3).await; + let _ = earlier + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + unconfirmed_to(&earlier, ALICE, &bob).await.expect("held").1 + }; + + // The new process, the request on Platform. + let (_manager, restarted) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + expect_dashpay_nonce(&restarted, &alice, 4).await; + expect_sent_request( + &restarted, + &alice, + &bob, + reference, + Some(sent_request_document(&alice, &bob, reference)), + ) + .await; + let signatures = signed.load(Ordering::SeqCst); + let adopted = restarted + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await + .expect("adopted"); + assert_eq!(adopted.account_reference, reference); + assert_eq!(signed.load(Ordering::SeqCst), signatures, "nothing signed"); + assert!(unconfirmed_to(&restarted, ALICE, &bob).await.is_none()); + managed(&restarted, ALICE, |managed| { + assert_eq!( + managed + .dashpay() + .outgoing_request(&bob.id()) + .map(|request| request.account_reference), + Some(reference) + ); + }) + .await; + } + + /// An unconfirmed public request holds its pair against a private request + /// too, by its own refusal and with nothing paid, and keeps its sender + /// from being removed, which would drop the hold. + #[tokio::test] + async fn should_refuse_a_private_request_and_a_removal_while_a_public_one_is_unconfirmed() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_signer = signer(ALICE_PHRASE, &alice); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let persistence = RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ); + let manager = manager_on(Arc::clone(&persistence)).await; + #[cfg(feature = "shielded")] + let _store = { + let dir = tempfile::tempdir().expect("temporary shielded store"); + manager + .configure_shielded(dir.path().join("tree.sqlite")) + .await + .expect("the shielded store is configured"); + dir + }; + let alice_wallet = create_holding(&manager, ALICE_PHRASE, &alice).await; + let contact_xpub = alice_crypto + .receiving_xpub(&"m/9'/1'/15'/0'".parse::().expect("a path")) + .await + .expect("an xpub"); + { + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&alice_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("Alice") + .hold_unconfirmed_public_request( + bob.id(), + StateTransition::Batch(BatchTransition::V0(Default::default())), + 0, + 0, + contact_xpub, + ); + } + let paid = Arc::new(Mutex::new(Vec::new())); + let sent = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&paid), + ) + .await; + assert!( + matches!(&sent, Err(PlatformWalletError::PublicContactRequestUnconfirmed(recipient)) + if *recipient == bob.id()), + "{sent:?}" + ); + assert!(paid.lock().expect("paid").is_empty(), "nothing is paid"); + + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let removed = wm + .get_wallet_info_mut(&alice_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .remove_identity(&alice.id(), &iw.persister); + assert!( + matches!(&removed, Err(PlatformWalletError::PublicContactRequestUnconfirmed(recipient)) + if *recipient == bob.id()), + "{:?}", + removed.err() + ); + } + + /// The position records stored for `owner` so far. + fn positions_stored(persistence: &RecordingPersistence, owner: &Identifier) -> usize { + persistence + .stored + .lock() + .expect("stored") + .iter() + .filter(|changeset| { + changeset.contacts.as_ref().is_some_and(|contacts| { + contacts + .private_contact_requests_positions + .contains_key(owner) + }) + }) + .count() + } + + /// A private send whose wallet is removed and created again under its id + /// while the send is being prepared, after it reserved the pair, is + /// refused before anything is paid, and neither its release nor its + /// cleanup on drop touches the replacement: the replacement's own + /// reservation of the pair stays, and no marker is stored for it. A + /// handle taken before the replacement reserves nothing on it, and claims + /// nothing on it. + #[tokio::test] + async fn should_leave_a_wallet_created_again_alone_from_a_stale_private_send() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_signer = signer(ALICE_PHRASE, &alice); + let persistence = RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ); + let manager = manager_on(Arc::clone(&persistence)).await; + #[cfg(feature = "shielded")] + let _store = { + let dir = tempfile::tempdir().expect("temporary shielded store"); + manager + .configure_shielded(dir.path().join("tree.sqlite")) + .await + .expect("the shielded store is configured"); + dir + }; + let replace = |first: &Arc| { + let wallet_id = first.wallet_id(); + let manager = &manager; + let alice = &alice; + async move { + manager.remove_wallet(&wallet_id).await.expect("removed"); + let again = create_holding(manager, ALICE_PHRASE, alice).await; + assert_eq!(again.wallet_id(), wallet_id); + // The replacement reserves the pair itself. + { + let iw = again.identity(); + let mut wm = iw.wallet_manager.write().await; + let reserved = wm + .get_wallet_info_mut(&wallet_id) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("Alice") + .reserve_private_reply(identity(BOB_PHRASE, BOB).id()); + assert!(reserved.is_some()); + } + again + } + }; + + for dropped in [false, true] { + let first = create_holding(&manager, ALICE_PHRASE, &alice).await; + let reached = Arc::new(tokio::sync::Notify::new()); + let release = Arc::new(tokio::sync::Notify::new()); + // The second derivation, as the send prepares its request, after + // it reserved the pair. + let mut pausing = HookedCrypto::new(ALICE_PHRASE); + pausing.before_receiving_xpub = + Some(pause_on_call(2, Arc::clone(&reached), Arc::clone(&release))); + let paid = Arc::new(Mutex::new(Vec::new())); + let view = first.identity().dashpay(); + let (alice_id, bob_id) = (alice.id(), bob.id()); + let mut send = Box::pin(view.send_private_contact_request( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &pausing, + keep_entry(&paid), + )); + tokio::select! { + sent = &mut send => panic!("the send ran past its pause: {sent:?}"), + _ = reached.notified() => {} + } + assert!( + pending_to(&first, ALICE, &bob).await, + "the pair is reserved" + ); + let again = replace(&first).await; + let stored = positions_stored(&persistence, &alice.id()); + if dropped { + drop(send); + } else { + release.notify_one(); + let sent = send.await; + assert!( + matches!(sent, Err(PlatformWalletError::WalletRemovedBeforeSend(_))), + "{sent:?}" + ); + } + tokio::task::yield_now().await; + assert!(paid.lock().expect("paid").is_empty(), "nothing is paid"); + assert!( + pending_to(&again, ALICE, &bob).await, + "the replacement's reservation stays ({dropped})" + ); + assert_eq!( + positions_stored(&persistence, &alice.id()), + stored, + "no marker is stored for the replacement ({dropped})" + ); + + // A handle taken before the replacement acts on nothing of it. + let reserved = view + .with_managed(&alice.id(), |managed| { + managed.reserve_private_reply(bob.id()) + }) + .await; + assert!( + matches!(reserved, Err(PlatformWalletError::WalletNotFound(_))), + "{reserved:?}" + ); + let claimed = view + .claim_public_pair(&alice.id(), &bob.id(), false, false) + .await; + assert!( + matches!( + claimed, + Err(PlatformWalletError::WalletRemovedBeforeSend(_)) + ), + "{:?}", + claimed.err() + ); + manager + .remove_wallet(&again.wallet_id()) + .await + .expect("removed"); + } + } + + /// A public request is bound to its wallet's generation: while one claims + /// its pair under the wallet's lifecycle gate, paused here at its check + /// that the wallet is still live, the wallet cannot be removed; once the + /// wallet is removed and re-created under the same id, a send through the + /// old handle is refused before it claims anything, publishing nothing + /// and changing nothing on the replacement. + #[tokio::test] + async fn should_not_let_a_public_request_outlive_its_wallet() { + use std::future::Future; + use std::task::{Context, Waker}; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (manager, old) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let wallet_id = old.wallet_id(); + let (alice_id, bob_id) = (alice.id(), bob.id()); + { + // Stepped one wallet-lock section at a time: the private store read + // runs without the lifecycle gate, a removal free to take it; then + // the send takes the gate and waits under it, at its check that the + // wallet is still live, for the wallet lock this test holds. + let view = old.identity().dashpay(); + let mut send = Box::pin(view.send_contact_request_with_external_signer( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + )); + let mut cx = Context::from_waker(Waker::noop()); + let wallet_manager = old.wallet_manager(); + let mut held = wallet_manager.write().await; + let mut gated = false; + for _ in 0..200 { + assert!(send.as_mut().poll(&mut cx).is_pending()); + // In flight under the gate, which a removal takes exclusively + // before anything else: no removal can complete. + if tokio::time::timeout( + Duration::from_millis(20), + old.generation().teardown_guard(), + ) + .await + .is_err() + { + gated = true; + break; + } + let mut next = Box::pin(wallet_manager.write()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + drop(held); + assert!(send.as_mut().poll(&mut cx).is_pending()); + held = match next.as_mut().poll(&mut cx) { + std::task::Poll::Ready(guard) => guard, + std::task::Poll::Pending => panic!("the test's write is next"), + }; + } + assert!(gated, "a removal waits for the public request's claim"); + // Dropped, the send gives the wallet up. + drop(send); + drop(held); + } + + manager.remove_wallet(&wallet_id).await.expect("removed"); + let replacement = manager + .create_wallet_from_seed_bytes( + Network::Testnet, + &seed(ALICE_PHRASE), + WalletAccountCreationOptions::Default, + Some(0), + ) + .await + .expect("re-created"); + assert_eq!(replacement.wallet_id(), wallet_id); + { + let iw = replacement.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet_id) + .expect("the replacement's info") + .identity_manager + .add_identity(alice.clone(), 0, wallet_id, &iw.persister) + .expect("alice"); + } + let resumed = old + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &signer(ALICE_PHRASE, &alice), + &alice_crypto, + ) + .await; + assert!( + matches!( + resumed, + Err(PlatformWalletError::WalletRemovedBeforeSend(_)) + ), + "{resumed:?}" + ); + managed(&replacement, ALICE, |managed| { + assert!(managed.dashpay().outgoing_request(&bob.id()).is_none()); + assert!(!managed.dashpay().private_reply_pending(&bob.id())); + }) + .await; + } + + /// A public request's private store read, with its network reads and the + /// host's key resolution, does not hold the wallet's lifecycle gate: + /// parked at its scan, the send leaves a removal free to complete. The + /// wallet re-created meanwhile under its id, the old read's results never + /// reach the replacement, as they are applied only to the read's own + /// generation, and the old send is refused. + #[tokio::test] + async fn should_not_hold_a_removal_while_a_public_request_reads_the_private_store() { + use std::sync::Arc as StdArc; + use tokio::sync::Notify; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (manager, old) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let wallet_id = old.wallet_id(); + let called = StdArc::new(Notify::new()); + let release = StdArc::new(Notify::new()); + let send = { + let wallet = Arc::clone(&old); + let mut crypto = HookedCrypto::new(ALICE_PHRASE); + let (called, release) = (StdArc::clone(&called), StdArc::clone(&release)); + crypto.before_scan = Some(Arc::new(move || { + let (called, release) = (StdArc::clone(&called), StdArc::clone(&release)); + Box::pin(async move { + called.notify_one(); + release.notified().await; + }) + })); + let signer = signer(ALICE_PHRASE, &alice); + let (alice_id, bob_id) = (alice.id(), bob.id()); + tokio::spawn(async move { + wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + &signer, + &crypto, + ) + .await + }) + }; + tokio::time::timeout(Duration::from_secs(5), called.notified()) + .await + .expect("the send reads the private store"); + tokio::time::timeout(Duration::from_secs(5), manager.remove_wallet(&wallet_id)) + .await + .expect("a removal is not held behind the read") + .expect("removed"); + let replacement = manager + .create_wallet_from_seed_bytes( + Network::Testnet, + &seed(ALICE_PHRASE), + WalletAccountCreationOptions::Default, + Some(0), + ) + .await + .expect("re-created"); + { + let iw = replacement.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet_id) + .expect("the replacement's info") + .identity_manager + .add_identity(alice.clone(), 0, wallet_id, &iw.persister) + .expect("alice"); + } + release.notify_one(); + let sent = send.await.expect("send task"); + assert!( + matches!(sent, Err(PlatformWalletError::WalletRemovedBeforeSend(_))), + "{sent:?}" + ); + managed(&replacement, ALICE, |managed| { + assert!( + !managed.dashpay().private_contact_requests_read(), + "the old read's results do not reach the replacement" + ); + assert!(!managed.dashpay().public_contact_request_claimed(&bob.id())); + assert!(managed.dashpay().outgoing_request(&bob.id()).is_none()); + }) + .await; + } + + /// A public request's host signing does not hold the wallet's lifecycle + /// gate: parked at its signature, the send leaves a removal free to take + /// the gate and complete. Its signature, returning after the removal, + /// takes the gate, finds the wallet gone and publishes nothing. + #[tokio::test] + async fn should_not_hold_a_removal_while_a_public_request_is_signed() { + use dash_sdk::query_types::IdentityContractNonceFetcher; + use std::sync::Arc as StdArc; + use tokio::sync::Notify; + + #[derive(Debug)] + struct ParkedSigner { + inner: simple_signer::signer::SimpleSigner, + called: StdArc, + release: StdArc, + } + #[async_trait::async_trait] + impl Signer for ParkedSigner { + async fn sign( + &self, + key: &IdentityPublicKey, + data: &[u8], + ) -> Result { + self.called.notify_one(); + self.release.notified().await; + self.inner.sign(key, data).await + } + async fn sign_create_witness( + &self, + key: &IdentityPublicKey, + data: &[u8], + ) -> Result { + self.inner.sign_create_witness(key, data).await + } + fn can_sign_with(&self, key: &IdentityPublicKey) -> bool { + self.inner.can_sign_with(key) + } + } + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let wallet_id = alice_wallet.wallet_id(); + let mut sdk = (*alice_wallet.identity().sdk).clone(); + sdk.mock() + .expect_fetch( + ( + alice.id(), + dashpay_contract().expect("bundled DashPay").id(), + ), + Some(IdentityContractNonceFetcher(3)), + ) + .await + .expect("the nonce read"); + let called = StdArc::new(Notify::new()); + let release = StdArc::new(Notify::new()); + let send = { + let wallet = Arc::clone(&alice_wallet); + let signer = ParkedSigner { + inner: signer(ALICE_PHRASE, &alice), + called: StdArc::clone(&called), + release: StdArc::clone(&release), + }; + let (alice_id, bob_id) = (alice.id(), bob.id()); + tokio::spawn(async move { + let crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + &signer, + &crypto, + ) + .await + }) + }; + tokio::time::timeout(Duration::from_secs(5), called.notified()) + .await + .expect("the send reaches its signature"); + tokio::time::timeout(Duration::from_secs(5), manager.remove_wallet(&wallet_id)) + .await + .expect("a removal is not held behind the signing") + .expect("removed"); + release.notify_one(); + let sent = send.await.expect("send task"); + assert!( + matches!(sent, Err(PlatformWalletError::WalletRemovedBeforeSend(_))), + "{sent:?}" + ); + } + + /// A send dropped before it pays, here while its signer never answers, + /// leaves no reservation behind: nothing was paid, and no sync could + /// settle one. The recipient is free for the next send. + #[tokio::test] + async fn should_release_the_reservation_of_a_send_dropped_before_it_pays() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = alice_wallet.identity().dashpay(); + let asked = Arc::new(AtomicBool::new(false)); + let stalled = StalledSigner { + inner: signer(ALICE_PHRASE, &alice), + asked: Arc::clone(&asked), + }; + let paid = Arc::new(Mutex::new(Vec::new())); + + let cancelled = tokio::time::timeout( + Duration::from_millis(200), + view.send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &stalled, + &alice_crypto, + keep_entry(&paid), + ), + ) + .await; + assert!(cancelled.is_err(), "the send never completes"); + assert!( + asked.load(Ordering::SeqCst), + "it was dropped while signing, so after reserving" + ); + assert!(paid.lock().expect("paid").is_empty(), "nothing is paid"); + assert!(!pending_to(&alice_wallet, ALICE, &bob).await); + + let kept = Arc::new(Mutex::new(Vec::new())); + let next = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &signer(ALICE_PHRASE, &alice), + &alice_crypto, + keep_entry(&kept), + ) + .await; + assert!( + matches!( + next, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{next:?}" + ); + assert_eq!(kept.lock().expect("kept").len(), 1, "the next send pays"); + } + + /// A sync settles a pending request only once it records the entry: one + /// whose recipient cannot be read leaves no record, so the request stays + /// pending, and it settles on a later sync that reads the recipient. + #[tokio::test] + async fn should_settle_a_pending_request_only_once_its_entry_is_recorded() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = alice_wallet.identity().dashpay(); + let kept = Arc::new(Mutex::new(Vec::new())); + let sent = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&kept), + ) + .await; + assert!( + matches!( + sent, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{sent:?}" + ); + let entry = kept.lock().expect("kept").remove(0); + publish(&alice_wallet, 0, vec![entry.to_vec()]).await; + + set_identity_known(&alice_wallet, &bob, false).await; + let report = view + .sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("Alice reads the store"); + assert_eq!(report.requests, vec![]); + assert_eq!(report.unpersisted_identities, vec![alice.id()]); + managed(&alice_wallet, ALICE, |managed| { + assert!(managed.dashpay().private_reply_pending(&bob.id())); + assert!(managed.dashpay().outgoing_request(&bob.id()).is_none()); + }) + .await; + + set_identity_known(&alice_wallet, &bob, true).await; + let report = view + .sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("Alice reads the store again"); + assert_eq!(report.requests.len(), 1, "{:?}", report.requests); + managed(&alice_wallet, ALICE, |managed| { + assert!(!managed.dashpay().private_reply_pending(&bob.id())); + assert_eq!( + managed.dashpay().outgoing_request(&bob.id()), + Some(&report.requests[0]) + ); + }) + .await; + } + + /// A pending request whose entry is read back after a newer request to + /// the recipient is tracked, here as another device's rotation would be, + /// is settled: its entry executed, and the newer request stays tracked. + #[tokio::test] + async fn should_settle_a_pending_request_read_back_after_a_newer_one() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = alice_wallet.identity().dashpay(); + let kept = Arc::new(Mutex::new(Vec::new())); + let sent = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&kept), + ) + .await; + assert!( + matches!( + sent, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{sent:?}" + ); + let entry = kept.lock().expect("kept").remove(0); + + let mut newer = public_request(&alice, &bob, (1 << 28) | 5); + newer.core_height_created_at = 0; + { + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&alice_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("Alice") + .add_sent_contact_request(newer.clone(), &iw.persister) + .expect("the newer request"); + } + publish(&alice_wallet, 0, vec![entry.to_vec()]).await; + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("Alice reads the store"); + managed(&alice_wallet, ALICE, |managed| { + assert!(!managed.dashpay().private_reply_pending(&bob.id())); + assert_eq!(managed.dashpay().outgoing_request(&bob.id()), Some(&newer)); + }) + .await; + } + + /// A request paid for and unconfirmed before a restart is restored from + /// its entry: until a sync reads the entry back, neither a second private + /// request nor a public one goes to the recipient. Once recorded, the + /// entry restores nothing. + #[tokio::test] + async fn should_restore_a_pending_request_paid_for_before_a_restart() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, before) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + before + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&kept), + ) + .await + .expect_err("not read back"); + let entry = kept.lock().expect("kept").remove(0); + + let (_restarted_manager, restarted) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = restarted.identity().dashpay(); + assert!(!pending_to(&restarted, ALICE, &bob).await); + let restored = view + .restore_pending_private_contact_requests(std::slice::from_ref(&entry), &alice_crypto) + .await + .expect("restored"); + assert_eq!(restored, vec![(alice.id(), bob.id())]); + assert!(pending_to(&restarted, ALICE, &bob).await); + + let paid = Arc::new(Mutex::new(Vec::new())); + let second = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&paid), + ) + .await; + assert!( + matches!(second, Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob.id()), + "{second:?}" + ); + assert!( + paid.lock().expect("paid").is_empty(), + "nothing is paid twice" + ); + let public = view + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!(public, Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob.id()), + "{public:?}" + ); + + publish(&restarted, 0, vec![entry.to_vec()]).await; + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the restarted wallet reads the store"); + managed(&restarted, ALICE, |managed| { + assert!(!managed.dashpay().private_reply_pending(&bob.id())); + assert!(managed.dashpay().outgoing_request(&bob.id()).is_some()); + }) + .await; + assert_eq!( + view.restore_pending_private_contact_requests(&[entry], &alice_crypto) + .await + .expect("restored"), + vec![], + "a recorded entry is not restored" + ); + } + + /// A send whose payment finds a request to the same recipient paid for + /// and unconfirmed before a restart pays nothing: the recipient stays + /// reserved for that request, which a sync settles once it reads it back. + #[tokio::test] + async fn should_hold_a_send_for_a_request_paid_for_before_a_restart() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (alice_id, bob_id) = (alice.id(), bob.id()); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, before) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + before + .identity() + .dashpay() + .send_private_contact_request( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&kept), + ) + .await + .expect_err("not read back"); + let unconfirmed = vec![kept.lock().expect("kept").remove(0)]; + + // The host restores nothing at startup; the payment checks. + let (_restarted_manager, restarted) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = restarted.identity().dashpay(); + let paid = Arc::new(Mutex::new(Vec::new())); + let held = view + .send_private_contact_request( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + |entry: BinaryData, started: PaymentStarted| { + let paid = Arc::clone(&paid); + let unconfirmed = &unconfirmed; + let crypto = &alice_crypto; + async move { + if view + .hold_for_restored_private_contact_request( + unconfirmed, + crypto, + &alice_id, + &bob_id, + ) + .await? + { + return Err(PlatformWalletError::PrivateContactRequestPending(bob_id)); + } + started.mark(); + paid.lock().expect("paid").push(entry); + Ok(ResponseMetadata::default()) + } + }, + ) + .await; + assert!( + matches!(held, Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob_id), + "{held:?}" + ); + assert!(paid.lock().expect("paid").is_empty(), "nothing is paid"); + assert!(pending_to(&restarted, ALICE, &bob).await); + + // The restored entry, not the unpaid one, settles it. + publish(&restarted, 0, vec![unconfirmed[0].to_vec()]).await; + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the restarted wallet reads the store"); + assert!(!pending_to(&restarted, ALICE, &bob).await); + } + + /// A rotation whose payment is unconfirmed at a restart, over a request + /// that was recorded, is restored: the recorded request is older, so it + /// does not discharge the rotation. Until the rotation is read back, a + /// retried rotation is refused unpaid, whether the host restored at + /// startup or the payment finds it; once it is recorded, its entry, and + /// the older one, restore nothing. + #[tokio::test] + async fn should_restore_a_rotation_paid_for_before_a_restart() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (alice_id, bob_id) = (alice.id(), bob.id()); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, before) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + let v0 = before + .identity() + .dashpay() + .send_private_contact_request( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + append_entry(&before, 0, vec![], &kept), + ) + .await + .expect("v0 is recorded"); + assert_eq!(account_reference_version(v0.account_reference), 0); + let v0_entry = kept.lock().expect("kept").remove(0); + let unconfirmed = { + let kept = Arc::clone(&kept); + move |entry: BinaryData, started: PaymentStarted| { + started.mark(); + kept.lock().expect("kept").push(entry); + std::future::ready(Err::( + PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create", + reason: "the proof fetch timed out".to_string(), + }, + )) + } + }; + let rotation = before + .identity() + .dashpay() + .send_private_contact_request( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + unconfirmed, + ) + .await; + assert!( + matches!( + rotation, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{rotation:?}" + ); + let v1_entry = kept.lock().expect("kept").remove(0); + + // A restart: the store holds v0 only, which the restarted wallet + // records. The host restores the unconfirmed rotation. + let (_restarted_manager, restarted) = wallet( + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![v0_entry.to_vec()], + ) + .await; + let view = restarted.identity().dashpay(); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the restarted wallet reads the store"); + managed(&restarted, ALICE, |managed| { + assert_eq!(managed.dashpay().outgoing_request(&bob_id), Some(&v0)); + }) + .await; + assert_eq!( + view.restore_pending_private_contact_requests( + std::slice::from_ref(&v1_entry), + &alice_crypto + ) + .await + .expect("restored"), + vec![(alice_id, bob_id)], + "a recorded v0 does not discharge the v1 rotation" + ); + let retried = view + .send_private_contact_request( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + no_payment, + ) + .await; + assert!( + matches!(retried, Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob_id), + "{retried:?}" + ); + + // Another restart, the host restoring nothing: the payment of the + // retried rotation finds the unconfirmed one and pays nothing. + let (_held_manager, held_wallet) = wallet( + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![v0_entry.to_vec()], + ) + .await; + let held_view = held_wallet.identity().dashpay(); + let paid = Arc::new(Mutex::new(Vec::new())); + let unconfirmed_entries = vec![v1_entry.clone()]; + let held = held_view + .send_private_contact_request( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + |entry: BinaryData, started: PaymentStarted| { + let paid = Arc::clone(&paid); + let unconfirmed_entries = &unconfirmed_entries; + let crypto = &alice_crypto; + async move { + if held_view + .hold_for_restored_private_contact_request( + unconfirmed_entries, + crypto, + &alice_id, + &bob_id, + ) + .await? + { + return Err(PlatformWalletError::PrivateContactRequestPending(bob_id)); + } + started.mark(); + paid.lock().expect("paid").push(entry); + Ok(ResponseMetadata::default()) + } + }, + ) + .await; + assert!( + matches!(held, Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob_id), + "{held:?}" + ); + assert!(paid.lock().expect("paid").is_empty(), "nothing is paid"); + + // v1 lands and is read back, after v0 where each wallet's cursor is: + // settled, and discharged. + for wallet in [&restarted, &held_wallet] { + publish(wallet, 1, vec![v1_entry.to_vec()]).await; + wallet + .identity() + .dashpay() + .sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the store is read"); + managed(wallet, ALICE, |managed| { + assert!(!managed.dashpay().private_reply_pending(&bob_id)); + let tracked = managed + .dashpay() + .outgoing_request(&bob_id) + .expect("tracked"); + assert_eq!(account_reference_version(tracked.account_reference), 1); + }) + .await; + } + assert_eq!( + view.restore_pending_private_contact_requests(&[v1_entry, v0_entry], &alice_crypto) + .await + .expect("restored"), + vec![], + "a recorded rotation, and the request it rotated, restore nothing" + ); + } + + /// From now on, `wallet`'s mock SDK serves a store holding `entries` in + /// chunks of `chunk_size`, a page from each chunk's start to its end or + /// the store's. + async fn publish_chunked(wallet: &PlatformWallet, entries: &[Vec], chunk_size: usize) { + let total = entries.len() as u64; + for (index, chunk) in entries.chunks(chunk_size).enumerate() { + let start = (index * chunk_size) as u64; + let mut page = store_page(start, chunk.to_vec()); + page.total_count = total; + let contract = dashpay_contract().expect("bundled DashPay"); + let query = PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + start, + ); + let mut sdk = (*wallet.identity().sdk).clone(); + let mut mock = sdk.mock(); + mock.remove_fetch_expectation::(query.clone()) + .await; + mock.expect_fetch(query, Some(page)) + .await + .expect("page expectation"); + } + } + + /// What `wallet` tracks with `contacts` after a sync: each one's requests + /// both ways. + async fn tracked( + wallet: &PlatformWallet, + identity_id: [u8; 32], + contacts: &[Identifier], + ) -> Vec<(Option, Option)> { + managed(wallet, identity_id, |managed| { + contacts + .iter() + .map(|contact| { + ( + managed.dashpay().outgoing_request(contact).cloned(), + managed.dashpay().incoming_request(contact).cloned(), + ) + }) + .collect() + }) + .await + } + + /// A store of many pages is read in one pass, its pages fetched together + /// and scanned in batches: the wallet records what it records from the + /// same entries in one page, and derives the scan keys once a batch, not + /// once a page. + #[tokio::test] + async fn should_sync_a_store_of_many_pages_in_one_pass() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let carol = identity(CAROL_PHRASE, CAROL); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let bob_signer = signer(BOB_PHRASE, &bob); + let everyone = [&alice, &bob, &carol]; + + // Alice's requests to Bob and Carol, and Bob's to Alice. + let (_alice_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &everyone, vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + for (start, recipient) in [(0, bob.id()), (1, carol.id())] { + alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &recipient, + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + append_entry(&alice_wallet, start, vec![], &kept), + ) + .await + .expect("Alice sends"); + } + let to_bob = kept.lock().expect("kept")[0].to_vec(); + let (_bob_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &everyone, vec![to_bob]).await; + bob_wallet + .identity() + .dashpay() + .send_private_contact_request( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + None, + &bob_signer, + &bob_crypto, + append_entry(&bob_wallet, 1, vec![], &kept), + ) + .await + .expect("Bob sends"); + let entries: Vec> = kept + .lock() + .expect("kept") + .iter() + .map(|entry| entry.to_vec()) + .collect(); + assert_eq!(entries.len(), 3); + let contacts = [bob.id(), carol.id()]; + + // Restored from seed, once with the store in one page and once in + // pages of one entry. + let (_one_manager, one_page) = + wallet(ALICE_PHRASE, &alice, &everyone, entries.clone()).await; + let one_page_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let one = one_page + .identity() + .dashpay() + .sync_private_contact_requests(&one_page_crypto, 64) + .await + .expect("the one-page store reads"); + assert_eq!(one.pages_read, 1); + + let (_many_manager, many_pages) = wallet(ALICE_PHRASE, &alice, &everyone, vec![]).await; + publish_chunked(&many_pages, &entries, 1).await; + let many_pages_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let many = many_pages + .identity() + .dashpay() + .sync_private_contact_requests(&many_pages_crypto, 64) + .await + .expect("the store of many pages reads"); + assert_eq!(many.pages_read, 3); + assert!(many.complete); + assert_eq!(many.next_position, 3); + assert_eq!(many.rejected, vec![]); + assert_eq!(many.requests.len(), 3, "{:?}", many.requests); + // A page's received requests are recorded before its sent ones, so + // the order differs; the requests do not. + let sorted = |mut requests: Vec| { + requests.sort_by_key(|request| (request.sender_id, request.recipient_id)); + requests + }; + assert_eq!(sorted(many.requests.clone()), sorted(one.requests.clone())); + assert_eq!( + tracked(&many_pages, ALICE, &contacts).await, + tracked(&one_page, ALICE, &contacts).await + ); + let derivations = many_pages_crypto + .scan_key_derivations + .load(std::sync::atomic::Ordering::SeqCst); + assert!( + (1..many.pages_read).contains(&derivations), + "{derivations} derivations for {} pages", + many.pages_read + ); + } + + /// Alice's private request to Bob, carrying `shielded_address`, read back + /// from the store: its entry and Bob's record of it. + async fn alice_to_bob(shielded_address: [u8; 43]) -> (Vec, ContactRequest) { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let (_alice_manager, alice_wallet) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + Some(shielded_address), + &signer(ALICE_PHRASE, &alice), + &alice_crypto, + append_entry(&alice_wallet, 0, vec![], &kept), + ) + .await + .expect("Alice sends"); + let entry = kept.lock().expect("kept").remove(0).to_vec(); + let (_bob_manager, bob_wallet) = + wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![entry.clone()]).await; + bob_wallet + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store"); + let received = managed(&bob_wallet, BOB, |managed| { + managed.dashpay().incoming_request(&alice.id()).cloned() + }) + .await + .expect("Bob holds Alice's request"); + (entry, received) + } + + /// For a backend attesting the scan state, a sync stores the private + /// contact's shielded address and then the read position, after the + /// request the entry held. + #[tokio::test] + async fn should_store_the_read_position_after_what_the_entries_held() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let address = [0x55; 43]; + let (entry, _) = alice_to_bob(address).await; + let persistence = RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ); + let (_manager, bob_wallet) = wallet_on( + Arc::clone(&persistence), + BOB_PHRASE, + &bob, + &[&alice, &bob], + vec![entry], + ) + .await; + bob_wallet + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store"); + + let contacts = persistence.contacts(); + let index_of = |found: &dyn Fn(&ContactChangeSet) -> bool| { + contacts + .iter() + .position(found) + .expect("the changeset is stored") + }; + let request = index_of(&|changeset| !changeset.incoming_requests.is_empty()); + let addresses = index_of(&|changeset| { + changeset + .private_shielded_addresses + .get(&(bob.id(), alice.id())) + == Some(&address) + }); + let position = index_of(&|changeset| { + changeset + .private_contact_requests_positions + .get(&bob.id()) + .map(|position| position.position) + == Some(1) + }); + assert!( + request < addresses && addresses < position, + "request {request}, addresses {addresses}, position {position}" + ); + } + + /// A wallet loaded with a stored read position and shielded address, as a + /// backend attesting them restores them, reads the store on from there: + /// no page before it is fetched, which the mock, answering none, would + /// fail. The contact's shielded address is kept. + #[tokio::test] + async fn should_resume_a_private_sync_from_a_restored_position() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let address = [0x55; 43]; + let (entry, received) = alice_to_bob(address).await; + let persistence = RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ); + let (_manager, restored) = + wallet_on(persistence, BOB_PHRASE, &bob, &[&alice, &bob], vec![entry]).await; + { + let iw = restored.identity(); + let mut wm = iw.wallet_manager.write().await; + let managed = wm + .get_wallet_info_mut(&restored.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&bob.id()) + .expect("Bob"); + managed.apply_incoming_contact_request(received.clone()); + let key_fingerprint = managed.private_scan_key_fingerprint(); + managed.apply_private_contact_requests_position(PrivateContactRequestsPosition { + position: 1, + key_fingerprint, + private_payments_unresolved: false, + }); + managed.apply_private_shielded_address(alice.id(), address); + } + let contract = dashpay_contract().expect("bundled DashPay"); + { + let mut sdk = (*restored.identity().sdk).clone(); + sdk.mock() + .remove_fetch_expectation::( + PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + 0, + ), + ) + .await; + } + publish(&restored, 1, vec![]).await; + + let report = restored + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("the store reads on from position 1"); + assert_eq!(report.pages_read, 1); + assert!(report.complete); + assert_eq!(report.next_position, 1); + managed(&restored, BOB, |managed| { + assert_eq!( + managed + .dashpay() + .private_contact(&alice.id()) + .expect("a private contact") + .shielded_address, + Some(address) + ); + assert_eq!( + managed.dashpay().incoming_request(&alice.id()), + Some(&received) + ); + }) + .await; + } + + /// Un-ignoring a sender rewinds the private read position, and a backend + /// attesting the scan state, with atomic changesets, stores the rewind in + /// the changeset that stores the sender's removal, to commit together. + #[tokio::test] + async fn should_store_a_rewound_position_when_a_sender_is_unignored() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let persistence = RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ); + let (_manager, bob_wallet) = wallet_on( + Arc::clone(&persistence), + BOB_PHRASE, + &bob, + &[&alice, &bob], + vec![], + ) + .await; + let view = bob_wallet.identity().dashpay(); + { + let iw = bob_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&bob_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&bob.id()) + .expect("Bob") + .apply_private_contact_requests_position(PrivateContactRequestsPosition { + position: 7, + key_fingerprint: [0; 32], + private_payments_unresolved: false, + }); + } + view.ignore_contact_sender(&bob.id(), &alice.id()) + .await + .expect("ignored"); + view.unignore_contact_sender(&bob.id(), &alice.id()) + .await + .expect("un-ignored"); + let unignore = persistence + .contacts() + .into_iter() + .find(|changeset| changeset.unignored.contains(&(bob.id(), alice.id()))) + .expect("the un-ignore is stored"); + assert_eq!( + unignore + .private_contact_requests_positions + .iter() + .map(|(owner, position)| (*owner, position.position)) + .collect::>(), + vec![(bob.id(), 0)] + ); + } + + /// A backend that does not attest the scan state gets none of it, and a + /// load drops whatever it restored: the store is read from its start. + #[tokio::test] + async fn should_read_the_store_from_its_start_for_a_backend_without_the_capability() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let persistence = RecordingPersistence::attesting(PersistenceCapabilities::NONE); + let (_manager, bob_wallet) = wallet_on( + Arc::clone(&persistence), + BOB_PHRASE, + &bob, + &[&alice, &bob], + vec![entry], + ) + .await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store"); + view.ignore_contact_sender(&bob.id(), &alice.id()) + .await + .expect("ignored"); + view.unignore_contact_sender(&bob.id(), &alice.id()) + .await + .expect("un-ignored"); + assert!(persistence.contacts().iter().all(|changeset| { + changeset.private_contact_requests_positions.is_empty() + && changeset.private_shielded_addresses.is_empty() + && changeset.removed_private_shielded_addresses.is_empty() + })); + + let mut loaded = ManagedIdentity::new(bob.clone(), 0); + let key_fingerprint = loaded.private_scan_key_fingerprint(); + loaded.apply_private_contact_requests_position(PrivateContactRequestsPosition { + position: 5, + key_fingerprint, + private_payments_unresolved: false, + }); + loaded.apply_private_shielded_address(alice.id(), [0x55; 43]); + let mut start_state = IdentityManagerStartState::default(); + start_state + .wallet_identities + .entry(bob_wallet.wallet_id()) + .or_default() + .insert(0, loaded); + start_state.forget_private_contact_scan_state(); + let forgotten = &start_state.wallet_identities[&bob_wallet.wallet_id()][&0]; + assert_eq!(forgotten.dashpay().private_contact_requests_position(), 0); + assert_eq!( + forgotten.dashpay().private_shielded_address(&alice.id()), + None + ); + } + + /// A backend declaring the scan state without atomic changesets, which an + /// un-ignore's removal and rewind need to commit together, is treated as + /// keeping none of it: it gets none of the writes, a load drops the + /// position it restored, and a private payment, whose marker it could not + /// keep, is refused. + #[tokio::test] + async fn should_keep_no_scan_state_for_a_backend_without_atomic_changesets() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let persistence = RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE, + ); + let (_manager, bob_wallet) = wallet_on( + Arc::clone(&persistence), + BOB_PHRASE, + &bob, + &[&alice, &bob], + vec![entry], + ) + .await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store"); + view.ignore_contact_sender(&bob.id(), &alice.id()) + .await + .expect("ignored"); + view.unignore_contact_sender(&bob.id(), &alice.id()) + .await + .expect("un-ignored"); + assert!(persistence.contacts().iter().all(|changeset| { + changeset.private_contact_requests_positions.is_empty() + && changeset.private_shielded_addresses.is_empty() + })); + let refused = view + .send_private_contact_request( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + None, + &bob_signer, + &bob_crypto, + no_payment, + ) + .await; + assert!( + matches!( + refused, + Err(PlatformWalletError::PrivateContactRecoveryUnsupported) + ), + "{refused:?}" + ); + + // The un-ignore rewound the cursor: read on again, still storing nothing. + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store again"); + assert!(persistence + .contacts() + .iter() + .all(|changeset| changeset.private_contact_requests_positions.is_empty())); + let mut kept = scan_state_snapshot(&bob_wallet, &bob.id(), false).await; + kept.capabilities = PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE; + assert_eq!( + kept.identities[&0] + .dashpay() + .private_contact_requests_position(), + 1, + "the backend hands a position back" + ); + let manager = PlatformWalletManager::new( + Arc::new(dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await), + Arc::new(kept), + Arc::new(NoopEventHandler), + ); + manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + let reloaded = manager + .get_wallet(&bob_wallet.wallet_id()) + .await + .expect("the relaunched wallet"); + managed(&reloaded, BOB, |managed| { + assert_eq!( + managed.dashpay().private_contact_requests_position(), + 0, + "dropped" + ); + }) + .await; + } + + /// A hook a [`HookedCrypto`] runs before one of its calls. + type Hook = Arc std::pin::Pin + Send>> + Send + Sync>; + + /// A provider deriving from a test seed that runs hooks first: before + /// deriving a receiving xpub, as a slow or interactive signer pauses a + /// send's preparation, before scanning pages, and before scanning a + /// single page, as a restoration does. + struct HookedCrypto { + inner: SeedCryptoProvider, + before_receiving_xpub: Option, + before_scan: Option, + before_page_scan: Option, + } + + impl HookedCrypto { + fn new(phrase: &str) -> Self { + Self { + inner: SeedCryptoProvider::from_seed(seed(phrase), Network::Testnet), + before_receiving_xpub: None, + before_scan: None, + before_page_scan: None, + } + } + } + + #[async_trait::async_trait] + impl ContactCryptoProvider for HookedCrypto { + async fn receiving_xpub( + &self, + path: &DerivationPath, + ) -> Result { + if let Some(hook) = &self.before_receiving_xpub { + hook().await; + } + self.inner.receiving_xpub(path).await + } + + async fn ecdh_shared_secret( + &self, + path: &DerivationPath, + peer: &PublicKey, + ) -> Result, PlatformWalletError> { + self.inner.ecdh_shared_secret(path, peer).await + } + + async fn export_auto_accept_private_key( + &self, + path: &DerivationPath, + ) -> Result { + self.inner.export_auto_accept_private_key(path).await + } + + async fn account_reference( + &self, + path: &DerivationPath, + compact_xpub: &[u8], + account_index: u32, + version: u32, + ) -> Result { + self.inner + .account_reference(path, compact_xpub, account_index, version) + .await + } + + async fn unmask_account_reference( + &self, + path: &DerivationPath, + compact_xpub: &[u8], + account_reference: u32, + ) -> Result<(u32, u32), PlatformWalletError> { + self.inner + .unmask_account_reference(path, compact_xpub, account_reference) + .await + } + + async fn contact_info_seal( + &self, + root_path: &DerivationPath, + derivation_index: u32, + contact_id: &[u8; 32], + private_data_plaintext: &[u8], + private_data_iv: &[u8; 16], + ) -> Result + { + self.inner + .contact_info_seal( + root_path, + derivation_index, + contact_id, + private_data_plaintext, + private_data_iv, + ) + .await + } + + async fn contact_info_open( + &self, + root_path: &DerivationPath, + derivation_index: u32, + enc_to_user_id: &[u8; 32], + private_data_blob: &[u8], + ) -> Result + { + self.inner + .contact_info_open( + root_path, + derivation_index, + enc_to_user_id, + private_data_blob, + ) + .await + } + + async fn scan_private_document_page( + &self, + keys: &PrivateDocumentKeyPaths, + data_contract_id: Identifier, + document_type_name: &str, + start_position: u64, + page: &PrivateDocumentEntries, + ) -> Result { + if let Some(hook) = &self.before_page_scan { + hook().await; + } + self.inner + .scan_private_document_page( + keys, + data_contract_id, + document_type_name, + start_position, + page, + ) + .await + } + + async fn scan_private_document_pages( + &self, + keys: &PrivateDocumentKeyPaths, + data_contract_id: Identifier, + document_type_name: &str, + pages: &[(u64, &PrivateDocumentEntries)], + ) -> Result, PlatformWalletError> { + if let Some(hook) = &self.before_scan { + hook().await; + } + self.inner + .scan_private_document_pages(keys, data_contract_id, document_type_name, pages) + .await + } + + #[allow(clippy::too_many_arguments)] + async fn seal_private_contact_request( + &self, + sender_encryption_key_path: &DerivationPath, + dashpay_contract: &DataContract, + sender: &Identity, + sender_encryption_key_id: KeyID, + signing_key_id: KeyID, + signature: &[u8; 65], + recipient: &Identity, + recipient_key_id: KeyID, + request: &PrivateContactRequest, + esk_seed: &[u8; 32], + platform_version: &PlatformVersion, + ) -> Result { + self.inner + .seal_private_contact_request( + sender_encryption_key_path, + dashpay_contract, + sender, + sender_encryption_key_id, + signing_key_id, + signature, + recipient, + recipient_key_id, + request, + esk_seed, + platform_version, + ) + .await + } + } + + /// A hook that, the `call`th time it runs (from 1), says so on `reached` + /// and waits for `release`. + fn pause_on_call( + call: usize, + reached: Arc, + release: Arc, + ) -> Hook { + let runs = Arc::new(AtomicUsize::new(0)); + Arc::new(move || { + let (reached, release, runs) = ( + Arc::clone(&reached), + Arc::clone(&release), + Arc::clone(&runs), + ); + Box::pin(async move { + if runs.fetch_add(1, Ordering::SeqCst) + 1 == call { + reached.notify_one(); + release.notified().await; + } + }) + }) + } + + /// A public request that passed its channel check and is still being + /// prepared holds the pair: a private request started meanwhile is + /// refused before anything is paid, and only the public one goes on. + /// Once it ends, the pair is free again. + #[tokio::test] + async fn should_let_only_one_channel_send_to_a_pair_at_a_time() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = alice_wallet.identity().dashpay(); + let reached = Arc::new(tokio::sync::Notify::new()); + let release = Arc::new(tokio::sync::Notify::new()); + // The second derivation: the first checks the provider's seed before + // the store is read. + let mut pausing = HookedCrypto::new(ALICE_PHRASE); + pausing.before_receiving_xpub = + Some(pause_on_call(2, Arc::clone(&reached), Arc::clone(&release))); + let paid = Arc::new(Mutex::new(Vec::new())); + + let (alice_id, bob_id) = (alice.id(), bob.id()); + let public = view.send_contact_request_with_external_signer( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + &alice_signer, + &pausing, + ); + let private = async { + reached.notified().await; + let claimed = managed(&alice_wallet, ALICE, |managed| { + managed.dashpay().public_contact_request_claimed(&bob.id()) + }) + .await; + let sent = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&paid), + ) + .await; + release.notify_one(); + (claimed, sent) + }; + let (public, (claimed, private)) = tokio::join!(public, private); + assert!(claimed, "the paused public send holds the pair"); + assert!( + matches!(&private, Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if *recipient == bob.id()), + "{private:?}" + ); + assert!(paid.lock().expect("paid").is_empty(), "nothing is paid"); + assert!( + !matches!( + &public, + Err(PlatformWalletError::PrivateContactRequestPending(_) + | PlatformWalletError::PrivateContactRequestNeedsPrivateReply(_)) + ), + "the public send goes on to its submission, which this mock refuses: {public:?}" + ); + + assert!(!pending_to(&alice_wallet, ALICE, &bob).await); + managed(&alice_wallet, ALICE, |managed| { + assert!(!managed.dashpay().public_contact_request_claimed(&bob.id())); + }) + .await; + let kept = Arc::new(Mutex::new(Vec::new())); + let after = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&kept), + ) + .await; + assert!( + matches!( + after, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{after:?}" + ); + assert_eq!( + kept.lock().expect("kept").len(), + 1, + "the pair is free again" + ); + } + + /// `identity` without its key `key_id`, as a device that has not yet + /// fetched a key another device added holds it. + fn without_key(identity: &Identity, key_id: KeyID) -> Identity { + Identity::V0(IdentityV0 { + id: identity.id(), + public_keys: identity + .public_keys() + .iter() + .filter(|(id, _)| **id != key_id) + .map(|(id, key)| (*id, key.clone())) + .collect(), + balance: identity.balance(), + revision: identity.revision(), + }) + } + + /// A store read with keys missing one an entry is sealed to is read again + /// once a refresh brings the key: the refresh folds it in, the read + /// position and the read-to-the-end flag are rewound, and the next sync + /// records the request. + #[tokio::test] + async fn should_read_the_store_again_once_an_identity_gains_a_scanning_key() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &stale, &[&alice, &bob], vec![entry]).await; + let view = bob_wallet.identity().dashpay(); + + let report = view + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store with his older keys"); + assert_eq!( + report.requests, + vec![], + "the entry opens with no key he holds" + ); + assert!(store_read(&bob_wallet, BOB).await); + managed(&bob_wallet, BOB, |managed| { + assert_eq!(managed.dashpay().private_contact_requests_position(), 1); + }) + .await; + + bob_wallet + .identity() + .refresh_identity(&bob.id()) + .await + .expect("the refresh folds in the decryption key"); + view.reconcile_private_scan_keys() + .await + .expect("reconciled"); + assert!( + !store_read(&bob_wallet, BOB).await, + "a send reads the store again" + ); + managed(&bob_wallet, BOB, |managed| { + assert_eq!(managed.dashpay().private_contact_requests_position(), 0); + }) + .await; + + let report = view + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store again"); + assert_eq!(report.requests.len(), 1, "{:?}", report.requests); + managed(&bob_wallet, BOB, |managed| { + assert!(managed.dashpay().incoming_request(&alice.id()).is_some()); + }) + .await; + } + + /// A public request is decided with the keys Platform proves the sender + /// identity holds now: Bob read the store to its end with keys missing the + /// decryption key another device added, to which Alice's private request + /// is sealed. His public request to her fetches his identity, folds the + /// key in, reads the store again with it, finds her private request, and + /// is refused: a public one would publish the pair she kept private. + #[tokio::test] + async fn should_read_the_store_with_a_key_another_device_added_before_a_public_request() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &stale, &[&alice, &bob], vec![entry]).await; + let view = bob_wallet.identity().dashpay(); + let report = view + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store with his older keys"); + assert_eq!(report.requests, vec![], "nothing opens"); + assert!(store_read(&bob_wallet, BOB).await, "read to its end"); + + let public = view + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(sender)) + if sender == alice.id() + ), + "{public:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert!( + managed + .identity + .public_keys() + .contains_key(&DECRYPTION_KEY_ID), + "the key is folded in" + ); + assert!( + managed.dashpay().incoming_request(&alice.id()).is_some(), + "her private request is recorded" + ); + }) + .await; + } + + /// A public request is decided only once the sender identity is proved + /// at or above every store page the read rests on. Bob's store page, + /// proved at H, holds Alice's private request sealed to the decryption + /// key another device added at H; his cached identity lacks it. + /// + /// While every fetch of his identity is proved at H - 1, from a node a + /// block behind, without the key, each round's fetch stays below the page + /// and the request is refused with the SDK's stale node error, retryable, + /// with nothing sent. Once the fetch is proved at H, it brings the key, the + /// read is rewound, the next round reads the store again with it, finds + /// her request and refuses: a public one would publish the pair she kept + /// private. + #[tokio::test] + async fn should_decide_a_public_request_only_with_keys_proved_at_or_above_the_store_read() { + const H: u64 = 20; + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = + wallet(BOB_PHRASE, &stale, &[&alice, &stale], vec![entry]).await; + let mut sdk = (*bob_wallet.identity().sdk).clone(); + sdk.mock() + .set_response_height(H) + .set_response_height_of::(H - 1); + let view = bob_wallet.identity().dashpay(); + let (bob_id, alice_id) = (bob.id(), alice.id()); + let send = || { + view.send_contact_request_with_external_signer( + &bob_id, + &alice_id, + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + }; + + let behind = send().await; + assert!( + matches!( + &behind, + Err(PlatformWalletError::Sdk(dash_sdk::Error::StaleNode( + StaleNodeError::Height { + expected_height: H, + received_height, + .. + } + ))) if *received_height == H - 1 + ), + "{behind:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert!( + managed.dashpay().private_contact_requests_read(), + "read at H" + ); + assert!( + managed.dashpay().incoming_request(&alice.id()).is_none(), + "her request opens with no key he holds" + ); + assert!( + managed.dashpay().outgoing_request(&alice.id()).is_none(), + "nothing sent" + ); + }) + .await; + + // The identity is proved at H, with the key. + set_identity_known(&bob_wallet, &bob, true).await; + sdk.mock().set_response_height_of::(H); + let caught_up = send().await; + assert!( + matches!( + caught_up, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(sender)) + if sender == alice.id() + ), + "{caught_up:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert!(managed + .identity + .public_keys() + .contains_key(&DECRYPTION_KEY_ID)); + assert!( + managed.dashpay().incoming_request(&alice.id()).is_some(), + "her private request is recorded" + ); + }) + .await; + } + + /// A store page completed from two reads, the first from a node a block + /// behind, counts the higher one: Bob's page from 2 is read at H - 1 up to + /// that node's end, and completed at H with Alice's private request sealed + /// to the decryption key another device added at H. His identity proved at + /// H - 1, between the page's two heights, without the key, does not cover + /// the read: his public request is refused with the SDK's stale node error + /// against H. Once proved at H with the key, the store is read again, her + /// request is found, and the public request is refused. + #[tokio::test] + async fn should_cover_the_highest_read_of_a_completed_store_page_before_a_public_request() { + const H: u64 = 20; + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &stale, &[&alice, &stale], vec![]).await; + // Chunks of two: the page from 0, then the page from 2, read from a + // node whose store held 3 entries and completed from 3. + let filler = |byte: u8| vec![byte; 589]; + let page = |start: u64, entries: Vec>, total: u64| { + let mut page = store_page(start, entries); + page.chunk_power = Some(1); + page.total_count = total; + page + }; + let contract = dashpay_contract().expect("bundled DashPay"); + let query = |start| { + PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + start, + ) + }; + let mut sdk = (*bob_wallet.identity().sdk).clone(); + { + let mut mock = sdk.mock(); + for (start, page) in [ + (0, page(0, vec![filler(0xA0), filler(0xA1)], 4)), + (2, page(2, vec![filler(0xA2)], 3)), + (3, page(3, vec![entry], 4)), + (4, page(4, vec![], 4)), + ] { + mock.remove_fetch_expectation::(query(start)) + .await; + mock.expect_fetch(query(start), Some(page)) + .await + .expect("page expectation"); + } + mock.set_response_height(H - 1) + .set_response_height_for::(query(3), H) + .set_response_height_for::(query(4), H); + } + let view = bob_wallet.identity().dashpay(); + let (bob_id, alice_id) = (bob.id(), alice.id()); + let send = || { + view.send_contact_request_with_external_signer( + &bob_id, + &alice_id, + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + }; + + let between = send().await; + assert!( + matches!( + &between, + Err(PlatformWalletError::Sdk(dash_sdk::Error::StaleNode( + StaleNodeError::Height { + expected_height: H, + received_height, + .. + } + ))) if *received_height == H - 1 + ), + "{between:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert_eq!(managed.dashpay().private_store_read_height(), Some(H)); + assert!(managed.dashpay().incoming_request(&alice.id()).is_none()); + assert!( + managed.dashpay().outgoing_request(&alice.id()).is_none(), + "nothing sent" + ); + }) + .await; + + // The identity is proved at H, with the key. + set_identity_known(&bob_wallet, &bob, true).await; + sdk.mock().set_response_height_of::(H); + let covered = send().await; + assert!( + matches!( + covered, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(sender)) + if sender == alice.id() + ), + "{covered:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert!( + managed.dashpay().incoming_request(&alice.id()).is_some(), + "her private request is recorded" + ); + }) + .await; + } + + /// A read rewound by a key change counts as read to the end only once it + /// reaches the store already seen. Bob read the store at H with keys + /// missing the decryption key another device added, to which Alice's + /// request at position 1 is sealed. His public request brings the key and + /// rewinds the read; a node a block behind then answers the store from its + /// start holding only the entry before hers. That read does not count, so + /// the request is refused as not read, with nothing sent. Once the store is + /// read from the cursor at H, her request is found, and the public request + /// is refused. + #[tokio::test] + async fn should_not_count_a_rewound_read_from_behind_the_store_already_seen() { + const H: u64 = 20; + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &stale, &[&alice, &stale], vec![]).await; + let filler = vec![0xA0; 589]; + let page = |start: u64, entries: Vec>, total: u64| { + let mut page = store_page(start, entries); + page.total_count = total; + page + }; + let contract = dashpay_contract().expect("bundled DashPay"); + let query = |start| { + PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + start, + ) + }; + let sdk = (*bob_wallet.identity().sdk).clone(); + sdk.clone().mock().set_response_height(H); + let serve = |pages: Vec<(u64, PrivateDocumentEntries, u64)>| { + let mut sdk = sdk.clone(); + async move { + let mut mock = sdk.mock(); + for (start, page, height) in pages { + mock.remove_fetch_expectation::(query(start)) + .await; + mock.expect_fetch(query(start), Some(page)) + .await + .expect("page expectation"); + mock.set_response_height_for::(query(start), height); + } + } + }; + serve(vec![ + (0, page(0, vec![filler.clone(), entry.clone()], 2), H), + (2, page(2, vec![], 2), H), + ]) + .await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store at H with his older keys"); + assert!(store_read(&bob_wallet, BOB).await); + let (bob_id, alice_id) = (bob.id(), alice.id()); + let send = || { + view.send_contact_request_with_external_signer( + &bob_id, + &alice_id, + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + }; + + // The key reaches Bob's identity; a node a block behind answers. + set_identity_known(&bob_wallet, &bob, true).await; + serve(vec![ + (0, page(0, vec![filler.clone()], 1), H - 1), + (1, page(1, vec![], 1), H - 1), + ]) + .await; + let behind = send().await; + assert!( + matches!( + behind, + Err(PlatformWalletError::PrivateContactStoreNotRead(identity)) + if identity == bob.id() + ), + "{behind:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert!( + !managed.dashpay().private_contact_requests_read(), + "not counted" + ); + assert_eq!(managed.dashpay().private_store_read_height(), Some(H - 1)); + assert!(managed.dashpay().incoming_request(&alice.id()).is_none()); + assert!( + managed.dashpay().outgoing_request(&alice.id()).is_none(), + "nothing sent" + ); + }) + .await; + + // The store is read from the cursor at H. + serve(vec![(1, page(1, vec![entry], 2), H)]).await; + let caught_up = send().await; + assert!( + matches!( + caught_up, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(sender)) + if sender == alice.id() + ), + "{caught_up:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert!(managed.dashpay().private_contact_requests_read()); + assert!( + managed.dashpay().incoming_request(&alice.id()).is_some(), + "her private request is recorded" + ); + }) + .await; + } + + /// A public request, or a public acceptance, whose sender identity cannot + /// be fetched is refused as the SDK reported the fetch, before the store is + /// read again or anything is signed: the keys a read would scan with are + /// not shown current. + #[tokio::test] + async fn should_refuse_a_public_request_when_its_sender_identity_does_not_fetch() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &stale, &[&alice, &bob], vec![entry]).await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store with his older keys"); + set_identity_known(&bob_wallet, &bob, false).await; + + let public = view + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + // Refused by the identity fetch itself, not a step further on: the + // mock names the request it has no answer for. + let fetch_failed = |error: Option<&PlatformWalletError>| { + matches!(error, Some(PlatformWalletError::Sdk(error)) + if format!("{error:?}").contains("GetIdentityRequest")) + }; + assert!(fetch_failed(public.as_ref().err()), "{public:?}"); + let incoming = public_request(&alice, &bob, 3); + add_incoming(&bob_wallet, BOB, &incoming).await; + let accepted = view + .accept_contact_request_with_external_signer(&incoming, &bob_signer, &bob_crypto) + .await; + assert!(fetch_failed(accepted.as_ref().err()), "{accepted:?}"); + managed(&bob_wallet, BOB, |managed| { + assert!(!managed + .identity + .public_keys() + .contains_key(&DECRYPTION_KEY_ID)); + assert!( + managed.dashpay().outgoing_request(&alice.id()).is_none(), + "nothing sent" + ); + assert!(!managed.dashpay().private_reply_pending(&alice.id())); + }) + .await; + } + + /// A public request reads the store from its cursor every time, not once + /// per load: Bob read the store while it was empty, and Alice's private + /// request landed afterwards. His next public request to her reads it and + /// is refused, as a public one would publish the pair she kept private, + /// with no restart in between. + #[tokio::test] + async fn should_read_an_entry_landed_since_the_last_read_before_a_public_request() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the empty store"); + assert!(store_read(&bob_wallet, BOB).await); + + publish(&bob_wallet, 0, vec![entry]).await; + let public = view + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(sender)) + if sender == alice.id() + ), + "{public:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert!(managed.dashpay().incoming_request(&alice.id()).is_some()); + assert!( + managed.dashpay().outgoing_request(&alice.id()).is_none(), + "nothing sent" + ); + }) + .await; + } + + /// `wallet`'s mock answers the store as `chunks` of two entries each, + /// every page showing `total` entries and the chunk size, the page from + /// each start proved at the height given with it. + async fn serve_chunks(wallet: &PlatformWallet, total: u64, chunks: &[(u64, u64)]) { + let contract = dashpay_contract().expect("bundled DashPay"); + let mut sdk = (*wallet.identity().sdk).clone(); + let mut mock = sdk.mock(); + for (start, height) in chunks { + let query = PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + *start, + ); + let mut page = store_page(*start, vec![vec![0xA0 + *start as u8; 589]; 2]); + page.chunk_power = Some(1); + page.total_count = total; + mock.remove_fetch_expectation::(query.clone()) + .await; + mock.expect_fetch(query.clone(), Some(page)) + .await + .expect("page expectation"); + mock.set_response_height_for::(query, *height); + } + } + + /// A read rewound to its start counts as read to the end only when the + /// page that reaches the end was proved at or above the floor, whatever + /// the pages before it: after a rewind with floor H, a walk whose first + /// and last pages come from a node at H - 1 and whose middle page comes + /// from H does not set the read, though its highest page is at H. + #[tokio::test] + async fn should_count_a_rewound_read_by_the_height_of_the_page_reaching_the_end() { + const H: u64 = 20; + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &stale, &[&alice, &bob], vec![]).await; + (*bob_wallet.identity().sdk) + .clone() + .mock() + .set_response_height(H); + serve_chunks(&bob_wallet, 6, &[(0, H), (2, H), (4, H)]).await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 16) + .await + .expect("Bob reads the store at H with his older keys"); + assert!(store_read(&bob_wallet, BOB).await); + + // His key reaches the cache: the read is rewound, H its floor. + bob_wallet + .identity() + .refresh_identity(&bob.id()) + .await + .expect("the refresh folds in the key"); + view.reconcile_private_scan_keys() + .await + .expect("reconciled"); + assert!(!store_read(&bob_wallet, BOB).await, "rewound"); + + serve_chunks(&bob_wallet, 6, &[(0, H - 1), (2, H), (4, H - 1)]).await; + let report = view + .sync_private_contact_requests(&bob_crypto, 16) + .await + .expect("the read from 0"); + assert_eq!(report.next_position, 6, "the walk reached the end"); + managed(&bob_wallet, BOB, |managed| { + assert_eq!(managed.dashpay().private_store_read_height(), Some(H)); + assert!( + !managed.dashpay().private_contact_requests_read(), + "its end came from below the floor" + ); + }) + .await; + assert!(!report.read_to_end.contains(&bob.id())); + } + + /// A pass reaches the store's end only at the highest size a page of it + /// showed: after a first page showing six entries, a full chunk from a + /// node behind, its store ending at that chunk's end, leaves the pass + /// incomplete and the store not read to its end. + #[tokio::test] + async fn should_not_end_a_pass_at_a_later_page_from_a_node_behind() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + serve_chunks(&bob_wallet, 6, &[(0, 0)]).await; + serve_chunks(&bob_wallet, 4, &[(2, 0)]).await; + let report = bob_wallet + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 2) + .await + .expect("two pages"); + assert_eq!(report.next_position, 4); + assert!(!report.complete, "not at the end the first page showed"); + assert!(!store_read(&bob_wallet, BOB).await); + } + + /// A private accept is decided with the keys Platform proves the identity + /// holds now, as a public one is: Bob's other device replied privately to + /// Alice under the encryption key this device has not folded in, which + /// alone recovers the reply from the store. This device's private accept + /// fetches Bob's identity, folds the key in, reads the store again, + /// recovers the reply and adopts it, paying nothing. + #[tokio::test] + async fn should_adopt_a_reply_sealed_under_a_key_another_device_added() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (request, received) = alice_to_bob([0x55; 43]).await; + + // Bob's other device, holding every key, replies privately. + let (_other_manager, other) = + wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![request.clone()]).await; + other + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("the other device reads Alice's request"); + let reply = Arc::new(Mutex::new(Vec::new())); + let replied = other + .identity() + .dashpay() + .accept_private_contact_request( + &received, + None, + &bob_signer, + &bob_crypto, + keep_entry(&reply), + ) + .await; + assert!( + matches!( + replied, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {replied:?}" + ); + let reply = reply.lock().expect("reply").remove(0).to_vec(); + + // This device lacks the encryption key the reply was sealed under. + let stale = without_key(&bob, ENCRYPTION_KEY_ID); + let (_manager, bob_wallet) = + wallet(BOB_PHRASE, &stale, &[&alice, &bob], vec![request, reply]).await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("this device reads the store with its older keys"); + managed(&bob_wallet, BOB, |managed| { + assert!(managed.dashpay().incoming_request(&alice.id()).is_some()); + assert!( + managed.dashpay().outgoing_request(&alice.id()).is_none(), + "the reply does not open with its keys" + ); + }) + .await; + + let adopted = view + .accept_private_contact_request(&received, None, &bob_signer, &bob_crypto, no_payment) + .await + .expect("the reply is adopted"); + assert_eq!(adopted.contact_identity_id, alice.id()); + managed(&bob_wallet, BOB, |managed| { + assert!(managed + .identity + .public_keys() + .contains_key(&ENCRYPTION_KEY_ID)); + assert!(managed.dashpay().outgoing_request(&alice.id()).is_some()); + }) + .await; + } + + /// A pass whose provider resolves another wallet's seed, valid but + /// deriving unrelated keys that open nothing, is refused with nothing + /// read or recorded; the pass with the wallet's own seed then reads the + /// request the refused one would have passed over. + #[tokio::test] + async fn should_refuse_a_pass_with_another_seed_and_leave_its_position_unmoved() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![entry]).await; + let view = bob_wallet.identity().dashpay(); + + let another_seed = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let refused = view.sync_private_contact_requests(&another_seed, 4).await; + assert!( + matches!(refused, Err(PlatformWalletError::SeedMismatch { .. })), + "{refused:?}" + ); + managed(&bob_wallet, BOB, |managed| { + assert_eq!( + managed.dashpay().private_contact_requests_position(), + 0, + "nothing recorded as read" + ); + assert!(!managed.dashpay().private_contact_requests_read()); + assert!(managed.dashpay().incoming_request(&alice.id()).is_none()); + }) + .await; + + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("the pass with Bob's seed"); + managed(&bob_wallet, BOB, |managed| { + assert!(managed.dashpay().incoming_request(&alice.id()).is_some()); + assert_eq!(managed.dashpay().private_contact_requests_position(), 1); + }) + .await; + } + + /// A pass that started with older keys commits no progress once a key + /// update lands under it, even when the rewind that update brings is + /// taken while the pass runs: the next pass reads with the new keys from + /// where the update left the position. + #[tokio::test] + async fn should_not_advance_over_a_key_update_during_a_pass() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &stale, &[&alice, &bob], vec![entry]).await; + + let mut updating = HookedCrypto::new(BOB_PHRASE); + updating.before_scan = Some({ + let bob_wallet = Arc::clone(&bob_wallet); + let bob = bob.clone(); + Arc::new(move || { + let (bob_wallet, bob) = (Arc::clone(&bob_wallet), bob.clone()); + Box::pin(async move { + let iw = bob_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let managed = wm + .get_wallet_info_mut(&bob_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&bob.id()) + .expect("Bob"); + // A refresh's key, and a read before a send rewinding for it. + managed.identity = bob; + managed.reconcile_private_scan_keys(); + }) + }) + }); + bob_wallet + .identity() + .dashpay() + .sync_private_contact_requests(&updating, 4) + .await + .expect("the pass with older keys"); + managed(&bob_wallet, BOB, |managed| { + assert_eq!( + managed.dashpay().private_contact_requests_position(), + 0, + "no progress over the update" + ); + assert!(!managed.dashpay().private_contact_requests_read()); + assert!(managed.dashpay().incoming_request(&alice.id()).is_none()); + }) + .await; + + bob_wallet + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("the pass with the new keys"); + managed(&bob_wallet, BOB, |managed| { + assert!(managed.dashpay().incoming_request(&alice.id()).is_some()); + assert_eq!(managed.dashpay().private_contact_requests_position(), 1); + }) + .await; + } + + /// A pass whose keys changed under it raises nothing its read rests on. + /// Bob read the store at H with keys missing the decryption key another + /// device added, to which Alice's request at position 1 is sealed. A pass + /// started with those keys is overtaken by the key update, which rewinds + /// his read and keeps H as its floor; its page counts for nothing. So a + /// read with the new keys from a node a block behind, which holds only + /// the entry before hers, does not count as read to the end. + #[tokio::test] + async fn should_not_let_a_pass_with_replaced_keys_raise_the_read_height() { + const H: u64 = 20; + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let stale = without_key(&bob, DECRYPTION_KEY_ID); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &stale, &[&alice, &bob], vec![]).await; + let filler = vec![0xA0; 589]; + let page = |start: u64, entries: Vec>, total: u64| { + let mut page = store_page(start, entries); + page.total_count = total; + page + }; + let contract = dashpay_contract().expect("bundled DashPay"); + let query = |start| { + PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + start, + ) + }; + let sdk = (*bob_wallet.identity().sdk).clone(); + sdk.clone().mock().set_response_height(H); + let serve = |pages: Vec<(u64, PrivateDocumentEntries, u64)>| { + let mut sdk = sdk.clone(); + async move { + let mut mock = sdk.mock(); + for (start, page, height) in pages { + mock.remove_fetch_expectation::(query(start)) + .await; + mock.expect_fetch(query(start), Some(page)) + .await + .expect("page expectation"); + mock.set_response_height_for::(query(start), height); + } + } + }; + serve(vec![ + (0, page(0, vec![filler.clone(), entry], 2), H), + (2, page(2, vec![], 2), H), + ]) + .await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store at H with his older keys"); + assert!(store_read(&bob_wallet, BOB).await); + + // A pass from his cursor, overtaken by the key update before it scans. + let mut updating = HookedCrypto::new(BOB_PHRASE); + updating.before_scan = Some({ + let bob_wallet = Arc::clone(&bob_wallet); + let bob = bob.clone(); + Arc::new(move || { + let (bob_wallet, bob) = (Arc::clone(&bob_wallet), bob.clone()); + Box::pin(async move { + let iw = bob_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let managed = wm + .get_wallet_info_mut(&bob_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&bob.id()) + .expect("Bob"); + managed.identity = bob; + managed.reconcile_private_scan_keys(); + }) + }) + }); + view.sync_private_contact_requests(&updating, 4) + .await + .expect("the pass with the older keys"); + managed(&bob_wallet, BOB, |managed| { + assert!( + !managed.dashpay().private_contact_requests_read(), + "rewound" + ); + assert_eq!( + managed.dashpay().private_store_read_height(), + None, + "its page counts for nothing" + ); + }) + .await; + + // A read with the new keys, from a node a block behind. + serve(vec![ + (0, page(0, vec![filler], 1), H - 1), + (1, page(1, vec![], 1), H - 1), + ]) + .await; + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("the read from behind"); + managed(&bob_wallet, BOB, |managed| { + assert_eq!(managed.dashpay().private_store_read_height(), Some(H - 1)); + assert!( + !managed.dashpay().private_contact_requests_read(), + "not read to the end of the store already seen" + ); + assert!(managed.dashpay().incoming_request(&alice.id()).is_none()); + }) + .await; + } + + /// A reply dropped while its payment source is still being resolved, as + /// a host's prompt left open and abandoned, keeps no reservation: + /// nothing was paid, and a retry goes on to pay. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_release_a_reply_dropped_while_its_payment_is_resolved() { + use crate::wallet::platform_wallet::PrivateReplyPayment; + + struct NoProver; + impl dpp::shielded::builder::OrchardProver for NoProver { + fn proving_key(&self) -> &grovedb_commitment_tree::ProvingKey { + panic!("nothing is proved") + } + } + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, received) = alice_to_bob([0x55; 43]).await; + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![entry]).await; + bob_wallet + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store"); + + let dropped = tokio::time::timeout( + Duration::from_millis(200), + bob_wallet.accept_contact_request_replying_in_kind( + &received, + None, + &bob_signer, + &bob_crypto, + || { + std::future::pending::< + Result>, PlatformWalletError>, + >() + }, + ), + ) + .await; + assert!(dropped.is_err(), "the payment source never resolves"); + assert!(!pending_to(&bob_wallet, BOB, &alice).await); + + let reply = Arc::new(Mutex::new(Vec::new())); + let retried = bob_wallet + .identity() + .dashpay() + .accept_private_contact_request( + &received, + None, + &bob_signer, + &bob_crypto, + keep_entry(&reply), + ) + .await; + assert!( + matches!( + retried, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {retried:?}" + ); + assert_eq!(reply.lock().expect("reply").len(), 1, "the retry pays"); + } + + /// An endpoint that kept the submitted payment and answered with a + /// consensus verdict proves nothing, so the payment settles unconfirmed + /// with its journal record saved: a public request to the pair, which + /// would disclose it, and a replacement private payment, which would fund + /// a second request, are both refused while the original may execute. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_keep_a_pair_held_when_an_endpoint_refuses_its_payment() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let dir = tempfile::tempdir().expect("temporary shielded store"); + let store = Arc::new(tokio::sync::RwLock::new( + FileBackedShieldedStore::open_path(dir.path().join("tree.sqlite"), 100) + .expect("the store"), + )); + let subwallet = SubwalletId::new(alice_wallet.wallet_id(), 0); + let pay = { + let store = Arc::clone(&store); + let (sender, recipient) = (alice.id(), bob.id()); + move |entry: BinaryData, started: PaymentStarted| async move { + let transition = private_contact_request_payment(entry); + arm_redrive_before_broadcast( + &store, + subwallet, + Some([0x7A; 32]), + [7; 32], + vec![[1; 32]], + &transition, + "private document create from shielded pool", + Some(PrivateContactPayment { + sender: sender.to_buffer(), + recipient: recipient.to_buffer(), + account_reference: started + .account_reference() + .expect("the send names its request"), + }), + Some(&started), + 0, + ) + .await?; + // What the payment returns once the endpoint answered with a + // serialized consensus verdict: unconfirmed. + Err::(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create from shielded pool", + reason: "the endpoint answered with a consensus verdict".to_string(), + }) + } + }; + let view = alice_wallet.identity().dashpay(); + let sent = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + pay, + ) + .await; + assert!( + matches!( + sent, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{sent:?}" + ); + assert_eq!( + store + .read() + .await + .private_payment_journal(alice_wallet.wallet_id()) + .expect("the journal") + .len(), + 1, + "the journal record stays" + ); + let public = view + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "no disclosure: {public:?}" + ); + let replacement = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + no_payment, + ) + .await; + assert!( + matches!( + replacement, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "no replacement funding: {replacement:?}" + ); + } + + /// A restoration that read a payment's journal record before the record + /// was discharged and its reservation released, as a never-delivered + /// payment does, and applies only after, does not reserve the pair again: + /// no entry would ever settle that reservation. A retry to the pair pays. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_not_restore_a_payment_discharged_while_the_restore_waited() { + use std::future::Future; + use std::task::{Context, Waker}; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let dir = tempfile::tempdir().expect("temporary shielded store"); + let db_path = dir.path().join("tree.sqlite"); + let coordinator = Arc::new(NetworkShieldedCoordinator::new( + Arc::new(dash_sdk::Sdk::new_mock()), + Network::Testnet, + db_path.clone(), + FileBackedShieldedStore::open_path(&db_path, 100).expect("the store"), + )); + let subwallet = SubwalletId::new(alice_wallet.wallet_id(), 0); + let paid = Arc::new(Mutex::new(Vec::new())); + let pay = { + let store = Arc::clone(coordinator.store()); + let paid = Arc::clone(&paid); + let (sender, recipient) = (alice.id(), bob.id()); + move |entry: BinaryData, started: PaymentStarted| async move { + paid.lock().expect("paid").push(entry.clone()); + let transition = private_contact_request_payment(entry); + arm_redrive_before_broadcast( + &store, + subwallet, + Some([0x7B; 32]), + [7; 32], + vec![[1; 32]], + &transition, + "private document create from shielded pool", + Some(PrivateContactPayment { + sender: sender.to_buffer(), + recipient: recipient.to_buffer(), + account_reference: started + .account_reference() + .expect("the send names its request"), + }), + Some(&started), + 0, + ) + .await?; + Err::(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create from shielded pool", + reason: "the result wait timed out".to_string(), + }) + } + }; + let view = alice_wallet.identity().dashpay(); + let sent = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + pay, + ) + .await; + assert!( + matches!( + sent, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{sent:?}" + ); + let commitment: [u8; 32] = paid.lock().expect("paid")[0].as_slice()[..32] + .try_into() + .expect("an entry starts with its commitment"); + + let mut cx = Context::from_waker(Waker::noop()); + let held_store = coordinator.store().write().await; + let mut restore = Box::pin(alice_wallet.restore_private_contact_payments(&coordinator)); + assert!( + restore.as_mut().poll(&mut cx).is_pending(), + "waits for the store" + ); + let mut held_wallet = alice_wallet.wallet_manager().write().await; + drop(held_store); + // The restoration reads its journal snapshot, then waits for the wallet. + assert!( + restore.as_mut().poll(&mut cx).is_pending(), + "waits for the wallet" + ); + // Meanwhile the record is discharged and the reservation released. + coordinator + .store() + .write() + .await + .discharge_private_payment(alice_wallet.wallet_id(), &commitment) + .expect("discharged"); + alice_wallet + .persister() + .note_discharged_private_entries([commitment]); + held_wallet + .get_wallet_info_mut(&alice_wallet.wallet_id()) + .expect("the wallet") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("alice") + .release_discharged_private_replies(&BTreeSet::from([commitment])); + drop(held_wallet); + restore.await.expect("the restoration"); + assert!( + !pending_to(&alice_wallet, ALICE, &bob).await, + "not reserved again" + ); + + let retry = Arc::new(Mutex::new(Vec::new())); + let retried = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&retry), + ) + .await; + assert!( + matches!( + retried, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {retried:?}" + ); + assert_eq!(retry.lock().expect("retry").len(), 1, "the retry pays"); + } + + /// The legacy restoration from the redrive records + /// (`PlatformWallet::restore_pending_private_contact_requests`) that read + /// a payment's transition before its journal record was discharged, and + /// the discharge notice taken and its reservation released while it + /// waited to open the entry, does not reserve the pair again: it reserves + /// through the journal restoration's step, which checks the discharge + /// under the wallet lock. A retry to the pair pays. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_not_restore_from_a_redrive_a_payment_discharged_while_the_restore_waited() { + use std::future::Future; + use std::task::{Context, Waker}; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let fixture = ExpiryFixture::new().await; + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + let commitment: [u8; 32] = entry.as_slice()[..32] + .try_into() + .expect("an entry starts with its commitment"); + let wallet = &fixture.wallet; + + let mut cx = Context::from_waker(Waker::noop()); + let held_store = fixture.coordinator.store().write().await; + let mut restore = Box::pin( + wallet.restore_pending_private_contact_requests(&fixture.coordinator, &alice_crypto), + ); + assert!( + restore.as_mut().poll(&mut cx).is_pending(), + "waits for the store" + ); + let mut held_wallet = wallet.wallet_manager().write().await; + drop(held_store); + // The restoration reads the redrive records, then waits for the + // wallet before it opens the entry. + assert!( + restore.as_mut().poll(&mut cx).is_pending(), + "waits for the wallet" + ); + // Meanwhile the record is discharged, and the wallet takes the + // discharge notice and releases the reservation. + fixture + .coordinator + .store() + .write() + .await + .discharge_private_payment(wallet.wallet_id(), &commitment) + .expect("discharged"); + wallet + .persister() + .note_discharged_private_entries([commitment]); + let taken = wallet + .persister() + .take_unreleased_discharged_private_entries(); + assert_eq!(taken, BTreeSet::from([commitment]), "the notice is taken"); + held_wallet + .get_wallet_info_mut(&wallet.wallet_id()) + .expect("the wallet") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("alice") + .release_discharged_private_replies(&taken); + drop(held_wallet); + let restored = restore.await.expect("the restoration"); + assert!(restored.is_empty(), "{restored:?}"); + assert!(!pending_to(wallet, ALICE, &bob).await, "not reserved again"); + + let retry = Arc::new(Mutex::new(Vec::new())); + let retried = fixture.send_again(keep_entry(&retry)).await; + assert!( + matches!( + retried, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {retried:?}" + ); + assert_eq!(retry.lock().expect("retry").len(), 1, "the retry pays"); + } + + /// The check a private send makes right before it pays, over the journal + /// it read, does not hold the pair for a payment whose record was + /// discharged since: it reserves through the restorations' step. One + /// still journaled holds it. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_not_hold_a_pair_for_a_journaled_payment_discharged_since_the_read() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + for discharged in [true, false] { + let (_manager, alice_wallet) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let commitment = [0x5D; 32]; + if discharged { + alice_wallet + .persister() + .note_discharged_private_entries([commitment]); + } + let held = alice_wallet + .identity() + .dashpay() + .hold_for_journaled_private_payment(&alice.id(), &bob.id(), &[(0, commitment)]) + .await + .expect("the check"); + assert_eq!(held, !discharged, "discharged: {discharged}"); + assert_eq!( + pending_to(&alice_wallet, ALICE, &bob).await, + !discharged, + "discharged: {discharged}" + ); + } + } + + /// A restoration of a private payment's reservation through a handle + /// whose wallet was removed and re-created under its id reserves nothing + /// on the replacement: the step every restoration takes is fenced to the + /// handle's wallet generation. The replacement's own handle restores it. + #[tokio::test] + async fn should_not_restore_through_a_handle_whose_wallet_was_replaced() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (manager, old) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let wallet_id = old.wallet_id(); + let kept = Arc::new(Mutex::new(Vec::new())); + let sent = old + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&kept), + ) + .await; + assert!( + matches!( + sent, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {sent:?}" + ); + let entry = kept.lock().expect("kept")[0].clone(); + + manager.remove_wallet(&wallet_id).await.expect("removed"); + let replacement = manager + .create_wallet_from_seed_bytes( + Network::Testnet, + &seed(ALICE_PHRASE), + WalletAccountCreationOptions::Default, + Some(0), + ) + .await + .expect("re-created"); + assert_eq!(replacement.wallet_id(), wallet_id); + { + let iw = replacement.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet_id) + .expect("the replacement's info") + .identity_manager + .add_identity(alice.clone(), 0, wallet_id, &iw.persister) + .expect("alice"); + } + let stale = old + .identity() + .dashpay() + .restore_pending_private_contact_requests(std::slice::from_ref(&entry), &alice_crypto) + .await; + assert!( + matches!(stale, Err(PlatformWalletError::WalletNotFound(_))), + "{stale:?}" + ); + managed(&replacement, ALICE, |managed| { + assert!(!managed.dashpay().private_reply_pending(&bob.id())); + }) + .await; + let restored = replacement + .identity() + .dashpay() + .restore_pending_private_contact_requests(&[entry], &alice_crypto) + .await + .expect("restored"); + assert_eq!(restored, vec![(alice.id(), bob.id())]); + } + + /// Alice's wallet, bound to a coordinator over a new store, holding one + /// unspent input note: the private payment expiry tests pay from it. + #[cfg(feature = "shielded")] + struct ExpiryFixture { + _manager: PlatformWalletManager, + persistence: Arc, + wallet: Arc, + coordinator: Arc, + subwallet: SubwalletId, + input: ShieldedNote, + db_path: std::path::PathBuf, + _dir: tempfile::TempDir, + } + + #[cfg(feature = "shielded")] + impl ExpiryFixture { + /// The proved height of the anchor set the expiry tests judge by. + const ANCHOR_SET_HEIGHT: u64 = 10; + /// The anchor the payment's record names. + const ANCHOR: [u8; 32] = [0x7C; 32]; + + async fn new() -> Self { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + // A backend that keeps the viewing key, so the wallet binds. + let persistence = RecordingPersistence::attesting( + PersistenceCapabilities::SHIELDED_FVK_RESTART + .union(PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART), + ); + let (manager, wallet) = wallet_on( + Arc::clone(&persistence), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + let dir = tempfile::tempdir().expect("temporary shielded store"); + let db_path = dir.path().join("tree.sqlite"); + let coordinator = Arc::new(NetworkShieldedCoordinator::new( + Arc::clone(&wallet.identity().sdk), + Network::Testnet, + db_path.clone(), + FileBackedShieldedStore::open_path(&db_path, 100).expect("the store"), + )); + // Bound, the coordinator holds the wallet's persister, on which it + // notes the discharge. + wallet + .bind_shielded(&seed(ALICE_PHRASE), &[0], &coordinator) + .await + .expect("bound"); + let subwallet = SubwalletId::new(wallet.wallet_id(), 0); + let input = ShieldedNote { + position: 0, + cmx: [0x11; 32], + nullifier: [0x12; 32], + block_height: 1, + is_spent: false, + value: 1_000_000_000_000, + note_data: vec![], + }; + coordinator + .store() + .write() + .await + .save_note(subwallet, &input) + .expect("the input note"); + Self { + _manager: manager, + persistence, + wallet, + coordinator, + subwallet, + input, + db_path, + _dir: dir, + } + } + + /// Every response the mock answers is proved at `height`. + fn prove_at(&self, height: u64) { + let mut sdk = (*self.wallet.identity().sdk).clone(); + sdk.mock().set_response_height(height); + } + + /// Send a private request from Alice to Bob whose payment, spending + /// the input note against `anchor` read from a proof at + /// `anchor_height`, is journaled and times out unconfirmed. Returns + /// the entry paid for. + async fn pay_unconfirmed(&self, anchor: [u8; 32], anchor_height: u64) -> BinaryData { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let paid = Arc::new(Mutex::new(Vec::new())); + let pay = { + let store = Arc::clone(self.coordinator.store()); + let paid = Arc::clone(&paid); + let subwallet = self.subwallet; + let nullifier = self.input.nullifier; + let (sender, recipient) = (alice.id(), bob.id()); + move |entry: BinaryData, started: PaymentStarted| async move { + paid.lock().expect("paid").push(entry.clone()); + let transition = private_contact_request_payment(entry); + arm_redrive_before_broadcast( + &store, + subwallet, + Some([0x7D; 32]), + anchor, + vec![nullifier], + &transition, + "private document create from shielded pool", + Some(PrivateContactPayment { + sender: sender.to_buffer(), + recipient: recipient.to_buffer(), + account_reference: started + .account_reference() + .expect("the send names its request"), + }), + Some(&started), + anchor_height, + ) + .await?; + Err::(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create from shielded pool", + reason: "the result wait timed out".to_string(), + }) + } + }; + let sent = self + .wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + pay, + ) + .await; + assert!( + matches!( + sent, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{sent:?}" + ); + let entry = paid.lock().expect("paid")[0].clone(); + entry + } + + /// The journal records a pass reads before it fetches the anchor set. + async fn journal_snapshot( + &self, + ) -> Vec<(WalletId, crate::wallet::shielded::PrivatePaymentRecord)> { + private_payment_journal_snapshot( + &*self.coordinator.store().read().await, + [self.wallet.wallet_id()], + ) + } + + /// The discharge a pass runs after a note scan covering + /// `scan_covered_height`, against `journal` and the anchor set + /// `recorded` proved at [`Self::ANCHOR_SET_HEIGHT`]. + async fn discharge( + &self, + journal: &[(WalletId, crate::wallet::shielded::PrivatePaymentRecord)], + recorded: &HashSet<[u8; 32]>, + scan_covered_height: Option, + ) { + self.coordinator + .discharge_expired_private_payments( + journal, + PrunedAnchorEvidence { + recorded, + height: Self::ANCHOR_SET_HEIGHT, + scan_covered_height, + heightless: None, + }, + ) + .await; + } + + /// How many records the wallet's journal holds. + async fn journaled(&self) -> usize { + self.coordinator + .store() + .read() + .await + .private_payment_journal(self.wallet.wallet_id()) + .expect("the journal") + .len() + } + + /// Send Alice's request to Bob again with `pay`. + async fn send_again(&self, pay: F) -> Result + where + F: FnOnce(BinaryData, PaymentStarted) -> Fut + Send, + Fut: Future> + Send, + { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + self.wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + pay, + ) + .await + } + + /// The record stays and the pair it holds stays held. + async fn assert_kept(&self, case: &str) { + assert_eq!(self.journaled().await, 1, "{case}: the record stays"); + let held = self.send_again(no_payment).await; + assert!( + matches!( + held, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{case}: {held:?}" + ); + } + + /// The record is discharged, durably, and a retry to the pair pays. + async fn assert_discharged(&self, case: &str) { + assert_eq!(self.journaled().await, 0, "{case}: discharged"); + let retry = Arc::new(Mutex::new(Vec::new())); + let retried = self.send_again(keep_entry(&retry)).await; + assert!( + matches!( + retried, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{case}: paid, not read back: {retried:?}" + ); + assert_eq!( + retry.lock().expect("retry").len(), + 1, + "{case}: the retry pays" + ); + let reopened = + FileBackedShieldedStore::open_path(&self.db_path, 100).expect("reopened"); + assert!( + reopened + .private_payment_journal(self.wallet.wallet_id()) + .expect("the journal") + .is_empty(), + "{case}: the reopened store keeps the discharge" + ); + } + } + + /// A private payment refused before anything was delivered is retired, + /// its record and journal records with it, and the retirement is published + /// before the settlement waits for the store to record its activity. So a + /// send cancelled during that wait still leaves its pair free: a retry to + /// the pair pays, with no restart. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_free_a_pair_whose_undelivered_settlement_was_cancelled_after_retirement() { + use crate::wallet::shielded::{ + ShieldedActivityEntry, ShieldedActivityKind, ShieldedActivityStatus, ShieldedDirection, + }; + use std::future::Future; + use std::task::{Context, Waker}; + + let fixture = ExpiryFixture::new().await; + let pay = { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let store = Arc::clone(fixture.coordinator.store()); + let persister = fixture.wallet.persister().clone(); + let wallet_id = fixture.wallet.wallet_id(); + let subwallet = fixture.subwallet; + let input = fixture.input.clone(); + move |entry: BinaryData, started: PaymentStarted| async move { + let account_reference = started + .account_reference() + .expect("the send names its request"); + pay_private_document_with_outcome( + &store, + Some(&persister), + wallet_id, + subwallet, + &[input], + ShieldedActivityEntry { + id: [0x7D; 32], + kind: ShieldedActivityKind::ShieldedSpend, + direction: ShieldedDirection::Out, + amount: 0, + fee: Some(0), + counterparty: None, + memo: None, + block_height: None, + status: ShieldedActivityStatus::Pending, + created_at_ms: 1, + min_note_position: None, + note_cmxs: vec![], + spent_nullifiers: vec![], + }, + private_contact_request_payment(entry), + PrivateContactPayment { + sender: alice.id().to_buffer(), + recipient: bob.id().to_buffer(), + account_reference, + }, + &started, + TestBroadcastOutcome::RefusedBeforeDelivery, + ) + .await + } + }; + let wallet_id = fixture.wallet.wallet_id(); + let store = fixture.coordinator.store(); + let mut cx = Context::from_waker(Waker::noop()); + let mut send = Box::pin(fixture.send_again(pay)); + // Step the send one store section at a time: each turn a write of the + // test's own is queued behind the send's, so the send runs one + // section and then waits behind it. Stop once the payment was + // journaled and then retired: the send then waits to record its + // activity. + let mut held = store.write().await; + let mut journaled = false; + let mut retired = false; + for _ in 0..64 { + let records = held + .private_payment_journal(wallet_id) + .expect("journal") + .len(); + journaled |= records > 0; + if journaled && records == 0 { + retired = true; + break; + } + let mut next = Box::pin(store.write()); + assert!( + send.as_mut().poll(&mut cx).is_pending(), + "the send waits for the store" + ); + assert!(next.as_mut().poll(&mut cx).is_pending()); + drop(held); + assert!( + send.as_mut().poll(&mut cx).is_pending(), + "the send waits behind the test's write" + ); + held = match next.as_mut().poll(&mut cx) { + std::task::Poll::Ready(guard) => guard, + std::task::Poll::Pending => panic!("the test's write is next"), + }; + } + assert!(retired, "the payment was journaled, then retired"); + assert_eq!( + held.get_activity_by_entry_id(fixture.subwallet, &[0x7D; 32]) + .expect("activity") + .map(|entry| entry.status), + Some(ShieldedActivityStatus::Pending), + "the send waits for the store to record its activity" + ); + // Cancelled there. + drop(send); + drop(held); + + let retry = Arc::new(Mutex::new(Vec::new())); + let retried = fixture.send_again(keep_entry(&retry)).await; + assert!( + matches!( + retried, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {retried:?}" + ); + assert_eq!(retry.lock().expect("retry").len(), 1, "the retry pays"); + } + + /// An unresolved private payment holds its pair beyond its sender + /// identity's own state, and refuses the identity's removal (71): removed + /// and loaded again, the identity would start with no hold. Once its entry + /// is read back the identity's reservation settles, but the wallet's + /// journal keeps the payment until its record is discharged: until then + /// the pair stays held, the removal stays refused, and the identity's + /// stored marker stays set, so a restart without shielded support holds + /// it too. Discharged by a restoration from that read-back, with no + /// notice given by hand, the removal goes through, and the identity loaded + /// again through `load_identity_by_index_from_master` (the load an + /// external-signable wallet takes, sharing `load_identity_by_index`'s + /// body) sends a private request that reaches its payment. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_hold_a_pair_and_its_sender_until_the_private_payment_resolves() { + use crate::wallet::shielded::{ + ShieldedActivityEntry, ShieldedActivityKind, ShieldedActivityStatus, ShieldedDirection, + }; + use dash_sdk::platform::types::identity::PublicKeyHash; + use dpp::identity::identity_public_key::methods::hash::IdentityPublicKeyHashMethodsV0; + use key_wallet::bip32::ExtendedPrivKey; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let fixture = ExpiryFixture::new().await; + let wallet_id = fixture.wallet.wallet_id(); + let paid = Arc::new(Mutex::new(Vec::new())); + let pay = { + let store = Arc::clone(fixture.coordinator.store()); + let persister = fixture.wallet.persister().clone(); + let subwallet = fixture.subwallet; + let input = fixture.input.clone(); + let paid = Arc::clone(&paid); + let (sender, recipient) = (alice.id(), bob.id()); + move |entry: BinaryData, started: PaymentStarted| async move { + paid.lock().expect("paid").push(entry.clone()); + let account_reference = started + .account_reference() + .expect("the send names its request"); + pay_private_document_with_outcome( + &store, + Some(&persister), + wallet_id, + subwallet, + &[input], + ShieldedActivityEntry { + id: [0x7E; 32], + kind: ShieldedActivityKind::ShieldedSpend, + direction: ShieldedDirection::Out, + amount: 0, + fee: Some(0), + counterparty: None, + memo: None, + block_height: None, + status: ShieldedActivityStatus::Pending, + created_at_ms: 1, + min_note_position: None, + note_cmxs: vec![], + spent_nullifiers: vec![], + }, + private_contact_request_payment(entry), + PrivateContactPayment { + sender: sender.to_buffer(), + recipient: recipient.to_buffer(), + account_reference, + }, + &started, + TestBroadcastOutcome::Unconfirmed, + ) + .await + } + }; + let sent = fixture.send_again(pay).await; + assert!( + matches!( + sent, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{sent:?}" + ); + let entry = paid.lock().expect("paid")[0].clone(); + let commitment: [u8; 32] = entry.as_slice()[..32] + .try_into() + .expect("an entry starts with its commitment"); + let remove = || async { + let iw = fixture.wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet_id) + .expect("the wallet") + .identity_manager + .remove_identity(&alice.id(), &iw.persister) + .map(|_| ()) + }; + let refused = |result: &Result<(), PlatformWalletError>| { + matches!(result, Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if *recipient == bob.id()) + }; + let removed = remove().await; + assert!(refused(&removed), "removal refused while held: {removed:?}"); + + let public = fixture + .wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "public: {public:?}" + ); + let retry = Arc::new(Mutex::new(Vec::new())); + let private = fixture.send_again(keep_entry(&retry)).await; + assert!( + matches!( + private, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "private: {private:?}" + ); + assert!(retry.lock().expect("retry").is_empty(), "nothing paid"); + + // Its entry lands and a private sync reads it back: the identity's + // reservation settles, the journal record waits for its discharge. + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + fixture + .wallet + .identity() + .dashpay() + .sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read back"); + managed(&fixture.wallet, ALICE, |managed| { + assert!(!managed.dashpay().private_reply_pending(&bob.id())); + assert!(!managed.dashpay().private_payments_unresolved()); + }) + .await; + let persister = fixture.wallet.persister(); + assert!( + persister.private_pair_journaled(&alice.id(), &bob.id()), + "held until its record is discharged" + ); + assert_eq!( + last_marker( + &fixture.persistence.stored.lock().expect("stored"), + &alice.id() + ), + Some(true), + "the stored marker stays set while the journal keeps the payment" + ); + let removed = remove().await; + assert!(refused(&removed), "still refused: {removed:?}"); + + // Discharged from that read-back by a restoration. + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + assert!(fixture + .coordinator + .store() + .read() + .await + .private_payment_journal(wallet_id) + .expect("journal") + .iter() + .all(|record| record.commitment != commitment)); + assert!( + !persister.private_pair_journaled(&alice.id(), &bob.id()), + "the read-back discharge clears the wallet-level hold" + ); + remove().await.expect("removed once resolved"); + let probe = alice.public_keys()[&SIGNING_KEY_ID] + .public_key_hash() + .expect("a key hash"); + let mut sdk = (*fixture.wallet.identity().sdk).clone(); + sdk.mock() + .expect_fetch(PublicKeyHash(probe), Some(alice.clone())) + .await + .expect("the identity at index 0"); + fixture + .wallet + .identity() + .load_identity_by_index_from_master( + 0, + &ExtendedPrivKey::new_master(Network::Testnet, &seed(ALICE_PHRASE)) + .expect("the master key"), + ) + .await + .expect("loaded") + .expect("found at index 0"); + let private = fixture.send_again(keep_entry(&retry)).await; + assert!( + matches!( + private, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {private:?}" + ); + assert_eq!( + retry.lock().expect("retry").len(), + 1, + "a private request reaches its payment" + ); + } + + /// A sender identity is not removed while a contact request of it is in + /// flight (71), whichever channel: a public request parked at its host + /// signature holds its claim, and a private one parked at the signature + /// of the request it seals holds its reservation. Removed and loaded again in either + /// window, the identity would start with no hold, and the other channel + /// could publish the pair or pay for it. + #[tokio::test] + async fn should_refuse_removing_a_sender_while_a_contact_request_is_in_flight() { + use dash_sdk::query_types::IdentityContractNonceFetcher; + use std::sync::Arc as StdArc; + use tokio::sync::Notify; + + #[derive(Debug)] + struct ParkedSigner { + inner: simple_signer::signer::SimpleSigner, + called: StdArc, + release: StdArc, + } + #[async_trait::async_trait] + impl Signer for ParkedSigner { + async fn sign( + &self, + key: &IdentityPublicKey, + data: &[u8], + ) -> Result { + self.called.notify_one(); + self.release.notified().await; + self.inner.sign(key, data).await + } + async fn sign_create_witness( + &self, + key: &IdentityPublicKey, + data: &[u8], + ) -> Result { + self.inner.sign_create_witness(key, data).await + } + fn can_sign_with(&self, key: &IdentityPublicKey) -> bool { + self.inner.can_sign_with(key) + } + } + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + for public in [true, false] { + let (_manager, alice_wallet) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let wallet_id = alice_wallet.wallet_id(); + let mut sdk = (*alice_wallet.identity().sdk).clone(); + sdk.mock() + .expect_fetch( + ( + alice.id(), + dashpay_contract().expect("bundled DashPay").id(), + ), + Some(IdentityContractNonceFetcher(3)), + ) + .await + .expect("the nonce read"); + let called = StdArc::new(Notify::new()); + let release = StdArc::new(Notify::new()); + let send = { + let wallet = Arc::clone(&alice_wallet); + let (alice_id, bob_id) = (alice.id(), bob.id()); + let (called, release) = (StdArc::clone(&called), StdArc::clone(&release)); + let alice_signer = signer(ALICE_PHRASE, &alice); + tokio::spawn(async move { + let signer = ParkedSigner { + inner: alice_signer, + called, + release, + }; + let crypto = + SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + if public { + wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + &signer, + &crypto, + ) + .await + .map(|_| ()) + } else { + wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + None, + &signer, + &crypto, + |_: BinaryData, _: PaymentStarted| { + std::future::ready(Err::( + PlatformWalletError::ShieldedBroadcastFailed( + "not paid in this test".to_string(), + ), + )) + }, + ) + .await + .map(|_| ()) + } + }) + }; + tokio::time::timeout(Duration::from_secs(5), called.notified()) + .await + .expect("the send is in flight"); + let removed = { + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet_id) + .expect("the wallet") + .identity_manager + .remove_identity(&alice.id(), &iw.persister) + .map(|_| ()) + }; + assert!( + matches!(&removed, Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if *recipient == bob.id()), + "public {public}: {removed:?}" + ); + release.notify_one(); + let _ = send.await.expect("send task"); + managed(&alice_wallet, ALICE, |_| {}).await; + } + } + + /// The wallet holds a private payment's pair from just before its journal + /// records are saved; a payment whose records were not saved, here one + /// spending no note, paid nothing and holds nothing. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_not_hold_a_pair_for_a_payment_whose_journal_records_were_not_saved() { + use crate::wallet::shielded::{ + ShieldedActivityEntry, ShieldedActivityKind, ShieldedActivityStatus, ShieldedDirection, + }; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let fixture = ExpiryFixture::new().await; + let persister = fixture.wallet.persister().clone(); + let paid = pay_private_document_with_outcome( + fixture.coordinator.store(), + Some(&persister), + fixture.wallet.wallet_id(), + fixture.subwallet, + &[], + ShieldedActivityEntry { + id: [0x7F; 32], + kind: ShieldedActivityKind::ShieldedSpend, + direction: ShieldedDirection::Out, + amount: 0, + fee: Some(0), + counterparty: None, + memo: None, + block_height: None, + status: ShieldedActivityStatus::Pending, + created_at_ms: 1, + min_note_position: None, + note_cmxs: vec![], + spent_nullifiers: vec![], + }, + private_contact_request_payment(BinaryData::new(vec![0x5F; 589])), + PrivateContactPayment { + sender: alice.id().to_buffer(), + recipient: bob.id().to_buffer(), + account_reference: 1, + }, + &PaymentStarted::default(), + TestBroadcastOutcome::Unconfirmed, + ) + .await; + assert!(paid.is_err(), "{paid:?}"); + assert!(fixture + .coordinator + .store() + .read() + .await + .private_payment_journal(fixture.wallet.wallet_id()) + .expect("journal") + .is_empty()); + assert!(!persister.private_pair_journaled(&alice.id(), &bob.id())); + } + + /// A payment restored while the wallet did not manage its sender holds the + /// pair for that sender once it is loaded, through the wallet-level hold + /// its commitment owns: so its discharge releases the pair, and a retry + /// pays with no other restoration. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_release_an_absent_sender_s_pair_once_its_payment_is_discharged() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let wallet_id = alice_wallet.wallet_id(); + let commitment = [0x5C; 32]; + { + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet_id) + .expect("the wallet") + .identity_manager + .remove_identity(&alice.id(), &iw.persister) + .expect("removed"); + } + let view = alice_wallet.identity().dashpay(); + let restored = view + .restore_private_payments(&[(alice.id(), bob.id(), 1, commitment, None)], true) + .await + .expect("restored"); + assert!(restored.is_empty(), "the sender is not managed"); + { + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet_id) + .expect("the wallet") + .identity_manager + .add_identity(alice.clone(), 0, wallet_id, &iw.persister) + .expect("loaded"); + } + let send = |kept: Arc>>| { + let view = alice_wallet.identity().dashpay(); + let (alice_id, bob_id) = (alice.id(), bob.id()); + let (signer, crypto) = (&alice_signer, &alice_crypto); + async move { + view.send_private_contact_request( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + None, + signer, + crypto, + keep_entry(&kept), + ) + .await + } + }; + let kept = Arc::new(Mutex::new(Vec::new())); + let held = send(Arc::clone(&kept)).await; + assert!( + matches!( + held, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{held:?}" + ); + assert!(kept.lock().expect("kept").is_empty(), "held: nothing paid"); + + alice_wallet + .persister() + .note_discharged_private_entries([commitment]); + let retried = send(Arc::clone(&kept)).await; + assert!( + matches!( + retried, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {retried:?}" + ); + assert_eq!(kept.lock().expect("kept").len(), 1, "the retry pays"); + } + + /// A payment a restoration from the journal finds unresolved holds its + /// pair at the wallet too, and refuses its sender's removal (71): the + /// identity stays, and a public request to the pair is refused. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_refuse_removing_a_sender_holding_a_restored_payment() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = alice_wallet.identity().dashpay(); + let restored = view + .restore_private_payments(&[(alice.id(), bob.id(), 1, [0x5E; 32], None)], true) + .await + .expect("restored"); + assert_eq!(restored, vec![(alice.id(), bob.id())]); + { + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let removed = wm + .get_wallet_info_mut(&alice_wallet.wallet_id()) + .expect("the wallet") + .identity_manager + .remove_identity(&alice.id(), &iw.persister); + assert!( + matches!(&removed, Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if *recipient == bob.id()), + "{removed:?}" + ); + } + let public = view + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{public:?}" + ); + } + + /// A journal record with no anchor height, saved while the store's tree + /// held `TREE` leaves. A store that held no tree when it was opened bounds + /// no such anchor, so the record stays. Reopened, its height stays + /// unknown, and it is discharged only with the pool proved, at or below + /// the set's height, to hold `TREE` leaves or more, the scan covering the + /// set and the store read through its end at that height lacking its + /// entry. Evidence a block behind the anchor, every proof at H - 1 and the + /// pool short of its tree, discharges nothing. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_discharge_a_reopened_heightless_journal_record_only_once_the_pool_reached_its_tree( + ) { + const TREE: u64 = 4; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let fixture = ExpiryFixture::new().await; + let height = ExpiryFixture::ANCHOR_SET_HEIGHT; + fixture.prove_at(height); + let wallet_id = fixture.wallet.wallet_id(); + let record = PrivatePaymentRecord { + account_index: 0, + activity_id: [0x71; 32], + anchor: ExpiryFixture::ANCHOR, + anchor_height: None, + commitment: [0x72; 32], + payment: PrivateContactPayment { + sender: alice.id().to_buffer(), + recipient: bob.id().to_buffer(), + account_reference: 1, + }, + nullifiers: vec![fixture.input.nullifier], + entry_hash: None, + store_position: None, + }; + { + let mut store = fixture.coordinator.store().write().await; + for leaf in 0..TREE { + store + .append_commitment(&[leaf as u8 + 1; 32], true) + .expect("appended"); + } + store + .journal_private_payments(wallet_id, std::slice::from_ref(&record)) + .expect("journaled"); + } + let recorded = HashSet::new(); + // The store held no tree when it was opened: no bound. + let journal = fixture.journal_snapshot().await; + assert_eq!( + heightless_tree_bounds(&*fixture.coordinator.store().read().await, &[], &journal), + None, + "no tree held at open" + ); + fixture.discharge(&journal, &recorded, Some(height)).await; + assert_eq!(fixture.journaled().await, 1, "unbounded"); + + // Saved by an earlier process: this one reopens the store. + let reopened = NetworkShieldedCoordinator::new( + Arc::clone(&fixture.wallet.identity().sdk), + Network::Testnet, + fixture.db_path.clone(), + FileBackedShieldedStore::open_path(&fixture.db_path, 100).expect("reopened"), + ); + let records = |coordinator: &NetworkShieldedCoordinator| { + let store = Arc::clone(coordinator.store()); + async move { + store + .read() + .await + .private_payment_journal(wallet_id) + .expect("journal") + } + }; + let journal: Vec<(WalletId, PrivatePaymentRecord)> = records(&reopened) + .await + .into_iter() + .map(|record| (wallet_id, record)) + .collect(); + assert_eq!(journal[0].1.anchor_height, None, "its height stays unknown"); + let (tree_bound, anchor_floors) = + heightless_tree_bounds(&*reopened.store().read().await, &[], &journal) + .expect("bounded"); + assert_eq!(tree_bound, TREE, "the tree the earlier process held"); + // (set height, scan coverage, pool leaves and their height, discharged) + let cases = [ + ( + height - 1, + height - 1, + (TREE - 1, height - 1), + false, + "a block behind", + ), + ( + height, + height, + (TREE - 1, height), + false, + "the pool short of the tree", + ), + ( + height, + height, + (TREE, height + 1), + false, + "the pool proved above the set", + ), + ( + height, + height - 1, + (TREE, height), + false, + "the scan below the set", + ), + (height, height, (TREE, height), true, "proven"), + ]; + for (set_height, covered, (pool_leaves, pool_height), discharged, case) in cases { + let heightless = HeightlessAnchorEvidence { + tree_bound, + pool_leaves, + pool_height, + anchor_floors: anchor_floors.clone(), + }; + reopened + .discharge_expired_private_payments( + &journal, + PrunedAnchorEvidence { + recorded: &recorded, + height: set_height, + scan_covered_height: Some(covered), + heightless: Some(&heightless), + }, + ) + .await; + assert_eq!(records(&reopened).await.is_empty(), discharged, "{case}"); + } + assert!(FileBackedShieldedStore::open_path(&fixture.db_path, 100) + .expect("reopened again") + .private_payment_journal(wallet_id) + .expect("journal") + .is_empty()); + } + + /// An expiry read that finds a candidate's entry in the store shows its + /// payment executed: the record stays, holding its pair until a private + /// sync reads the entry back and records the request, and no later pass + /// reads the store again for it. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_not_read_the_store_again_for_an_entry_an_expiry_read_found() { + use dash_sdk::dapi_grpc::platform::v0::GetPrivateDocumentEntriesRequest; + use dash_sdk::platform::Query; + + let fixture = ExpiryFixture::new().await; + let height = ExpiryFixture::ANCHOR_SET_HEIGHT; + fixture.prove_at(height); + let entry = fixture.pay_unconfirmed(ExpiryFixture::ANCHOR, height).await; + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + let mut sdk = (*fixture.wallet.identity().sdk).clone(); + let request: GetPrivateDocumentEntriesRequest = PrivateDocumentEntriesQuery::new( + dashpay_contract().expect("bundled DashPay").id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + 0, + ) + .query(&sdk.query_settings()) + .expect("encodes"); + let recorded = HashSet::new(); + let journal = fixture.journal_snapshot().await; + + let before = sdk.mock().request_count(&request).await; + fixture.discharge(&journal, &recorded, Some(height)).await; + let read = sdk.mock().request_count(&request).await; + assert!(read > before, "the expiry read the store"); + assert_eq!( + fixture.journaled().await, + 1, + "landed: kept for its read-back" + ); + + fixture.discharge(&journal, &recorded, Some(height)).await; + assert_eq!( + sdk.mock().request_count(&request).await, + read, + "no store read for it again" + ); + assert_eq!(fixture.journaled().await, 1); + } + + /// A private payment read back, its journal record then discharged by the + /// coordinator as every sync pass does: the read-back settles the + /// identity's own reservation and stores its marker set, as the journal + /// still keeps the payment, and the next public request, releasing what + /// the discharge freed, stores it cleared although the identity's own part + /// was already clear. Reloaded from that record, as any build loads it, + /// the identity holds no public request back. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_store_the_marker_cleared_once_a_read_back_payment_is_discharged() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let fixture = ExpiryFixture::new().await; + let marker = || { + last_marker( + &fixture.persistence.stored.lock().expect("stored"), + &alice.id(), + ) + }; + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, ExpiryFixture::ANCHOR_SET_HEIGHT) + .await; + assert_eq!(marker(), Some(true), "marked before paying"); + // The wallet holds the pair from the journal too, as a payment's + // submission or a restoration notes it. + fixture + .wallet + .restore_private_contact_payments(&fixture.coordinator) + .await + .expect("restored"); + let persister = fixture.wallet.persister(); + assert!(persister.private_pair_journaled(&alice.id(), &bob.id())); + + // Read back: the identity's own reservation settles, and the journal + // still keeps the payment, so the marker stays set. + publish(&fixture.wallet, 0, vec![entry.to_vec()]).await; + let view = fixture.wallet.identity().dashpay(); + view.sync_private_contact_requests(&alice_crypto, 4) + .await + .expect("the entry is read back"); + assert!(!pending_to(&fixture.wallet, ALICE, &bob).await, "settled"); + assert!(persister.private_pair_journaled(&alice.id(), &bob.id())); + assert_eq!(marker(), Some(true), "the journal still keeps it"); + + // The coordinator's ordinary discharge of the records read back. + fixture + .coordinator + .discharge_read_back_private_payments() + .await; + assert_eq!(fixture.journaled().await, 0, "discharged"); + assert!(!persister.private_pair_journaled(&alice.id(), &bob.id())); + + // The next public request releases what the discharge freed and + // stores the marker cleared, before it is decided on the pair. + let public = view + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply( + _ + )) + ), + "{public:?}" + ); + assert_eq!(marker(), Some(false), "stored cleared"); + + // Reloaded from the record last stored, the identity is not held. + let kept = Arc::new( + scan_state_snapshot(&fixture.wallet, &alice.id(), marker().expect("stored")).await, + ); + // The store as the earlier process left it, read from its cursor. + let manager = PlatformWalletManager::new( + Arc::new( + dashpay_sdk( + &[&alice, &bob], + vec![entry.to_vec()], + PlatformVersion::latest(), + None, + ) + .await, + ), + Arc::clone(&kept), + Arc::new(NoopEventHandler), + ); + manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + // A host keeping the private scan state configures the shielded store + // at activation: until then, a loaded wallet is held. + #[cfg(feature = "shielded")] + let _store = { + let dir = tempfile::tempdir().expect("temporary shielded store"); + manager + .configure_shielded(dir.path().join("tree.sqlite")) + .await + .expect("the shielded store is configured"); + dir + }; + let restarted = manager + .get_wallet(&fixture.wallet.wallet_id()) + .await + .expect("the relaunched wallet"); + assert!(!restarted.private_payments_held().await); + assert!( + restarted + .identity() + .dashpay() + .private_contact_readiness(&alice.id()) + .await + .expect("the readiness") + .private_payments_restored + ); + // Past the hold, the send is decided on the pair itself: its channel + // is private, as the request read back shows. + let public = restarted + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(recipient)) + if recipient == bob.id() + ), + "{public:?}" + ); + } + + /// The store read that shows a payment's entry absent counts a page by the + /// lowest of its reads: a page completed at the floor from a first read + /// one block below it does not show the store at the floor, and the read + /// fails; read wholly at the floor, it shows the entry absent. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_not_take_a_store_page_completed_from_below_the_floor_as_absence() { + let fixture = ExpiryFixture::new().await; + let floor = ExpiryFixture::ANCHOR_SET_HEIGHT; + let filler = |byte: u8| vec![byte; 64]; + let page = |start: u64, entries: Vec>, total: u64| { + let mut page = store_page(start, entries); + page.chunk_power = Some(1); + page.total_count = total; + page + }; + let contract = dashpay_contract().expect("bundled DashPay"); + let query = |start| { + PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + start, + ) + }; + let mut sdk = (*fixture.wallet.identity().sdk).clone(); + { + let mut mock = sdk.mock(); + for (start, page) in [ + (0, page(0, vec![filler(0xA0), filler(0xA1)], 4)), + (2, page(2, vec![filler(0xA2)], 3)), + (3, page(3, vec![filler(0xA3)], 4)), + ] { + mock.remove_fetch_expectation::(query(start)) + .await; + mock.expect_fetch(query(start), Some(page)) + .await + .expect("page expectation"); + } + mock.set_response_height(floor) + .set_response_height_for::(query(2), floor - 1); + } + let candidates = HashSet::from([[0x72; 32]]); + let below = fixture + .coordinator + .private_contact_requests_held( + &(candidates) + .iter() + .map(|commitment| (*commitment, None)) + .collect(), + 0, + floor, + ) + .await; + assert!(below.is_err(), "{below:?}"); + + sdk.mock() + .set_response_height_for::(query(2), floor); + let held = fixture + .coordinator + .private_contact_requests_held( + &(candidates) + .iter() + .map(|commitment| (*commitment, None)) + .collect(), + 0, + floor, + ) + .await + .expect("read at the floor"); + assert!(held.is_empty(), "absent"); + } + + /// A wallet removed while a private payment of its identity may still + /// execute keeps that payment in the shielded store's journal, which + /// outlives the removal, and a wallet re-created under its id holds the + /// payment's pair from it. With the store configured, the journal is read + /// as the wallet registers: once its identity is loaded, its public + /// request is refused as pending. With none configured yet, the wallet is + /// held until one is, as its persister keeps the private scan state: + /// refused as not restored, then held as pending once + /// `configure_shielded` reads the journal. Configuring the store also + /// reads it for a wallet registered before. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_hold_the_journaled_pairs_of_a_wallet_re_created_under_its_id() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let alice_seed = seed(ALICE_PHRASE); + let (alice_id, bob_id) = (alice.id(), bob.id()); + for configured_first in [true, false] { + let dir = tempfile::tempdir().expect("temporary shielded store"); + let path = dir.path().join("tree.sqlite"); + let manager = PlatformWalletManager::new( + Arc::new( + dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await, + ), + Arc::new(NoPersistence), + Arc::new(NoopEventHandler), + ); + let create = || { + manager.create_wallet_from_seed_bytes( + Network::Testnet, + &alice_seed, + WalletAccountCreationOptions::Default, + Some(0), + ) + }; + let first = create().await.expect("the wallet"); + let wallet_id = first.wallet_id(); + // A private payment from Alice to Bob that may still execute. + FileBackedShieldedStore::open_path(&path, 100) + .expect("the store") + .journal_private_payments( + wallet_id, + &[PrivatePaymentRecord { + account_index: 0, + activity_id: [0x71; 32], + anchor: [0x7C; 32], + anchor_height: Some(1), + commitment: [0x72; 32], + payment: PrivateContactPayment { + sender: alice.id().to_buffer(), + recipient: bob.id().to_buffer(), + account_reference: 1, + }, + nullifiers: vec![[0x12; 32]], + entry_hash: None, + store_position: None, + }], + ) + .expect("journaled"); + if configured_first { + manager + .configure_shielded(&path) + .await + .expect("the shielded store is configured"); + assert!( + first + .persister() + .private_pair_journaled(&alice.id(), &bob.id()), + "configuring reads the journal of a wallet no load held" + ); + } + + manager.remove_wallet(&wallet_id).await.expect("removed"); + let recreated = create().await.expect("re-created under its id"); + assert_eq!(recreated.wallet_id(), wallet_id); + { + let iw = recreated.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet_id) + .expect("wallet info") + .identity_manager + .add_identity(alice.clone(), 0, wallet_id, &iw.persister) + .expect("Alice, loaded again"); + } + let view = recreated.identity().dashpay(); + let public = || { + view.send_contact_request_with_external_signer( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + }; + if !configured_first { + let held = public().await; + assert!( + matches!( + held, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{held:?}" + ); + manager + .configure_shielded(&path) + .await + .expect("the shielded store is configured"); + } + assert!( + recreated + .persister() + .private_pair_journaled(&alice.id(), &bob.id()), + "held from the journal, configured first: {configured_first}" + ); + let pending = public().await; + assert!( + matches!( + pending, + Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob.id() + ), + "configured first: {configured_first}: {pending:?}" + ); + } + } + + /// Journal, in the shielded store at `path`, a private payment from Alice to + /// Bob made by wallet `wallet_id` that may still execute. + #[cfg(feature = "shielded")] + fn journal_alice_to_bob(path: &std::path::Path, wallet_id: WalletId) { + let (alice, bob) = (identity(ALICE_PHRASE, ALICE), identity(BOB_PHRASE, BOB)); + FileBackedShieldedStore::open_path(path, 100) + .expect("the store") + .journal_private_payments( + wallet_id, + &[PrivatePaymentRecord { + account_index: 0, + activity_id: [0x71; 32], + anchor: [0x7C; 32], + anchor_height: Some(1), + commitment: [0x72; 32], + payment: PrivateContactPayment { + sender: alice.id().to_buffer(), + recipient: bob.id().to_buffer(), + account_reference: 1, + }, + nullifiers: vec![[0x12; 32]], + entry_hash: None, + store_position: None, + }], + ) + .expect("journaled"); + } + + /// A manager over `persistence`, with Alice and Bob known to its SDK. + async fn manager_on( + persistence: Arc

, + ) -> PlatformWalletManager

{ + let (alice, bob) = (identity(ALICE_PHRASE, ALICE), identity(BOB_PHRASE, BOB)); + PlatformWalletManager::new( + Arc::new(dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await), + persistence, + Arc::new(NoopEventHandler), + ) + } + + /// `manager`'s wallet of `phrase`, created as a host creates one, holding + /// `own` as loaded from Platform: a fresh managed identity, no marker. + async fn create_holding( + manager: &PlatformWalletManager

, + phrase: &str, + own: &Identity, + ) -> Arc { + let wallet = manager + .create_wallet_from_seed_bytes( + Network::Testnet, + &seed(phrase), + WalletAccountCreationOptions::Default, + Some(0), + ) + .await + .expect("the wallet"); + let iw = wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .add_identity(own.clone(), 0, wallet.wallet_id(), &iw.persister) + .expect("the identity"); + drop(wm); + wallet + } + + /// A persister that kept a removed wallet's marked private scan state + /// record, as `ClientStartState::retained_private_contact_scan_states` + /// asks, and holds nothing else of it. + struct RetainingPersistence { + wallet_id: WalletId, + owner: Identifier, + capabilities: PersistenceCapabilities, + } + + impl PlatformWalletPersistence for RetainingPersistence { + fn persistence_capabilities(&self) -> PersistenceCapabilities { + self.capabilities + } + + fn store( + &self, + _wallet_id: WalletId, + _changeset: PlatformWalletChangeSet, + ) -> Result<(), PersistenceError> { + Ok(()) + } + + fn flush(&self, _wallet_id: WalletId) -> Result<(), PersistenceError> { + Ok(()) + } + + fn load(&self) -> Result { + let mut state = ClientStartState::default(); + state.retained_private_contact_scan_states.insert( + self.wallet_id, + BTreeMap::from([( + self.owner, + PrivateContactRequestsPosition { + position: 7, + key_fingerprint: [0x5C; 32], + private_payments_unresolved: true, + }, + )]), + ); + Ok(state) + } + } + + /// An identity whose private scan state record its persister kept marked + /// after the wallet was removed is held once the same seed is registered + /// again by a new manager and the identity loaded afresh from Platform, + /// before any shielded store is configured, in every build: a public + /// request is refused as not restored. Its read starts from the store's + /// start, not the position kept, as the requests read before it went + /// with the wallet's other rows. + #[tokio::test] + async fn should_hold_an_identity_whose_marked_record_outlived_its_wallet() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let wallet_id = { + let manager = manager_on(RecordingPersistence::attesting( + PersistenceCapabilities::NONE, + )) + .await; + let first = create_holding(&manager, ALICE_PHRASE, &alice).await; + let wallet_id = first.wallet_id(); + manager.remove_wallet(&wallet_id).await.expect("removed"); + wallet_id + }; + for capabilities in [ + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + PersistenceCapabilities::NONE, + ] { + let manager = manager_on(Arc::new(RetainingPersistence { + wallet_id, + owner: alice.id(), + capabilities, + })) + .await; + let again = create_holding(&manager, ALICE_PHRASE, &alice).await; + assert_eq!(again.wallet_id(), wallet_id); + managed(&again, ALICE, |managed| { + assert!( + managed.dashpay().private_payments_unrestored(), + "held by the kept marker" + ); + assert_eq!( + managed.dashpay().private_contact_requests_position(), + 0, + "read from the store's start" + ); + }) + .await; + let public = again + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{capabilities:?}: {public:?}" + ); + } + } + + /// A load honours a record its persister kept marked for the wallet's id + /// after an earlier wallet under it was removed, though the identity's + /// own record is cleared: the loaded identity is held. + #[tokio::test] + async fn should_hold_a_loaded_identity_whose_record_a_persister_kept_marked() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (_before_manager, before) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let mut kept = scan_state_snapshot(&before, &alice.id(), false).await; + kept.retained = BTreeMap::from([( + before.wallet_id(), + BTreeMap::from([( + alice.id(), + PrivateContactRequestsPosition { + position: 3, + key_fingerprint: [0x5C; 32], + private_payments_unresolved: true, + }, + )]), + )]); + let manager = PlatformWalletManager::new( + Arc::new(dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await), + Arc::new(kept), + Arc::new(NoopEventHandler), + ); + manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + let restarted = manager + .get_wallet(&before.wallet_id()) + .await + .expect("the relaunched wallet"); + managed(&restarted, ALICE, |managed| { + assert!(managed.dashpay().private_payments_unrestored()); + }) + .await; + } + + /// A wallet published with no shielded store configured, its persister + /// keeping the private scan state, is held until the journal is read, + /// whatever its history: a fresh wallet is refused as not restored, and + /// the store, configured, releases it when its journal holds nothing. A + /// wallet removed while a private payment of its may still execute, and + /// registered again from the same seed by a new manager, as after a + /// restart, before the store is configured, with its identity loaded + /// afresh from Platform (no marker, no history in this manager), is + /// refused as not restored too, and as pending once the store's journal is + /// read. A persister that does not keep the scan state, so cannot pay a + /// private request, is never held for want of a store. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_hold_a_wallet_published_with_no_shielded_store_until_its_journal_is_read() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let attesting = || { + RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ) + }; + let (alice_id, bob_id) = (alice.id(), bob.id()); + let (alice_crypto, alice_signer) = (&alice_crypto, &alice_signer); + let public = |wallet: Arc| async move { + wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice_id, + &bob_id, + None, + AutoAcceptProofSource::None, + alice_signer, + alice_crypto, + ) + .await + }; + let not_restored = |result: &Result| { + matches!( + result, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ) + }; + + // A fresh wallet, an empty journal. + let dir = tempfile::tempdir().expect("temporary shielded store"); + let path = dir.path().join("tree.sqlite"); + let manager = manager_on(attesting()).await; + let fresh = create_holding(&manager, ALICE_PHRASE, &alice).await; + assert!(fresh.private_payments_held().await, "held with no store"); + let held = public(Arc::clone(&fresh)).await; + assert!(not_restored(&held), "{held:?}"); + manager + .configure_shielded(&path) + .await + .expect("the shielded store is configured"); + assert!( + !fresh.private_payments_held().await, + "an empty journal releases it" + ); + + // Removed with a payment journaled, registered again by a new manager + // before the store is configured. + let dir = tempfile::tempdir().expect("temporary shielded store"); + let path = dir.path().join("tree.sqlite"); + let before = manager_on(attesting()).await; + let removed = create_holding(&before, ALICE_PHRASE, &alice).await; + let wallet_id = removed.wallet_id(); + journal_alice_to_bob(&path, wallet_id); + before.remove_wallet(&wallet_id).await.expect("removed"); + drop(removed); + drop(before); + let after = manager_on(attesting()).await; + let again = create_holding(&after, ALICE_PHRASE, &alice).await; + assert_eq!(again.wallet_id(), wallet_id); + let held = public(Arc::clone(&again)).await; + assert!(not_restored(&held), "before configure: {held:?}"); + after + .configure_shielded(&path) + .await + .expect("the shielded store is configured"); + assert!(again + .persister() + .private_pair_journaled(&alice.id(), &bob.id())); + let pending = public(Arc::clone(&again)).await; + assert!( + matches!( + pending, + Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob.id() + ), + "after configure: {pending:?}" + ); + + // A persister that does not keep the scan state. + let manager = manager_on(RecordingPersistence::attesting( + PersistenceCapabilities::NONE, + )) + .await; + let unheld = create_holding(&manager, ALICE_PHRASE, &alice).await; + assert!( + !unheld.private_payments_held().await, + "never held for want of a store" + ); + } + + /// With the store configured, a wallet removed and created again under its + /// id, its journal holding nothing, is not held: no history of the id is + /// kept, so a registration retried after one that failed or was removed is + /// a first one. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_not_hold_a_wallet_created_again_over_an_empty_journal() { + let alice = identity(ALICE_PHRASE, ALICE); + let dir = tempfile::tempdir().expect("temporary shielded store"); + let manager = manager_on(RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + )) + .await; + manager + .configure_shielded(dir.path().join("tree.sqlite")) + .await + .expect("the shielded store is configured"); + let first = create_holding(&manager, ALICE_PHRASE, &alice).await; + assert!(!first.private_payments_held().await); + let wallet_id = first.wallet_id(); + manager.remove_wallet(&wallet_id).await.expect("removed"); + let again = create_holding(&manager, ALICE_PHRASE, &alice).await; + assert!( + !again.private_payments_held().await, + "created again, not held" + ); + } + + /// A registration racing the store's configuration ends restored, however + /// the two interleave: one that found no store holds the wallet, and the + /// configuration either finds it published or the registration finds the + /// store once it published it. + #[cfg(feature = "shielded")] + #[tokio::test(flavor = "multi_thread", worker_threads = 4)] + async fn should_restore_a_wallet_registered_while_the_store_is_configured() { + let alice = identity(ALICE_PHRASE, ALICE); + for _ in 0..6 { + let dir = tempfile::tempdir().expect("temporary shielded store"); + let path = dir.path().join("tree.sqlite"); + let manager = Arc::new( + manager_on(RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + )) + .await, + ); + let configuring = { + let manager = Arc::clone(&manager); + tokio::spawn(async move { manager.configure_shielded(&path).await }) + }; + let wallet = create_holding(&manager, ALICE_PHRASE, &alice).await; + configuring + .await + .expect("the configuration runs") + .expect("the shielded store is configured"); + let restored = tokio::time::timeout(Duration::from_secs(5), async { + while wallet.private_payments_held().await { + tokio::time::sleep(Duration::from_millis(10)).await; + } + }) + .await; + assert!(restored.is_ok(), "the wallet stays held"); + } + } + + /// A wallet still held once it is published, under a store configured + /// since its registration found none, is restored by the check the + /// registration makes once the wallet is published: the configuration's + /// own walk ran before the wallet was published, so it did not see it. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_restore_a_wallet_still_held_once_published_under_a_store_configured_since() { + let alice = identity(ALICE_PHRASE, ALICE); + let dir = tempfile::tempdir().expect("temporary shielded store"); + let manager = manager_on(RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + )) + .await; + manager + .configure_shielded(dir.path().join("tree.sqlite")) + .await + .expect("the shielded store is configured"); + let wallet = create_holding(&manager, ALICE_PHRASE, &alice).await; + // As the registration's check before the store was configured left it. + wallet.persister().hold_until_private_payments_restored(); + manager + .restore_private_payments_configured_since(&wallet) + .await; + assert!(!wallet.private_payments_held().await); + } + + /// The first configure reads the journal of every wallet whose id it may + /// keep payments of, held or not: a backend that no longer attests the + /// private scan state holds no wallet for want of a store, yet the + /// payments journaled while it did still hold their pairs. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_read_the_journal_of_a_wallet_not_held_at_the_first_configure() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let dir = tempfile::tempdir().expect("temporary shielded store"); + let path = dir.path().join("tree.sqlite"); + let manager = manager_on(RecordingPersistence::attesting( + PersistenceCapabilities::NONE, + )) + .await; + let wallet = create_holding(&manager, ALICE_PHRASE, &alice).await; + assert!(!wallet.private_payments_held().await); + journal_alice_to_bob(&path, wallet.wallet_id()); + manager + .configure_shielded(&path) + .await + .expect("the shielded store is configured"); + assert!(wallet + .persister() + .private_pair_journaled(&alice.id(), &bob.id())); + } + + /// A repeat `configure_shielded`, as a host makes on every bind from its + /// main thread, returns at once while a scan holds the store's writer: a + /// wallet still held is restored once the writer is released. + #[cfg(feature = "shielded")] + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn should_configure_again_without_waiting_on_a_busy_store() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let dir = tempfile::tempdir().expect("temporary shielded store"); + let path = dir.path().join("tree.sqlite"); + let manager = manager_on(RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + )) + .await; + manager + .configure_shielded(&path) + .await + .expect("the shielded store is configured"); + let coordinator = manager.shielded_coordinator().await.expect("configured"); + let scan = coordinator.store().write().await; + // Registered while the scan holds the store: held, its restoration + // deferred. + let held = create_holding(&manager, BOB_PHRASE, &bob).await; + assert!(held.private_payments_held().await); + let again = + tokio::time::timeout(Duration::from_secs(1), manager.configure_shielded(&path)).await; + assert!( + matches!(again, Ok(Ok(()))), + "the repeat configure does not wait on the store" + ); + drop(scan); + let restored = tokio::time::timeout(Duration::from_secs(5), async { + while held.private_payments_held().await { + tokio::time::sleep(Duration::from_millis(10)).await; + } + }) + .await; + assert!(restored.is_ok(), "restored once the store frees"); + let _ = alice; + } + + /// A restoration left unfinished, deferred for a busy store and its task + /// gone, is run again by the next contact request before it is refused as + /// not restored: once the store frees, a public request to the pair the + /// journal keeps is refused as pending, not as unrestored. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_retry_an_unfinished_restoration_before_a_contact_request() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, wallet) = wallet_on( + RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + let dir = tempfile::tempdir().expect("temporary shielded store"); + let path = dir.path().join("tree.sqlite"); + journal_alice_to_bob(&path, wallet.wallet_id()); + let coordinator = Arc::new(NetworkShieldedCoordinator::new( + Arc::clone(&wallet.identity().sdk), + Network::Testnet, + path.clone(), + FileBackedShieldedStore::open_path(&path, 100).expect("the store"), + )); + let scan = coordinator.store().write().await; + let deferred = wallet + .restore_private_payments_or_defer(&coordinator) + .await + .expect("deferred for the busy store"); + deferred.abort(); + let _ = deferred.await; + drop(scan); + assert!(wallet.private_payments_held().await, "its task is gone"); + let view = wallet.identity().dashpay(); + let readiness = view + .private_contact_readiness(&alice.id()) + .await + .expect("the readiness"); + assert!(!readiness.private_payments_restored); + assert_eq!( + readiness.private_payments_restore_failure, None, + "not failed, only not run" + ); + let public = view + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestPending(recipient)) + if recipient == bob.id() + ), + "{public:?}" + ); + assert!( + !wallet.private_payments_held().await, + "restored by the send" + ); + } + + /// A restoration that fails holds the wallet and is reported with its + /// reason while it does; a contact request is refused as not restored. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_report_why_a_restoration_failed_while_the_wallet_is_held() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, wallet) = wallet_on( + RecordingPersistence::attesting( + PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART, + ), + ALICE_PHRASE, + &alice, + &[&alice, &bob], + vec![], + ) + .await; + let dir = tempfile::tempdir().expect("temporary shielded store"); + let path = dir.path().join("tree.sqlite"); + journal_alice_to_bob(&path, wallet.wallet_id()); + rusqlite::Connection::open(&path) + .expect("the store's file") + .execute( + "UPDATE shielded_private_payment_journal SET record = x'00'", + [], + ) + .expect("the record damaged"); + let coordinator = Arc::new(NetworkShieldedCoordinator::new( + Arc::clone(&wallet.identity().sdk), + Network::Testnet, + path.clone(), + FileBackedShieldedStore::open_path(&path, 100).expect("the store"), + )); + let failed = wallet.restore_private_contact_payments(&coordinator).await; + assert!(failed.is_err(), "{failed:?}"); + let view = wallet.identity().dashpay(); + let readiness = view + .private_contact_readiness(&alice.id()) + .await + .expect("the readiness"); + assert!(!readiness.private_payments_restored); + assert!( + readiness + .private_payments_restore_failure + .as_deref() + .is_some_and(|reason| reason.contains("does not read back")), + "{readiness:?}" + ); + let public = view + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{public:?}" + ); + } + + /// A private payment that never executes is proven expired once its + /// anchor is pruned and its entry is absent from the store: the + /// coordinator discharges its journal record, the pair is freed, a retry + /// to it pays, and a reopened store restores no hold. So it is when a + /// competing spend consumed its input first: the absent entry shows it + /// never executed. A still-recorded anchor keeps the record and the hold. + /// An entry in the store keeps the record, for its read-back to discharge: + /// the next send reads the store first and records the request, so a new + /// private request to the pair is then a rotation, which pays. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_free_a_pair_once_its_private_payment_provably_expired() { + #[derive(Clone, Copy, Debug, PartialEq)] + enum Case { + Expired, + AnchorRecorded, + InputSpent, + EntryAppended, + } + let height = ExpiryFixture::ANCHOR_SET_HEIGHT; + for case in [ + Case::Expired, + Case::AnchorRecorded, + Case::InputSpent, + Case::EntryAppended, + ] { + let fixture = ExpiryFixture::new().await; + fixture.prove_at(height); + let entry = fixture.pay_unconfirmed(ExpiryFixture::ANCHOR, height).await; + match case { + Case::InputSpent => { + fixture + .coordinator + .store() + .write() + .await + .mark_spent(fixture.subwallet, &fixture.input.nullifier) + .expect("spent"); + } + Case::EntryAppended => publish(&fixture.wallet, 0, vec![entry.to_vec()]).await, + Case::Expired | Case::AnchorRecorded => {} + } + let recorded: HashSet<[u8; 32]> = match case { + Case::AnchorRecorded => HashSet::from([ExpiryFixture::ANCHOR]), + _ => HashSet::new(), + }; + let journal = fixture.journal_snapshot().await; + fixture.discharge(&journal, &recorded, Some(height)).await; + match case { + Case::Expired | Case::InputSpent => { + fixture.assert_discharged(&format!("{case:?}")).await; + } + Case::AnchorRecorded => fixture.assert_kept(&format!("{case:?}")).await, + Case::EntryAppended => { + assert_eq!(fixture.journaled().await, 1, "kept for its read-back"); + let rotation = Arc::new(Mutex::new(Vec::new())); + let rotated = fixture.send_again(keep_entry(&rotation)).await; + assert!( + matches!( + rotated, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "read back, then rotated: {rotated:?}" + ); + assert_eq!(rotation.lock().expect("rotation").len(), 1); + assert!(fixture.wallet.persister().has_read_back_private_entries()); + } + } + } + } + + /// The expiry evidence is pinned to the anchor set's proved height H and + /// to the journal records read before it: a record journaled after the + /// snapshot, one armed again since, one whose anchor was read above H, a + /// note scan or a store read below H each discharge nothing. The payment + /// whose scan or store read was below H is discharged once both cover H, + /// and a retry to its pair pays. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_discharge_an_expired_private_payment_only_on_evidence_at_its_anchor_set_height() + { + #[derive(Clone, Copy, Debug, PartialEq)] + enum Case { + JournaledAfterSnapshot, + ArmedAgainSinceSnapshot, + AnchorReadAboveSet, + ScanBelowSet, + StoreBelowSet, + } + let height = ExpiryFixture::ANCHOR_SET_HEIGHT; + let recorded = HashSet::new(); + for case in [ + Case::JournaledAfterSnapshot, + Case::ArmedAgainSinceSnapshot, + Case::AnchorReadAboveSet, + Case::ScanBelowSet, + Case::StoreBelowSet, + ] { + let fixture = ExpiryFixture::new().await; + // Read before the anchor set: the payment is journaled after it. + let before = fixture.journal_snapshot().await; + fixture.prove_at(match case { + Case::StoreBelowSet => height - 1, + _ => height, + }); + let anchor_height = match case { + Case::AnchorReadAboveSet => height + 1, + _ => height, + }; + let entry = fixture + .pay_unconfirmed(ExpiryFixture::ANCHOR, anchor_height) + .await; + let journal = match case { + Case::JournaledAfterSnapshot => before, + _ => fixture.journal_snapshot().await, + }; + assert!( + case == Case::JournaledAfterSnapshot || journal.len() == 1, + "{case:?}: the snapshot holds the record" + ); + if case == Case::ArmedAgainSinceSnapshot { + // A retry armed the same entry again, against a newer anchor + // the set may not hold yet. + let payment = journal[0].1.payment; + arm_redrive_before_broadcast( + fixture.coordinator.store(), + fixture.subwallet, + Some([0x7D; 32]), + [0x7E; 32], + vec![fixture.input.nullifier], + &private_contact_request_payment(entry.clone()), + "private document create from shielded pool", + Some(payment), + None, + height, + ) + .await + .expect("armed again"); + } + let scan_covered_height = match case { + Case::ScanBelowSet => Some(height - 1), + _ => Some(height), + }; + fixture + .discharge(&journal, &recorded, scan_covered_height) + .await; + fixture.assert_kept(&format!("{case:?}")).await; + if matches!(case, Case::ScanBelowSet | Case::StoreBelowSet) { + // The same payment, once the scan and the store read cover H. + fixture.prove_at(height); + fixture.discharge(&journal, &recorded, Some(height)).await; + fixture + .assert_discharged(&format!("{case:?} at the set's height")) + .await; + } + } + } + + /// The store read for expiry keeps only the candidates it finds, however + /// many other entries it reads to show them absent. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_keep_only_candidate_commitments_from_the_store_read_for_expiry() { + let fixture = ExpiryFixture::new().await; + let held = [0xC1; 32]; + let absent = [0xC2; 32]; + let mut entries: Vec> = (0u32..2_000) + .map(|index| { + let mut entry = vec![0u8; 64]; + entry[..4].copy_from_slice(&index.to_be_bytes()); + entry[4] = 0xEE; + entry + }) + .collect(); + let mut candidate_entry = held.to_vec(); + candidate_entry.extend_from_slice(&[0u8; 32]); + entries.insert(1_234, candidate_entry); + publish(&fixture.wallet, 0, entries).await; + let kept = fixture + .coordinator + .private_contact_requests_held( + &(HashSet::from([held, absent])) + .iter() + .map(|commitment| (*commitment, None)) + .collect(), + 0, + 0, + ) + .await + .expect("the store reads"); + assert_eq!(kept, HashSet::from([held])); + } + + /// A payment that may have reached the network keeps its pair pending + /// whatever error it returns, as its transition may still execute; one + /// whose transition provably never left the wallet releases it. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_keep_a_pair_pending_once_its_payment_may_have_reached_the_network() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + for never_left in [false, true] { + let (_manager, alice_wallet) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let failing = move |_: BinaryData, started: PaymentStarted| { + started.mark(); + if never_left { + started.note_never_delivered(); + } + std::future::ready(Err::( + PlatformWalletError::ShieldedBroadcastFailed( + "rejected on its merits".to_string(), + ), + )) + }; + let sent = alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + failing, + ) + .await; + assert!( + matches!(sent, Err(PlatformWalletError::ShieldedBroadcastFailed(_))), + "{sent:?}" + ); + assert_eq!( + pending_to(&alice_wallet, ALICE, &bob).await, + !never_left, + "never left the wallet: {never_left}" + ); + } + } + + /// The type 29 transition paying for `entry`, with placeholder actions: + /// as the shielded store keeps a payment's signed transition. + #[cfg(feature = "shielded")] + fn private_contact_request_payment( + entry: BinaryData, + ) -> dpp::state_transition::StateTransition { + use dpp::shielded::SerializedAction; + use dpp::state_transition::private_document_create_from_shielded_pool_transition::methods::PrivateDocumentCreateFromShieldedPoolTransitionMethodsV0; + use dpp::state_transition::private_document_create_from_shielded_pool_transition::PrivateDocumentCreateFromShieldedPoolTransition; + + let action = SerializedAction { + nullifier: [1; 32], + rk: [2; 32], + cmx: [3; 32], + encrypted_note: vec![4; 216], + cv_net: [5; 32], + spend_auth_sig: [6; 64], + }; + PrivateDocumentCreateFromShieldedPoolTransition::try_from_bundle( + dashpay_contract().expect("bundled DashPay").id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME.to_string(), + vec![entry], + vec![action.clone(), action], + 0, + [7; 32], + vec![8; 64], + [9; 64], + PlatformVersion::latest(), + ) + .expect("a type 29 transition") + } + + /// A process that exits after its private payment was admitted, during + /// the wait for its result, still leaves the payment's record, saved + /// before the broadcast: a restarted wallet restores the request's + /// reservation from it, so neither a second private request nor a + /// public one goes to the recipient. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_restore_a_request_whose_process_exited_during_its_result_wait() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let dir = tempfile::tempdir().expect("temporary shielded store"); + let db_path = dir.path().join("tree.sqlite"); + let coordinator_at = |db_path: std::path::PathBuf| { + let store = FileBackedShieldedStore::open_path(&db_path, 100).expect("open the store"); + Arc::new(NetworkShieldedCoordinator::new( + Arc::new(dash_sdk::Sdk::new_mock()), + Network::Testnet, + db_path, + store, + )) + }; + + let before = coordinator_at(db_path.clone()); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let subwallet = SubwalletId::new(alice_wallet.wallet_id(), 0); + let pay = { + let store = Arc::clone(before.store()); + move |entry: BinaryData, started: PaymentStarted| async move { + // As the shielded payment does: the record saved, marked, + // broadcast and admitted; then the result never comes. + let transition = private_contact_request_payment(entry); + arm_redrive_before_broadcast( + &store, + subwallet, + Some([0x77; 32]), + [7; 32], + vec![[1; 32]], + &transition, + "private document create from shielded pool", + None, + Some(&started), + 0, + ) + .await?; + std::future::pending::<()>().await; + Ok(ResponseMetadata::default()) + } + }; + let exited = tokio::time::timeout( + Duration::from_millis(200), + alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + pay, + ), + ) + .await; + assert!(exited.is_err(), "the process exits during the wait"); + drop(before); + + let after = coordinator_at(db_path); + let (_restarted_manager, restarted) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + assert_eq!(restarted.wallet_id(), alice_wallet.wallet_id()); + assert!(!pending_to(&restarted, ALICE, &bob).await); + let restored = restarted + .restore_pending_private_contact_requests(&after, &alice_crypto) + .await + .expect("restored from the saved record"); + assert_eq!(restored, vec![(alice.id(), bob.id())]); + assert!(pending_to(&restarted, ALICE, &bob).await); + let public = restarted + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + &alice_signer, + &alice_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "{public:?}" + ); + } + + /// Two accepts of one private request straddling the first reply's + /// settlement: the second read that no reply was sent before the first + /// ran, and reaches its reply after the first's was recorded and its + /// reservation settled. It adopts that reply, and its payment never runs. + #[tokio::test] + async fn should_adopt_a_reply_another_accept_recorded_in_between() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, received) = alice_to_bob([0x55; 43]).await; + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![entry]).await; + let view = bob_wallet.identity().dashpay(); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store"); + let first_done = Arc::new(tokio::sync::Notify::new()); + let reply = Arc::new(Mutex::new(Vec::new())); + + let second = view.accept_contact_request_replying_with(&received, &bob_crypto, || { + let first_done = Arc::clone(&first_done); + let (received, bob_signer, bob_crypto) = (&received, &bob_signer, &bob_crypto); + async move { + first_done.notified().await; + view.send_private_reply(received, None, bob_signer, bob_crypto, no_payment) + .await + } + }); + let first = async { + let accepted = view + .accept_private_contact_request( + &received, + None, + &bob_signer, + &bob_crypto, + append_entry(&bob_wallet, 1, vec![], &reply), + ) + .await; + first_done.notify_one(); + accepted + }; + let (second, first) = tokio::join!(second, first); + let first = first.expect("the first reply is paid and recorded"); + let second = second.expect("the second accept adopts it"); + assert_eq!(second.outgoing_request, first.outgoing_request); + assert_eq!(reply.lock().expect("reply").len(), 1, "one reply is paid"); + assert!(!pending_to(&bob_wallet, BOB, &alice).await); + } + + /// A `pay` that must not run. + fn no_payment( + _: BinaryData, + _: PaymentStarted, + ) -> std::future::Ready> { + panic!("nothing is paid") + } + + /// Whether `wallet`'s identity `identity_id` read the private store to its + /// end since load. + async fn store_read(wallet: &PlatformWallet, identity_id: [u8; 32]) -> bool { + managed(wallet, identity_id, |managed| { + managed.dashpay().private_contact_requests_read() + }) + .await + } + + /// A private reply paid for and confirmed but not read back leaves + /// nothing that survives a restart. After one, with Alice's request + /// already known (as a sync that stopped between the two leaves it), the + /// accept a host calls reads the store first, finds the reply, and adopts + /// it: nothing is paid twice. + #[tokio::test] + async fn should_adopt_a_private_reply_paid_for_before_a_restart() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let bob_signer = signer(BOB_PHRASE, &bob); + let (_alice_manager, alice_wallet) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + append_entry(&alice_wallet, 0, vec![], &kept), + ) + .await + .expect("Alice sends the request"); + let request_entry = kept.lock().expect("kept").remove(0); + + let (_bob_manager, before) = wallet( + BOB_PHRASE, + &bob, + &[&alice, &bob], + vec![request_entry.to_vec()], + ) + .await; + before + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("Bob reads the store"); + let received = managed(&before, BOB, |managed| { + managed.dashpay().incoming_request(&alice.id()).cloned() + }) + .await + .expect("Bob holds Alice's request"); + let reply = Arc::new(Mutex::new(Vec::new())); + let paid = before + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &received, + None, + &bob_signer, + &bob_crypto, + keep_entry(&reply), + ) + .await; + assert!( + matches!( + paid, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid and confirmed, not read back: {paid:?}" + ); + let reply_entry = reply.lock().expect("reply").remove(0); + + // The restart: the reply is in the store, the reservation is gone. + let (_restarted_manager, restarted) = wallet( + BOB_PHRASE, + &bob, + &[&alice, &bob], + vec![request_entry.to_vec(), reply_entry.to_vec()], + ) + .await; + { + let iw = restarted.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&restarted.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&bob.id()) + .expect("Bob") + .add_incoming_contact_request(received.clone(), &iw.persister) + .expect("Alice's request"); + } + assert!(!store_read(&restarted, BOB).await); + let established = restarted + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &received, + None, + &bob_signer, + &bob_crypto, + no_payment, + ) + .await + .expect("the reply read back is adopted"); + assert_eq!(established.contact_identity_id, alice.id()); + assert_eq!(established.incoming_request, received); + assert!(established.outgoing_request.came_privately()); + assert!(store_read(&restarted, BOB).await); + assert!(!pending_to(&restarted, BOB, &alice).await); + } + + /// Track `request` as an incoming request of `wallet`'s identity + /// `identity_id`, as a restarted wallet restores the public ones. + async fn add_incoming( + wallet: &PlatformWallet, + identity_id: [u8; 32], + request: &ContactRequest, + ) { + let iw = wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&Identifier::from(identity_id)) + .expect("managed identity") + .add_incoming_contact_request(request.clone(), &iw.persister) + .expect("incoming request"); + } + + /// A private reply to a public request, paid for and not read back, + /// leaves nothing that survives a restart. After one, before any sync, + /// a public send to the contact and the accept a host calls each read + /// the store first and find the reply: the send is refused, as the + /// pair's requests went privately, and the accept adopts the reply. + /// Nothing is broadcast or paid again. + #[tokio::test] + async fn should_not_reply_publicly_after_a_restart_with_a_private_reply_unread() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let incoming = public_request(&alice, &bob, 3); + let (_before_manager, before) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + add_incoming(&before, BOB, &incoming).await; + let reply = Arc::new(Mutex::new(Vec::new())); + let paid = before + .identity() + .dashpay() + .accept_private_contact_request( + &incoming, + None, + &bob_signer, + &bob_crypto, + keep_entry(&reply), + ) + .await; + assert!( + matches!( + paid, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid and confirmed, not read back: {paid:?}" + ); + let reply_entry = reply.lock().expect("reply").remove(0).to_vec(); + + // Restarted with the reply in the store: a public send first. + let (_sending_manager, sending) = + wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![reply_entry.clone()]).await; + add_incoming(&sending, BOB, &incoming).await; + let public = sending + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(contact)) + if contact == alice.id() + ), + "{public:?}" + ); + + // Restarted again: the accept a host calls first. + let (_accepting_manager, accepting) = + wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![reply_entry]).await; + add_incoming(&accepting, BOB, &incoming).await; + let established = accepting + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &incoming, + None, + &bob_signer, + &bob_crypto, + no_payment, + ) + .await + .expect("the private reply read back is adopted"); + assert_eq!(established.contact_identity_id, alice.id()); + assert_eq!(established.incoming_request, incoming); + assert!(established.outgoing_request.came_privately()); + } + + /// After a restart, before any sync, the accept a host calls reads the + /// store before it chooses the reply: a public request since followed by + /// a private one from the same sender, unread, takes a private reply, + /// where choosing from the public request alone would pick a public one + /// and refuse it once the store is read. + #[tokio::test] + async fn should_reply_privately_in_kind_once_a_restart_reads_a_private_request() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let bob_signer = signer(BOB_PHRASE, &bob); + let public = public_request(&alice, &bob, 3); + + // Alice's public request, then a private one to Bob. + let (_alice_manager, alice_wallet) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + { + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&alice_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("Alice") + .add_sent_contact_request(public.clone(), &iw.persister) + .expect("the public request"); + } + let kept = Arc::new(Mutex::new(Vec::new())); + alice_wallet + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + append_entry(&alice_wallet, 0, vec![], &kept), + ) + .await + .expect("Alice sends the private request"); + let private_entry = kept.lock().expect("kept").remove(0).to_vec(); + + // Bob, restarted, holds the public request; the private one is in the + // store, unread. + let (_bob_manager, bob_wallet) = + wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![private_entry]).await; + add_incoming(&bob_wallet, BOB, &public).await; + let reply = Arc::new(Mutex::new(Vec::new())); + let accepted = bob_wallet + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &public, + None, + &bob_signer, + &bob_crypto, + keep_entry(&reply), + ) + .await; + assert!( + matches!( + accepted, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "a private reply, paid and not read back: {accepted:?}" + ); + assert_eq!(reply.lock().expect("reply").len(), 1, "one reply is paid"); + } + + /// A private reply to a public request whose payment is unconfirmed when + /// the process ends is saved with the request it pays for: binding the + /// restarted wallet to its shielded coordinator reserves the pair again, + /// with no host call and no keys. Before any sync, neither the accept a + /// host calls nor a public send then goes to the contact. Before the + /// bind, the relaunched wallet, which bound its shielded account before, + /// refuses both too, with nothing sent: the reservation is not restored + /// yet. Once the reply's entry is appended and read back, the hold + /// resolves. A payment whose broadcast may have been delivered is saved + /// and kept exactly so (`settle_private_document_payment`). + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_not_reply_publicly_after_a_restart_with_a_private_reply_unconfirmed() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let incoming = public_request(&alice, &bob, 3); + let dir = tempfile::tempdir().expect("temporary shielded store"); + let db_path = dir.path().join("tree.sqlite"); + let coordinator_at = |db_path: std::path::PathBuf| { + let store = FileBackedShieldedStore::open_path(&db_path, 100).expect("open the store"); + Arc::new(NetworkShieldedCoordinator::new( + Arc::new(dash_sdk::Sdk::new_mock()), + Network::Testnet, + db_path, + store, + )) + }; + + let before_coordinator = coordinator_at(db_path.clone()); + let (_before_manager, before) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + add_incoming(&before, BOB, &incoming).await; + // What the backend keeps of the wallet, before the reply is paid. + let kept = Arc::new(snapshot(&before, &bob.id(), BOB_PHRASE).await); + let subwallet = SubwalletId::new(before.wallet_id(), 0); + let paid_entries = Arc::new(Mutex::new(Vec::new())); + let pay = { + let store = Arc::clone(before_coordinator.store()); + let paid_entries = Arc::clone(&paid_entries); + let (sender, recipient) = (bob.id(), alice.id()); + move |entry: BinaryData, started: PaymentStarted| async move { + paid_entries.lock().expect("paid").push(entry.clone()); + // As the shielded payment does: the record saved with the + // request it pays for, marked, broadcast; its result unknown. + let transition = private_contact_request_payment(entry); + let payment = PrivateContactPayment { + sender: sender.to_buffer(), + recipient: recipient.to_buffer(), + account_reference: started + .account_reference() + .expect("the send names its request"), + }; + arm_redrive_before_broadcast( + &store, + subwallet, + Some([0x77; 32]), + [7; 32], + vec![[1; 32]], + &transition, + "private document create from shielded pool", + Some(payment), + Some(&started), + 0, + ) + .await?; + Err::(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create", + reason: "the result wait timed out".to_string(), + }) + } + }; + let paid = before + .identity() + .dashpay() + .accept_private_contact_request(&incoming, None, &bob_signer, &bob_crypto, pay) + .await; + assert!( + matches!( + paid, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{paid:?}" + ); + drop(before_coordinator); + + // The restart: the reply is not in the store and the host restores + // nothing; only the bind can. + let after = coordinator_at(db_path); + let restarted_manager = PlatformWalletManager::new( + Arc::new(dashpay_sdk(&[&alice, &bob], vec![], PlatformVersion::latest(), None).await), + kept, + Arc::new(NoopEventHandler), + ); + restarted_manager + .load_from_persistor() + .await + .expect("the relaunch loads"); + let restarted = restarted_manager + .get_wallet(&before.wallet_id()) + .await + .expect("the relaunched wallet"); + assert!(!pending_to(&restarted, BOB, &alice).await); + + // Before the bind: refused, with nothing read or sent. + let accepted = restarted + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &incoming, + None, + &bob_signer, + &bob_crypto, + no_payment, + ) + .await; + assert!( + matches!( + accepted, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{accepted:?}" + ); + let public = restarted + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactPaymentsNotRestored) + ), + "{public:?}" + ); + + restarted + .bind_shielded(&seed(BOB_PHRASE), &[0], &after) + .await + .expect("bound"); + assert!( + pending_to(&restarted, BOB, &alice).await, + "the bind restores the reservation" + ); + // An identical rebind while a scan holds the store returns without + // waiting for it. The bind already restored from this store, so the + // wallet is not held again, and the pair stays held by its restored + // reservation. + { + let scan = after.store().write().await; + tokio::time::timeout( + Duration::from_secs(5), + restarted.bind_shielded(&seed(BOB_PHRASE), &[0], &after), + ) + .await + .expect("the rebind does not wait for the store") + .expect("rebound"); + assert!( + !restarted.private_payments_held().await, + "restored from this store already: not held again" + ); + assert!(pending_to(&restarted, BOB, &alice).await); + drop(scan); + } + assert!(!restarted.private_payments_held().await); + assert!(pending_to(&restarted, BOB, &alice).await); + + let accepted = restarted + .identity() + .dashpay() + .accept_contact_request_replying_in_kind( + &incoming, + None, + &bob_signer, + &bob_crypto, + no_payment, + ) + .await; + assert!( + matches!( + accepted, + Err(PlatformWalletError::PrivateContactRequestPending(contact)) + if contact == alice.id() + ), + "{accepted:?}" + ); + let public = restarted + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestPending(contact)) + if contact == alice.id() + ), + "{public:?}" + ); + + // Once the reply's entry is appended and read back, its reservation + // settles: the hold resolves. + let entry = paid_entries.lock().expect("paid").remove(0); + publish(&restarted, 0, vec![entry.to_vec()]).await; + restarted + .identity() + .dashpay() + .sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("the store is read"); + assert!( + !pending_to(&restarted, BOB, &alice).await, + "settled once read back" + ); + // Read back and recorded durably, its journal record is discharged: + // the next restoration finds none, and the pair stays free. + restarted + .restore_private_contact_payments(&after) + .await + .expect("restored"); + assert!( + after + .store() + .read() + .await + .private_payment_journal(restarted.wallet_id()) + .expect("the journal") + .is_empty(), + "discharged once read back" + ); + assert!(!pending_to(&restarted, BOB, &alice).await); + } + + /// A payment saved with its request is restored only while neither that + /// request nor a later one is recorded: a request read back before the + /// restart discharges it, a rotation past the tracked request does not, + /// and a sender that is not the wallet's identity is skipped. + #[cfg(feature = "shielded")] + #[tokio::test] + async fn should_restore_a_saved_payment_only_while_its_request_is_unrecorded() { + use platform_encryption::ACCOUNT_REFERENCE_VERSION_SHIFT; + + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + let reference = 5; + let rotated = reference | (1 << ACCOUNT_REFERENCE_VERSION_SHIFT); + { + let iw = bob_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&bob_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&bob.id()) + .expect("Bob") + .add_sent_contact_request(public_request(&bob, &alice, reference), &iw.persister) + .expect("sent request"); + } + let view = bob_wallet.identity().dashpay(); + + let recorded = view + .restore_private_payments( + &[ + (bob.id(), alice.id(), reference, [9; 32], None), + (alice.id(), bob.id(), reference, [8; 32], None), + ], + true, + ) + .await + .expect("restore"); + assert!(recorded.is_empty(), "{recorded:?}"); + assert!(!pending_to(&bob_wallet, BOB, &alice).await); + + let rotation = view + .restore_private_payments(&[(bob.id(), alice.id(), rotated, [9; 32], None)], true) + .await + .expect("restore"); + assert_eq!(rotation, vec![(bob.id(), alice.id())]); + assert!(pending_to(&bob_wallet, BOB, &alice).await); + } + + /// On a network a verified answer shows below protocol version 15 there + /// is no private store to read: a public send goes on to its broadcast, + /// as it did before private contact requests, rather than being refused + /// for a read that cannot run. + #[tokio::test] + async fn should_send_publicly_on_a_network_below_protocol_version_15() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (_manager, bob_wallet) = wallet_at( + Arc::new(NoPersistence), + BOB_PHRASE, + &bob, + &[&alice, &bob], + vec![], + PlatformVersion::get(14).expect("protocol version 14"), + Some(14), + ) + .await; + let sent = bob_wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + // Past the read and the claim: the transition is being built, and + // this mock does not answer its nonce fetch. + assert!( + matches!(&sent, Err(PlatformWalletError::Sdk(error)) + if error.to_string().contains("GetIdentityContractNonceRequest")), + "the send goes on to its transition: {sent:?}" + ); + assert!(!store_read(&bob_wallet, BOB).await, "nothing was read"); + } + + /// An SDK pinned below protocol version 15 refuses to read the private + /// store whatever the network runs. On a network a verified answer shows + /// at 15, or one whose version is not verified, the store may hold a + /// private request, so a public send is refused with that refusal and + /// sends nothing. + #[tokio::test] + async fn should_refuse_a_public_send_from_an_sdk_pinned_below_a_network_at_15() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + for verified_network in [Some(15), None] { + let (_manager, bob_wallet) = wallet_at( + Arc::new(NoPersistence), + BOB_PHRASE, + &bob, + &[&alice, &bob], + vec![], + PlatformVersion::get(14).expect("protocol version 14"), + verified_network, + ) + .await; + let sent = bob_wallet + .identity() + .dashpay() + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + &sent, + Err(PlatformWalletError::Sdk( + dash_sdk::Error::ProtocolVersionNotActive { .. } + )) + ), + "verified {verified_network:?}: {sent:?}" + ); + } + } + + /// A public request's claim is released only by its own attempt: a send + /// that outlived its wallet's removal and re-creation under the same id, + /// dropped once the new wallet's send claimed the same pair, leaves that + /// claim in place, and the new send's own release frees the pair. + #[tokio::test] + async fn should_release_only_its_own_claim_across_a_wallet_re_creation() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let (manager, old_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let old_claim = old_wallet + .identity() + .dashpay() + .claim_public_pair(&alice.id(), &bob.id(), false, false) + .await + .expect("claimed") + .expect("a claim"); + + manager + .remove_wallet(&old_wallet.wallet_id()) + .await + .expect("removed"); + let new_wallet = manager + .create_wallet_from_seed_bytes( + Network::Testnet, + &seed(ALICE_PHRASE), + WalletAccountCreationOptions::Default, + Some(0), + ) + .await + .expect("re-created"); + assert_eq!(new_wallet.wallet_id(), old_wallet.wallet_id()); + { + let iw = new_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&new_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .add_identity(alice.clone(), 0, new_wallet.wallet_id(), &iw.persister) + .expect("own identity"); + } + let new_claim = new_wallet + .identity() + .dashpay() + .claim_public_pair(&alice.id(), &bob.id(), false, false) + .await + .expect("claimed") + .expect("a claim"); + let claimed = || async { + managed(&new_wallet, ALICE, |managed| { + managed.dashpay().public_contact_request_claimed(&bob.id()) + }) + .await + }; + + drop(old_claim); + assert!( + claimed().await, + "the old send's release leaves the new claim" + ); + drop(new_claim); + assert!(!claimed().await, "the new send's release frees the pair"); + } + + /// Unignoring a sender rewinds the private read and clears its + /// readiness: a pass that read the store with the sender ignored passed + /// over its private request, so a public send to it reads the store + /// again first, finds the request, and is refused, publishing nothing. + #[tokio::test] + async fn should_read_the_store_again_before_a_public_send_once_a_sender_is_unignored() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![entry]).await; + let view = bob_wallet.identity().dashpay(); + view.ignore_contact_sender(&bob.id(), &alice.id()) + .await + .expect("ignored"); + view.sync_private_contact_requests(&bob_crypto, 4) + .await + .expect("the pass"); + assert!(store_read(&bob_wallet, BOB).await); + assert!( + managed(&bob_wallet, BOB, |managed| { + managed.dashpay().incoming_request(&alice.id()).is_none() + }) + .await, + "passed over while ignored" + ); + + view.unignore_contact_sender(&bob.id(), &alice.id()) + .await + .expect("unignored"); + assert!(!store_read(&bob_wallet, BOB).await, "read again first"); + let public = view + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(contact)) + if contact == alice.id() + ), + "{public:?}" + ); + } + + /// A sender unignored while a pass runs, after the pass passed over its + /// private request: the pass reaches the store's end without taking the + /// store as read, so a public send to the sender reads it again first, + /// finds the request, and is refused, publishing nothing. + #[tokio::test] + async fn should_not_take_the_store_as_read_by_a_pass_a_sender_was_unignored_under() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let bob_crypto = SeedCryptoProvider::from_seed(seed(BOB_PHRASE), Network::Testnet); + let bob_signer = signer(BOB_PHRASE, &bob); + let (entry, _) = alice_to_bob([0x55; 43]).await; + // Alice's request first, then pages enough for a second scan batch. + let mut entries = vec![entry]; + entries.extend((1..=PRIVATE_SCAN_BATCH_PAGES as u8).map(|byte| vec![byte; 589])); + let (_manager, bob_wallet) = wallet(BOB_PHRASE, &bob, &[&alice, &bob], vec![]).await; + publish_chunked(&bob_wallet, &entries, 1).await; + let view = bob_wallet.identity().dashpay(); + view.ignore_contact_sender(&bob.id(), &alice.id()) + .await + .expect("ignored"); + + // Unignored before the pass scans its second batch, once the first, + // holding Alice's request, was ingested with her ignored. + let mut unignoring = HookedCrypto::new(BOB_PHRASE); + unignoring.before_scan = Some({ + let bob_wallet = Arc::clone(&bob_wallet); + let scans = Arc::new(std::sync::atomic::AtomicUsize::new(0)); + let (bob_id, alice_id) = (bob.id(), alice.id()); + Arc::new(move || { + let (bob_wallet, scans) = (Arc::clone(&bob_wallet), Arc::clone(&scans)); + Box::pin(async move { + if scans.fetch_add(1, Ordering::SeqCst) == 1 { + bob_wallet + .identity() + .dashpay() + .unignore_contact_sender(&bob_id, &alice_id) + .await + .expect("unignored"); + } + }) + }) + }); + view.sync_private_contact_requests(&unignoring, 64) + .await + .expect("the pass"); + assert!( + !store_read(&bob_wallet, BOB).await, + "not read for a sender unignored under the pass" + ); + + let public = view + .send_contact_request_with_external_signer( + &bob.id(), + &alice.id(), + None, + AutoAcceptProofSource::None, + &bob_signer, + &bob_crypto, + ) + .await; + assert!( + matches!( + public, + Err(PlatformWalletError::PrivateContactRequestNeedsPrivateReply(contact)) + if contact == alice.id() + ), + "{public:?}" + ); + } + + /// A private send reads the store to its end first. While that read cannot + /// finish, here because the recipient of a request the store holds from + /// Alice cannot be read, it is refused as not read, with nothing reserved, + /// sealed or paid; a sync error comes back as it is; once the store reads, + /// the send goes on. + #[tokio::test] + async fn should_refuse_a_private_send_until_the_store_reads_to_its_end() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, before) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let kept = Arc::new(Mutex::new(Vec::new())); + before + .identity() + .dashpay() + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry(&kept), + ) + .await + .expect_err("not read back"); + let entry = kept.lock().expect("kept").remove(0); + + let (_restarted_manager, restarted) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![entry.to_vec()]).await; + let view = restarted.identity().dashpay(); + macro_rules! send { + ($pay:expr) => { + view.send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + $pay, + ) + .await + }; + } + + set_identity_known(&restarted, &bob, false).await; + let held = send!(no_payment); + assert!( + matches!(held, Err(PlatformWalletError::PrivateContactStoreNotRead(identity)) + if identity == alice.id()), + "{held:?}" + ); + assert!(!store_read(&restarted, ALICE).await); + assert!( + !pending_to(&restarted, ALICE, &bob).await, + "nothing reserved" + ); + + let contract = dashpay_contract().expect("bundled DashPay"); + let page = PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + 0, + ); + { + let mut sdk = (*restarted.identity().sdk).clone(); + sdk.mock() + .remove_fetch_expectation::(page) + .await; + } + let failed = send!(no_payment); + assert!( + matches!(failed, Err(PlatformWalletError::Sdk(_))), + "{failed:?}" + ); + + publish(&restarted, 0, vec![entry.to_vec()]).await; + set_identity_known(&restarted, &bob, true).await; + let paid = Arc::new(Mutex::new(Vec::new())); + let sent = send!(keep_entry(&paid)); + assert!( + matches!( + sent, + Err(PlatformWalletError::PrivateContactRequestPending(_)) + ), + "paid, not read back: {sent:?}" + ); + assert_eq!(paid.lock().expect("paid").len(), 1, "the send goes on"); + assert!(store_read(&restarted, ALICE).await); + managed(&restarted, ALICE, |managed| { + assert!( + managed.dashpay().outgoing_request(&bob.id()).is_some(), + "the request paid for before the restart is recorded first" + ); + }) + .await; + } + + /// Every private send reads the store from its cursor before it pays, not + /// only the first since load: once a page read fails, a later send pays + /// nothing and the read's error comes back. + #[tokio::test] + async fn should_read_the_private_store_before_every_private_send() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let carol = identity(BOB_PHRASE, [0xC1; 32]); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = + wallet(ALICE_PHRASE, &alice, &[&alice, &bob, &carol], vec![]).await; + let view = alice_wallet.identity().dashpay(); + macro_rules! send { + ($recipient:expr, $kept:expr) => { + view.send_private_contact_request( + &alice.id(), + &$recipient, + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + keep_entry($kept), + ) + .await + }; + } + assert!(!store_read(&alice_wallet, ALICE).await); + let read_when_paid = Arc::new(AtomicBool::new(false)); + view.send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + |_: BinaryData, started: PaymentStarted| { + started.mark(); + let read_when_paid = Arc::clone(&read_when_paid); + let wallet = &alice_wallet; + async move { + read_when_paid.store(store_read(wallet, ALICE).await, Ordering::SeqCst); + Ok(ResponseMetadata { + time_ms: BLOCK_TIME_MS, + ..Default::default() + }) + } + }, + ) + .await + .expect_err("not read back"); + assert!( + read_when_paid.load(Ordering::SeqCst), + "the store was read before the first payment" + ); + + let contract = dashpay_contract().expect("bundled DashPay"); + { + let mut sdk = (*alice_wallet.identity().sdk).clone(); + sdk.mock() + .remove_fetch_expectation::( + PrivateDocumentEntriesQuery::new( + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + 0, + ), + ) + .await; + } + let second = Arc::new(Mutex::new(Vec::new())); + let sent = send!(carol.id(), &second); + assert!( + matches!(sent, Err(PlatformWalletError::Sdk(_))), + "the read before paying fails: {sent:?}" + ); + assert!(second.lock().expect("second").is_empty(), "nothing paid"); + assert!(!pending_to(&alice_wallet, ALICE, &carol).await); + } + + /// Once the account reference's rotation version is at its last, a + /// request with the same xpub and key would repeat the tracked one: it is + /// refused before anything is paid, and nothing stays pending. + #[tokio::test] + async fn should_refuse_a_request_once_every_rotation_version_is_used() { + let alice = identity(ALICE_PHRASE, ALICE); + let bob = identity(BOB_PHRASE, BOB); + let alice_crypto = SeedCryptoProvider::from_seed(seed(ALICE_PHRASE), Network::Testnet); + let alice_signer = signer(ALICE_PHRASE, &alice); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[&alice, &bob], vec![]).await; + let view = alice_wallet.identity().dashpay(); + let kept = Arc::new(Mutex::new(Vec::new())); + let sent = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + append_entry(&alice_wallet, 0, vec![], &kept), + ) + .await + .expect("Alice sends the request, read back"); + assert_eq!(account_reference_version(sent.account_reference), 0); + + let mut exhausted = sent.clone(); + exhausted.account_reference = (sent.account_reference & 0x0FFF_FFFF) | (15 << 28); + assert_eq!(account_reference_version(exhausted.account_reference), 15); + { + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + wm.get_wallet_info_mut(&alice_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("Alice") + .add_sent_contact_request(exhausted, &iw.persister) + .expect("the version 15 request"); + } + + let result = view + .send_private_contact_request( + &alice.id(), + &bob.id(), + None, + AutoAcceptProofSource::None, + None, + &alice_signer, + &alice_crypto, + |_: BinaryData, _: PaymentStarted| -> std::future::Ready> { + panic!("a request that repeats the tracked one is not paid for") + }, + ) + .await; + assert!( + matches!(&result, Err(PlatformWalletError::InvalidParameter(message)) + if message.contains("no account reference version is left")), + "{result:?}" + ); + assert!(!pending_to(&alice_wallet, ALICE, &bob).await); + } + + /// A cursor rewound under a pass is not advanced again that pass, so the + /// next reads from the rewind. + #[tokio::test] + async fn should_keep_a_cursor_rewound_under_a_pass() { + let alice = identity(ALICE_PHRASE, ALICE); + let (_manager, alice_wallet) = wallet(ALICE_PHRASE, &alice, &[], vec![]).await; + let iw = alice_wallet.identity(); + let mut wm = iw.wallet_manager.write().await; + let managed = wm + .get_wallet_info_mut(&alice_wallet.wallet_id()) + .expect("wallet info") + .identity_manager + .managed_identity_mut(&alice.id()) + .expect("Alice"); + let mut scanned = ScannedIdentity { + key_fingerprint: managed.private_scan_key_fingerprint(), + identity_id: alice.id(), + identity_index: 0, + position: 0, + failed: false, + rewound: false, + }; + scanned.advance(managed, 100); + assert_eq!(managed.dashpay().private_contact_requests_position(), 100); + // Unignoring a sender rewinds the cursor while a page is read. + let carol = Identifier::from([0xC1; 32]); + managed.ignore_sender(&carol); + managed.unignore_sender(&carol); + assert_eq!(managed.dashpay().private_contact_requests_position(), 0); + scanned.advance(managed, 200); + scanned.advance(managed, 300); + assert_eq!( + managed.dashpay().private_contact_requests_position(), + 0, + "the rewind stands for the rest of the pass" + ); + assert!(scanned.rewound); + } + + /// The record of a private request rebuilds byte for byte from the same + /// entry, and another entry's record encrypts under other IVs. + #[test] + fn should_record_a_private_request_the_same_way_every_time() { + let request = PrivateContactRequest { + account_reference: 7, + extended_public_key: [0x33; COMPACT_XPUB_LEN], + account_label: Some("label".to_string()), + auto_accept_proof: None, + shielded_address: None, + }; + let record = |commitment: [u8; 32]| { + private_request_record( + Identifier::from(ALICE), + Identifier::from(BOB), + 1, + 2, + &request, + &commitment, + &[9; 32], + BLOCK_TIME_MS, + ) + }; + assert_eq!(record([1; 32]), record([1; 32])); + assert!(record([1; 32]).came_privately()); + assert_ne!( + record([1; 32]).encrypted_public_key, + record([2; 32]).encrypted_public_key, + "another entry encrypts under other IVs" + ); + assert_eq!( + decrypt_extended_public_key(&[9; 32], &record([1; 32]).encrypted_public_key) + .expect("the xpub opens"), + vec![0x33; COMPACT_XPUB_LEN] + ); + } +} diff --git a/packages/rs-platform-wallet/src/wallet/identity/network/sdk_writer.rs b/packages/rs-platform-wallet/src/wallet/identity/network/sdk_writer.rs index 765074e7b7a..cb4bdf12651 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/network/sdk_writer.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/network/sdk_writer.rs @@ -1,9 +1,9 @@ //! Concrete helper over the SDK's DashPay write/broadcast surface. //! //! The two operations `IdentityWallet` performs over the SDK — -//! [`Sdk::send_contact_request`](dash_sdk::Sdk::send_contact_request) +//! [`Sdk::sign_contact_request`](dash_sdk::Sdk::sign_contact_request) //! and a document put — cannot be expressed as plain method calls at -//! the call sites: `send_contact_request` is generic over **seven** +//! the call sites: `sign_contact_request` is generic over **seven** //! type parameters (the signer plus three ECDH/xpub closure pairs) and //! the document put rides on the signer-generic //! [`PutDocument`](dash_sdk::platform::transition::put_document::PutDocument) @@ -28,7 +28,7 @@ use dpp::identity::{Identity, IdentityPublicKey}; use dash_sdk::dapi_grpc::platform::v0::ResponseMetadata; use dash_sdk::platform::dashpay::{ ContactRequestInput, EcdhProvider, RecipientIdentity, SendContactRequestInput, - SendContactRequestResult, + SignedContactRequest, }; use crate::error::PlatformWalletError; @@ -150,7 +150,7 @@ pub(crate) struct PutDocumentParams<'a> { /// /// Held as a field on [`IdentityWallet`](super::IdentityWallet), /// forwarding to the real SDK. Its two methods erase the SDK's -/// generic write signatures (`send_contact_request`'s seven type +/// generic write signatures (`sign_contact_request`'s seven type /// params, the signer-generic `PutDocument`) behind concrete, by-value /// inputs so the call sites in `contact_requests.rs` / /// `contact_info.rs` stay simple. @@ -179,11 +179,13 @@ impl SdkWriter { } /// Build the ECDH provider + xpub closure from the pre-derived - /// inputs and broadcast the contact-request document. - pub(crate) async fn send_contact_request( + /// inputs and sign the contact-request document's create transition, + /// which the caller broadcasts: it keeps the signed bytes, so a retry + /// broadcasts the same transition rather than signing a second request. + pub(crate) async fn sign_contact_request( &self, params: SendContactRequestParams<'_>, - ) -> Result { + ) -> Result { let SendContactRequestParams { sender_identity, recipient_identity, @@ -247,7 +249,7 @@ impl SdkWriter { let xpub_bytes_clone = xpub_bytes.clone(); self.sdk - .send_contact_request(send_input, ecdh_provider, |_account_ref: u32| async move { + .sign_contact_request(send_input, ecdh_provider, |_account_ref: u32| async move { Ok::, dash_sdk::Error>(xpub_bytes_clone) }) .await diff --git a/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/contact_requests.rs b/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/contact_requests.rs index b16b60ca532..ac70cc4f35a 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/contact_requests.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/contact_requests.rs @@ -5,15 +5,35 @@ //! - Receiving contact requests (incoming) //! - Automatically establishing contacts when both parties send requests +use super::dashpay::{PendingPrivateReply, UnconfirmedPublicRequest}; use super::ManagedIdentity; use crate::changeset::{ - ContactChangeSet, ContactRequestEntry, ReceivedContactRequestKey, SentContactRequestKey, + ContactChangeSet, ContactRequestEntry, PrivateContactRequestsPosition, + ReceivedContactRequestKey, SentContactRequestKey, }; use crate::wallet::identity::crypto::contact_info::ContactInfoPrivateData; use crate::wallet::persister::WalletPersister; use crate::{ContactRequest, EstablishedContact}; +use dpp::identity::accessors::IdentityGettersV0; +use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; +use dpp::identity::{KeyType, Purpose}; use dpp::prelude::Identifier; +use dpp::state_transition::StateTransition; +use key_wallet::bip32::ExtendedPubKey; use platform_encryption::account_reference_version; +use sha2::{Digest, Sha256}; +use std::sync::atomic::{AtomicU64, Ordering}; + +/// The attempt id the next private request reservation or public request +/// claim takes. Process-wide, so a handle that outlived its wallet's removal +/// and re-creation under the same id cannot release a reservation or a claim +/// the new wallet made. +static NEXT_CONTACT_REQUEST_ATTEMPT: AtomicU64 = AtomicU64::new(0); + +/// A new attempt id ([`NEXT_CONTACT_REQUEST_ATTEMPT`]). +fn next_contact_request_attempt() -> u64 { + NEXT_CONTACT_REQUEST_ATTEMPT.fetch_add(1, Ordering::Relaxed) +} impl ManagedIdentity { /// The masked `accountReference` of the most recent request WE sent @@ -376,6 +396,11 @@ impl ManagedIdentity { // Rewind the receive cursor so the next sweep re-fetches the // now-un-ignored sender's on-chain requests. self.dashpay.high_water_received_ms = None; + // A pass that read the store to its end passed over the sender's + // private requests: the store is not read for this identity until a + // pass reads it again from the rewound position, so a send reads it + // first. + self.rewind_private_store_read(); let mut cs = ContactChangeSet::default(); cs.unignored.insert((owner_id, *sender_id)); @@ -791,6 +816,463 @@ impl ManagedIdentity { advance_if_unchanged(self.dashpay.high_water_received_ms, snapshot, max_fetched); } + /// Note that a private sync read DashPay's private contact request store + /// to its end for this identity, with nothing held back, the page that + /// reached the end proved at `end_height` or above (the lowest height of + /// its reads): counted only when that is at or above the height a rewind + /// left as its floor (`DashPayState::private_store_read_floor`), so a read + /// whose end comes from a node behind the store already seen does not + /// count, whatever the heights of the pages before it. Returns whether it + /// counted. + pub(crate) fn note_private_contact_requests_read(&mut self, end_height: u64) -> bool { + let dashpay = &mut self.dashpay; + let counted = dashpay + .private_store_read_floor + .is_none_or(|floor| end_height >= floor); + if counted { + dashpay.private_contact_requests_read = true; + } + counted + } + + /// Rewind this identity's read of DashPay's private contact request + /// store to its start: the position goes back to 0, the read is no longer + /// read to the end, and the height it rested on is reset, kept as the + /// floor a read since must reach (`DashPayState::private_store_read_floor`). + fn rewind_private_store_read(&mut self) { + let dashpay = &mut self.dashpay; + dashpay.private_contact_requests_position = 0; + dashpay.private_contact_requests_read = false; + if let Some(read) = dashpay.private_store_read_height.take() { + dashpay.private_store_read_floor = Some( + dashpay + .private_store_read_floor + .map_or(read, |floor| floor.max(read)), + ); + } + } + + /// Rewind this identity's read of DashPay's private contact request + /// store to `position` when it is past it, as + /// [`Self::rewind_private_store_read`] rewinds it to 0: the read is no + /// longer to the end, and the height it rested on becomes the floor a + /// read since must reach. Returns whether it moved. A restoration rewinds + /// to the position a journal record kept, so a private payment whose + /// request the identity does not track has its entry read again. + #[cfg(feature = "shielded")] + pub(crate) fn rewind_private_store_read_to(&mut self, position: u64) -> bool { + if self.dashpay.private_contact_requests_position <= position { + return false; + } + self.rewind_private_store_read(); + self.dashpay.private_contact_requests_position = position; + true + } + + /// Note that a private sync read a page of DashPay's private contact + /// request store, proved at `height`, for this identity + /// (`DashPayState::private_store_read_height`). + pub(crate) fn note_private_store_page_read(&mut self, height: u64) { + let read = &mut self.dashpay.private_store_read_height; + *read = Some(read.map_or(height, |read| read.max(height))); + } + + /// [`Self::note_private_contact_requests_read`], for tests outside this + /// crate that read an identity's state after a private sync. + #[cfg(any(test, feature = "test-utils"))] + pub fn note_private_contact_requests_read_for_tests(&mut self) { + self.dashpay.private_contact_requests_read = true; + } + + /// Advance the private contact request cursor to `next_position` once + /// every entry before it was read and what it held for this identity + /// ingested. Never moves it back, and leaves it where a concurrent + /// [`Self::unignore_sender`] rewound it from `snapshot`. + pub(crate) fn advance_private_contact_requests_position( + &mut self, + snapshot: u64, + next_position: u64, + ) { + let position = &mut self.dashpay.private_contact_requests_position; + if *position == snapshot && next_position > snapshot { + *position = next_position; + } + } + + /// Restore the position of DashPay's private contact request store this + /// identity reads from next, as a backend persisted it + /// (`ContactChangeSet::private_contact_requests_positions`): the loader's + /// replay, for a backend attesting + /// [`PRIVATE_CONTACT_REQUEST_SCAN_STATE`](crate::changeset::PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE). + /// The record replayed last decides the identity's load-time hold, so a + /// later record cleared lifts an earlier marked one; the live + /// per-recipient reservations are left alone, and a restoration from + /// the shielded store's journal holds every pair whose payment may still + /// execute whatever the marker says. + pub fn apply_private_contact_requests_position( + &mut self, + position: PrivateContactRequestsPosition, + ) { + self.dashpay.private_contact_requests_position = position.position; + self.dashpay.private_scan_keys = Some(position.key_fingerprint); + self.dashpay.private_payments_unrestored = position.private_payments_unresolved; + } + + /// Hold this identity as a load holds one whose position record is + /// marked (`DashPayState::private_payments_unrestored`): a persister kept + /// its record marked though the identity was added afresh, with no + /// reservation or record of the payment the marker stands for, as after + /// its wallet was removed and registered again. Only the hold is taken: + /// the record's read position covers requests that went with the wallet's + /// other rows, so the store is read for the identity from its start. + pub(crate) fn hold_for_retained_private_payment_marker(&mut self) { + self.dashpay.private_payments_unrestored = true; + } + + /// The reservations of this identity's private payments from an earlier + /// process are restored from the shielded store: release the hold a load + /// set ([`DashPayState::private_payments_unrestored`]). Returns whether it + /// was set, so the caller stores the record it changed. + /// + /// [`DashPayState::private_payments_unrestored`]: super::DashPayState::private_payments_unrestored + #[cfg(feature = "shielded")] + pub(crate) fn note_private_payments_restored(&mut self) -> bool { + std::mem::take(&mut self.dashpay.private_payments_unrestored) + } + + /// The fingerprint of the keys a private sync scans DashPay's private + /// contact request store with for this identity: SHA-256 over its HD + /// index and each `ECDSA_SECP256K1` `ENCRYPTION` or `DECRYPTION` key, by + /// id, purpose and data, in key id order. Disabled keys count, as an + /// entry sealed before a key was disabled still opens with it. + pub fn private_scan_key_fingerprint(&self) -> [u8; 32] { + let mut hasher = Sha256::new(); + match self.identity_index { + Some(index) => { + hasher.update([1]); + hasher.update(index.to_le_bytes()); + } + None => hasher.update([0]), + } + for (key_id, key) in self.identity.public_keys() { + if key.key_type() != KeyType::ECDSA_SECP256K1 + || !matches!(key.purpose(), Purpose::ENCRYPTION | Purpose::DECRYPTION) + { + continue; + } + let data = key.data().as_slice(); + hasher.update(key_id.to_le_bytes()); + hasher.update([key.purpose() as u8]); + hasher.update((data.len() as u64).to_le_bytes()); + hasher.update(data); + } + hasher.finalize().into() + } + + /// Tie the private read position and the read-to-the-end flag to the + /// identity's scanning keys: when the keys no longer match the ones they + /// hold for, entries to or from a key added since were never opened, so + /// both are rewound to read the store again from 0. Returns the position + /// record to store when it changed. + pub(crate) fn reconcile_private_scan_keys(&mut self) -> Option { + let key_fingerprint = self.private_scan_key_fingerprint(); + if self.dashpay.private_scan_keys == Some(key_fingerprint) { + return None; + } + if self.dashpay.private_scan_keys.is_some() + || self.dashpay.private_contact_requests_position > 0 + { + self.rewind_private_store_read(); + } + self.dashpay.private_scan_keys = Some(key_fingerprint); + Some(self.private_contact_requests_position_record()) + } + + /// The private read position as a backend stores it: with the + /// fingerprint of the keys it holds for, and whether a private payment of + /// this identity may be unresolved + /// ([`DashPayState::private_payments_unresolved`]). + /// + /// [`DashPayState::private_payments_unresolved`]: super::DashPayState::private_payments_unresolved + pub(crate) fn private_contact_requests_position_record( + &self, + ) -> PrivateContactRequestsPosition { + PrivateContactRequestsPosition { + position: self.dashpay.private_contact_requests_position, + key_fingerprint: self + .dashpay + .private_scan_keys + .unwrap_or_else(|| self.private_scan_key_fingerprint()), + private_payments_unresolved: self.dashpay.private_payments_unresolved(), + } + } + + /// Restore the shielded address `contact`'s tracked private request to + /// this identity carries, as a backend persisted it + /// (`ContactChangeSet::private_shielded_addresses`): the loader's replay. + pub fn apply_private_shielded_address(&mut self, contact: Identifier, address: [u8; 43]) { + self.dashpay + .private_shielded_addresses + .insert(contact, address); + } + + /// Replay a persisted removal of `contact`'s shielded address + /// (`ContactChangeSet::removed_private_shielded_addresses`). + pub fn apply_removed_private_shielded_address(&mut self, contact: &Identifier) { + self.dashpay.private_shielded_addresses.remove(contact); + } + + /// Drop the private contact request scan state a load restored, for a + /// backend that does not attest it persists it: the store is read from + /// its start, and the addresses come back with the requests that carry + /// them. A restored hold on an unresolved private payment + /// ([`DashPayState::private_payments_unrestored`]) is kept: a backend that + /// handed one back kept it when it attested the capability, and dropping + /// it would let the identity publish the pair while the payment may still + /// execute. Kept, it holds until a restoration clears it. + /// + /// [`DashPayState::private_payments_unrestored`]: super::DashPayState::private_payments_unrestored + pub(crate) fn forget_private_contact_scan_state(&mut self) { + self.dashpay.private_contact_requests_position = 0; + self.dashpay.private_scan_keys = None; + self.dashpay.private_shielded_addresses.clear(); + } + + /// Record the shielded address `request`, a private request from + /// `request.sender_id`, carries, when it is the request tracked from that + /// contact: an older request ingest passed over does not replace the + /// address of the newer one. + pub(crate) fn note_private_shielded_address( + &mut self, + request: &ContactRequest, + shielded_address: Option<[u8; 43]>, + ) { + let tracked = self + .dashpay + .incoming_request(&request.sender_id) + .is_some_and(|tracked| { + tracked.came_privately() + && tracked.account_reference == request.account_reference + && tracked.encrypted_public_key == request.encrypted_public_key + }); + if !tracked { + return; + } + match shielded_address { + Some(address) => { + self.dashpay + .private_shielded_addresses + .insert(request.sender_id, address); + } + None => { + self.dashpay + .private_shielded_addresses + .remove(&request.sender_id); + } + } + } + + /// Reserve the one private request to `recipient` that may be in flight, + /// returning the attempt that holds it; `None` when one already is. See + /// [`DashPayState::private_reply_pending`](super::DashPayState::private_reply_pending). + pub(crate) fn reserve_private_reply(&mut self, recipient: Identifier) -> Option { + // A public request being sent to the recipient, or one unconfirmed, + // holds the pair too. + if self + .dashpay + .pending_private_replies + .contains_key(&recipient) + || self + .dashpay + .public_contact_request_claims + .contains_key(&recipient) + || self + .dashpay + .unconfirmed_public_requests + .contains_key(&recipient) + { + return None; + } + Some(self.insert_private_reply(recipient, None)) + } + + /// Claim the pair with `recipient` for a public request about to be + /// sent, under a new attempt it returns: until that attempt releases it + /// ([`Self::release_public_contact_request`]), no private request to the + /// recipient is reserved. Concurrent public sends each hold their own. + pub(crate) fn claim_public_contact_request(&mut self, recipient: Identifier) -> u64 { + let attempt = next_contact_request_attempt(); + self.dashpay + .public_contact_request_claims + .entry(recipient) + .or_default() + .insert(attempt); + attempt + } + + /// Release the claim `attempt` took ([`Self::claim_public_contact_request`]); + /// another attempt's claim on the pair stays. + pub(crate) fn release_public_contact_request(&mut self, recipient: &Identifier, attempt: u64) { + if let Some(claims) = self + .dashpay + .public_contact_request_claims + .get_mut(recipient) + { + claims.remove(&attempt); + if claims.is_empty() { + self.dashpay.public_contact_request_claims.remove(recipient); + } + } + } + + /// Hold the pair with `recipient` for the public request `transition` + /// signs, whose broadcast may have been delivered, under a new attempt it + /// returns: until that attempt settles it + /// ([`Self::settle_unconfirmed_public_request`]), no other request to the + /// recipient is signed, public or private. A request already held for the + /// recipient is replaced, as only one can be signed while another is held. + pub(crate) fn hold_unconfirmed_public_request( + &mut self, + recipient: Identifier, + transition: StateTransition, + account_reference: u32, + account_index: u32, + contact_xpub: ExtendedPubKey, + ) -> u64 { + let attempt = next_contact_request_attempt(); + self.dashpay.unconfirmed_public_requests.insert( + recipient, + UnconfirmedPublicRequest { + attempt, + transition, + account_reference, + account_index, + contact_xpub, + }, + ); + attempt + } + + /// Settle the unconfirmed public request `attempt` holds to `recipient`: + /// a proved read showed its document on Platform, or showed the + /// transition can no longer write it. Nothing when another attempt holds + /// the recipient by now. + pub(crate) fn settle_unconfirmed_public_request( + &mut self, + recipient: &Identifier, + attempt: u64, + ) { + if self + .dashpay + .unconfirmed_public_requests + .get(recipient) + .is_some_and(|held| held.attempt == attempt) + { + self.dashpay.unconfirmed_public_requests.remove(recipient); + } + } + + /// Reserve `recipient` under a new attempt, `commitment` its entry's. + fn insert_private_reply(&mut self, recipient: Identifier, commitment: Option<[u8; 32]>) -> u64 { + let attempt = next_contact_request_attempt(); + self.dashpay.pending_private_replies.insert( + recipient, + PendingPrivateReply { + attempt, + commitment, + }, + ); + attempt + } + + /// Note the commitment of the entry `attempt` sealed its request to + /// `recipient` as, which the private sync settles it by. Nothing when the + /// recipient is not reserved by that attempt. + pub(crate) fn note_private_reply_commitment( + &mut self, + recipient: Identifier, + attempt: u64, + commitment: [u8; 32], + ) { + if let Some(pending) = self + .dashpay + .pending_private_replies + .get_mut(&recipient) + .filter(|pending| pending.attempt == attempt) + { + pending.commitment = Some(commitment); + } + } + + /// Drop the reservation `attempt` holds on `recipient`: its request was + /// never paid for, or its payment definitely failed. Nothing when another + /// attempt holds the recipient by now. + pub(crate) fn release_private_reply(&mut self, recipient: &Identifier, attempt: u64) { + if self + .dashpay + .pending_private_replies + .get(recipient) + .is_some_and(|pending| pending.attempt == attempt) + { + self.dashpay.pending_private_replies.remove(recipient); + } + } + + /// Release every pending request sealed as one of `commitments`, whose + /// payments' journal records were discharged (read back elsewhere, never + /// delivered, or proven expired), whichever attempt holds it. + pub(crate) fn release_discharged_private_replies( + &mut self, + commitments: &std::collections::BTreeSet<[u8; 32]>, + ) { + self.dashpay.pending_private_replies.retain(|_, pending| { + pending + .commitment + .is_none_or(|commitment| !commitments.contains(&commitment)) + }); + } + + /// Settle the pending request to `recipient` sealed as `commitment`: the + /// private sync read that entry back and recorded it. + pub(crate) fn settle_private_reply(&mut self, recipient: &Identifier, commitment: &[u8; 32]) { + if self + .dashpay + .pending_private_replies + .get(recipient) + .is_some_and(|pending| pending.commitment == Some(*commitment)) + { + self.dashpay.pending_private_replies.remove(recipient); + } + } + + /// Reserve `recipient` again for the entry sealed as `commitment`, whose + /// payment is unconfirmed since before a restart. A recipient already + /// reserved keeps its attempt, and gets the commitment only when it has + /// none yet. + pub(crate) fn restore_private_reply(&mut self, recipient: Identifier, commitment: [u8; 32]) { + match self.dashpay.pending_private_replies.get_mut(&recipient) { + Some(pending) => { + pending.commitment.get_or_insert(commitment); + } + None => { + self.insert_private_reply(recipient, Some(commitment)); + } + } + } + + /// Hold `recipient` for the entry sealed as `commitment`, whose payment is + /// unconfirmed since before a restart, instead of the one the attempt + /// reserving it sealed: that one is not paid for, so only this entry can + /// settle the reservation. + pub(crate) fn retarget_private_reply(&mut self, recipient: Identifier, commitment: [u8; 32]) { + match self.dashpay.pending_private_replies.get_mut(&recipient) { + Some(pending) => pending.commitment = Some(commitment), + None => { + self.insert_private_reply(recipient, Some(commitment)); + } + } + } + /// Sent-direction counterpart of [`Self::advance_high_water_received`]; /// same compare-and-advance semantics and caller contract. pub fn advance_high_water_sent(&mut self, snapshot: Option, max_fetched: Option) { @@ -946,6 +1428,26 @@ mod tests { WalletPersister::new([0u8; 32], Arc::new(Failing)) } + /// The private scan state replayed last decides an identity's load-time + /// hold: a later record cleared lifts an earlier marked one. + #[test] + fn should_take_the_last_replayed_private_payment_marker() { + let mut managed = create_test_identity([0x31; 32]); + let marked = |unresolved: bool| PrivateContactRequestsPosition { + private_payments_unresolved: unresolved, + ..managed_position() + }; + managed.apply_private_contact_requests_position(marked(true)); + assert!(managed.dashpay().private_payments_unrestored()); + managed.apply_private_contact_requests_position(marked(false)); + assert!(!managed.dashpay().private_payments_unrestored()); + } + + /// A private scan state record with nothing marked. + fn managed_position() -> PrivateContactRequestsPosition { + create_test_identity([0x32; 32]).private_contact_requests_position_record() + } + fn create_test_identity(id_bytes: [u8; 32]) -> ManagedIdentity { let identity_v0 = IdentityV0 { id: Identifier::from(id_bytes), @@ -2140,4 +2642,74 @@ mod tests { "replay un-ignore must not rewind the live cursor" ); } + + /// A reservation belongs to the attempt that made it: once attempt A's + /// request is read back and settled and B reserves the recipient, A's + /// late cleanup neither releases B's reservation nor notes a commitment + /// on it. + #[test] + fn should_keep_a_later_attempts_reservation_from_an_earlier_attempts_cleanup() { + let mut managed = create_test_identity([1u8; 32]); + let bob = Identifier::from([2u8; 32]); + + let a = managed.reserve_private_reply(bob).expect("A reserves"); + assert_eq!(managed.reserve_private_reply(bob), None, "one at a time"); + managed.note_private_reply_commitment(bob, a, [0xA; 32]); + managed.settle_private_reply(&bob, &[0xA; 32]); + assert!(!managed.dashpay().private_reply_pending(&bob)); + + let b = managed.reserve_private_reply(bob).expect("B reserves"); + assert_ne!(a, b); + managed.release_private_reply(&bob, a); + managed.note_private_reply_commitment(bob, a, [0xA; 32]); + assert!( + managed.dashpay().private_reply_pending(&bob), + "A's cleanup leaves B's reservation" + ); + managed.settle_private_reply(&bob, &[0xA; 32]); + assert!( + managed.dashpay().private_reply_pending(&bob), + "A's entry does not settle B's request" + ); + + managed.note_private_reply_commitment(bob, b, [0xB; 32]); + managed.settle_private_reply(&bob, &[0xB; 32]); + assert!(!managed.dashpay().private_reply_pending(&bob)); + } + + /// A reservation restored from an unconfirmed payment takes the entry's + /// commitment; one already held keeps its attempt and gets a commitment + /// only when it has none, unless it is retargeted to the restored entry. + #[test] + fn should_restore_a_reservation_without_taking_over_a_held_one() { + let mut managed = create_test_identity([1u8; 32]); + let bob = Identifier::from([2u8; 32]); + let carol = Identifier::from([3u8; 32]); + + managed.restore_private_reply(bob, [0xB; 32]); + assert!(managed.dashpay().private_reply_pending(&bob)); + assert_eq!(managed.reserve_private_reply(bob), None); + managed.settle_private_reply(&bob, &[0xB; 32]); + assert!(!managed.dashpay().private_reply_pending(&bob)); + + let held = managed.reserve_private_reply(carol).expect("Carol is free"); + managed.restore_private_reply(carol, [0xC; 32]); + managed.restore_private_reply(carol, [0xD; 32]); + managed.release_private_reply(&carol, held + 1); + assert!( + managed.dashpay().private_reply_pending(&carol), + "the attempt holding it is kept" + ); + managed.settle_private_reply(&carol, &[0xD; 32]); + assert!( + managed.dashpay().private_reply_pending(&carol), + "only a missing commitment is filled in" + ); + + managed.retarget_private_reply(carol, [0xD; 32]); + managed.settle_private_reply(&carol, &[0xC; 32]); + assert!(managed.dashpay().private_reply_pending(&carol)); + managed.settle_private_reply(&carol, &[0xD; 32]); + assert!(!managed.dashpay().private_reply_pending(&carol)); + } } diff --git a/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/dashpay.rs b/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/dashpay.rs index dbade254b1b..a9b1fdeca06 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/dashpay.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/dashpay.rs @@ -11,8 +11,54 @@ use crate::wallet::identity::{ ContactProfileEntry, ContactRequest, DashPayProfile, EstablishedContact, PaymentEntry, }; use dpp::prelude::Identifier; +use dpp::state_transition::StateTransition; +use key_wallet::bip32::ExtendedPubKey; use std::collections::{BTreeMap, BTreeSet}; +/// How an identity and a contact exchanged private contact requests (protocol +/// version 15), and what those carry beyond what a [`ContactRequest`] holds. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct PrivateContact { + /// The contact's tracked request to this identity came privately + /// ([`ContactRequest::came_privately`]), so accepting it replies privately + /// too. + pub received_privately: bool, + /// This identity's tracked request to the contact went privately. + pub sent_privately: bool, + /// The Orchard address the contact asked to be paid at privately: an + /// 11-byte diversifier and a 32-byte transmission key. + pub shielded_address: Option<[u8; 43]>, +} + +/// The private request to one recipient that may be in flight: the attempt +/// that reserved it and, once sealed, the commitment of its entry. Only that +/// attempt notes the commitment or releases it; the private sync settles it +/// by the commitment. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) struct PendingPrivateReply { + pub(crate) attempt: u64, + pub(crate) commitment: Option<[u8; 32]>, +} + +/// A public contact request to one recipient whose broadcast may have been +/// delivered, and whose outcome no proof settled yet +/// ([`DashPayState::public_contact_request_unconfirmed`]): the signed +/// transition, which a retry broadcasts again, and what recording the request +/// takes once it is proved on Platform. Only the attempt that held it settles +/// it. +#[derive(Debug, Clone)] +pub(crate) struct UnconfirmedPublicRequest { + pub(crate) attempt: u64, + pub(crate) transition: StateTransition, + /// The account reference the request carries: its document is looked up + /// by the sender, the recipient and it, DashPay's unique index. + pub(crate) account_reference: u32, + /// Our receiving (friendship) account for the pair, registered once the + /// request is recorded, as a send registers it. + pub(crate) account_index: u32, + pub(crate) contact_xpub: ExtendedPubKey, +} + /// DashPay social state carried by one [`ManagedIdentity`](super::ManagedIdentity). #[derive(Debug, Clone, Default)] pub struct DashPayState { @@ -79,6 +125,103 @@ pub struct DashPayState { /// High-water mark for the sent direction (`$ownerId == me`). pub(super) high_water_sent_ms: Option, + /// The position of DashPay's private contact request store (protocol + /// version 15) to scan from next for this identity: every entry before it + /// was read and what it held for this identity ingested. Persisted, after + /// what the entries before it held, for a backend attesting + /// `PRIVATE_CONTACT_REQUEST_SCAN_STATE`, so a relaunch reads on from it; + /// otherwise a cold start scans the store again from 0, and ingest is a + /// fixpoint. [`ManagedIdentity::unignore_sender`] rewinds it, as it does + /// the received cursor. + /// + /// [`ManagedIdentity::unignore_sender`]: super::ManagedIdentity::unignore_sender + pub(super) private_contact_requests_position: u64, + + /// Whether a private sync read DashPay's private contact request store + /// to its end for this identity since the wallet was loaded, with nothing + /// held back. Until then a private send or accept reads it first: a + /// request paid for in an earlier process may be in the store unread, and + /// the reservation that kept it from being paid twice did not survive. + /// In memory only; a rewind of the read clears it + /// (`ManagedIdentity::rewind_private_store_read`). + pub(super) private_contact_requests_read: bool, + + /// The highest height a read of a page of DashPay's private contact + /// request store was proved at, among the pages a private sync read for + /// this identity since load, a page completed from several reads counting + /// its highest: what `private_contact_requests_read` rests on. A request sealed + /// to one of its keys is in such a page only if the key was added at or + /// below it, so the store read covers the identity's keys as proved at or + /// above it, and a public request is decided only with those + /// (`DashPayView::read_private_store_before_deciding`). `None` before any + /// page was read with the identity's keys since its read was last rewound + /// (`ManagedIdentity::rewind_private_store_read`). In memory only. + pub(super) private_store_read_height: Option, + + /// The highest `private_store_read_height` a rewind of the read reset: + /// the store was seen at that height, so a read since, with the keys the + /// rewind was for, counts as read to the end + /// (`private_contact_requests_read`) only once it reaches it. A read from + /// a node behind it would otherwise pass over entries the wallet already + /// saw, which the earlier keys could not open. `None` before any rewind of + /// a read. In memory only; never lowered. + pub(super) private_store_read_floor: Option, + + /// The fingerprint of the scanning keys `private_contact_requests_position` + /// and `private_contact_requests_read` hold for + /// (`ManagedIdentity::private_scan_key_fingerprint`): entries to or from + /// a key added since were not opened. When the identity's keys no + /// longer match it, both are rewound (`reconcile_private_scan_keys`). + /// `None` before the first reconcile. + pub(super) private_scan_keys: Option<[u8; 32]>, + + /// The shielded address each contact's tracked private request to this + /// identity carries. Persisted for a backend attesting + /// `PRIVATE_CONTACT_REQUEST_SCAN_STATE`; otherwise rebuilt by the scan a + /// cold start runs. Whether a request came privately is the request's + /// own ([`ContactRequest::came_privately`]), so it holds across restarts. + pub(super) private_shielded_addresses: BTreeMap, + + /// The private requests to each recipient that are being paid for, or + /// were paid for and are not yet read back from the store, each owned by + /// the attempt that reserved it. While one is pending no other request to + /// the recipient is sent, private or public, as the store keeps every + /// entry appended and a second payment could execute too. The private + /// sync settles one when it reads the entry back and records it. In + /// memory only: after a restart, those whose payment is unconfirmed are + /// restored from the shielded store's unconfirmed spends. + pub(super) pending_private_replies: BTreeMap, + + /// The public requests to each recipient being sent, by attempt: each + /// claims the pair from before its channel is decided until it is + /// submitted and recorded, and while one does no private request to the + /// recipient is reserved, as a reserved one refuses a public send. A + /// claim is released only by its own attempt, whose id is process-wide, + /// so a send that outlived its wallet's removal and re-creation under the + /// same id cannot release a claim of the new wallet. In memory only. + pub(super) public_contact_request_claims: BTreeMap>, + + /// The public request to each recipient whose broadcast may have been + /// delivered while no proof settled its outcome: it may still execute, so + /// no other request to the recipient is signed, public or private, until a + /// proved read shows its document on Platform (it is then recorded as + /// sent) or shows the transition can no longer write it. A retry + /// broadcasts the same signed bytes. In memory only, bound to the wallet + /// generation that holds this state: a process that starts afresh reads + /// the identity contract nonce from Platform and finds a request already + /// on Platform before it sends, which is what keeps a second one from + /// executing then. + pub(super) unconfirmed_public_requests: BTreeMap, + + /// Whether this identity was loaded with a private contact request + /// payment that may be unresolved + /// (`PrivateContactRequestsPosition::private_payments_unresolved`) and no + /// restoration from the shielded store has restored its reservations + /// since. While set, the identity sends and accepts no public contact + /// request, as no reservation holds the pair its payment is for. In + /// memory, from what a load restored. + pub(super) private_payments_unrestored: bool, + /// Lowest Platform-assigned `$createdAtCoreBlockHeight` among OUR sent /// `contactRequest` docs to each recipient seen by a sweep this process. /// @@ -233,6 +376,130 @@ impl DashPayState { .or_else(|| self.sent_contact_requests.get(contact)) } + /// The contact's tracked request to us: the established contact's + /// incoming side, else a pending incoming request. + pub fn incoming_request(&self, contact: &Identifier) -> Option<&ContactRequest> { + self.established_contacts + .get(contact) + .map(|established| &established.incoming_request) + .or_else(|| self.incoming_contact_requests.get(contact)) + } + + /// The position of DashPay's private contact request store to scan from + /// next for this identity; see the field doc. + pub fn private_contact_requests_position(&self) -> u64 { + self.private_contact_requests_position + } + + /// Whether a private request to `contact` is being paid for, or was paid + /// for and is not yet read back from the store; see the field doc. + pub fn private_reply_pending(&self, contact: &Identifier) -> bool { + self.pending_private_replies.contains_key(contact) + } + + /// Whether any private request this identity sent is reserved as + /// pending ([`Self::private_reply_pending`]). + #[cfg(feature = "shielded")] + pub(crate) fn private_replies_pending(&self) -> bool { + !self.pending_private_replies.is_empty() + } + + /// A recipient this identity holds a contact request in flight to, if + /// any: a private request it is paying for or has not read back + /// ([`Self::private_reply_pending`]), or a public one claimed and not yet + /// recorded ([`Self::public_contact_request_claimed`]) or unconfirmed + /// ([`Self::public_contact_request_unconfirmed`]). + pub fn contact_request_in_flight(&self) -> Option { + self.pending_private_replies + .keys() + .chain(self.public_contact_request_claims.keys()) + .chain(self.unconfirmed_public_requests.keys()) + .next() + .copied() + } + + /// Whether a public request to `contact` was broadcast and may have been + /// delivered, with no proof settling its outcome yet; see the field doc. + pub fn public_contact_request_unconfirmed(&self, contact: &Identifier) -> bool { + self.unconfirmed_public_requests.contains_key(contact) + } + + /// The unconfirmed public request to `contact`, if any + /// ([`Self::public_contact_request_unconfirmed`]). + pub(crate) fn unconfirmed_public_request( + &self, + contact: &Identifier, + ) -> Option<&UnconfirmedPublicRequest> { + self.unconfirmed_public_requests.get(contact) + } + + /// The recipients this identity holds an unconfirmed public request to + /// ([`Self::public_contact_request_unconfirmed`]). + pub(crate) fn unconfirmed_public_request_recipients(&self) -> Vec { + self.unconfirmed_public_requests.keys().copied().collect() + } + + /// Whether this identity was loaded with a private contact request payment + /// that may be unresolved, and no restoration from the shielded store has + /// restored its reservations since: its public contact requests are held. + pub fn private_payments_unrestored(&self) -> bool { + self.private_payments_unrestored + } + + /// Whether a private contact request this identity paid for may still be + /// unresolved, as its position record stores it + /// (`PrivateContactRequestsPosition::private_payments_unresolved`): it + /// holds a private request it is paying for or has not read back, or it + /// was loaded with one no restoration has restored since. + pub fn private_payments_unresolved(&self) -> bool { + !self.pending_private_replies.is_empty() || self.private_payments_unrestored + } + + /// The shielded address kept for `contact`, whichever way the tracked + /// requests went; [`Self::private_contact`] gives it only while the + /// contact's request to us came privately. + pub(crate) fn private_shielded_address(&self, contact: &Identifier) -> Option<[u8; 43]> { + self.private_shielded_addresses.get(contact).copied() + } + + /// Whether a public request to `contact` is being sent; see the field + /// doc. + pub fn public_contact_request_claimed(&self, contact: &Identifier) -> bool { + self.public_contact_request_claims.contains_key(contact) + } + + /// Whether a private sync read DashPay's private contact request store + /// to its end for this identity since load; see the field doc. + pub fn private_contact_requests_read(&self) -> bool { + self.private_contact_requests_read + } + + /// The highest proved height of a store page a private sync read for this + /// identity since load, if one did ([`Self::private_contact_requests_read`]). + pub(crate) fn private_store_read_height(&self) -> Option { + self.private_store_read_height + } + + /// How this identity and `contact` exchanged private requests, from the + /// tracked requests either way; `None` when neither went privately. + pub fn private_contact(&self, contact: &Identifier) -> Option { + let received_privately = self + .incoming_request(contact) + .is_some_and(ContactRequest::came_privately); + let sent_privately = self + .outgoing_request(contact) + .is_some_and(ContactRequest::came_privately); + (received_privately || sent_privately).then(|| PrivateContact { + received_privately, + sent_privately, + shielded_address: self + .private_shielded_addresses + .get(contact) + .copied() + .filter(|_| received_privately), + }) + } + /// Whether a sent-request sweep completed this process; see the field doc. pub fn sent_sweep_completed(&self) -> bool { self.sent_sweep_completed diff --git a/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/mod.rs b/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/mod.rs index 436dbaaabf6..c11f1e91f8a 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/mod.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/state/managed_identity/mod.rs @@ -9,7 +9,7 @@ mod dashpay; mod identity_ops; mod sync; -pub use dashpay::DashPayState; +pub use dashpay::{DashPayState, PrivateContact}; // `block_time` + `key_storage` moved to `crate::wallet::identity::types`. // Re-export so every `impl ManagedIdentity` block below keeps working diff --git a/packages/rs-platform-wallet/src/wallet/identity/state/manager/lifecycle.rs b/packages/rs-platform-wallet/src/wallet/identity/state/manager/lifecycle.rs index 2efbf0f4345..294e836f9d8 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/state/manager/lifecycle.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/state/manager/lifecycle.rs @@ -96,6 +96,11 @@ impl IdentityManager { // iterate values know which wallet + slot they came from // without re-threading the keys. managed_identity.wallet_id = Some(wallet_id); + // Held before anything can send or accept for it, when a persister + // kept its record marked. + if self.retained_private_payment_markers.remove(&identity_id) { + managed_identity.hold_for_retained_private_payment_marker(); + } self.wallet_identities .entry(wallet_id) @@ -114,6 +119,29 @@ impl IdentityManager { Ok(()) } + /// Hold every identity in `owners`, whose private contact request scan + /// state record a persister kept marked + /// (`PrivateContactRequestsPosition::private_payments_unresolved`), as a + /// load holds one loaded with its record marked + /// (`DashPayState::private_payments_unrestored`): one this manager holds + /// now at once, every other when it is added. Its private payment may + /// still execute, while the identity, added afresh, holds no reservation + /// or record of it. Only a restoration from the shielded store's journal + /// releases the hold. + pub(crate) fn retain_private_payment_markers( + &mut self, + owners: impl IntoIterator, + ) { + for owner in owners { + match self.managed_identity_mut(&owner) { + Some(managed) => managed.hold_for_retained_private_payment_marker(), + None => { + self.retained_private_payment_markers.insert(owner); + } + } + } + } + /// Add an identity to the out-of-wallet (observed read-only) bucket. /// /// There is no separate `WatchedIdentity` type; observed identities @@ -180,11 +208,45 @@ impl IdentityManager { /// Removal is terminal in storage as well as in memory: the persister /// deletes the identity and every row it owns, so re-adding the same /// id later starts from a blank identity. + /// + /// Refused, with nothing removed, while the identity's private contact + /// request channel is held: a contact request in flight, private or + /// public, or a private payment that may still execute, whether its own + /// state or the wallet's journal holds it + /// ([`PlatformWalletError::PrivateContactRequestPending`]; a public one + /// whose outcome is unconfirmed is + /// [`PlatformWalletError::PublicContactRequestUnconfirmed`]), or one from an + /// earlier process not restored yet + /// ([`PlatformWalletError::PrivateContactPaymentsNotRestored`]). Removed + /// and loaded again, the identity would start with none of those holds, + /// and its persisted marker with it, so a public request could publish a + /// pair a private payment still keeps off chain. pub fn remove_identity( &mut self, identity_id: &Identifier, persister: &WalletPersister, ) -> Result { + if let Some(managed) = self.managed_identity(identity_id) { + let dashpay = managed.dashpay(); + if let Some(recipient) = dashpay + .unconfirmed_public_request_recipients() + .first() + .copied() + { + return Err(PlatformWalletError::PublicContactRequestUnconfirmed( + recipient, + )); + } + if let Some(recipient) = dashpay + .contact_request_in_flight() + .or_else(|| persister.private_sender_journaled(identity_id)) + { + return Err(PlatformWalletError::PrivateContactRequestPending(recipient)); + } + if dashpay.private_payments_unrestored() { + return Err(PlatformWalletError::PrivateContactPaymentsNotRestored); + } + } // Drop the side-index entry first; its value tells us which // bucket the identity lives in so we can avoid a second scan. let location = self diff --git a/packages/rs-platform-wallet/src/wallet/identity/state/manager/mod.rs b/packages/rs-platform-wallet/src/wallet/identity/state/manager/mod.rs index 32237f583e4..236f259e4b2 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/state/manager/mod.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/state/manager/mod.rs @@ -35,7 +35,7 @@ use crate::changeset::{IdentityManagerStartState, IdentityScanStateEntry}; use crate::wallet::platform_wallet::WalletId; use dpp::identity::accessors::IdentityGettersV0; use dpp::prelude::Identifier; -use std::collections::BTreeMap; +use std::collections::{BTreeMap, BTreeSet}; /// Plain alias for the BIP-9 HD identity index used as the inner-bucket /// key for wallet-owned identities. Keeps the type signatures readable @@ -107,6 +107,13 @@ pub struct IdentityManager { /// [`IdentityManagerStartState::scan_states`] for why that is deliberately /// not read as "complete". identity_scan_states: BTreeMap, + + /// The identities whose private contact request scan state record a + /// persister kept marked, for a wallet removed or registered again, that + /// this manager does not hold yet + /// (`ClientStartState::retained_private_contact_scan_states`): each is held + /// as it is added ([`Self::retain_private_payment_markers`]). + retained_private_payment_markers: BTreeSet, } impl From for IdentityManager { @@ -141,6 +148,7 @@ impl From for IdentityManager { wallet_identities, location_index, identity_scan_states: scan_states, + retained_private_payment_markers: BTreeSet::new(), } } } diff --git a/packages/rs-platform-wallet/src/wallet/identity/state/mod.rs b/packages/rs-platform-wallet/src/wallet/identity/state/mod.rs index affa70d0156..05f321ec6ef 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/state/mod.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/state/mod.rs @@ -8,7 +8,7 @@ pub mod managed_identity; pub mod manager; -pub use managed_identity::{BlockTime, DashPayState, ManagedIdentity}; +pub use managed_identity::{BlockTime, DashPayState, ManagedIdentity, PrivateContact}; pub use manager::IdentityLocation; pub use manager::IdentityManager; pub use manager::RegistrationIndex; diff --git a/packages/rs-platform-wallet/src/wallet/identity/types/dashpay/contact_request.rs b/packages/rs-platform-wallet/src/wallet/identity/types/dashpay/contact_request.rs index c039823fa34..d6ac8b83ec7 100644 --- a/packages/rs-platform-wallet/src/wallet/identity/types/dashpay/contact_request.rs +++ b/packages/rs-platform-wallet/src/wallet/identity/types/dashpay/contact_request.rs @@ -70,6 +70,15 @@ impl ContactRequest { } } + /// Whether the request came as a private contact request (protocol + /// version 15) rather than a `contactRequest` document. A document always + /// carries its Platform-assigned `$createdAtCoreBlockHeight`, which + /// DashPay requires and no Core chain puts at 0; a private request's entry + /// carries none, so the wallet records it at 0. + pub fn came_privately(&self) -> bool { + self.core_height_created_at == 0 + } + /// Check if this is an outgoing request for the given identity pub fn is_outgoing(&self, identity_id: &Identifier) -> bool { self.sender_id == *identity_id diff --git a/packages/rs-platform-wallet/src/wallet/masternode_withdrawal.rs b/packages/rs-platform-wallet/src/wallet/masternode_withdrawal.rs index 32bf9206254..bf96ebddfee 100644 --- a/packages/rs-platform-wallet/src/wallet/masternode_withdrawal.rs +++ b/packages/rs-platform-wallet/src/wallet/masternode_withdrawal.rs @@ -54,9 +54,10 @@ use dpp::state_transition::identity_credit_withdrawal_transition::{ IdentityCreditWithdrawalTransition, MIN_CORE_FEE_PER_BYTE, }; use dpp::state_transition::proof_result::StateTransitionProofResult; +use dpp::state_transition::StateTransition; use dpp::withdrawal::Pooling; -use crate::broadcast_outcome::{broadcast_definitely_failed, carries_consensus_rejection}; +use crate::broadcast_outcome::{broadcast_tracking_delivery, BroadcastDelivery}; use crate::error::{PlatformWalletError, SIGNER_KEY_UNAVAILABLE_PREFIX}; use crate::wallet::core::is_signable_funding_account; use crate::wallet::identity::network::{ @@ -288,14 +289,16 @@ impl PlatformWallet { /// - the identity is missing, or doesn't carry the expected /// `OWNER` / `TRANSFER` key for the wallet's hash160. /// - /// Outcomes after the transition leaves this wallet are kept distinct: - /// a definitive rejection (consensus error, or a transport verdict that - /// rules out delivery) is an ordinary error and may be retried; anything - /// ambiguous — broadcast accepted (or its ACK lost) and the result wait - /// failed — is [`PlatformWalletError::MasternodeWithdrawalUnconfirmed`] - /// and MUST NOT be retried until the claimable balance is re-read: the - /// identity nonce was already consumed for this attempt, so a blind retry - /// would submit a second withdrawal. + /// Outcomes of the broadcast are kept distinct. A transition that never + /// left this wallet (refused before anything was sent) is an ordinary + /// error and may be retried. Once a dispatch may have reached a node, + /// anything short of a proved result, an endpoint's refusal or a + /// consensus verdict included, is + /// [`PlatformWalletError::MasternodeWithdrawalUnconfirmed`] and MUST NOT + /// be retried until the claimable balance is re-read: no proof backs an + /// endpoint's answer, and the identity nonce was already taken for this + /// attempt, so a blind retry would submit a second withdrawal with the + /// next one. pub async fn masternode_withdraw( &self, request: MasternodeWithdrawalRequest, @@ -387,9 +390,11 @@ impl PlatformWallet { /// `expected_hash160`, sign with `signer` at `path` through /// [`DerivedKeyIdentitySigner`] (which re-checks the derived key against /// `expected_hash160` before emitting a signature), broadcast, and wait for -/// the proved balance. Error semantics: definitive rejections stay -/// retryable, ambiguous outcomes are -/// [`PlatformWalletError::MasternodeWithdrawalUnconfirmed`]. +/// the proved balance. Error semantics: a failure before the broadcast, or a +/// broadcast refused before anything was sent, stays retryable; every other +/// outcome short of a proved result is +/// [`PlatformWalletError::MasternodeWithdrawalUnconfirmed`] +/// ([`settle_masternode_withdrawal`]). #[allow(clippy::too_many_arguments)] pub(crate) async fn execute_masternode_withdrawal( sdk: &dash_sdk::Sdk, @@ -481,38 +486,94 @@ pub(crate) async fn execute_masternode_withdrawal .await .map_err(|e| definitive(dash_sdk::Error::Protocol(e)))?; - // Broadcast, then wait — split so an ambiguous outcome stays typed. - let unconfirmed = |reason: String| PlatformWalletError::MasternodeWithdrawalUnconfirmed { - identity_id, - amount_credits, - reason, - }; - match state_transition.broadcast(sdk, None).await { - Ok(()) => {} - Err(e) if broadcast_definitely_failed(&e) => return Err(definitive(e)), - Err(e) => { + broadcast_masternode_withdrawal(sdk, &state_transition, identity_id, amount_credits).await +} + +/// Broadcast the signed masternode withdrawal `state_transition`, keeping +/// what every dispatch proved ([`broadcast_tracking_delivery`]), then wait +/// for its result: split so an outcome that is not known stays typed +/// ([`settle_masternode_withdrawal`]). +async fn broadcast_masternode_withdrawal( + sdk: &dash_sdk::Sdk, + state_transition: &StateTransition, + identity_id: Identifier, + amount_credits: u64, +) -> Result { + let delivery = broadcast_tracking_delivery(sdk, state_transition).await; + settle_masternode_withdrawal(identity_id, amount_credits, delivery, || { + state_transition.wait_for_affected_state::(sdk, None) + }) + .await +} + +/// What a signed masternode withdrawal's broadcast (`delivery`) and result +/// wait (`wait`, run only when a dispatch may have reached a node) came to: +/// the identity's proved remaining balance, or the error the withdrawal +/// reports. +/// +/// Only a transition that never left the wallet +/// ([`BroadcastDelivery::NeverDelivered`]: refused before anything was sent) +/// is an ordinary, retryable error: nothing holds its bytes but the wallet, +/// so it can never execute. Once a dispatch may have reached a node, every +/// outcome short of the proved balance is +/// [`PlatformWalletError::MasternodeWithdrawalUnconfirmed`]: a wait that +/// fails, an endpoint's refusal of the broadcast and a consensus verdict on +/// either call included. The endpoint that sends a verdict is +/// unauthenticated, no proof or quorum signature backs it, and one that kept +/// or forwarded the signed transition can answer with any verdict, while a +/// retry signs a second withdrawal with the next identity nonce. +/// +/// The withdrawal keeps no record of its signed transition: what settles an +/// unconfirmed one is the identity's nonce (once the nonce it signed with +/// reads as used, it executed or can no longer execute) and the claimable +/// balance, which the host re-reads before it submits again. +async fn settle_masternode_withdrawal( + identity_id: Identifier, + amount_credits: u64, + delivery: BroadcastDelivery, + wait: W, +) -> Result +where + W: FnOnce() -> Fut, + Fut: std::future::Future>, +{ + // What the broadcast was answered with, kept for the reason an + // unconfirmed withdrawal reports. + let broadcast_answer = match delivery { + BroadcastDelivery::Admitted => None, + BroadcastDelivery::NeverDelivered(e) => { + return Err(PlatformWalletError::InvalidIdentityData(format!( + "masternode withdrawal failed: {e}" + ))); + } + BroadcastDelivery::MaybeDelivered(e) => { tracing::warn!( identity = %identity_id, error = %e, - "masternode withdrawal broadcast returned no verdict; the transition may \ - have been admitted — falling through to the result wait" + "masternode withdrawal broadcast may have been delivered; falling through \ + to the result wait" ); + Some(e.to_string()) } - } + }; + let unconfirmed = |waited: String| PlatformWalletError::MasternodeWithdrawalUnconfirmed { + identity_id, + amount_credits, + reason: match &broadcast_answer { + Some(answer) => format!("{waited}; its broadcast answered: {answer}"), + None => waited, + }, + }; - match state_transition - .wait_for_affected_state::(sdk, None) - .await - { + match wait().await { Ok(StateTransitionProofResult::VerifiedPartialIdentity(partial)) => partial .balance .ok_or_else(|| unconfirmed("the result proof carried no identity balance".to_string())), - // Proved, but not the shape a withdrawal produces — the transition - // landed; only the balance read-back is missing. + // Verified, but not the identity balance a withdrawal's result + // carries: the remaining balance is not proved. Ok(_) => Err(unconfirmed( "the result proof did not carry the identity's balance".to_string(), )), - Err(e) if carries_consensus_rejection(&e) => Err(definitive(e)), Err(e) => Err(unconfirmed(e.to_string())), } } @@ -724,11 +785,221 @@ where #[cfg(test)] mod tests { use super::*; + use crate::broadcast_outcome::test_sdks::{sdk_refusing_connections, sdk_without_addresses}; + use dash_sdk::dapi_client::transport::TransportError; + use dash_sdk::dapi_client::DapiClientError; + use dash_sdk::dapi_grpc::tonic::{Code, Status}; + use dash_sdk::error::StateTransitionBroadcastError; use dashcore::crypto::ecdsa::{EcdsaPublicKey as PublicKey, EcdsaSecretKey as SecretKey}; + use dpp::consensus::basic::{BasicError, UnsupportedFeatureError}; + use dpp::consensus::ConsensusError; use dpp::identity::identity_public_key::v0::IdentityPublicKeyV0; - use dpp::identity::{Purpose, SecurityLevel}; + use dpp::identity::{PartialIdentity, Purpose, SecurityLevel}; + use dpp::state_transition::identity_credit_withdrawal_transition::v1::IdentityCreditWithdrawalTransitionV1; + use std::cell::Cell; use std::str::FromStr; + /// The identity the withdrawal tests withdraw from, and the amount. + const WITHDRAWN_FROM: [u8; 32] = [0x31; 32]; + const WITHDRAWN: u64 = 1_000_000; + + /// A node's refusal of a dispatch, as an offline or overloaded endpoint + /// answers one. + fn unavailable() -> dash_sdk::Error { + dash_sdk::Error::DapiClientError(DapiClientError::Transport(TransportError::Grpc( + Status::new(Code::Unavailable, "test"), + ))) + } + + fn verdict() -> ConsensusError { + ConsensusError::BasicError(BasicError::UnsupportedFeatureError( + UnsupportedFeatureError::new("test".to_string(), 1), + )) + } + + /// A consensus verdict as a broadcast returns one. + fn broadcast_verdict() -> dash_sdk::Error { + dash_sdk::Error::Protocol(ProtocolError::ConsensusError(Box::new(verdict()))) + } + + /// A consensus verdict as the result wait returns one. + fn wait_verdict() -> dash_sdk::Error { + dash_sdk::Error::StateTransitionBroadcastError(StateTransitionBroadcastError { + code: 1, + message: "rejected".to_string(), + cause: Some(verdict()), + }) + } + + fn wait_timeout() -> dash_sdk::Error { + dash_sdk::Error::TimeoutReached(std::time::Duration::from_secs(80), "waiting".to_string()) + } + + fn proved_balance(balance: Option) -> StateTransitionProofResult { + StateTransitionProofResult::VerifiedPartialIdentity(PartialIdentity { + id: Identifier::from(WITHDRAWN_FROM), + loaded_public_keys: Default::default(), + balance, + revision: None, + not_found_public_keys: Default::default(), + }) + } + + fn is_unconfirmed(settled: &Result) -> bool { + matches!( + settled, + Err(PlatformWalletError::MasternodeWithdrawalUnconfirmed { + identity_id, + amount_credits: WITHDRAWN, + .. + }) if *identity_id == Identifier::from(WITHDRAWN_FROM) + ) + } + + /// Once a dispatch may have reached a node, a withdrawal whose result is + /// not proved is unconfirmed, never failed: a node's refusal of the + /// broadcast and a consensus verdict on either call included, as no proof + /// backs an endpoint's answer and a retry signs a second withdrawal. The + /// reason keeps what the wait and the broadcast were answered with. + #[tokio::test] + async fn should_report_a_masternode_withdrawal_unconfirmed_once_a_dispatch_may_have_reached_a_node( + ) { + let cases = [ + ( + "a node refused the broadcast, the wait timed out", + BroadcastDelivery::MaybeDelivered(unavailable()), + wait_timeout(), + ), + ( + "the broadcast was answered with a consensus verdict", + BroadcastDelivery::MaybeDelivered(broadcast_verdict()), + wait_timeout(), + ), + ( + "admitted, the wait was answered with a consensus verdict", + BroadcastDelivery::Admitted, + wait_verdict(), + ), + ( + "admitted, the wait timed out", + BroadcastDelivery::Admitted, + wait_timeout(), + ), + ]; + for (case, delivery, wait_error) in cases { + let broadcast_answer = match &delivery { + BroadcastDelivery::MaybeDelivered(e) => Some(e.to_string()), + _ => None, + }; + let waited = wait_error.to_string(); + let settled = settle_masternode_withdrawal( + Identifier::from(WITHDRAWN_FROM), + WITHDRAWN, + delivery, + || std::future::ready(Err(wait_error)), + ) + .await; + let Err(PlatformWalletError::MasternodeWithdrawalUnconfirmed { reason, .. }) = settled + else { + panic!("{case}: {settled:?}"); + }; + assert!(reason.contains(&waited), "{case}: {reason}"); + if let Some(answer) = broadcast_answer { + assert!(reason.contains(&answer), "{case}: {reason}"); + } + } + } + + /// Only a withdrawal whose transition never left the wallet is an + /// ordinary, retryable failure, and nothing waits for its result. + #[tokio::test] + async fn should_report_a_masternode_withdrawal_failed_only_when_nothing_was_sent() { + let waited = Cell::new(false); + let settled = settle_masternode_withdrawal( + Identifier::from(WITHDRAWN_FROM), + WITHDRAWN, + BroadcastDelivery::NeverDelivered(dash_sdk::Error::DapiClientError( + DapiClientError::NoAvailableAddresses, + )), + || { + waited.set(true); + std::future::ready(Err(wait_timeout())) + }, + ) + .await; + assert!( + matches!(settled, Err(PlatformWalletError::InvalidIdentityData(_))), + "{settled:?}" + ); + assert!(!waited.get(), "nothing was sent, so nothing is waited for"); + } + + /// A proved result returns the identity's remaining balance, whatever the + /// broadcast answered; a proof that carries no balance leaves the + /// withdrawal unconfirmed. + #[tokio::test] + async fn should_return_a_masternode_withdrawal_s_proved_balance() { + for delivery in [ + BroadcastDelivery::Admitted, + BroadcastDelivery::MaybeDelivered(unavailable()), + ] { + let settled = settle_masternode_withdrawal( + Identifier::from(WITHDRAWN_FROM), + WITHDRAWN, + delivery, + || std::future::ready(Ok(proved_balance(Some(7)))), + ) + .await; + assert!(matches!(settled, Ok(7)), "{settled:?}"); + } + let settled = settle_masternode_withdrawal( + Identifier::from(WITHDRAWN_FROM), + WITHDRAWN, + BroadcastDelivery::Admitted, + || std::future::ready(Ok(proved_balance(None))), + ) + .await; + assert!(is_unconfirmed(&settled), "{settled:?}"); + } + + /// The broadcast of a signed withdrawal through a network SDK: a node that + /// refuses the connection leaves it unconfirmed, as a transport failure + /// cannot show that nothing was sent, and an SDK with no address to send + /// to leaves it failed. + #[tokio::test] + async fn should_report_a_masternode_withdrawal_unconfirmed_when_its_node_refuses_the_connection( + ) { + let transition: StateTransition = IdentityCreditWithdrawalTransitionV1 { + identity_id: Identifier::from(WITHDRAWN_FROM), + amount: WITHDRAWN, + nonce: 4, + ..Default::default() + } + .into(); + + let (refusing, _port) = sdk_refusing_connections(); + let refused = broadcast_masternode_withdrawal( + &refusing, + &transition, + Identifier::from(WITHDRAWN_FROM), + WITHDRAWN, + ) + .await; + assert!(is_unconfirmed(&refused), "{refused:?}"); + + let never_sent = broadcast_masternode_withdrawal( + &sdk_without_addresses(), + &transition, + Identifier::from(WITHDRAWN_FROM), + WITHDRAWN, + ) + .await; + assert!( + matches!(never_sent, Err(PlatformWalletError::InvalidIdentityData(_))), + "{never_sent:?}" + ); + } + /// Test signer: one fixed secp256k1 key regardless of path. struct FixedKeySigner { secret: SecretKey, diff --git a/packages/rs-platform-wallet/src/wallet/mod.rs b/packages/rs-platform-wallet/src/wallet/mod.rs index 748f17de197..bbf1c58caf4 100644 --- a/packages/rs-platform-wallet/src/wallet/mod.rs +++ b/packages/rs-platform-wallet/src/wallet/mod.rs @@ -26,11 +26,11 @@ pub use platform_addresses::{ PerAccountPlatformAddressState, PerWalletPlatformAddressState, PlatformAddressTag, PlatformAddressWallet, }; -#[cfg(feature = "shielded")] -pub use platform_wallet::ShieldedShieldPreflight; pub use platform_wallet::{ PlatformWallet, PlatformWalletInfo, WalletId, WalletStateReadGuard, WalletStateWriteGuard, }; +#[cfg(feature = "shielded")] +pub use platform_wallet::{PrivateReplyPayment, ShieldedShieldPreflight}; pub use provider_key_at_index::{ProviderDerivedKey, ProviderKeyKind}; #[cfg(feature = "shielded")] pub use shielded::operations::shield_fee_reserve_credits; diff --git a/packages/rs-platform-wallet/src/wallet/persister.rs b/packages/rs-platform-wallet/src/wallet/persister.rs index a61e9082e17..4f30a4c2e4c 100644 --- a/packages/rs-platform-wallet/src/wallet/persister.rs +++ b/packages/rs-platform-wallet/src/wallet/persister.rs @@ -4,6 +4,8 @@ //! - [`WalletPersister`] — wraps the shared [`PlatformWalletPersistence`] with //! a fixed `wallet_id` so callers don't need to pass the ID on every call. +use std::collections::{BTreeMap, BTreeSet}; +use std::sync::atomic::{AtomicBool, AtomicU64, Ordering}; use std::sync::Arc; use dashcore::Txid; @@ -57,6 +59,104 @@ pub struct WalletPersister { wallet_id: WalletId, inner: Arc, contact_payment_gate: Arc>, + /// Commitments of private contact request entries a private sync read + /// back and recorded durably, whose records in the shielded store's + /// private payment journal are to be discharged: the wallet's view + /// notes them, and whoever holds the store discharges them (the shielded + /// coordinator's sync pass, a restoration, a private payment). Shared by + /// the clones the wallet and the coordinator hold. In memory only: a + /// record left undischarged by a restart holds nothing, as the request + /// it pays for is recorded. Only a shielded build keeps a journal to + /// discharge, so only it keeps them. + #[cfg(feature = "shielded")] + read_back_private_entries: Arc>>, + /// Commitments of private contact request entries a private sync read + /// back and recorded, whose records' flush failed: noted read back + /// (`read_back_private_entries`) once a later flush succeeds + /// ([`Self::note_read_back_once_durable`]), at the wallet's next private + /// sync, send or reservation. Shared by the clones the wallet and the + /// coordinator hold. In memory only: a restart loses them with the + /// records the failed flush did not keep. + #[cfg(feature = "shielded")] + unflushed_read_back_private_entries: Arc>>, + /// The commitments of the private contact request payments whose journal + /// records were discharged in this session (read back, never delivered, + /// or proven expired). Shared by the clones the wallet and the + /// coordinator hold. In memory only, as are the reservations they guard. + discharged_private_entries: Arc>, + /// Whether the reservations of this wallet's unconfirmed private contact + /// request payments from an earlier process may still be unrestored: + /// raised at load for a wallet that bound a shielded account before, and + /// lowered once a restoration from the shielded store succeeds. While it + /// is up, public contact requests are neither sent nor accepted. Shared by + /// the clones the wallet and its views hold. In memory only. + private_payments_unrestored: Arc, + /// The marker each identity's position record was last stored with in + /// this session (`PrivateContactRequestsPosition::private_payments_unresolved`): + /// a record whose marker, its identity's and the journal's together, + /// differs from it is stored again. Absent when none was stored, or the + /// last store or its flush failed. Shared by the clones the wallet and + /// the coordinator hold. In memory only. + stored_private_markers: Arc>>, + /// Whether a flush of this wallet's records failed for good in this + /// process, the backend dropping what it buffered: what the wallet tracks + /// in memory since may then not be on disk, so nothing is discharged on + /// the strength of it alone ([`Self::buffered_writes_lost`]). Shared by + /// the clones the wallet and the coordinator hold. In memory only: the + /// next process tracks what its load read from disk. + #[cfg(feature = "shielded")] + buffered_writes_lost: Arc, + /// The largest size of DashPay's private contact request store a page + /// this wallet read proved, in this process + /// ([`Self::private_store_size_proved`]). In memory only. + private_store_size_proved: Arc, + /// Why the last restoration of this wallet's private payments failed, + /// while no later one succeeded (`PlatformWalletError::PrivateContactPaymentsNotRestored` + /// then holds for it, not only for one not run yet). Shared by the + /// clones the wallet and its views hold. In memory only. + private_payment_restore_failure: Arc>>, + /// How the wallet's views run one more restoration of its private + /// payments, without waiting on the shielded store, before a contact + /// request is refused as not restored: installed by the wallet whenever + /// it builds a restoration with a shielded coordinator. Shared by the + /// clones the wallet and its views hold. In memory only. + #[cfg(feature = "shielded")] + private_payment_restore_retry: Arc>>, +} + +/// One more restoration of a wallet's private payments, run on the persister +/// it is given (`WalletPersister::retry_private_payment_restore`): taking it +/// as an argument, rather than holding one, keeps the persister that stores +/// it from holding itself. +#[cfg(feature = "shielded")] +pub(crate) type PrivatePaymentRestoreRetry = Arc< + dyn Fn(WalletPersister) -> std::pin::Pin + Send>> + + Send + + Sync, +>; + +/// The commitments [`WalletPersister::note_discharged_private_entries`] noted, +/// and the pairs the journal's unresolved payments hold, all updated under one +/// lock. +#[derive(Default)] +struct DischargedPrivateEntries { + /// Noted since the last take, for the wallet to release the reservations + /// it holds for them ([`WalletPersister::take_unreleased_discharged_private_entries`]). + unreleased: BTreeSet<[u8; 32]>, + /// Every one noted in this session, kept after the take: a restoration + /// that read a record before it was discharged, and reserves its pair + /// after, checks it here first under the wallet lock + /// ([`WalletPersister::private_entry_discharged`]). Only a shielded build + /// keeps a journal to discharge: empty otherwise. + session: BTreeSet<[u8; 32]>, + /// The (sender, recipient) pair of each private contact request payment + /// the shielded store's journal keeps, by its entry's commitment + /// ([`WalletPersister::note_journaled_private_payments`]): the wallet's + /// hold on the pair, which no identity's removal drops. A commitment in + /// `session` is never added, and one noted there is removed, so a + /// discharged payment holds nothing. Only a shielded build journals: + /// empty otherwise. + journaled: BTreeMap<[u8; 32], (Identifier, Identifier)>, } impl WalletPersister { @@ -65,9 +165,349 @@ impl WalletPersister { wallet_id, inner, contact_payment_gate: Arc::new(tokio::sync::Mutex::new(())), + #[cfg(feature = "shielded")] + read_back_private_entries: Arc::default(), + #[cfg(feature = "shielded")] + unflushed_read_back_private_entries: Arc::default(), + discharged_private_entries: Arc::default(), + private_payments_unrestored: Arc::default(), + stored_private_markers: Arc::default(), + #[cfg(feature = "shielded")] + buffered_writes_lost: Arc::default(), + private_store_size_proved: Arc::default(), + private_payment_restore_failure: Arc::default(), + #[cfg(feature = "shielded")] + private_payment_restore_retry: Arc::default(), + } + } + + /// Note how the last restoration of this wallet's private payments went: + /// `Some(reason)` when it failed, `None` once one succeeded + /// ([`Self::private_payment_restore_failure`]). + #[cfg(feature = "shielded")] + pub(crate) fn note_private_payment_restore(&self, failure: Option) { + *self + .private_payment_restore_failure + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) = failure; + } + + /// Why the last restoration of this wallet's private payments failed, if + /// it did and none succeeded since. + pub(crate) fn private_payment_restore_failure(&self) -> Option { + self.private_payment_restore_failure + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .clone() + } + + /// Install how the wallet's views run one more restoration of its private + /// payments ([`Self::retry_private_payment_restore`]). + #[cfg(feature = "shielded")] + pub(crate) fn set_private_payment_restore_retry(&self, retry: PrivatePaymentRestoreRetry) { + *self + .private_payment_restore_retry + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(retry); + } + + /// Run one more restoration of this wallet's private payments, which waits + /// on nothing: a busy shielded store leaves the wallet held. Returns + /// whether one ran, as none does before the wallet built a restoration + /// with a shielded coordinator. + #[cfg(feature = "shielded")] + pub(crate) async fn retry_private_payment_restore(&self) -> bool { + let retry = self + .private_payment_restore_retry + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .clone(); + match retry { + Some(retry) => { + retry(self.clone()).await; + true + } + None => false, } } + /// Note that `owner`'s position record was stored with the marker + /// `marker`, or, with `None`, that whether it was is not known: its last + /// store or flush failed ([`Self::private_marker_stored`]). + pub(crate) fn note_private_marker_stored(&self, owner: Identifier, marker: Option) { + let mut stored = self + .stored_private_markers + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + match marker { + Some(marker) => stored.insert(owner, marker), + None => stored.remove(&owner), + }; + } + + /// The marker `owner`'s position record was last stored with in this + /// session, if one was and its store did not fail since + /// ([`Self::note_private_marker_stored`]). + pub(crate) fn private_marker_stored(&self, owner: &Identifier) -> Option { + self.stored_private_markers + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .get(owner) + .copied() + } + + /// Note the commitments of private contact request entries a private sync + /// read back and recorded durably, for their journal records to be + /// discharged ([`Self::take_read_back_private_entries`]). + #[cfg(feature = "shielded")] + pub(crate) fn note_read_back_private_entries( + &self, + commitments: impl IntoIterator, + ) { + self.read_back_entries().extend(commitments); + } + + /// Note `commitments`, of private requests a private sync read back and + /// recorded, for their journal records to be discharged + /// ([`Self::note_read_back_private_entries`]), once what records them is + /// durable: at once for a backend that commits inline, after a flush + /// otherwise. Those a transient flush failure left are kept, with every + /// one kept before, and noted by the next call whose flush succeeds: an + /// empty one retries them. Those any other failure left are dropped, as the + /// backend dropped the records they rest on. Their journal records, and so + /// the pairs they hold, stay until noted. The host's flush runs with none + /// of the persister's locks held, so a call during it, from another thread + /// or the flush itself, neither waits nor loses what it adds. + /// + /// None is noted once a flush of the wallet's records failed for good in + /// this process ([`Self::buffered_writes_lost`]): a request read back + /// since may be one the wallet tracked before the loss, which a read of + /// its entry again finds tracked and stores nothing for, so its record + /// may be in memory only. Those journal records stay for the next + /// process, whose restoration reads their entries again from what is on + /// disk. + #[cfg(feature = "shielded")] + pub(crate) fn note_read_back_once_durable( + &self, + commitments: impl IntoIterator, + ) { + let pending = { + let mut unflushed = self.unflushed_read_back_entries(); + unflushed.extend(commitments); + std::mem::take(&mut *unflushed) + }; + if pending.is_empty() { + return; + } + if self.buffered_writes_lost() { + tracing::warn!( + dropped = pending.len(), + "private requests read back after this wallet's records were lost are not \ + noted; their journal records stay for the next process" + ); + return; + } + if !self.store_commits_inline() { + if let Err(error) = self.flush() { + if error.is_transient() { + tracing::warn!( + %error, + kept = pending.len(), + "private requests read back are not durably recorded; their journal \ + records stay until a later flush succeeds" + ); + // A transient failure keeps the buffer: with any added + // meanwhile. + self.unflushed_read_back_entries().extend(pending); + } else { + // Any other failure dropped the buffer, the records these + // notices rest on with it: the notices go, so their journal + // records, and the pairs they hold, stay. Their read is not + // rewound: a read again would find the requests already + // tracked, store nothing, and note them again over records + // that never reached disk. The markers stored into that + // buffer are forgotten, so the next comparison stores them + // again (`Self::private_marker_stored`). + tracing::error!( + %error, + dropped = pending.len(), + "private requests read back are not durably recorded, and the backend \ + dropped what it buffered; their journal records stay" + ); + self.stored_private_markers + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .clear(); + } + return; + } + } + self.note_read_back_private_entries(pending); + } + + /// Whether the read-back of `commitment` waits for a flush that failed + /// transiently ([`Self::note_read_back_once_durable`]): that path + /// discharges its journal record once a flush succeeds. + #[cfg(feature = "shielded")] + pub(crate) fn read_back_awaiting_flush(&self, commitment: &[u8; 32]) -> bool { + self.unflushed_read_back_entries().contains(commitment) + } + + #[cfg(feature = "shielded")] + fn unflushed_read_back_entries(&self) -> std::sync::MutexGuard<'_, BTreeSet<[u8; 32]>> { + self.unflushed_read_back_private_entries + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + } + + /// Take the commitments [`Self::note_read_back_private_entries`] noted: + /// a caller that fails to discharge one notes it again. + #[cfg(feature = "shielded")] + pub(crate) fn take_read_back_private_entries(&self) -> BTreeSet<[u8; 32]> { + std::mem::take(&mut *self.read_back_entries()) + } + + /// Note `commitments`, whose private payments' journal records were just + /// discharged: a restoration that read them before skips them + /// ([`Self::private_entry_discharged`]), and the wallet releases what it + /// still reserves for them + /// ([`Self::take_unreleased_discharged_private_entries`]). + #[cfg(feature = "shielded")] + pub(crate) fn note_discharged_private_entries( + &self, + commitments: impl IntoIterator, + ) { + let mut discharged = self.discharged_entries(); + for commitment in commitments { + discharged.unreleased.insert(commitment); + discharged.session.insert(commitment); + discharged.journaled.remove(&commitment); + } + } + + /// Note `payments`, each a private contact request payment's entry + /// commitment with its (sender, recipient) pair, as kept, or about to be + /// kept, by the shielded store's private payment journal: until each is + /// discharged ([`Self::note_discharged_private_entries`]) the wallet holds + /// its pair ([`Self::private_pair_journaled`]), whatever happens to the + /// sender identity. A payment discharged in this session is not noted. + /// Noted before a payment is journaled, and by every restoration from the + /// journal, so the pairs held cover every record the journal keeps. + #[cfg(feature = "shielded")] + pub(crate) fn note_journaled_private_payments( + &self, + payments: impl IntoIterator, + ) { + let mut entries = self.discharged_entries(); + for (commitment, sender, recipient) in payments { + if !entries.session.contains(&commitment) { + entries.journaled.insert(commitment, (sender, recipient)); + } + } + } + + /// Forget `commitments`, noted by [`Self::note_journaled_private_payments`] + /// for a payment whose journal records were then not saved: nothing was + /// paid, so its pair is not held for it. + #[cfg(feature = "shielded")] + pub(crate) fn forget_journaled_private_payments(&self, commitments: &[[u8; 32]]) { + let mut entries = self.discharged_entries(); + for commitment in commitments { + entries.journaled.remove(commitment); + } + } + + /// A recipient of a private payment from `sender` the journal keeps + /// unresolved ([`Self::note_journaled_private_payments`]), if any: the + /// sender then holds a payment that may still execute, whatever its + /// identity's own state says. + pub(crate) fn private_sender_journaled(&self, sender: &Identifier) -> Option { + self.discharged_entries() + .journaled + .values() + .find(|(journaled_sender, _)| journaled_sender == sender) + .map(|(_, recipient)| *recipient) + } + + /// Whether a private payment the journal keeps unresolved holds the pair + /// `sender`, `recipient` ([`Self::note_journaled_private_payments`]): then + /// neither a public request nor another private one is sent for it. + pub(crate) fn private_pair_journaled( + &self, + sender: &Identifier, + recipient: &Identifier, + ) -> bool { + self.discharged_entries() + .journaled + .values() + .any(|pair| *pair == (*sender, *recipient)) + } + + /// Whether the journal record of `commitment` was discharged in this + /// session, its reservation released or not. + pub(crate) fn private_entry_discharged(&self, commitment: &[u8; 32]) -> bool { + self.discharged_entries().session.contains(commitment) + } + + /// Whether [`Self::note_discharged_private_entries`] noted any commitment + /// since the last take. + pub(crate) fn has_unreleased_discharged_private_entries(&self) -> bool { + !self.discharged_entries().unreleased.is_empty() + } + + /// Take the commitments [`Self::note_discharged_private_entries`] noted + /// since the last take. Take them only where they are applied with + /// nothing awaited in between. + pub(crate) fn take_unreleased_discharged_private_entries(&self) -> BTreeSet<[u8; 32]> { + std::mem::take(&mut self.discharged_entries().unreleased) + } + + fn discharged_entries(&self) -> std::sync::MutexGuard<'_, DischargedPrivateEntries> { + self.discharged_private_entries + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + } + + /// Whether [`Self::note_read_back_private_entries`] noted any commitment + /// not taken yet. + #[cfg(feature = "shielded")] + pub(crate) fn has_read_back_private_entries(&self) -> bool { + !self.read_back_entries().is_empty() + } + + /// Hold this wallet's public contact requests, sent or accepted, until + /// [`Self::private_payments_restored`]: its shielded store may hold an + /// unconfirmed private payment from an earlier process whose pair no + /// reservation holds yet. + #[cfg(feature = "shielded")] + pub(crate) fn hold_until_private_payments_restored(&self) { + self.private_payments_unrestored + .store(true, Ordering::Release); + } + + /// The reservations of this wallet's unconfirmed private payments are + /// restored: release the hold [`Self::hold_until_private_payments_restored`] + /// raised. Called after the restored reservations are in place, so a send + /// that sees the hold gone sees them. + #[cfg(feature = "shielded")] + pub(crate) fn private_payments_restored(&self) { + self.private_payments_unrestored + .store(false, Ordering::Release); + } + + /// Whether [`Self::hold_until_private_payments_restored`] holds this + /// wallet's public contact requests. + pub(crate) fn private_payments_unrestored(&self) -> bool { + self.private_payments_unrestored.load(Ordering::Acquire) + } + + #[cfg(feature = "shielded")] + fn read_back_entries(&self) -> std::sync::MutexGuard<'_, BTreeSet<[u8; 32]>> { + self.read_back_private_entries + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + } + /// Keep contact-pool snapshots in reservation order across Core and /// withdrawal sends, including a Core broadcast rejection's pool rollback. /// @@ -118,7 +558,40 @@ impl WalletPersister { } pub(crate) fn flush(&self) -> Result<(), PersistenceError> { - self.inner.flush(self.wallet_id) + let flushed = self.inner.flush(self.wallet_id); + #[cfg(feature = "shielded")] + if flushed.as_ref().is_err_and(|error| !error.is_transient()) { + self.buffered_writes_lost.store(true, Ordering::SeqCst); + } + flushed + } + + /// Whether a flush of this wallet's records failed for good in this + /// process (anything but a transient failure, which keeps the buffer): + /// what the wallet tracked before it may not be on disk, though it is in + /// memory. For the rest of the process no journal record is discharged on + /// the strength of a tracked request: no read-back is noted + /// ([`Self::note_read_back_once_durable`]), and a restoration leaves the + /// records it finds settled for the next process. + #[cfg(feature = "shielded")] + pub(crate) fn buffered_writes_lost(&self) -> bool { + self.buffered_writes_lost.load(Ordering::SeqCst) + } + + /// Note that a page this wallet read proved DashPay's private contact + /// request store held `size` entries. + pub(crate) fn note_private_store_size_proved(&self, size: u64) { + self.private_store_size_proved + .fetch_max(size, Ordering::SeqCst); + } + + /// The largest size of DashPay's private contact request store a page + /// this wallet read proved, in this process, 0 before any. The store only + /// grows and every size is read from a proof, so the store holds at least + /// this many entries from then on: a read reaches its end only once its + /// cursor reaches it, whatever a later page from a node behind shows. + pub(crate) fn private_store_size_proved(&self) -> u64 { + self.private_store_size_proved.load(Ordering::SeqCst) } pub(crate) fn store_commits_inline(&self) -> bool { @@ -136,6 +609,14 @@ impl WalletPersister { self.inner.persistence_capabilities() } + /// Whether the backend stores and restores the private contact request + /// sync's scan state + /// ([`PersistenceCapabilities::PRIVATE_CONTACT_REQUEST_SCAN_STATE`]). + pub(crate) fn persists_private_contact_scan_state(&self) -> bool { + self.persistence_capabilities() + .contains(PersistenceCapabilities::PRIVATE_CONTACT_SCAN_STATE_RESTART) + } + pub(crate) fn load(&self) -> Result { self.inner.load() } @@ -243,6 +724,12 @@ impl PlatformWalletPersistence for NoPlatformPersistence { #[cfg(test)] mod tests { use super::*; + #[cfg(feature = "shielded")] + use crate::changeset::PersistenceErrorKind; + #[cfg(feature = "shielded")] + use std::sync::{mpsc, OnceLock}; + #[cfg(feature = "shielded")] + use std::time::Duration; /// `persists_durably` is a fail-closed security capability: an /// implementation that does NOT explicitly attest durability must read as @@ -270,4 +757,67 @@ mod tests { assert!(!BareMinimum.persists_durably()); assert!(!NoPlatformPersistence.persists_durably()); } + + /// The host's flush runs with no lock of the persister held: a flush that + /// notes another read-back commitment through the same persister, as a + /// reentrant backend or another thread would, completes, and nothing a + /// failed flush was given is lost: the next flush that succeeds notes + /// them all. + #[cfg(feature = "shielded")] + #[test] + fn should_flush_read_back_notices_without_holding_their_lock() { + struct Reentrant { + persister: OnceLock, + flush_fails: AtomicBool, + reentered: AtomicBool, + } + impl PlatformWalletPersistence for Reentrant { + fn store( + &self, + _wallet_id: WalletId, + _changeset: PlatformWalletChangeSet, + ) -> Result<(), PersistenceError> { + Ok(()) + } + fn flush(&self, _wallet_id: WalletId) -> Result<(), PersistenceError> { + // The first flush notes another commitment before it ends. + if !self.reentered.swap(true, Ordering::SeqCst) { + if let Some(persister) = self.persister.get() { + persister.note_read_back_once_durable([[2; 32]]); + } + } + if self.flush_fails.load(Ordering::SeqCst) { + return Err(PersistenceError::backend_with_kind( + PersistenceErrorKind::Transient, + "the disk is busy", + )); + } + Ok(()) + } + fn load(&self) -> Result { + Ok(ClientStartState::default()) + } + } + + let (done, finished) = mpsc::channel(); + std::thread::spawn(move || { + let backend = Arc::new(Reentrant { + persister: OnceLock::new(), + flush_fails: AtomicBool::new(true), + reentered: AtomicBool::new(false), + }); + let persister = WalletPersister::new([0; 32], Arc::clone(&backend) as _); + let _ = backend.persister.set(persister.clone()); + persister.note_read_back_once_durable([[1; 32]]); + let noted_on_failure = persister.has_read_back_private_entries(); + backend.flush_fails.store(false, Ordering::SeqCst); + persister.note_read_back_once_durable([]); + let _ = done.send((noted_on_failure, persister.take_read_back_private_entries())); + }); + let (noted_on_failure, noted) = finished + .recv_timeout(Duration::from_secs(10)) + .expect("the flushes complete"); + assert!(!noted_on_failure, "a failed flush notes nothing"); + assert_eq!(noted, BTreeSet::from([[1; 32], [2; 32]]), "nothing lost"); + } } diff --git a/packages/rs-platform-wallet/src/wallet/platform_wallet.rs b/packages/rs-platform-wallet/src/wallet/platform_wallet.rs index 50a564b04df..0797bb46ca1 100644 --- a/packages/rs-platform-wallet/src/wallet/platform_wallet.rs +++ b/packages/rs-platform-wallet/src/wallet/platform_wallet.rs @@ -17,6 +17,8 @@ use super::asset_lock::manager::AssetLockManager; use super::asset_lock::tracked::TrackedAssetLock; use super::core::{CoreWallet, WalletBalance, WalletGeneration}; use super::identity::{IdentityManager, IdentityWallet}; +#[cfg(feature = "shielded")] +use super::persister::PrivatePaymentRestoreRetry; use super::persister::WalletPersister; #[cfg(feature = "shielded")] use super::platform_addresses::merge_platform_payment_candidate_addresses; @@ -42,10 +44,51 @@ use dpp::fee::Credits; use dpp::identity::signer::Signer; use dpp::identity::{Identity, IdentityPublicKey}; use dpp::prelude::Identifier; +#[cfg(feature = "shielded")] +use { + super::identity::network::{ + dashpay_contract, restore_journaled_private_payments, JournaledPrivatePayment, + }, + super::shielded::operations::{ + discharge_read_back_private_payments, private_document_create_from_pool_with_metadata, + }, + super::shielded::store::{ + PendingRedrive, PrivateContactPayment, PrivatePaymentEntry, PrivatePaymentRecord, + }, + super::shielded::{ + FileBackedShieldedStore, NetworkShieldedCoordinator, OrchardKeySet, ShieldedStore, + }, + crate::{ + AutoAcceptProofSource, ContactCryptoProvider, ContactRequest, EstablishedContact, + PaymentStarted, + }, + dash_sdk::dapi_grpc::platform::v0::ResponseMetadata, + dash_sdk::platform::dashpay::PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + dpp::data_contract::accessors::v0::DataContractV0Getters, + dpp::platform_value::BinaryData, + dpp::serialization::PlatformDeserializableTrusted, + dpp::shielded::builder::OrchardProver, + dpp::state_transition::private_document_create_from_shielded_pool_transition::accessors::PrivateDocumentCreateFromShieldedPoolTransitionAccessorsV0, + dpp::state_transition::StateTransition, + sha2::{Digest, Sha256}, +}; /// Unique identifier for a wallet (32-byte hash). pub type WalletId = [u8; 32]; +/// What a private contact request reply is paid with, which +/// [`PlatformWallet::accept_contact_request_replying_in_kind`] asks for only +/// when the reply is private: the shielded coordinator, the seed the spend +/// authority is derived from (dropped once it is), the shielded account and +/// the prover. +#[cfg(feature = "shielded")] +pub struct PrivateReplyPayment { + pub coordinator: Arc, + pub seed: Seed, + pub account: u32, + pub prover: P, +} + /// Cached capacity snapshot for shielding a Platform Payment account. /// /// The figures are computed from the same lexicographic address ordering and @@ -391,6 +434,13 @@ pub struct PlatformWallet { /// wallet handles observe the one flag. #[cfg(feature = "shielded")] pub(crate) shielded_detached: Arc, + /// This generation's restorations of its private contact request + /// payments from a shielded store's journal: the store one last succeeded + /// from, and the store a deferred one is queued for + /// ([`Self::restore_private_payments_or_defer`]). `Arc` so cloned wallet + /// handles share them. + #[cfg(feature = "shielded")] + private_payment_restores: Arc>, } impl PlatformWallet { @@ -737,6 +787,7 @@ impl PlatformWallet { persister: wallet_persister.clone(), sync_fault, durable_cursors, + generation: Arc::clone(&generation), broadcaster: dashpay_broadcaster, // DashPay write helper: forwards to the live SDK, erasing its // generic write signatures behind concrete by-value methods. @@ -771,6 +822,8 @@ impl PlatformWallet { shield_guard: Arc::new(tokio::sync::Mutex::new(())), #[cfg(feature = "shielded")] shielded_detached: Arc::new(std::sync::atomic::AtomicBool::new(false)), + #[cfg(feature = "shielded")] + private_payment_restores: Arc::default(), } } @@ -984,6 +1037,11 @@ impl PlatformWallet { /// registration (which would leave sync decrypting under one key /// while addresses and spends use another), nor between the /// restore's registration check and its store write. + /// + /// Once installed, the reservations of the private contact requests the + /// store holds unconfirmed payments for are restored into this wallet's + /// identities ([`Self::restore_private_contact_payments`]), with no host + /// call and no crypto provider. #[cfg(feature = "shielded")] async fn install_shielded_views( &self, @@ -991,6 +1049,84 @@ impl PlatformWallet { coordinator: &Arc, start: crate::changeset::ClientStartState, snapshot_generation: u64, + ) -> Result<(), PlatformWalletError> { + self.install_shielded_views_in_one_transaction( + account_views, + coordinator, + start, + snapshot_generation, + ) + .await?; + // After the install transaction: the restore takes the store and + // wallet locks on its own. + self.restore_private_payments_or_defer(coordinator).await; + Ok(()) + } + + /// Restore this wallet's private contact request payments from + /// `coordinator`'s store at once, or, while the store is busy, on a task + /// once it frees. It never waits for the store, which a running scan may + /// hold for minutes while a host binds on its UI thread. + /// + /// A busy store holds the wallet's contact requests until the deferred + /// restoration succeeds, unless this generation already restored from that + /// store: then its reservations are in place and nothing is held or + /// queued. At most one deferred restoration per store is queued: a bind + /// while one waits queues none. The queue frees however its task ends, + /// a panic or an abort included (`DeferredFinish`). Returns the task of + /// the deferred restoration when one was queued. + #[cfg(feature = "shielded")] + pub(crate) async fn restore_private_payments_or_defer( + &self, + coordinator: &Arc, + ) -> Option> { + let restore = self.private_payment_restore(coordinator); + match restore.restore_and_release(false).await { + Ok(Some(_)) => None, + Ok(None) => { + if restore.restored_from_this_store() || !restore.queue_deferred() { + return None; + } + tracing::debug!( + wallet_id = %hex::encode(self.wallet_id), + "the shielded store is busy; private contact request payments are \ + restored once it frees" + ); + // Owned by the task's future from before it is first polled, + // so the queue frees even for a task dropped unpolled. + let restore = DeferredFinish(restore); + Some(tokio::spawn(async move { + if let Err(error) = restore.0.restore_and_release(true).await { + tracing::warn!( + wallet_id = %hex::encode(restore.0.wallet_id), + %error, + "private contact request payments not restored; the wallet's \ + contact requests stay held" + ); + } + })) + } + Err(error) => { + tracing::warn!( + wallet_id = %hex::encode(self.wallet_id), + %error, + "private contact request payments not restored at bind; the wallet's \ + contact requests stay held until a restoration succeeds" + ); + None + } + } + } + + /// The body of [`Self::install_shielded_views`]: one coordinator install + /// transaction. + #[cfg(feature = "shielded")] + async fn install_shielded_views_in_one_transaction( + &self, + account_views: std::collections::BTreeMap, + coordinator: &Arc, + start: crate::changeset::ClientStartState, + snapshot_generation: u64, ) -> Result<(), PlatformWalletError> { // Serialize registration with identity-shield proof construction. Otherwise // an account could disappear before that operation arms its durable guard. @@ -1529,6 +1665,447 @@ impl PlatformWallet { Ok(proven_balance) } + /// Send a DashPay private contact request (protocol version 15) from + /// `sender_identity_id` to `recipient_identity_id`, paying for it from + /// `account`'s shielded notes: nothing on chain names either identity. The + /// request carries `account_label`, `auto_accept_proof` and our + /// `shielded_address` for the contact, is signed by `signer` as the + /// sender's transitions are, and is sealed by `crypto`, which keeps the + /// encryption key. `seed` supplies the transient spend authority (see + /// [`shielded_transfer_to`](Self::shielded_transfer_to)). See + /// [`DashPayView::send_private_contact_request`](crate::DashPayView::send_private_contact_request). + #[cfg(feature = "shielded")] + #[allow(clippy::too_many_arguments)] + pub async fn send_private_contact_request( + &self, + coordinator: &Arc, + seed: &[u8], + account: u32, + sender_identity_id: &Identifier, + recipient_identity_id: &Identifier, + account_label: Option, + auto_accept_proof: AutoAcceptProofSource, + shielded_address: Option<[u8; 43]>, + signer: &S, + crypto: &C, + prover: P, + ) -> Result + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + P: OrchardProver + Send + Sync, + { + let keyset = self.derive_spend_keyset(seed, account).await?; + self.identity + .dashpay() + .send_private_contact_request( + sender_identity_id, + recipient_identity_id, + account_label, + auto_accept_proof, + shielded_address, + signer, + crypto, + |entry, started| { + self.pay_private_contact_request( + coordinator, + keyset, + account, + sender_identity_id, + recipient_identity_id, + entry, + started, + prover, + ) + }, + ) + .await + } + + /// Accept a DashPay contact request that came privately, replying + /// privately and paying for the reply from `account`'s shielded notes, as + /// [`send_private_contact_request`](Self::send_private_contact_request) + /// pays and signing it with `signer`. `shielded_address` is the address + /// the contact may pay us at privately. See + /// [`DashPayView::accept_private_contact_request`](crate::DashPayView::accept_private_contact_request). + #[cfg(feature = "shielded")] + #[allow(clippy::too_many_arguments)] + pub async fn accept_private_contact_request( + &self, + coordinator: &Arc, + seed: &[u8], + account: u32, + request: &ContactRequest, + shielded_address: Option<[u8; 43]>, + signer: &S, + crypto: &C, + prover: P, + ) -> Result + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + P: OrchardProver + Send + Sync, + { + let keyset = self.derive_spend_keyset(seed, account).await?; + self.identity + .dashpay() + .accept_private_contact_request( + request, + shielded_address, + signer, + crypto, + |entry, started| { + self.pay_private_contact_request( + coordinator, + keyset, + account, + &request.recipient_id, + &request.sender_id, + entry, + started, + prover, + ) + }, + ) + .await + } + + /// Accept a DashPay contact request replying the way it came: privately, + /// paid from a shielded account, when it came privately and no reply + /// exists yet, else with a `contactRequest` document signed by `signer`. + /// `payment` gives what a private reply is paid with (the shielded + /// coordinator, the seed for the spend authority, the account and the + /// prover) and is called only for a private reply, so a public reply or + /// an adopted one needs neither shielded support nor the seed. See + /// [`DashPayView::accept_contact_request_replying_in_kind`](crate::DashPayView::accept_contact_request_replying_in_kind). + #[cfg(feature = "shielded")] + pub async fn accept_contact_request_replying_in_kind( + &self, + request: &ContactRequest, + shielded_address: Option<[u8; 43]>, + signer: &S, + crypto: &C, + payment: R, + ) -> Result + where + S: Signer + Send + Sync, + C: ContactCryptoProvider + Sync, + P: OrchardProver + Send + Sync, + Seed: AsRef<[u8]> + Send, + R: FnOnce() -> RFut + Send, + RFut: std::future::Future, PlatformWalletError>> + + Send, + { + self.identity + .dashpay() + .accept_contact_request_replying_in_kind( + request, + shielded_address, + signer, + crypto, + |entry, started| async move { + // Resolving the payment and deriving the spend key come + // first, before `started` is marked: a reply dropped + // meanwhile releases its reservation. + let PrivateReplyPayment { + coordinator, + seed, + account, + prover, + } = payment().await?; + let keyset = self.derive_spend_keyset(seed.as_ref(), account).await?; + drop(seed); + self.pay_private_contact_request( + &coordinator, + keyset, + account, + &request.recipient_id, + &request.sender_id, + entry, + started, + prover, + ) + .await + }, + ) + .await + } + + /// Restore, at startup, the pending DashPay private contact requests + /// whose payment is unconfirmed since before a restart, from the signed + /// transitions `coordinator`'s store keeps for this wallet's unconfirmed + /// spends: until a private sync reads each back, no other request to its + /// recipient is sent, privately or publicly. `crypto` opens the entries. + /// Returns the (sender, recipient) pairs restored. A private send runs + /// the same check right before it pays, so without this call a second + /// private request is still held; this call holds public ones too. A + /// payment saved with its request needs no call: binding restores it + /// ([`Self::restore_private_contact_payments`]). This call stays for + /// records saved before that, and for an identity added after the bind. + /// See + /// [`DashPayView::restore_pending_private_contact_requests`](crate::DashPayView::restore_pending_private_contact_requests) + /// for what it does not cover. + #[cfg(feature = "shielded")] + pub async fn restore_pending_private_contact_requests( + &self, + coordinator: &Arc, + crypto: &C, + ) -> Result, PlatformWalletError> + where + C: ContactCryptoProvider + Sync, + { + let entries = self + .unconfirmed_private_contact_requests(coordinator) + .await?; + self.identity + .dashpay() + .restore_pending_private_contact_requests(&entries, crypto) + .await + } + + /// Restore the reservations of this wallet's private contact request + /// payments that may still execute, from the shielded store's private + /// payment journal (sender, recipient, account reference and entry + /// commitment of each, saved durably before it could reach the network), + /// and release the holds a load set: no keys open anything. Run when the + /// wallet binds to the coordinator, so restored reservations hold every + /// public and private send from then on. Returns the (sender, recipient) + /// pairs restored. + /// + /// Fails closed, every hold staying and the wallet's raised if it was + /// not: for a coordinator of another network, a wallet removed or + /// re-created since this handle was taken, a journal record that does + /// not read back, a saved spend whose transition does not decode and + /// that no journal record accounts for, a private contact request + /// payment saved before the journal kept it with no request to restore + /// its pair from, and an identity loaded marking a private payment that + /// may be unresolved when the journal is new + /// ([`PlatformWalletError::ShieldedRecoveryCorrupted`]). A payment saved + /// before the journal kept it, with its request, is added to the + /// journal. + /// + /// Run also by [`PlatformWalletManager::configure_shielded`] for the + /// wallets the manager holds, by the registration or load of a wallet once + /// the store is configured, and once by a contact request refused as not + /// restored: no keys are needed. Once it succeeds, the wallet's contact + /// requests go ahead, which are held + /// ([`PlatformWalletError::PrivateContactPaymentsNotRestored`]) for a wallet + /// published with no shielded store configured while its persister keeps + /// the private scan state, one loaded after binding a shielded account, one + /// whose last restoration failed or waits for a busy store, and an identity + /// whose position record, its own or one its persister kept after its + /// wallet's removal, marks a private payment that may be unresolved. A + /// payment whose request its sender does not track rewinds the sender's + /// read of the store to where it was when it paid, so the entry is read + /// again. + /// + /// [`PlatformWalletManager::configure_shielded`]: crate::PlatformWalletManager::configure_shielded + #[cfg(feature = "shielded")] + pub async fn restore_private_contact_payments( + &self, + coordinator: &Arc, + ) -> Result, PlatformWalletError> { + self.private_payment_restore(coordinator) + .restore_and_release(true) + .await + .map(Option::unwrap_or_default) + } + + /// The handles a restoration of this wallet's private contact request + /// payments runs on ([`Self::restore_private_contact_payments`]). + /// + /// Installs on the persister one more restoration from `coordinator`, for + /// the wallet's views to run, without waiting on the store, before a + /// contact request is refused as not restored + /// (`WalletPersister::retry_private_payment_restore`): a failed or + /// deferred restoration then lifts at the next send. + #[cfg(feature = "shielded")] + fn private_payment_restore( + &self, + coordinator: &Arc, + ) -> PrivatePaymentRestore { + let retry: PrivatePaymentRestoreRetry = { + let coordinator = Arc::downgrade(coordinator); + let wallet_manager = Arc::clone(&self.wallet_manager); + let generation = Arc::clone(&self.generation); + let restores = Arc::clone(&self.private_payment_restores); + let (wallet_id, network) = (self.wallet_id, self.sdk.network); + Arc::new(move |persister: WalletPersister| { + let restore = coordinator + .upgrade() + .map(|coordinator| PrivatePaymentRestore { + coordinator, + wallet_manager: Arc::clone(&wallet_manager), + persister, + generation: Arc::clone(&generation), + restores: Arc::clone(&restores), + wallet_id, + network, + }); + Box::pin(async move { + let Some(restore) = restore else { + return; + }; + if let Err(error) = restore.restore_and_release(false).await { + tracing::warn!( + wallet_id = %hex::encode(wallet_id), + %error, + "private contact request payments not restored before a send; \ + the wallet's contact requests stay held" + ); + } + }) + }) + }; + self.persister.set_private_payment_restore_retry(retry); + PrivatePaymentRestore { + coordinator: Arc::clone(coordinator), + wallet_manager: Arc::clone(&self.wallet_manager), + persister: self.persister.clone(), + generation: Arc::clone(&self.generation), + restores: Arc::clone(&self.private_payment_restores), + wallet_id: self.wallet_id, + network: self.sdk.network, + } + } + + /// Whether this wallet's public contact requests wait for its private + /// payments from an earlier process to be restored + /// ([`Self::restore_private_contact_payments`]): it bound a shielded account + /// before, or one of its identities was loaded marking a private payment + /// that may be unresolved. + pub async fn private_payments_held(&self) -> bool { + self.persister.private_payments_unrestored() + || self + .identity + .dashpay() + .any_private_payments_unrestored() + .await + } + + /// The entries of the private contact requests whose payment from this + /// wallet's notes `coordinator`'s store holds as unconfirmed. + #[cfg(feature = "shielded")] + async fn unconfirmed_private_contact_requests( + &self, + coordinator: &Arc, + ) -> Result, PlatformWalletError> { + let dashpay_id = dashpay_contract()?.id(); + let store = coordinator.store().read().await; + let redrives = store + .pending_redrives_for_wallet(self.wallet_id) + .map_err(PlatformWalletError::from)?; + Ok(private_contact_request_redrive_entries( + redrives.iter().map(|(_, redrive)| redrive), + dashpay_id, + )) + } + + /// Append the sealed private contact request `entry`, from + /// `sender_identity_id` to `recipient_identity_id`, to DashPay's store, + /// paying from `account`'s notes, and return the metadata of the proof + /// that it was appended. + /// + /// A request between the same pair whose payment is unconfirmed since + /// before a restart may still execute: then nothing is paid, and the + /// recipient stays reserved for that request + /// ([`PlatformWalletError::PrivateContactRequestPending`]). + /// + /// Holds the wallet generation's lifecycle gate from the liveness check + /// until the spend returns, so a removal waits for it. A wallet removed or + /// re-created since this handle was taken is refused with + /// [`PlatformWalletError::WalletRemovedBeforeSend`], with nothing + /// restored, recorded or paid. A caller must not hold the gate. + /// + /// `started` is marked right before the transition may reach the + /// network, after the restore check and the proof: until then a send + /// dropped releases its reservation. + #[cfg(feature = "shielded")] + #[allow(clippy::too_many_arguments)] + async fn pay_private_contact_request

( + &self, + coordinator: &Arc, + keyset: OrchardKeySet, + account: u32, + sender_identity_id: &Identifier, + recipient_identity_id: &Identifier, + entry: BinaryData, + started: PaymentStarted, + prover: P, + ) -> Result + where + P: OrchardProver, + { + // The generation's lifecycle gate, held across the liveness check, + // the restore and the spend, before the wallet manager lock as the + // teardown takes them: a removal cannot complete in between, so a + // removed wallet's spend never records activity, recreating its + // shielded state, or reaches the network. + let _lifecycle = self.core().generation_payment_guard().await; + if !self.core().is_current_generation().await { + return Err(PlatformWalletError::WalletRemovedBeforeSend(hex::encode( + self.wallet_id, + ))); + } + // An earlier payment of the pair the journal keeps may still execute, + // whether or not its redrive record reads: then nothing is paid. The + // journal is read strictly: a record that does not read refuses. + let journaled: Vec<(u32, [u8; 32])> = { + let mut store = coordinator.store().write().await; + discharge_read_back_private_payments(&mut *store, &self.persister, self.wallet_id); + store + .private_payment_journal(self.wallet_id) + .map_err(PlatformWalletError::from)? + .into_iter() + .filter(|record| { + Identifier::from(record.payment.sender) == *sender_identity_id + && Identifier::from(record.payment.recipient) == *recipient_identity_id + }) + .map(|record| (record.payment.account_reference, record.commitment)) + .collect() + }; + if self + .identity + .dashpay() + .hold_for_journaled_private_payment( + sender_identity_id, + recipient_identity_id, + &journaled, + ) + .await? + { + return Err(PlatformWalletError::PrivateContactRequestPending( + *recipient_identity_id, + )); + } + let dashpay_id = dashpay_contract()?.id(); + // Saved with the payment's record, so a restart restores the pair's + // reservation without opening the entry. + let private_contact = + started + .account_reference() + .map(|account_reference| PrivateContactPayment { + sender: sender_identity_id.to_buffer(), + recipient: recipient_identity_id.to_buffer(), + account_reference, + }); + private_document_create_from_pool_with_metadata( + &self.sdk, + coordinator.store(), + Some(&self.persister), + self.wallet_id, + &keyset, + account, + dashpay_id, + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + vec![entry], + private_contact, + &started, + &prover, + ) + .await + } + /// Withdraw from `account`'s notes to a Core L1 address /// (Base58Check string). `core_fee_per_byte` is the L1 fee /// rate (duffs/byte). `seed` supplies the transient spend @@ -1774,6 +2351,11 @@ impl PlatformWallet { /// at `payment_account` doesn't exist, or /// `PlatformShieldCapacityExceeded` if the selected Platform-address set /// can't cover `amount` plus the fee reserve. + /// + /// Succeeds once the shield's verified result reads every input address + /// at or past the nonce the shield signed. The activity row stays pending + /// until the shielded scan observes the note on-chain: the result proves + /// the input addresses, not this shield or its note. #[cfg(feature = "shielded")] pub async fn shielded_shield_from_account( &self, @@ -2245,6 +2827,7 @@ impl PlatformWallet { wallets: _, #[cfg(feature = "shielded")] shielded: _, + retained_private_contact_scan_states: _, } = self.load_persisted()?; if let Some(persisted) = platform_addresses.remove(&self.wallet_id) { @@ -2276,6 +2859,8 @@ impl Clone for PlatformWallet { shield_guard: self.shield_guard.clone(), #[cfg(feature = "shielded")] shielded_detached: self.shielded_detached.clone(), + #[cfg(feature = "shielded")] + private_payment_restores: self.private_payment_restores.clone(), } } } @@ -2350,6 +2935,499 @@ impl DerefMut for WalletStateWriteGuard<'_> { } } +/// The commitments of the entries a saved private contact request payment +/// appends, read from its signed transition. Refused with +/// [`PlatformWalletError::ShieldedRecoveryCorrupted`] when the transition does +/// not decode, is not a private document create (type 29) appending to +/// DashPay's `privateContactRequest` store (`dashpay_id` being DashPay's +/// contract id), carries no entry, or carries one shorter than its 32-byte +/// commitment: the payment's pair is restored from it, so a payment that does +/// not read back fails the restoration rather than release the holds. +#[cfg(feature = "shielded")] +fn associated_payment_commitments( + redrive: &PendingRedrive, + dashpay_id: Identifier, +) -> Result, PlatformWalletError> { + let corrupted = |reason: String| PlatformWalletError::ShieldedRecoveryCorrupted { + account_index: None, + reason, + }; + let transition = match StateTransition::deserialize_from_bytes_trusted(&redrive.st_bytes) { + Ok(StateTransition::PrivateDocumentCreateFromShieldedPool(transition)) => transition, + Ok(_) => { + return Err(corrupted( + "a saved private contact request payment's transition is not a private \ + document create" + .to_string(), + )) + } + Err(error) => { + return Err(corrupted(format!( + "a saved private contact request payment's transition does not decode: {error}" + ))) + } + }; + if transition.data_contract_id() != dashpay_id + || transition.document_type_name() != PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME + { + return Err(corrupted(format!( + "a saved private contact request payment appends to {} {}, not DashPay's \ + {PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME}", + transition.data_contract_id(), + transition.document_type_name() + ))); + } + if transition.entries().is_empty() { + return Err(corrupted( + "a saved private contact request payment carries no entry".to_string(), + )); + } + transition + .entries() + .iter() + .map(|entry| { + let commitment = entry + .as_slice() + .get(..32) + .and_then(|commitment| <[u8; 32]>::try_from(commitment).ok()) + .ok_or_else(|| { + corrupted( + "a saved private contact request payment's entry is shorter than its \ + commitment" + .to_string(), + ) + })?; + Ok(PrivatePaymentEntry { + commitment, + entry_hash: Sha256::digest(entry.as_slice()).into(), + }) + }) + .collect() +} + +/// The handles a restoration of a wallet's private contact request payments +/// from the shielded store's journal runs on, owned, so one the store is +/// busy for runs on a task ([`PlatformWallet::restore_private_contact_payments`]). +#[cfg(feature = "shielded")] +struct PrivatePaymentRestore { + coordinator: Arc, + wallet_manager: Arc>>, + persister: WalletPersister, + generation: Arc, + restores: Arc>, + wallet_id: WalletId, + network: dashcore::Network, +} + +/// A deferred restoration, freeing its queue +/// ([`PrivatePaymentRestore::finish_deferred`]) however its task ends: run, +/// panicked, or dropped with its runtime or by an abort, polled or not. +/// Otherwise a task that ended early would leave the queue taken, so no later +/// bind would queue another and the wallet would stay held until a configure +/// or a restart. +#[cfg(feature = "shielded")] +struct DeferredFinish(PrivatePaymentRestore); + +#[cfg(feature = "shielded")] +impl Drop for DeferredFinish { + fn drop(&mut self) { + self.0.finish_deferred(); + } +} + +/// A wallet generation's restorations of its private contact request +/// payments ([`PlatformWallet::restore_private_payments_or_defer`]). Weak, so +/// a store dropped since is never taken for a new one at the same address. +#[cfg(feature = "shielded")] +#[derive(Default)] +struct PrivatePaymentRestores { + /// The store a restoration last succeeded from. + restored_from: std::sync::Weak>, + /// The store a deferred restoration is queued for. + queued_for: std::sync::Weak>, + /// How many deferred restorations were queued, for tests. + #[cfg(test)] + queued: usize, +} + +#[cfg(feature = "shielded")] +impl PrivatePaymentRestore { + /// Restore, and raise or release the wallet's hold as it went: released + /// once a restoration succeeds, raised when it fails, and when it cannot + /// run yet unless this generation already restored from this store. + /// `Ok(None)` when the store is busy and `wait` is false. + async fn restore_and_release( + &self, + wait: bool, + ) -> Result>, PlatformWalletError> { + let restored = self.restore(wait).await; + match &restored { + Ok(Some(_)) => { + self.restores_lock().restored_from = Arc::downgrade(self.coordinator.store()); + self.persister.note_private_payment_restore(None); + self.persister.private_payments_restored(); + } + Ok(None) if self.restored_from_this_store() => {} + Ok(None) => self.persister.hold_until_private_payments_restored(), + Err(error) => { + self.persister + .note_private_payment_restore(Some(error.to_string())); + self.persister.hold_until_private_payments_restored(); + } + } + restored + } + + /// Whether the requests the wallet tracks are durable now: at once for a + /// backend that commits inline, as each was stored before it was + /// tracked; after a flush that succeeds otherwise. + fn settled_requests_durable(&self) -> bool { + if self.persister.store_commits_inline() { + return true; + } + match self.persister.flush() { + Ok(()) => true, + Err(error) => { + tracing::warn!( + wallet_id = %hex::encode(self.wallet_id), + %error, + "the requests settling private payments are not flushed; their journal \ + records stay for a later restoration" + ); + false + } + } + } + + fn restores_lock(&self) -> std::sync::MutexGuard<'_, PrivatePaymentRestores> { + self.restores + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + } + + /// Whether this generation already restored from this coordinator's store. + fn restored_from_this_store(&self) -> bool { + self.restores_lock() + .restored_from + .upgrade() + .is_some_and(|store| Arc::ptr_eq(&store, self.coordinator.store())) + } + + /// Queue a deferred restoration from this store, unless one is queued + /// already. Returns whether it was queued. + fn queue_deferred(&self) -> bool { + let mut restores = self.restores_lock(); + if restores + .queued_for + .upgrade() + .is_some_and(|store| Arc::ptr_eq(&store, self.coordinator.store())) + { + return false; + } + restores.queued_for = Arc::downgrade(self.coordinator.store()); + #[cfg(test)] + { + restores.queued += 1; + } + true + } + + /// The deferred restoration from this store ran: another may be queued. + fn finish_deferred(&self) { + let mut restores = self.restores_lock(); + if restores + .queued_for + .upgrade() + .is_some_and(|store| Arc::ptr_eq(&store, self.coordinator.store())) + { + restores.queued_for = std::sync::Weak::new(); + } + } + + /// The restoration [`PlatformWallet::restore_private_contact_payments`] + /// documents, fenced against the wallet's replacement. + /// + /// It holds no lifecycle gate, so a removal never waits for its store + /// waits. The fence is the step that reserves the pairs + /// (`reserve_unresolved_private_payments`), which checks the wallet's + /// generation under the wallet manager's write lock, the one a removal + /// takes: a restoration of a wallet removed, or re-created under its id, + /// reserves nothing on the replacement and fails. What it does before + /// that holds whatever the generation: the journal's read-back + /// discharges and migrations are facts about the shared store, and the + /// holds it raises or releases are this generation's own. + async fn restore( + &self, + wait: bool, + ) -> Result>, PlatformWalletError> { + if self.coordinator.network() != self.network { + return Err(PlatformWalletError::InvalidParameter(format!( + "the shielded coordinator is for {:?}, this wallet for {:?}", + self.coordinator.network(), + self.network + ))); + } + let current = { + let wm = self.wallet_manager.read().await; + wm.get_wallet_info(&self.wallet_id) + .is_some_and(|info| Arc::ptr_eq(&info.generation, &self.generation)) + }; + if !current { + return Err(PlatformWalletError::WalletNotFound(hex::encode( + self.wallet_id, + ))); + } + let dashpay_id = dashpay_contract()?.id(); + // Read-backs whose flush failed transiently are noted once a flush + // succeeds now, so the journal read below discharges their records. + self.persister + .note_read_back_once_durable(std::iter::empty()); + let (payments, journal_authoritative) = { + let mut store = if wait { + self.coordinator.store().write().await + } else { + match self.coordinator.store().try_write() { + Ok(store) => store, + Err(_) => return Ok(None), + } + }; + read_private_payment_journal(&mut *store, &self.persister, self.wallet_id, dashpay_id)? + }; + let (restored, settled) = restore_journaled_private_payments( + &self.wallet_manager, + &self.generation, + &self.persister, + self.wallet_id, + &payments, + journal_authoritative, + ) + .await?; + // A record whose request the tracked one records or supersedes was + // read back by an earlier process, which ended before it discharged + // it: discharged now, so its store is not read for it on every launch. + // A busy store leaves it for the next restoration. + // + // Only once what records that request is durable, as a restart would + // otherwise find neither it nor the record. A backend that commits + // inline stored it before the wallet tracked it. Any other is flushed + // first, and a flush that fails leaves the records for a later + // restoration; so does a flush that failed for good earlier in this + // process, after which the tracked request may be in memory only. A + // record whose read-back still waits for its flush is left to that + // path, which discharges it once a flush succeeds. + let settled: Vec<[u8; 32]> = settled + .into_iter() + .filter(|commitment| !self.persister.read_back_awaiting_flush(commitment)) + .collect(); + if !settled.is_empty() + && !self.persister.buffered_writes_lost() + && self.settled_requests_durable() + { + let store = if wait { + Some(self.coordinator.store().write().await) + } else { + self.coordinator.store().try_write().ok() + }; + if let Some(mut store) = store { + let discharged: Vec<[u8; 32]> = settled + .into_iter() + .filter(|commitment| { + store + .discharge_private_payment(self.wallet_id, commitment) + .inspect_err(|error| { + tracing::warn!( + wallet_id = %hex::encode(self.wallet_id), + %error, + "a settled private payment's journal record was not \ + discharged; the next restoration discharges it" + ) + }) + .is_ok() + }) + .collect(); + drop(store); + self.persister.note_discharged_private_entries(discharged); + } + } + // Opened only once a restoration succeeded: a restoration that failed + // closed over a deleted or replaced store fails the same way until a + // known-good store is back. One left closed here is opened by the + // next restoration, which no unresolved marker holds back now. + if !journal_authoritative { + let opened = if wait { + Some(self.coordinator.store().write().await) + } else { + self.coordinator.store().try_write().ok() + } + .map(|mut store| store.open_private_payment_journal(self.wallet_id)); + if let Some(Err(error)) = opened { + tracing::warn!( + wallet_id = %hex::encode(self.wallet_id), + %error, + "the private payment journal was not opened; the next restoration opens it" + ); + } + } + Ok(Some(restored)) + } +} + +/// Read `wallet_id`'s private payment journal for a restoration, as +/// (sender, recipient, account reference, entry commitment), with whether it +/// is authoritative (open: a restoration from it succeeded before). The +/// read-back notices are discharged first. While the journal is new, a spend +/// saved before it kept the wallet's payments is accounted for: one paying +/// for a private contact request with its request saved is added to the +/// journal, one with no request, or whose transition does not decode and +/// that no record accounts for, fails the read +/// ([`PlatformWalletError::ShieldedRecoveryCorrupted`]). +#[cfg(feature = "shielded")] +fn read_private_payment_journal( + store: &mut S, + persister: &WalletPersister, + wallet_id: WalletId, + dashpay_id: Identifier, +) -> Result<(Vec, bool), PlatformWalletError> +where + PlatformWalletError: From, +{ + discharge_read_back_private_payments(store, persister, wallet_id); + let journal_authoritative = store.private_payment_journal_open(wallet_id)?; + let mut records = store.private_payment_journal(wallet_id)?; + let journaled: std::collections::BTreeSet<[u8; 32]> = + records.iter().map(|record| record.commitment).collect(); + let accounted: std::collections::BTreeSet<[u8; 32]> = + records.iter().map(|record| record.activity_id).collect(); + let corrupted = + |account_index: u32, reason: &str| PlatformWalletError::ShieldedRecoveryCorrupted { + account_index: Some(account_index), + reason: reason.to_string(), + }; + // The private contact request payments saved before the journal kept + // them: type 29 spends to DashPay's store no record accounts for. + // While the journal is new only: once a restoration from it succeeded, + // every payment is journaled with its redrive record in one write, so a + // record no journal record accounts for paid for nothing, or was + // discharged. + let mut unjournaled = Vec::new(); + let saved_before_the_journal = if journal_authoritative { + Vec::new() + } else { + store.pending_redrives_for_wallet(wallet_id)? + }; + for (id, redrive) in saved_before_the_journal { + // Identity debits are never private document payments. + if redrive.nullifiers.is_empty() || accounted.contains(&redrive.activity_id) { + continue; + } + let transition = match StateTransition::deserialize_from_bytes_trusted(&redrive.st_bytes) { + Ok(StateTransition::PrivateDocumentCreateFromShieldedPool(transition)) => transition, + Ok(_) => continue, + Err(_) => { + return Err(corrupted( + id.account_index, + "a saved spend's transition does not decode, and no private payment journal \ + record shows it pays for no private contact request", + )) + } + }; + if transition.data_contract_id() == dashpay_id + && transition.document_type_name() == PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME + { + unjournaled.push((id, redrive)); + } + } + // Read only when needed, so a damaged association of a payment the + // journal keeps holds nothing up: for an unjournaled payment, and for a + // new journal, which accounts for nothing saved before it, damaged + // records retained without being loaded included. + let associations: BTreeMap<[u8; 32], PrivateContactPayment> = if journal_authoritative { + BTreeMap::new() + } else { + store + .private_contact_redrives_for_wallet(wallet_id)? + .into_iter() + .map(|(redrive, payment)| (redrive.activity_id, payment)) + .collect() + }; + let mut migrated = Vec::new(); + for (id, redrive) in unjournaled { + let Some(payment) = associations.get(&redrive.activity_id) else { + return Err(corrupted( + id.account_index, + "a private contact request payment saved before the journal kept them carries \ + no request, so its pair cannot be restored", + )); + }; + for entry in associated_payment_commitments(&redrive, dashpay_id)? { + if !journaled.contains(&entry.commitment) { + migrated.push(PrivatePaymentRecord { + account_index: id.account_index, + activity_id: redrive.activity_id, + anchor: redrive.anchor, + // As the record keeps it: unknown for one saved before + // heights were kept, whose expiry is then never proven, + // so its pair stays held. + anchor_height: redrive.anchor_height, + commitment: entry.commitment, + payment: *payment, + nullifiers: redrive.nullifiers.clone(), + entry_hash: Some(entry.entry_hash), + // Not kept with a record saved before the journal: its + // expiry reads the store from its start. + store_position: None, + }); + } + } + } + if !migrated.is_empty() { + store.journal_private_payments(wallet_id, &migrated)?; + records.extend(migrated); + } + Ok(( + records + .into_iter() + .map(|record| { + ( + Identifier::from(record.payment.sender), + Identifier::from(record.payment.recipient), + record.payment.account_reference, + record.commitment, + record.store_position, + ) + }) + .collect(), + journal_authoritative, + )) +} + +/// The entries of every private document create (type 29) among `redrives` +/// that appends to DashPay's `privateContactRequest` store, `dashpay_id` +/// being DashPay's contract id. A record whose transition does not decode +/// is skipped. +#[cfg(feature = "shielded")] +fn private_contact_request_redrive_entries<'a>( + redrives: impl IntoIterator, + dashpay_id: Identifier, +) -> Vec { + redrives + .into_iter() + .filter_map(|redrive| { + match StateTransition::deserialize_from_bytes_trusted(&redrive.st_bytes) { + Ok(StateTransition::PrivateDocumentCreateFromShieldedPool(transition)) + if transition.data_contract_id() == dashpay_id + && transition.document_type_name() + == PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME => + { + Some(transition.entries().to_vec()) + } + _ => None, + } + }) + .flatten() + .collect() +} + /// Verify a bech32m recipient's network class matches `network` before decoding. /// /// The address decoder is network-agnostic (`tdash` is shared by @@ -2381,6 +3459,396 @@ fn check_recipient_hrp( Ok(()) } +#[cfg(all(test, feature = "shielded"))] +mod private_contact_request_redrive_tests { + use super::*; + use dpp::serialization::PlatformSerializable; + use dpp::shielded::SerializedAction; + use dpp::state_transition::private_document_create_from_shielded_pool_transition::methods::PrivateDocumentCreateFromShieldedPoolTransitionMethodsV0; + use dpp::state_transition::private_document_create_from_shielded_pool_transition::PrivateDocumentCreateFromShieldedPoolTransition; + use dpp::version::PlatformVersion; + + /// A type 29 transition appending `entries` to the store of + /// `document_type_name` of `data_contract_id`, with placeholder actions. + fn private_document_create( + data_contract_id: Identifier, + document_type_name: &str, + entries: Vec, + ) -> StateTransition { + let action = SerializedAction { + nullifier: [1; 32], + rk: [2; 32], + cmx: [3; 32], + encrypted_note: vec![4; 216], + cv_net: [5; 32], + spend_auth_sig: [6; 64], + }; + PrivateDocumentCreateFromShieldedPoolTransition::try_from_bundle( + data_contract_id, + document_type_name.to_string(), + entries, + vec![action.clone(), action], + 0, + [7; 32], + vec![8; 64], + [9; 64], + PlatformVersion::latest(), + ) + .expect("a type 29 transition") + } + + /// The unconfirmed spend that broadcast `st_bytes`. + fn redrive(st_bytes: Vec) -> PendingRedrive { + PendingRedrive { + activity_id: [1; 32], + anchor: [7; 32], + nullifiers: vec![[1; 32]], + st_bytes, + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + } + } + + /// Only the entries of type 29 transitions to DashPay's private contact + /// request store are read: not another contract's, not another document + /// type's, and not a record that does not decode. + #[test] + fn should_read_dashpays_private_contact_requests_from_unconfirmed_spends() { + let dashpay_id = dashpay_contract().expect("bundled DashPay").id(); + let entry = |byte: u8| BinaryData::new(vec![byte; 589]); + let serialized = |transition: StateTransition| { + transition + .serialize_to_bytes() + .expect("the transition serializes") + }; + let redrives = [ + redrive(serialized(private_document_create( + dashpay_id, + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + vec![entry(1), entry(2)], + ))), + redrive(serialized(private_document_create( + Identifier::new([4; 32]), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + vec![entry(3)], + ))), + redrive(serialized(private_document_create( + dashpay_id, + "privateNote", + vec![entry(4)], + ))), + redrive(vec![0xFF; 16]), + redrive(serialized(private_document_create( + dashpay_id, + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + vec![entry(5)], + ))), + ]; + assert_eq!( + private_contact_request_redrive_entries(&redrives, dashpay_id), + vec![entry(1), entry(2), entry(5)] + ); + assert_eq!( + private_contact_request_redrive_entries(&[] as &[PendingRedrive], dashpay_id), + Vec::::new() + ); + } +} + +#[cfg(all(test, feature = "shielded"))] +mod private_contact_request_payment_tests { + use super::*; + use crate::events::{EventHandler, PlatformEventHandler}; + use crate::wallet::persister::NoPlatformPersistence; + use crate::wallet::shielded::FileBackedShieldedStore; + use crate::PlatformWalletManager; + use grovedb_commitment_tree::ProvingKey; + use key_wallet::wallet::initialization::WalletAccountCreationOptions; + use std::time::Duration; + + const SEED: [u8; 64] = [0x42; 64]; + + struct NoopEventHandler; + impl EventHandler for NoopEventHandler {} + impl PlatformEventHandler for NoopEventHandler {} + + /// A prover the refused or unfunded payments here never reach. + struct UnreachableProver; + impl OrchardProver for UnreachableProver { + fn proving_key(&self) -> &ProvingKey { + panic!("nothing is proved") + } + } + + fn coordinator_at(dir: &std::path::Path) -> Arc { + coordinator_on(dir, dashcore::Network::Testnet) + } + + fn coordinator_on( + dir: &std::path::Path, + network: dashcore::Network, + ) -> Arc { + let db_path = dir.join("tree.sqlite"); + let store = FileBackedShieldedStore::open_path(&db_path, 100).expect("open file store"); + Arc::new(NetworkShieldedCoordinator::new( + Arc::new(dash_sdk::Sdk::new_mock()), + network, + db_path, + store, + )) + } + + async fn manager_with_wallet() -> ( + Arc>, + Arc, + ) { + let manager = Arc::new(PlatformWalletManager::new( + Arc::new(dash_sdk::Sdk::new_mock()), + Arc::new(NoPlatformPersistence), + Arc::new(NoopEventHandler), + )); + let wallet = add_wallet(&manager).await; + (manager, wallet) + } + + async fn add_wallet( + manager: &PlatformWalletManager, + ) -> Arc { + manager + .create_wallet_from_seed_bytes( + dashcore::Network::Testnet, + &SEED, + WalletAccountCreationOptions::Default, + Some(0), + ) + .await + .expect("wallet") + } + + /// Pay for a private contact request from `wallet`'s account 0. + async fn pay( + wallet: &PlatformWallet, + coordinator: &Arc, + ) -> Result { + let keyset = + OrchardKeySet::from_seed(&SEED, dashcore::Network::Testnet, 0).expect("keyset"); + wallet + .pay_private_contact_request( + coordinator, + keyset, + 0, + &Identifier::from([0xA1; 32]), + &Identifier::from([0xB1; 32]), + BinaryData::new(vec![1; 589]), + PaymentStarted::default(), + UnreachableProver, + ) + .await + } + + /// A handle to a wallet removed, or re-created under the same id, since + /// it was taken pays nothing for a private contact request: it is + /// refused at the liveness check, before the spend. + #[tokio::test] + async fn should_refuse_a_private_payment_from_a_wallet_no_longer_current() { + let dir = tempfile::tempdir().expect("temporary shielded store"); + let coordinator = coordinator_at(dir.path()); + let (manager, removed) = manager_with_wallet().await; + let wallet_id = removed.wallet_id(); + manager.remove_wallet(&wallet_id).await.expect("removed"); + let refused = pay(&removed, &coordinator).await; + assert!( + matches!(&refused, Err(PlatformWalletError::WalletRemovedBeforeSend(id)) + if *id == hex::encode(wallet_id)), + "{refused:?}" + ); + + let recreated = add_wallet(&manager).await; + assert_eq!(recreated.wallet_id(), wallet_id); + let refused = pay(&removed, &coordinator).await; + assert!( + matches!( + refused, + Err(PlatformWalletError::WalletRemovedBeforeSend(_)) + ), + "{refused:?}" + ); + let current = pay(&recreated, &coordinator).await; + assert!( + !matches!( + current, + Err(PlatformWalletError::WalletRemovedBeforeSend(_)) + ), + "the current wallet's payment goes on to the spend: {current:?}" + ); + } + + /// A removal waits for a private payment that entered its fenced section, + /// here held at the shielded store, and completes once it returns. + #[tokio::test] + async fn should_hold_a_wallets_removal_until_its_private_payment_returns() { + let dir = tempfile::tempdir().expect("temporary shielded store"); + let coordinator = coordinator_at(dir.path()); + let (manager, wallet) = manager_with_wallet().await; + let wallet_id = wallet.wallet_id(); + + let store = coordinator.store().write().await; + let payment = { + let wallet = Arc::clone(&wallet); + let coordinator = Arc::clone(&coordinator); + tokio::spawn(async move { pay(&wallet, &coordinator).await }) + }; + tokio::time::sleep(Duration::from_millis(100)).await; + let removal = { + let manager = Arc::clone(&manager); + tokio::spawn(async move { manager.remove_wallet(&wallet_id).await.map(|_| ()) }) + }; + tokio::time::sleep(Duration::from_millis(200)).await; + assert!(!payment.is_finished(), "the payment waits at the store"); + assert!( + !removal.is_finished(), + "the removal waits for the payment in flight" + ); + assert!(wallet.core().is_current_generation().await); + + drop(store); + let paid = payment.await.expect("payment task"); + assert!( + !matches!(paid, Err(PlatformWalletError::WalletRemovedBeforeSend(_))), + "the wallet was current when it was checked: {paid:?}" + ); + removal + .await + .expect("removal task") + .expect("the removal completes"); + assert!(!wallet.core().is_current_generation().await); + } + + /// A restoration waiting for a busy shielded store holds no lifecycle + /// gate: a removal is not held behind its store wait. The step that + /// reserves its pairs fences it to the wallet's generation instead. + #[tokio::test] + async fn should_not_hold_a_removal_behind_a_restoration_s_store_wait() { + let dir = tempfile::tempdir().expect("temporary shielded store"); + let (_manager, wallet) = manager_with_wallet().await; + let coordinator = coordinator_on(dir.path(), wallet.sdk.network); + + let store = coordinator.store().write().await; + let restore = { + let wallet = Arc::clone(&wallet); + let coordinator = Arc::clone(&coordinator); + tokio::spawn(async move { wallet.restore_private_contact_payments(&coordinator).await }) + }; + tokio::time::sleep(Duration::from_millis(100)).await; + assert!(!restore.is_finished(), "the restoration waits at the store"); + let teardown = tokio::time::timeout( + Duration::from_millis(200), + wallet.generation.teardown_guard(), + ) + .await; + assert!( + teardown.is_ok(), + "a removal takes the lifecycle gate while the restoration waits" + ); + drop(teardown); + drop(store); + restore + .await + .expect("restore task") + .expect("the restoration completes"); + } + + /// A deferred restoration whose task ends early, here aborted while it + /// waits for the store, still frees the queue: the next bind queues one. + #[tokio::test] + async fn should_free_the_deferred_restore_queue_when_its_task_is_dropped() { + let dir = tempfile::tempdir().expect("temporary shielded store"); + let (_manager, wallet) = manager_with_wallet().await; + let coordinator = coordinator_on(dir.path(), wallet.sdk.network); + let queued = || { + wallet + .private_payment_restores + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .queued + }; + + let store = coordinator.store().write().await; + let task = wallet + .restore_private_payments_or_defer(&coordinator) + .await + .expect("queued"); + assert!(wallet + .restore_private_payments_or_defer(&coordinator) + .await + .is_none()); + task.abort(); + assert!(task.await.is_err_and(|error| error.is_cancelled())); + assert!( + wallet + .restore_private_payments_or_defer(&coordinator) + .await + .is_some(), + "the aborted task freed the queue" + ); + assert_eq!(queued(), 2); + drop(store); + } + + /// A bind while the shielded store is busy defers the restoration of + /// the wallet's private payments to one task per store: a second bind + /// while it waits queues none. Once a restoration from that store + /// succeeded, a busy store neither holds the wallet's contact requests + /// again nor queues another. + #[tokio::test] + async fn should_coalesce_deferred_restorations_and_keep_a_restored_wallet_available() { + let dir = tempfile::tempdir().expect("temporary shielded store"); + let (_manager, wallet) = manager_with_wallet().await; + let coordinator = coordinator_on(dir.path(), wallet.sdk.network); + let queued = || { + wallet + .private_payment_restores + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .queued + }; + + let store = coordinator.store().write().await; + assert!(wallet + .restore_private_payments_or_defer(&coordinator) + .await + .is_some()); + assert!(wallet + .restore_private_payments_or_defer(&coordinator) + .await + .is_none()); + assert_eq!(queued(), 1, "one deferred restoration per store"); + assert!(wallet.private_payments_held().await, "held until it runs"); + drop(store); + for _ in 0..100 { + if !wallet.private_payments_held().await { + break; + } + tokio::time::sleep(Duration::from_millis(10)).await; + } + assert!(!wallet.private_payments_held().await, "restored"); + + let store = coordinator.store().write().await; + assert!(wallet + .restore_private_payments_or_defer(&coordinator) + .await + .is_none()); + assert!( + !wallet.private_payments_held().await, + "a busy store holds a restored wallet no more" + ); + assert_eq!(queued(), 1, "and queues nothing"); + drop(store); + } +} + #[cfg(all(test, feature = "shielded"))] mod check_recipient_hrp_tests { use super::*; diff --git a/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs b/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs index 03adbe56175..b9700306b2e 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs @@ -365,6 +365,7 @@ async fn local_balance_restores_funds_and_durable_pending_reservations_offline() attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .unwrap(); diff --git a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs index 884f44d8dda..3720a2deefe 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs @@ -51,10 +51,11 @@ //! //! [`sync_notes_across`]: super::sync::sync_notes_across -use std::collections::{BTreeMap, HashSet}; +use std::collections::{BTreeMap, BTreeSet, HashSet}; use std::path::PathBuf; use std::sync::Arc; +use sha2::{Digest, Sha256}; use tokio_util::sync::CancellationToken; use crate::changeset::merge::Merge; @@ -90,17 +91,22 @@ use super::balance::{ use super::file_store::FileBackedShieldedStore; use super::keys::AccountViewingKeys; use super::store::{ - IdentityDebitRecoveryRecord, IdentityDebitRecoveryStatus, ShieldedStore, StalePendingSpend, - SubwalletId, + IdentityDebitRecoveryRecord, IdentityDebitRecoveryStatus, PrivatePaymentRecord, ShieldedStore, + StalePendingSpend, SubwalletId, }; use super::CAUGHT_UP_COOLDOWN; use crate::error::PlatformWalletError; use crate::manager::shielded_sync::{ShieldedSyncPassSummary, WalletShieldedOutcome}; +use crate::wallet::identity::network::dashpay_contract; use crate::wallet::persister::WalletPersister; use crate::wallet::platform_wallet::WalletId; +use dash_sdk::platform::dashpay::PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME; +use dash_sdk::platform::private_document_scan::MAX_CONCURRENT_PRIVATE_DOCUMENT_PAGE_FETCHES; +use dpp::data_contract::accessors::v0::DataContractV0Getters; use dpp::serialization::PlatformDeserializableTrusted; use dpp::state_transition::shield_from_identity_transition::accessors::ShieldFromIdentityTransitionAccessorsV0; use dpp::state_transition::StateTransition; +use futures::StreamExt; /// Network-scoped shielded coordinator. /// @@ -174,6 +180,16 @@ pub struct NetworkShieldedCoordinator { /// activity; bypassed by `force` syncs. last_caught_up_at: std::sync::Mutex>, + /// The journal records, by wallet and entry commitment, whose entry an + /// expiry read found in DashPay's private store + /// ([`Self::discharge_expired_private_payments`]): their payments + /// executed, so they are no candidates for expiry and no later pass reads + /// the store again for them. Each record stays, holding its pair, until a + /// private sync reads its entry back and records the request, which + /// discharges it; then it leaves this set too. In memory only: a restart + /// reads the store for it once more. + landed_private_payments: std::sync::Mutex>, + /// Optional progress callback fired once per chunk inside /// `sync_shielded_notes`. Lets the manager translate chunk-level /// progress into `PlatformEventHandler::on_shielded_sync_progress` @@ -400,6 +416,7 @@ impl NetworkShieldedCoordinator { accounts: Arc::new(RwLock::new(BTreeMap::new())), persisters: Arc::new(RwLock::new(BTreeMap::new())), last_caught_up_at: std::sync::Mutex::new(None), + landed_private_payments: std::sync::Mutex::new(BTreeSet::new()), progress_handler: std::sync::Mutex::new(None), tree_progress_handler: std::sync::Mutex::new(None), lifecycle: tokio::sync::Mutex::new(()), @@ -470,6 +487,19 @@ impl NetworkShieldedCoordinator { &self.db_path } + /// Whether the store's private payment journal may keep a record of + /// `wallet_id`'s: it does, it does not read, or the store is busy, as this + /// waits on nothing. A wallet created or loaded under an id another process + /// journaled payments under has them unresolved, which only the journal + /// shows (`PlatformWalletManager::restore_private_contact_payment_holds`). + pub(crate) fn may_journal_private_payments_of(&self, wallet_id: WalletId) -> bool { + self.store.try_read().map_or(true, |store| { + store + .private_payment_journal(wallet_id) + .map_or(true, |records| !records.is_empty()) + }) + } + /// Reference to the shared store. The full sync / spend /// surfaces land on the coordinator itself; this accessor /// exists for tests and for migration scaffolding in Phase 1. @@ -1295,6 +1325,31 @@ impl NetworkShieldedCoordinator { Ok(()) } + /// Discharge the private payment journal records of the private contact + /// requests each registered wallet's private sync read back and recorded + /// durably (`WalletPersister::note_read_back_private_entries`). + pub(crate) async fn discharge_read_back_private_payments(&self) { + let noted: Vec<(WalletId, WalletPersister)> = self + .persisters + .read() + .await + .iter() + .filter(|(_, persister)| persister.has_read_back_private_entries()) + .map(|(wallet_id, persister)| (*wallet_id, persister.clone())) + .collect(); + if noted.is_empty() { + return; + } + let mut store = self.store.write().await; + for (wallet_id, persister) in ¬ed { + super::operations::discharge_read_back_private_payments( + &mut *store, + persister, + *wallet_id, + ); + } + } + /// Run one shielded sync pass for every registered wallet on /// this coordinator's network. Returns a per-wallet outcome /// summary suitable for emission to UI / persistence layers @@ -1340,6 +1395,10 @@ impl NetworkShieldedCoordinator { return ShieldedSyncPassSummary::default(); } + // Every pass, cooldown or not: the private requests a private sync read + // back discharge their journal records. + self.discharge_read_back_private_payments().await; + // Network-wide cooldown gate. Snapshot the remaining // window into a local before any await — `std::sync::Mutex` // is `!Send` across await points (clippy's @@ -1472,20 +1531,15 @@ impl NetworkShieldedCoordinator { // Runs before the balance read so freed notes are reflected in // this pass's balances. Skipped on a cancelled pass: the re-drive // broadcasts, and a skipped release simply waits for the next pass. - if let Some((snapshot, recorded)) = stranded_release.filter(|_| !cancelled) { - // Snapshot the per-wallet persisters BEFORE the loop and drop - // the read guard: `redrive_pending_spends` performs network - // broadcasts, and holding the persisters lock across those - // awaits would block wallet register/unregister for the - // duration of the round trips. - let subwallet_persisters: Vec<(SubwalletId, Option)> = { - let persisters = self.persisters.read().await; - subwallets - .iter() - .map(|(id, _)| (*id, persisters.get(&id.wallet_id).cloned())) - .collect() - }; - for (id, persister) in &subwallet_persisters { + if let Some(PreScanEvidence { + stale, + journal, + recorded, + recorded_height, + heightless, + }) = stranded_release.filter(|_| !cancelled) + { + for (id, _) in &subwallets { // Network broadcasts: a stop that lands after the scan's // snapshot above stops the loop here, and the helper // checks the token before each request it starts. @@ -1495,8 +1549,6 @@ impl NetworkShieldedCoordinator { super::operations::redrive_pending_spends( &self.sdk, &self.store, - persister.as_ref(), - id.wallet_id, *id, &recorded, cancel, @@ -1504,7 +1556,15 @@ impl NetworkShieldedCoordinator { .await; } if !cancel.is_cancelled() { - self.release_stranded_spends(snapshot, &recorded).await; + let evidence = PrunedAnchorEvidence { + recorded: &recorded, + height: recorded_height, + scan_covered_height: notes.covered_height, + heightless: heightless.as_ref(), + }; + self.release_stranded_spends(stale, evidence).await; + self.discharge_expired_private_payments(&journal, evidence) + .await; } } @@ -1654,30 +1714,40 @@ impl NetworkShieldedCoordinator { .unwrap_or(0) } - /// Pre-scan half of the stranded-reservation release: snapshot the - /// anchored reservations armed right now and fetch Platform's recorded - /// anchor set, or `None` when there is nothing to do. + /// Pre-scan half of the stranded-reservation release and of the private + /// payment expiry: snapshot the anchored reservations armed right now and + /// the wallets' private payment journal records, then fetch Platform's + /// recorded anchor set with the height of its proof, or `None` when there + /// is nothing to do. /// /// MUST run before the pass's note scan — the release's fund-safety /// argument ([`Self::release_stranded_spends`]) rests on both the - /// snapshot and the set predating the scan's spent-note reconcile. + /// snapshot and the set predating the scan's spent-note reconcile. The + /// journal is read before the set: a payment journaled after the fetch + /// may name a newer anchor than the set holds, so it is no candidate this + /// pass ([`Self::discharge_expired_private_payments`]). When one of them + /// names its anchor without the anchor's height and the store bounds the + /// trees such anchors came from, the pool's proved leaf count is fetched + /// first, before the set ([`HeightlessAnchorEvidence`]). /// - /// Skips the network round-trip when no anchored reservation exists (the - /// common case), and treats a recorded-anchor fetch failure as - /// non-fatal — a sync must not fail because that query hiccupped; the - /// release simply waits for the next pass. + /// Skips the network round-trip when neither an anchored reservation nor + /// a journal record exists (the common case), and treats a + /// recorded-anchor fetch failure as non-fatal: a sync must not fail + /// because that query hiccupped, and the release simply waits for the + /// next pass. async fn prefetch_stranded_release( &self, subwallets: &[(SubwalletId, AccountViewingKeys)], - ) -> Option<(Vec<(SubwalletId, StalePendingSpend)>, HashSet<[u8; 32]>)> { - // Gather anchored reservations across every synced subwallet. The - // common case is none — then the network round-trip is skipped. - let stale: Vec<(SubwalletId, StalePendingSpend)> = { + ) -> Option { + // Gather anchored reservations across every synced subwallet, and the + // journal records of their wallets. The common case is none, and then + // the network round-trip is skipped. + let (stale, journal, tree_bounds) = { let store = self.store.read().await; - let mut acc = Vec::new(); + let mut stale: Vec<(SubwalletId, StalePendingSpend)> = Vec::new(); for (id, _) in subwallets { match store.stale_pending_spends(*id) { - Ok(entries) => acc.extend(entries.into_iter().map(|entry| (*id, entry))), + Ok(entries) => stale.extend(entries.into_iter().map(|entry| (*id, entry))), Err(e) => tracing::warn!( wallet_id = %hex::encode(id.wallet_id), account = id.account_index, @@ -1686,16 +1756,58 @@ impl NetworkShieldedCoordinator { ), } } - acc + let journal = private_payment_journal_snapshot( + &*store, + subwallets.iter().map(|(id, _)| id.wallet_id), + ); + let tree_bounds = heightless_tree_bounds(&*store, &stale, &journal); + (stale, journal, tree_bounds) }; - if stale.is_empty() { + if stale.is_empty() && journal.is_empty() { return None; } use dash_sdk::platform::fetch_current_no_parameters::FetchCurrent; - match dash_sdk::query_types::ShieldedAnchors::fetch_current(&self.sdk).await { - Ok(dash_sdk::query_types::ShieldedAnchors(anchors)) => { - Some((stale, anchors.into_iter().collect())) + // The pool's leaf count, read before the anchor set so that it is + // proved at or below the set's height whenever both reads reach + // nodes at the same tip. A count proved above that height shows + // nothing this pass ([`HeightlessAnchorEvidence::recorded_by`]). + let heightless = match tree_bounds { + Some((tree_bound, anchor_floors)) => { + match dash_sdk::query_types::ShieldedNotesCount::fetch_current_with_metadata( + &self.sdk, + ) + .await + { + Ok((dash_sdk::query_types::ShieldedNotesCount(pool_leaves), metadata)) => { + Some(HeightlessAnchorEvidence { + tree_bound, + pool_leaves, + pool_height: metadata.height, + anchor_floors, + }) + } + Err(e) => { + tracing::warn!( + error = %e, + "shielded reservation release: failed to fetch the pool's leaf \ + count; records without an anchor height stay this pass" + ); + None + } + } + } + None => None, + }; + match dash_sdk::query_types::ShieldedAnchors::fetch_current_with_metadata(&self.sdk).await { + Ok((dash_sdk::query_types::ShieldedAnchors(anchors), metadata)) => { + Some(PreScanEvidence { + stale, + journal, + recorded: anchors.into_iter().collect(), + recorded_height: metadata.height, + heightless, + }) } Err(e) => { tracing::warn!( @@ -1716,27 +1828,30 @@ impl NetworkShieldedCoordinator { /// fact have landed), released only when the tx lands or the app /// restarts. A spend accepted but that never lands would otherwise /// strand its notes for the whole session. Here, after the pass's - /// spent-note reconcile, any reservation from the PRE-scan `snapshot` - /// whose anchor is absent from the PRE-scan `recorded` set is provably - /// dead: `validate_anchor_exists` accepts a spend only while its anchor - /// is retained (`shielded_anchor_retention_blocks = 1000`), so once the - /// anchor is pruned the transition can never execute. The notes are - /// freed and the linked activity row flipped to Failed so the UI shows - /// a clear, retryable failure instead of "Pending" forever. The - /// on-chain nullifier set stays the authoritative double-spend guard. + /// spent-note reconcile, a reservation from the PRE-scan `snapshot` is + /// released once `evidence` proves its anchor pruned + /// ([`PrunedAnchorEvidence::proves_pruned`]): `validate_anchor_exists` + /// accepts a spend only while its anchor is retained + /// (`shielded_anchor_retention_blocks = 1000`), so once the anchor is + /// pruned the transition can never execute. The notes are freed and the + /// linked activity row flipped to Failed so the UI shows a clear, + /// retryable failure instead of "Pending" forever. The on-chain + /// nullifier set stays the authoritative double-spend guard. /// - /// Fund-safe by construction, resting on two ordering facts: + /// Fund-safe by construction, resting on two facts: /// - /// 1. Both inputs predate the scan ([`Self::prefetch_stranded_release`]), - /// and the scan's spent-note reconcile ran to completion in between. - /// An anchor absent from the pre-scan set was pruned before the scan - /// began (a pruned root can never re-enter the set — the tree only - /// grows), so if that spend nevertheless executed, it executed at a - /// height the scan covered — the reconcile already cleared its - /// reservation, which fact 2 catches. + /// 1. The evidence is pinned to the anchor set's proved height H: the + /// reservation's anchor was in a set proved at or below H, so the set + /// at H lacks it only once it was pruned (an anchor absent but read + /// above H may be newer than the set), and the pass's note scan, + /// covering H, replayed every nullifier spent at or below H. So if + /// that spend executed, it did so at or below H, and the reconcile + /// already cleared its reservation, which fact 2 catches. Short of + /// that, as with a scan whose proofs are a block behind the set's, + /// nothing is released this pass. /// 2. Each release is a check-and-clear under a single store write /// guard: the reservation is cleared only while the nullifier is - /// still armed with the snapshot's exact anchor + activity. A + /// still armed with the snapshot's exact anchor, height + activity. A /// reservation resolved concurrently (the reconcile above, or the /// spend's own result-wait confirming mid-pass) — or cleared and /// re-armed by a retry with a fresh anchor — is skipped, and its @@ -1744,11 +1859,17 @@ impl NetworkShieldedCoordinator { /// /// A still-recorded (slow-but-landing) spend is never released, and an /// anchor-less reservation (reserved but not yet built) is never in the - /// snapshot (`stale_pending_spends` returns only anchored entries). + /// snapshot (`stale_pending_spends` returns only anchored entries). A + /// reservation whose anchor height is not known (one restored from a + /// record saved before heights were kept) gets H once the set at H + /// holds its anchor ([`ShieldedStore::note_anchor_recorded`]), and is + /// released only on a later set that lacks it, or on a set that lacks it + /// with the pool proved, at or below that set's height, to have reached + /// the tree the anchor is a root of ([`HeightlessAnchorEvidence`]). async fn release_stranded_spends( &self, snapshot: Vec<(SubwalletId, StalePendingSpend)>, - recorded: &HashSet<[u8; 32]>, + evidence: PrunedAnchorEvidence<'_>, ) { // Persister map is only written on wallet register/unregister — // one read acquisition covers the whole loop. @@ -1756,10 +1877,18 @@ impl NetworkShieldedCoordinator { // Every note of a multi-note spend carries the same activity id: // flip each linked row once, not once per nullifier. let mut flipped: HashSet<[u8; 32]> = HashSet::new(); - for (id, (nullifier, anchor, activity_id)) in snapshot { - // Fund-safety invariant: release ONLY when the anchor is absent - // from the recorded set. A still-recorded anchor may yet land. - if recorded.contains(&anchor) { + // Reservations whose anchor height is not known, and whose anchor the + // set at H holds: given H, a later set lacking it shows it pruned. + let mut seen_recorded: std::collections::BTreeSet<(SubwalletId, [u8; 32])> = + std::collections::BTreeSet::new(); + for (id, (nullifier, anchor, activity_id, anchor_height)) in snapshot { + if anchor_height.is_none() && evidence.recorded.contains(&anchor) { + seen_recorded.insert((id, anchor)); + } + // Fund-safety invariant: release ONLY on proof the anchor was + // pruned with the scan covering it. A still-recorded anchor may + // yet land; an absent one read above H may be newer than the set. + if !evidence.proves_pruned(&anchor, anchor_height) { continue; } // Check-and-clear under ONE write acquisition: the snapshot @@ -1771,9 +1900,12 @@ impl NetworkShieldedCoordinator { { let mut store = self.store.write().await; let still_same = match store.stale_pending_spends(id) { - Ok(current) => current - .iter() - .any(|(n, a, act)| *n == nullifier && *a == anchor && *act == activity_id), + Ok(current) => current.iter().any(|(n, a, act, height)| { + *n == nullifier + && *a == anchor + && *act == activity_id + && *height == anchor_height + }), Err(e) => { tracing::warn!( wallet_id = %hex::encode(id.wallet_id), @@ -1839,6 +1971,222 @@ impl NetworkShieldedCoordinator { .await; } } + if !seen_recorded.is_empty() { + let mut store = self.store.write().await; + for (id, anchor) in seen_recorded { + if let Err(e) = store.note_anchor_recorded(id, &anchor, evidence.height) { + tracing::warn!( + wallet_id = %hex::encode(id.wallet_id), + account = id.account_index, + error = %e, + "shielded reservation release: the anchor's recorded height was not \ + kept; its reservations stay until it is" + ); + } + } + } + } + + /// Discharge the private payment journal records of payments proven + /// expired, durably, and note them on their wallet's persister so the + /// wallet releases the pairs they hold + /// (`WalletPersister::note_discharged_private_entries`). + /// + /// The candidates are `journal`, the records the pass read before it + /// fetched the anchor set `evidence` holds, proved at H. A payment is + /// proven never to execute when: + /// + /// 1. its record still reads in the journal exactly as `journal` has it: + /// a payment journaled since, or armed again, may name an anchor newer + /// than the set; + /// 2. `evidence` proves its anchor pruned + /// ([`PrunedAnchorEvidence::proves_pruned`], the rule the note release + /// judges by): read from a set proved at or below H + /// (`anchor_height`), or, for a record without it, recorded at or + /// below H as the pool's proved leaf count shows + /// ([`HeightlessAnchorEvidence`]), absent from the set at H, and the + /// pass's note scan covering H. A pruned root never re-enters the set, so the + /// transition cannot execute above H + /// (`shielded_anchor_retention_blocks` 1000, pruned every + /// `shielded_anchor_pruning_interval` 100 blocks); + /// 3. its entry is absent from DashPay's private contact request store, + /// read raw through its end with every page proved at or above H + /// ([`Self::private_contact_requests_held`]): an entry starts with its + /// commitment, so none needs opening. The transition appends its entry + /// in the block that spends its inputs, so an entry absent at or above + /// H, the transition unable to execute above H, shows it never + /// executed. Whether its inputs are spent does not matter: a competing + /// spend that consumed them does not keep its pair held. + /// + /// Anything short of that discharges nothing this pass, and the next pass + /// retries: a scan or a store read below H, a read that fails, a record + /// changed since. A relay refusal or a missing redrive record is never + /// taken as proof. Point 1 is checked again under the store write guard + /// that discharges the record. + pub(crate) async fn discharge_expired_private_payments( + &self, + journal: &[(WalletId, PrivatePaymentRecord)], + evidence: PrunedAnchorEvidence<'_>, + ) { + let recorded_height = evidence.height; + // Entries found landed before are no candidates: their payments + // executed. One whose record is gone was read back and leaves. + let landed: BTreeSet<(WalletId, [u8; 32])> = { + let mut landed = self + .landed_private_payments + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + landed.retain(|(wallet_id, commitment)| { + journal + .iter() + .any(|(owner, record)| owner == wallet_id && record.commitment == *commitment) + }); + landed.clone() + }; + let pruned: Vec<&(WalletId, PrivatePaymentRecord)> = journal + .iter() + .filter(|(wallet_id, record)| !landed.contains(&(*wallet_id, record.commitment))) + .filter(|(_, record)| evidence.proves_pruned(&record.anchor, record.anchor_height)) + .collect(); + if pruned.is_empty() { + return; + } + let candidates: Vec<(WalletId, PrivatePaymentRecord)> = { + let store = self.store.read().await; + pruned + .into_iter() + .filter(|(wallet_id, record)| unchanged(&*store, *wallet_id, record)) + .cloned() + .collect() + }; + if candidates.is_empty() { + return; + } + let commitments: BTreeMap<[u8; 32], Option<[u8; 32]>> = candidates + .iter() + .map(|(_, record)| (record.commitment, record.entry_hash)) + .collect(); + // Each entry is appended at or after its sender's read position when + // it paid; a record that kept none is read for from the store's start. + let start = candidates + .iter() + .map(|(_, record)| record.store_position) + .try_fold(u64::MAX, |lowest, position| position.map(|p| lowest.min(p))) + .unwrap_or(0); + let held = match self + .private_contact_requests_held(&commitments, start, recorded_height) + .await + { + Ok(held) => held, + Err(error) => { + tracing::warn!( + %error, + "private payment expiry: the private contact request store was not read at \ + the anchor set's height; retried next pass" + ); + return; + } + }; + // An entry the store holds at or above H executed: its record waits + // for a private sync to read it back, and no later pass reads the + // store again for it. + self.landed_private_payments + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .extend( + candidates + .iter() + .filter(|(_, record)| held.contains(&record.commitment)) + .map(|(wallet_id, record)| (*wallet_id, record.commitment)), + ); + let persisters = self.persisters.read().await; + let mut store = self.store.write().await; + for (wallet_id, record) in candidates { + if held.contains(&record.commitment) || !unchanged(&*store, wallet_id, &record) { + continue; + } + match store.discharge_private_payment(wallet_id, &record.commitment) { + Ok(_) => { + tracing::info!( + wallet_id = %hex::encode(wallet_id), + commitment = %hex::encode(record.commitment), + "a private payment's anchor was pruned and its entry is absent from the \ + store: it never executed and never can, its pair is freed" + ); + if let Some(persister) = persisters.get(&wallet_id) { + persister.note_discharged_private_entries([record.commitment]); + } + } + Err(error) => tracing::warn!( + wallet_id = %hex::encode(wallet_id), + %error, + "an expired private payment's journal record was not discharged; retried \ + next pass" + ), + } + } + } + + /// Which of `candidates` DashPay's private contact request store holds, + /// read now from `start` through the end its first page shows, raw: an + /// entry starts with its commitment, and is taken as the candidate's only + /// when the whole entry hashes to the hash the candidate's journal record + /// kept (`PrivatePaymentRecord::entry_hash`), as anyone who saw the + /// commitment can append an entry starting with it; a record saved before + /// the hash was kept matches on the commitment. Only the matches are kept, + /// though every entry is read to show the others absent. Every page must + /// be proved at or above `floor`, the first page's end with it: a page + /// below fails the read, as the store it shows may predate the floor. + pub(crate) async fn private_contact_requests_held( + &self, + candidates: &BTreeMap<[u8; 32], Option<[u8; 32]>>, + start: u64, + floor: u64, + ) -> Result, PlatformWalletError> { + let contract_id = dashpay_contract()?.id(); + let mut pages = std::pin::pin!(self.sdk.private_document_pages_with_heights( + contract_id, + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + start, + MAX_CONCURRENT_PRIVATE_DOCUMENT_PAGE_FETCHES, + )); + let mut held = HashSet::new(); + let mut read = false; + while let Some(page) = pages.next().await { + let (page, heights) = page?; + // Every read the page holds, at or above the floor. + let height = heights.min; + if height < floor { + return Err(PlatformWalletError::ShieldedSyncFailed(format!( + "the private contact request store's page from position {} is proved at \ + height {height}, below {floor}", + page.start_position + ))); + } + read = true; + for entry in page.entries.entries { + let Some(commitment) = entry + .data + .get(..32) + .and_then(|commitment| <[u8; 32]>::try_from(commitment).ok()) + else { + continue; + }; + let matches = candidates.get(&commitment).is_some_and(|hash| match hash { + Some(hash) => <[u8; 32]>::from(Sha256::digest(&entry.data)) == *hash, + None => true, + }); + if matches { + held.insert(commitment); + } + } + } + if !read { + return Err(PlatformWalletError::ShieldedSyncFailed( + "the private contact request store returned no page".to_string(), + )); + } + Ok(held) } /// Derive best-effort activity entries from each subwallet's @@ -2239,6 +2587,238 @@ fn is_own_orchard_recipient(views: &AccountViewingKeys, recipient: &[u8]) -> boo .is_some() } +/// The evidence a sync pass has that an anchor was pruned: Platform's recorded +/// anchor set `recorded`, proved at `height` (H) and read before the pass's +/// note scan, the height that scan covers (`scan_covered_height`, +/// `MultiSyncNotesResult::covered_height`), and, for records that carry no +/// anchor height, what bounds the trees their anchors came from +/// (`heightless`). The one rule the note release +/// ([`NetworkShieldedCoordinator::release_stranded_spends`]) and the private +/// payment expiry +/// ([`NetworkShieldedCoordinator::discharge_expired_private_payments`]) judge +/// an anchor by. +#[derive(Clone, Copy)] +pub(crate) struct PrunedAnchorEvidence<'a> { + pub(crate) recorded: &'a HashSet<[u8; 32]>, + pub(crate) height: u64, + pub(crate) scan_covered_height: Option, + /// `None` when the pass gathered none: a record without an anchor height + /// is then never proven pruned, unless a set is seen holding its anchor + /// ([`ShieldedStore::note_anchor_recorded`]). + pub(crate) heightless: Option<&'a HeightlessAnchorEvidence>, +} + +impl PrunedAnchorEvidence<'_> { + /// Whether a spend built on `anchor`, which was in Platform's recorded + /// set at `anchor_height`, is proven unable to execute above H, with all + /// it could have done at or below H seen by the note scan: + /// + /// 1. the anchor was recorded at or below H: `anchor_height` is known and + /// at or below H, or, for one not known, the pool is proved to have + /// reached the tree the anchor is a root of at or below H + /// ([`HeightlessAnchorEvidence::recorded_by`]). Then the set at H holds + /// the anchor unless it was pruned, and the set lacks it: a pruned root + /// never re-enters the set, so the spend cannot execute above H. An + /// anchor read above H, or at an unknown height without that proof, + /// may simply be newer than the set. + /// 2. the scan covers H: a spend that executed at or below H spent its + /// nullifiers where the scan replayed them. + pub(crate) fn proves_pruned(&self, anchor: &[u8; 32], anchor_height: Option) -> bool { + let recorded_by_the_set = match anchor_height { + Some(read) => read <= self.height, + None => self + .heightless + .is_some_and(|heightless| heightless.recorded_by(anchor, self.height)), + }; + recorded_by_the_set + && !self.recorded.contains(anchor) + && self + .scan_covered_height + .is_some_and(|covered| covered >= self.height) + } +} + +/// What shows that an anchor a record names without its height was recorded +/// by a given height. +/// +/// Every anchor is the root of the local commitment tree at some size S, and +/// Platform records a root at the end of the first block its pool's tree ends +/// at that size (`record_shielded_pool_anchor_if_changed`), the size never +/// shrinking. So a pool proved to hold S leaves or more at a height has +/// recorded the anchor by then. S is not kept, but two bounds are: +/// +/// - S is at most [`Self::tree_bound`], the largest tree the store has held +/// ([`ShieldedStore::legacy_anchor_tree_bound`]): every record this build +/// saves keeps its anchor height, so one without was saved by an earlier +/// build, from a tree no larger than this store held when this build first +/// opened it, and every reset since kept the size it reset first. A reset +/// by an earlier build before that is not seen; the floors below still +/// bound such an anchor's tree. The tree grows only by proved note +/// batches, so the pool reaches that size. +/// - S is more than the position of every note spent on the anchor: a +/// witness to a note proves it in the tree the anchor is a root of +/// ([`Self::anchor_floors`]). +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct HeightlessAnchorEvidence { + /// The largest commitment tree the store has held. + pub(crate) tree_bound: u64, + /// The pool's leaf count, proved in this process at [`Self::pool_height`]. + pub(crate) pool_leaves: u64, + /// The height [`Self::pool_leaves`] was proved at. + pub(crate) pool_height: u64, + /// Per anchor of a record without an anchor height, one past the highest + /// tree position among the notes spent on it that the store holds. + pub(crate) anchor_floors: BTreeMap<[u8; 32], u64>, +} + +impl HeightlessAnchorEvidence { + /// Whether Platform recorded `anchor`, named without its height, at or + /// below `height`: the pool was proved at or below `height` to hold at + /// least [`Self::tree_bound`] leaves, and at least one more than every + /// note spent on it. + pub(crate) fn recorded_by(&self, anchor: &[u8; 32], height: u64) -> bool { + let floor = self.anchor_floors.get(anchor).copied().unwrap_or(0); + self.pool_height <= height && self.pool_leaves >= self.tree_bound.max(floor) + } +} + +/// The bounds `store` keeps on the trees of the anchors that `stale` and +/// `journal` name without their heights: the largest tree it has held +/// ([`HeightlessAnchorEvidence::tree_bound`]) and the floors of those anchors +/// ([`HeightlessAnchorEvidence::anchor_floors`]). `None` when no anchor is +/// named without its height, or the store keeps no such bound. +pub(crate) fn heightless_tree_bounds( + store: &S, + stale: &[(SubwalletId, StalePendingSpend)], + journal: &[(WalletId, PrivatePaymentRecord)], +) -> Option<(u64, BTreeMap<[u8; 32], u64>)> { + let heightless = stale + .iter() + .any(|(_, (_, _, _, anchor_height))| anchor_height.is_none()) + || journal + .iter() + .any(|(_, record)| record.anchor_height.is_none()); + if !heightless { + return None; + } + let tree_bound = store.legacy_anchor_tree_bound()?; + Some((tree_bound, heightless_anchor_floors(store, stale, journal))) +} + +/// Per anchor that a reservation in `stale` or a record in `journal` names +/// without its height, one past the highest commitment tree position among +/// the notes spent on it that `store` holds +/// ([`HeightlessAnchorEvidence::anchor_floors`]). A note the store does not +/// hold, or a subwallet whose notes do not read, raises no floor. +fn heightless_anchor_floors( + store: &S, + stale: &[(SubwalletId, StalePendingSpend)], + journal: &[(WalletId, PrivatePaymentRecord)], +) -> BTreeMap<[u8; 32], u64> { + let spends = stale + .iter() + .filter(|(_, (_, _, _, anchor_height))| anchor_height.is_none()) + .map(|(id, (nullifier, anchor, _, _))| (*id, *anchor, std::slice::from_ref(nullifier))) + .chain( + journal + .iter() + .filter(|(_, record)| record.anchor_height.is_none()) + .map(|(wallet_id, record)| { + ( + SubwalletId::new(*wallet_id, record.account_index), + record.anchor, + record.nullifiers.as_slice(), + ) + }), + ); + let mut positions: BTreeMap> = BTreeMap::new(); + let mut floors: BTreeMap<[u8; 32], u64> = BTreeMap::new(); + for (id, anchor, nullifiers) in spends { + let notes = positions + .entry(id) + .or_insert_with(|| match store.get_all_notes(id) { + Ok(notes) => notes + .into_iter() + .map(|note| (note.nullifier, note.position)) + .collect(), + Err(error) => { + tracing::warn!( + wallet_id = %hex::encode(id.wallet_id), + account = id.account_index, + %error, + "shielded reservation release: the notes do not read; they raise no tree \ + floor for anchors without a height" + ); + BTreeMap::new() + } + }); + for position in nullifiers + .iter() + .filter_map(|nullifier| notes.get(nullifier)) + { + let floor = floors.entry(anchor).or_insert(0); + *floor = (*floor).max(position.saturating_add(1)); + } + } + floors +} + +/// What a sync pass reads before its note scan, for the steps after it that +/// may act only on evidence from before the scan +/// ([`NetworkShieldedCoordinator::prefetch_stranded_release`]). +struct PreScanEvidence { + /// The anchored reservations, for + /// [`NetworkShieldedCoordinator::release_stranded_spends`]. + stale: Vec<(SubwalletId, StalePendingSpend)>, + /// The private payment journal records of the synced wallets, read before + /// the anchor set was fetched, for + /// [`NetworkShieldedCoordinator::discharge_expired_private_payments`]. + journal: Vec<(WalletId, PrivatePaymentRecord)>, + /// Platform's recorded anchor set. + recorded: HashSet<[u8; 32]>, + /// The height of the proof the anchor set was read from. + recorded_height: u64, + /// What bounds the trees of the anchors `stale` and `journal` name + /// without their heights, read before the anchor set; `None` when none + /// does, or none was needed. + heightless: Option, +} + +/// The private payment journal records of `wallet_ids`, each wallet once, in +/// order. A wallet whose journal does not read has none here: nothing of it is +/// a candidate for expiry. +pub(crate) fn private_payment_journal_snapshot( + store: &S, + wallet_ids: impl IntoIterator, +) -> Vec<(WalletId, PrivatePaymentRecord)> { + let wallets: std::collections::BTreeSet = wallet_ids.into_iter().collect(); + let mut journal = Vec::new(); + for wallet_id in wallets { + match store.private_payment_journal(wallet_id) { + Ok(records) => journal.extend(records.into_iter().map(|record| (wallet_id, record))), + Err(error) => tracing::warn!( + wallet_id = %hex::encode(wallet_id), + %error, + "private payment expiry: the journal does not read; no payment of the wallet \ + is a candidate this pass" + ), + } + } + journal +} + +/// Whether `wallet_id`'s journal still holds `record` exactly as a pass's +/// snapshot read it. A store read that fails says no. +fn unchanged( + store: &S, + wallet_id: WalletId, + record: &PrivatePaymentRecord, +) -> bool { + store + .private_payment_journal(wallet_id) + .is_ok_and(|records| records.contains(record)) +} + #[cfg(test)] mod tests { use super::*; @@ -2247,7 +2827,9 @@ mod tests { use crate::changeset::ShieldedChangeSet; use crate::wallet::shielded::activity::compute_activity_id; - use crate::wallet::shielded::store::PendingRedrive; + use crate::wallet::shielded::store::{ + InMemoryShieldedStore, PendingRedrive, PrivateContactPayment, ShieldedNote, + }; use dpp::platform_value::BinaryData; use dpp::serialization::PlatformSerializable; use dpp::shielded::SerializedAction; @@ -2350,6 +2932,7 @@ mod tests { attempts: 0, identity_nonce_finalized: true, identity_user_abandoned: false, + anchor_height: None, }, cmxs, ) @@ -2923,6 +3506,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; coordinator .store() @@ -3299,6 +3883,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; coordinator .store() @@ -3412,6 +3997,7 @@ mod tests { attempts: 0, identity_nonce_finalized: true, identity_user_abandoned: false, + anchor_height: None, }, ) .unwrap(); @@ -3758,24 +4344,32 @@ mod tests { let mut store = coordinator.store.write().await; store.mark_pending(id, &pruned_nf).expect("mark pruned"); store - .set_pending_spend(id, &pruned_nf, pruned_anchor, pruned_act) + .set_pending_spend(id, &pruned_nf, pruned_anchor, pruned_act, Some(10)) .expect("arm pruned"); store.mark_pending(id, &live_nf).expect("mark live"); store - .set_pending_spend(id, &live_nf, live_anchor, live_act) + .set_pending_spend(id, &live_nf, live_anchor, live_act, Some(10)) .expect("arm live"); } // Snapshot as the pre-scan prefetch would have produced it; the // recorded set holds only the live anchor (the other was "pruned"). let snapshot = vec![ - (id, (pruned_nf, pruned_anchor, Some(pruned_act))), - (id, (live_nf, live_anchor, Some(live_act))), + (id, (pruned_nf, pruned_anchor, Some(pruned_act), Some(10))), + (id, (live_nf, live_anchor, Some(live_act), Some(10))), ]; let recorded: HashSet<[u8; 32]> = [live_anchor].into_iter().collect(); coordinator - .release_stranded_spends(snapshot, &recorded) + .release_stranded_spends( + snapshot, + PrunedAnchorEvidence { + recorded: &recorded, + height: 10, + scan_covered_height: Some(10), + heightless: None, + }, + ) .await; let remaining = coordinator @@ -3797,6 +4391,464 @@ mod tests { let _ = std::fs::remove_dir_all(&dir); } + /// The whole sync pass, its note scan proved a block below the anchor set + /// (within the SDK's one-block tolerance): a spend built on an anchor the + /// set lacks may have executed in that block, which the scan has not + /// shown, so its note stays reserved, its saved record stays and its + /// activity stays Pending. Once the scan covers the set's height, the + /// pass releases it. An anchor read above the set's height, absent from + /// it, may be newer than the set and is never released by it. + #[tokio::test] + async fn should_release_a_stranded_spend_only_once_the_scan_covers_the_anchor_set() { + use super::super::activity::{ + ShieldedActivityEntry, ShieldedActivityKind, ShieldedDirection, + }; + use crate::wallet::shielded::ShieldedNote; + use drive_proof_verifier::types::{ + NoParamQuery, ShieldedAnchors, ShieldedEncryptedNotes, ShieldedEncryptedNotesQuery, + }; + + const SET_HEIGHT: u64 = 50; + let mut sdk = dash_sdk::Sdk::new_mock(); + let count = 2048 + * u32::from( + sdk.version() + .drive_abci + .query + .shielded_queries + .max_query_chunks, + ); + // The scan's window of 16 chunk fetches, all of an empty pool. + for chunk in 0..16 { + sdk.mock() + .expect_fetch( + ShieldedEncryptedNotesQuery { + start_index: u64::from(count) * chunk, + count, + }, + Some(ShieldedEncryptedNotes { + notes: Vec::new(), + total_count: 0, + }), + ) + .await + .expect("an empty chunk"); + } + sdk.mock() + .expect_fetch(NoParamQuery {}, Some(ShieldedAnchors(vec![[0xEE; 32]]))) + .await + .expect("the anchor set"); + sdk.mock() + .set_response_height_of::(SET_HEIGHT) + .set_response_height_of::(SET_HEIGHT - 1); + + let dir = temp_dir("release_scan_below_set"); + std::fs::create_dir_all(&dir).expect("create temp dir"); + let db_path = dir.join("tree.sqlite"); + let coordinator = NetworkShieldedCoordinator::new( + Arc::new(sdk.clone()), + dashcore::Network::Testnet, + db_path.clone(), + FileBackedShieldedStore::open_path(&db_path, 100).expect("open file store"), + ); + let wallet_id: WalletId = [0x11; 32]; + let views = OrchardKeySet::from_seed(&[0x42u8; 64], dashcore::Network::Testnet, 0) + .expect("derive viewing keys") + .viewing_keys(); + coordinator + .register_wallet( + wallet_id, + BTreeMap::from([(0u32, views)]), + WalletPersister::new(wallet_id, Arc::new(NoPlatformPersistence)), + ) + .await + .expect("register wallet"); + let id = SubwalletId::new(wallet_id, 0); + // Two broadcast spends whose anchors the set lacks: one read below + // the set's height, one above it. + let spends = [ + ([0x21; 32], [0x22; 32], [0x23; 32], SET_HEIGHT - 5), + ([0x31; 32], [0x32; 32], [0x33; 32], SET_HEIGHT + 1), + ]; + { + let mut store = coordinator.store().write().await; + for (index, (nullifier, anchor, activity, anchor_height)) in spends.iter().enumerate() { + let note = ShieldedNote { + position: index as u64, + cmx: [0x40 + index as u8; 32], + nullifier: *nullifier, + block_height: 1, + is_spent: false, + value: 1_000, + note_data: vec![0u8; 115], + }; + store.save_note(id, ¬e).expect("note"); + store.mark_pending(id, nullifier).expect("reserved"); + store + .set_pending_spend(id, nullifier, *anchor, *activity, Some(*anchor_height)) + .expect("anchored"); + store + .arm_redrive( + id, + PendingRedrive { + activity_id: *activity, + anchor: *anchor, + nullifiers: vec![*nullifier], + st_bytes: vec![0xDE, 0xAD], + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: Some(*anchor_height), + }, + ) + .expect("record"); + store + .save_activity( + id, + &ShieldedActivityEntry { + id: *activity, + kind: ShieldedActivityKind::Unshield, + direction: ShieldedDirection::Out, + amount: 900, + fee: None, + counterparty: None, + memo: None, + block_height: None, + status: ShieldedActivityStatus::Pending, + created_at_ms: 1, + min_note_position: None, + note_cmxs: vec![], + spent_nullifiers: vec![*nullifier], + }, + ) + .expect("activity"); + } + } + let state = |store: &FileBackedShieldedStore, nullifier: [u8; 32], activity: [u8; 32]| { + let reserved = !store + .get_unspent_notes(id) + .expect("notes") + .iter() + .any(|note| note.nullifier == nullifier); + let saved = store + .pending_redrives(id) + .expect("records") + .iter() + .any(|record| record.activity_id == activity); + let status = store + .get_activity_by_entry_id(id, &activity) + .expect("activity") + .map(|entry| entry.status); + (reserved, saved, status) + }; + let held = (true, true, Some(ShieldedActivityStatus::Pending)); + + coordinator.sync(true, &CancellationToken::new()).await; + { + let store = coordinator.store().read().await; + for (nullifier, _, activity, _) in &spends { + assert_eq!( + state(&store, *nullifier, *activity), + held, + "a scan a block below the set releases nothing" + ); + } + } + + sdk.mock() + .set_response_height_of::(SET_HEIGHT); + coordinator.sync(true, &CancellationToken::new()).await; + let store = coordinator.store().read().await; + assert_eq!( + state(&store, spends[0].0, spends[0].2), + (false, false, Some(ShieldedActivityStatus::Failed)), + "proven pruned once the scan covers the set" + ); + assert_eq!( + state(&store, spends[1].0, spends[1].2), + held, + "an anchor read above the set may be newer than it" + ); + drop(store); + let _ = std::fs::remove_dir_all(&dir); + } + + /// A reservation restored from a record saved before anchor heights were + /// kept has no known height: its anchor absent from a set may be newer + /// than it, so it is not released. A set holding the anchor gives it that + /// set's height, durably, and a later set lacking it, with the scan + /// covering that set, releases it. + #[tokio::test] + async fn should_release_a_heightless_reservation_only_after_a_set_held_its_anchor() { + let dir = temp_dir("release_heightless"); + let coordinator = coordinator_with_one_wallet(&dir).await; + let id = SubwalletId::new([0x11; 32], 0); + let nullifier = [0x51; 32]; + let anchor = [0x52; 32]; + let activity = [0x53; 32]; + { + let mut store = coordinator.store.write().await; + store.mark_pending(id, &nullifier).expect("reserved"); + store + .set_pending_spend(id, &nullifier, anchor, activity, None) + .expect("anchored, no height"); + store + .arm_redrive( + id, + PendingRedrive { + activity_id: activity, + anchor, + nullifiers: vec![nullifier], + st_bytes: vec![0xDE, 0xAD], + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }, + ) + .expect("record"); + } + let stale = |coordinator: &NetworkShieldedCoordinator| { + let store = coordinator.store.clone(); + async move { store.read().await.stale_pending_spends(id).expect("stale") } + }; + let release = |recorded: HashSet<[u8; 32]>, height: u64| { + let snapshot_store = coordinator.store.clone(); + let coordinator = &coordinator; + async move { + let snapshot: Vec<(SubwalletId, StalePendingSpend)> = snapshot_store + .read() + .await + .stale_pending_spends(id) + .expect("stale") + .into_iter() + .map(|entry| (id, entry)) + .collect(); + coordinator + .release_stranded_spends( + snapshot, + PrunedAnchorEvidence { + recorded: &recorded, + height, + scan_covered_height: Some(height), + heightless: None, + }, + ) + .await; + } + }; + + // Absent from the first set seen: perhaps newer than it. + release(HashSet::new(), 10).await; + assert_eq!( + stale(&coordinator).await, + vec![(nullifier, anchor, Some(activity), None)], + "not proven pruned" + ); + // A set holding it gives it the set's height. + release(HashSet::from([anchor]), 20).await; + assert_eq!( + stale(&coordinator).await, + vec![(nullifier, anchor, Some(activity), Some(20))], + ); + let reopened = + FileBackedShieldedStore::open_path(dir.join("tree.sqlite"), 100).expect("reopened"); + assert_eq!( + reopened.pending_redrives(id).expect("records")[0].anchor_height, + Some(20), + "kept durably" + ); + drop(reopened); + // A later set lacking it releases it. + release(HashSet::new(), 30).await; + assert!(stale(&coordinator).await.is_empty(), "proven pruned"); + let _ = std::fs::remove_dir_all(&dir); + } + + /// A note spend an earlier process saved before anchor heights were kept, + /// from a tree of `TREE` leaves. Reopened, its height stays unknown, and a + /// set lacking its anchor shows it pruned only with the pool proved, at or + /// below the set's height, to hold `TREE` leaves or more, and the scan + /// covering the set. Evidence a block behind the anchor, with every proof + /// at H - 1 and the pool short of its tree, releases nothing: the anchor + /// may postdate that set. + #[tokio::test] + async fn should_release_a_reopened_heightless_reservation_only_once_the_pool_reached_its_tree() + { + const TREE: u64 = 4; + const H: u64 = 10; + let dir = temp_dir("release_reopened_heightless"); + std::fs::create_dir_all(&dir).expect("create temp dir"); + let db_path = dir.join("tree.sqlite"); + let id = SubwalletId::new([0x11; 32], 0); + let (nullifier, anchor, activity) = ([0x61; 32], [0x62; 32], [0x63; 32]); + { + // An earlier process, before heights were kept. + let mut store = FileBackedShieldedStore::open_path(&db_path, 100).expect("open"); + for leaf in 0..TREE { + store + .append_commitment(&[leaf as u8 + 1; 32], true) + .expect("appended"); + } + store.mark_pending(id, &nullifier).expect("reserved"); + store + .arm_redrive( + id, + PendingRedrive { + activity_id: activity, + anchor, + nullifiers: vec![nullifier], + st_bytes: vec![0xDE, 0xAD], + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }, + ) + .expect("record"); + } + let coordinator = NetworkShieldedCoordinator::new( + Arc::new(dash_sdk::Sdk::new_mock()), + dashcore::Network::Testnet, + db_path.clone(), + FileBackedShieldedStore::open_path(&db_path, 100).expect("reopened"), + ); + let stale = || async { + coordinator + .store + .read() + .await + .stale_pending_spends(id) + .expect("stale") + }; + assert_eq!( + stale().await, + vec![(nullifier, anchor, Some(activity), None)], + "its height stays unknown" + ); + let recorded = HashSet::new(); + // (set height, scan coverage, pool leaves and their height, released) + let cases = [ + ( + H - 1, + H - 1, + Some((TREE - 1, H - 1)), + false, + "a block behind", + ), + (H, H, None, false, "no pool count"), + ( + H, + H, + Some((TREE - 1, H)), + false, + "the pool short of the tree", + ), + ( + H, + H, + Some((TREE, H + 1)), + false, + "the pool proved above the set", + ), + (H, H - 1, Some((TREE, H)), false, "the scan below the set"), + (H, H, Some((TREE, H - 1)), true, "proven"), + ]; + for (set_height, covered, pool, released, case) in cases { + let snapshot: Vec<(SubwalletId, StalePendingSpend)> = + stale().await.into_iter().map(|entry| (id, entry)).collect(); + let heightless = { + let store = coordinator.store.read().await; + let (tree_bound, anchor_floors) = + heightless_tree_bounds(&*store, &snapshot, &[]).expect("bounded"); + assert_eq!(tree_bound, TREE, "the tree the earlier process held"); + pool.map(|(pool_leaves, pool_height)| HeightlessAnchorEvidence { + tree_bound, + pool_leaves, + pool_height, + anchor_floors, + }) + }; + coordinator + .release_stranded_spends( + snapshot, + PrunedAnchorEvidence { + recorded: &recorded, + height: set_height, + scan_covered_height: Some(covered), + heightless: heightless.as_ref(), + }, + ) + .await; + assert_eq!(stale().await.is_empty(), released, "{case}"); + } + let _ = std::fs::remove_dir_all(&dir); + } + + /// The floor of an anchor named without its height is one past the + /// highest position of the notes spent on it that the store holds, over + /// every reservation and journal record naming it, and a pool count + /// shows the anchor recorded only once it reaches both that floor and the + /// tree bound. A note the store does not hold raises no floor. + #[test] + fn should_bound_a_heightless_anchor_s_tree_by_the_notes_spent_on_it() { + let (anchor, other, dated) = ([0x51; 32], [0x52; 32], [0x53; 32]); + let wallet_id = [0x11; 32]; + let id = SubwalletId::new(wallet_id, 0); + let note = |position: u64, nullifier: u8| ShieldedNote { + position, + cmx: [nullifier; 32], + nullifier: [nullifier; 32], + block_height: 1, + is_spent: false, + value: 1, + note_data: vec![], + }; + let mut store = InMemoryShieldedStore::new(); + for (position, nullifier) in [(3, 0x61), (8, 0x62), (20, 0x63)] { + store + .save_note(id, ¬e(position, nullifier)) + .expect("saved"); + } + let stale = vec![ + (id, ([0x61; 32], anchor, None, None)), + (id, ([0x64; 32], other, None, None)), + // A dated reservation raises no floor. + (id, ([0x63; 32], dated, None, Some(5))), + ]; + let journal = vec![( + wallet_id, + PrivatePaymentRecord { + account_index: 0, + activity_id: [0x71; 32], + anchor, + anchor_height: None, + commitment: [0x72; 32], + payment: PrivateContactPayment { + sender: [1; 32], + recipient: [2; 32], + account_reference: 0, + }, + nullifiers: vec![[0x62; 32], [0x65; 32]], + entry_hash: None, + store_position: None, + }, + )]; + let floors = heightless_anchor_floors(&store, &stale, &journal); + assert_eq!(floors, BTreeMap::from([(anchor, 9)])); + let evidence = |pool_leaves| HeightlessAnchorEvidence { + tree_bound: 6, + pool_leaves, + pool_height: 10, + anchor_floors: floors.clone(), + }; + assert!(!evidence(8).recorded_by(&anchor, 10), "below its floor"); + assert!(evidence(9).recorded_by(&anchor, 10), "at its floor"); + assert!(!evidence(5).recorded_by(&other, 10), "below the bound"); + assert!(evidence(6).recorded_by(&other, 10), "at the bound"); + assert!(!evidence(9).recorded_by(&anchor, 9), "proved above the set"); + } + /// A token cancelled before the pass starts: no network call (the /// mock SDK would otherwise fail every wallet), no store change and /// no caught-up cooldown stamp (dashpay/platform#5200). diff --git a/packages/rs-platform-wallet/src/wallet/shielded/file_store.rs b/packages/rs-platform-wallet/src/wallet/shielded/file_store.rs index 0970e75d48a..1b22d0a32f7 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/file_store.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/file_store.rs @@ -11,7 +11,7 @@ //! tree (or, when the host persister is wired up, restored from //! SwiftData before sync runs). -use std::collections::BTreeMap; +use std::collections::{BTreeMap, BTreeSet}; use std::error::Error as StdError; use std::fmt; use std::path::{Path, PathBuf}; @@ -23,12 +23,20 @@ use grovedb_commitment_tree::{ClientPersistentCommitmentTree, Position, Retentio use super::balance::{ShieldedBalanceSource, ShieldedLocalAccountBalance}; use super::store::{ - PendingRedrive, ShieldedNote, ShieldedOutgoingNote, ShieldedStore, StalePendingSpend, - SubwalletId, SubwalletState, + PendingRedrive, PrivateContactPayment, PrivatePaymentEntry, PrivatePaymentRecord, ShieldedNote, + ShieldedOutgoingNote, ShieldedStore, StalePendingSpend, SubwalletId, SubwalletState, }; use crate::error::PlatformWalletError; use crate::wallet::platform_wallet::WalletId; +/// The note-spend kind of a private document create from the shielded pool +/// (type 29), the transition a private contact request payment is. +const PRIVATE_DOCUMENT_CREATE_KIND: &str = "private document create from shielded pool"; + +/// A private payment journal row: the entry's commitment, which keys it, and +/// the record's bytes ([`PrivatePaymentRecord::to_bytes`]). +type JournalRow = ([u8; 32], Vec); + /// Error type for [`FileBackedShieldedStore`]. #[derive(Debug)] pub enum FileShieldedStoreError { @@ -102,16 +110,245 @@ pub struct FileBackedShieldedStore { /// Per-subwallet notes + sync state, keyed by `(wallet_id, /// account_index)`. Lazily populated on first use of an id. subwallets: BTreeMap, - /// Second connection on the same SQLite file, owning the - /// `shielded_pending_spends` table (armed [`PendingRedrive`] - /// records). Separate from `tree` because the commitment-tree - /// wrapper takes its `Connection` by value; WAL mode makes the - /// two-connection setup safe. `Mutex` for the same `Sync`-shim - /// reason as `tree`. + /// Second connection on the same SQLite file, owning the recovery + /// tables: `shielded_pending_spends` (armed [`PendingRedrive`] records) + /// and the private payment journal. Separate from `tree` because the + /// commitment-tree wrapper takes its `Connection` by value; WAL mode + /// makes the two-connection setup safe. It commits at + /// `synchronous=FULL` ([`Self::open_recovery_connection`]): a recovery + /// record saved before a broadcast must survive a power loss, unlike the + /// rebuildable tree. `Mutex` for the same `Sync`-shim reason as `tree`. pending_conn: Mutex, + /// The private contact request each armed record pays for, by subwallet + /// and activity id, as the `private_contact_payment` column keeps it. + /// Read joined with the live records, so an entry whose record was + /// dropped is passed over. A record with no association (SQL NULL, as + /// one saved before associations were kept) has no entry. + private_contact_payments: BTreeMap<(SubwalletId, [u8; 32]), SavedPrivateContactPayment>, + /// The wallets of damaged records retained but not loaded that carry a + /// private contact request association, `None` for one whose wallet does + /// not read either: the payment they stand for cannot be restored, so + /// restoring a covered wallet's reservations fails + /// ([`ShieldedStore::private_contact_redrives_for_wallet`]). + unloaded_private_contact_payments: BTreeSet>, + /// The private payment journal's records, by wallet and commitment, as + /// the `shielded_private_payment_journal` table keeps them. + private_payment_journal: BTreeMap<(WalletId, [u8; 32]), PrivatePaymentRecord>, + /// The wallets whose private payment journal is open, as the + /// `shielded_private_payment_journal_wallets` table keeps them. + private_payment_journals: BTreeSet, + /// The wallets of journal records that do not read back, `None` for one + /// whose wallet does not read either. The row stays, and reading a + /// covered wallet's journal fails, so its holds stay. + unreadable_private_payment_journal: BTreeSet>, + /// The largest commitment tree the store had held when it was opened + /// ([`ShieldedStore::legacy_anchor_tree_bound`]); `None` for none. + legacy_anchor_tree_bound: Option, +} + +/// The private contact request association a saved record carries. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum SavedPrivateContactPayment { + /// The association, as it was saved. + Readable(PrivateContactPayment), + /// A non-null association that does not decode, or a column that does + /// not read: restoring the record's wallet fails, so its holds stay. + Unreadable, } impl FileBackedShieldedStore { + /// Drop the private contact request associations of `id` whose record is + /// gone, as its redrives are removed. The listing joins with the live + /// records, so a left one restores nothing, but would stay in memory + /// until the store is reopened. + fn evict_private_contact_payments(&mut self, id: SubwalletId) { + let live = self.subwallets.get(&id); + self.private_contact_payments + .retain(|(owner, activity_id), _| { + *owner != id || live.is_some_and(|sw| sw.redrives.contains_key(activity_id)) + }); + } + + /// Persist `redrive`, with the private contact request it pays for when + /// it does, and the journal `records` of the entries it appends, in one + /// transaction committed at `synchronous=FULL`. + fn arm_redrive_paying_for( + &mut self, + id: SubwalletId, + redrive: PendingRedrive, + payment: Option, + records: &[PrivatePaymentRecord], + ) -> Result<(), FileShieldedStoreError> { + let journal_rows = Self::journal_rows(records)?; + { + let mut conn = self + .pending_conn + .lock() + .map_err(|e| FileShieldedStoreError::Storage(format!("pending_conn mutex: {e}")))?; + let tx = conn + .transaction() + .map_err(|e| FileShieldedStoreError::Storage(format!("begin redrive: {e}")))?; + let nullifier_blob: Vec = redrive.nullifiers.iter().flatten().copied().collect(); + tx.execute( + "INSERT OR REPLACE INTO shielded_pending_spends \ + (wallet_id, account_index, activity_id, anchor, nullifiers, st_bytes, attempts, identity_nonce_finalized, identity_user_abandoned, private_contact_payment, anchor_height) \ + VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)", + rusqlite::params![ + id.wallet_id.as_slice(), + id.account_index, + redrive.activity_id.as_slice(), + redrive.anchor.as_slice(), + nullifier_blob, + redrive.st_bytes, + redrive.attempts, + redrive.identity_nonce_finalized, + redrive.identity_user_abandoned, + payment.map(|payment| payment.to_bytes().to_vec()), + // A height past SQLite's integer range is kept unknown, + // which only holds the notes longer. + redrive + .anchor_height + .and_then(|height| i64::try_from(height).ok()), + ], + ) + .map_err(|e| FileShieldedStoreError::Storage(format!("persist redrive: {e}")))?; + Self::insert_journal_rows(&tx, id.wallet_id, &journal_rows)?; + tx.commit() + .map_err(|e| FileShieldedStoreError::Storage(format!("commit redrive: {e}")))?; + } + if !records.is_empty() { + self.private_payment_journals.insert(id.wallet_id); + } + for record in records { + self.private_payment_journal + .insert((id.wallet_id, record.commitment), record.clone()); + } + match payment { + Some(payment) => { + self.private_contact_payments.insert( + (id, redrive.activity_id), + SavedPrivateContactPayment::Readable(payment), + ); + } + None => { + self.private_contact_payments + .remove(&(id, redrive.activity_id)); + } + } + self.subwallets.entry(id).or_default().arm_redrive(redrive); + Ok(()) + } + + /// The rows `records` are kept as: commitment and record bytes. Fails + /// for a record [`PrivatePaymentRecord::to_bytes`] refuses. + fn journal_rows( + records: &[PrivatePaymentRecord], + ) -> Result, FileShieldedStoreError> { + records + .iter() + .map(|record| { + record + .to_bytes() + .map(|bytes| (record.commitment, bytes)) + .ok_or_else(|| { + FileShieldedStoreError::Storage( + "a private payment's journal record spends no note, or too many" + .to_string(), + ) + }) + }) + .collect() + } + + /// Insert `rows` into `wallet_id`'s journal within `tx`, opening the + /// journal too. + fn insert_journal_rows( + tx: &rusqlite::Transaction<'_>, + wallet_id: WalletId, + rows: &[JournalRow], + ) -> Result<(), FileShieldedStoreError> { + if rows.is_empty() { + return Ok(()); + } + tx.execute( + "INSERT OR IGNORE INTO shielded_private_payment_journal_wallets (wallet_id) \ + VALUES (?1)", + rusqlite::params![wallet_id.as_slice()], + ) + .map_err(|e| FileShieldedStoreError::Storage(format!("open payment journal: {e}")))?; + for (commitment, bytes) in rows { + tx.execute( + "INSERT OR REPLACE INTO shielded_private_payment_journal \ + (wallet_id, commitment, record) VALUES (?1, ?2, ?3)", + rusqlite::params![wallet_id.as_slice(), commitment.as_slice(), bytes], + ) + .map_err(|e| FileShieldedStoreError::Storage(format!("journal payment: {e}")))?; + } + Ok(()) + } + + /// Load the private payment journal into memory. A row that does not + /// read back stays, and flags its wallet + /// (`unreadable_private_payment_journal`); the open does not fail. + fn load_private_payment_journal(&mut self) -> Result<(), FileShieldedStoreError> { + let conn = self + .pending_conn + .lock() + .map_err(|e| FileShieldedStoreError::Storage(format!("pending_conn mutex: {e}")))?; + let mut journals = conn + .prepare("SELECT wallet_id FROM shielded_private_payment_journal_wallets") + .map_err(|e| FileShieldedStoreError::Storage(format!("prepare journals: {e}")))?; + let wallets = journals + .query_map([], |row| row.get::<_, Vec>(0)) + .map_err(|e| FileShieldedStoreError::Storage(format!("query journals: {e}")))?; + for wallet in wallets { + // A journal whose wallet does not read is not open for any wallet. + if let Some(wallet_id) = wallet + .ok() + .and_then(|bytes| <[u8; 32]>::try_from(bytes.as_slice()).ok()) + { + self.private_payment_journals.insert(wallet_id); + } + } + drop(journals); + let mut statement = conn + .prepare("SELECT wallet_id, commitment, record FROM shielded_private_payment_journal") + .map_err(|e| FileShieldedStoreError::Storage(format!("prepare journal: {e}")))?; + let rows = statement + .query_map([], |row| { + Ok(( + row.get::<_, Vec>(0).ok(), + row.get::<_, Vec>(1).ok(), + row.get::<_, Vec>(2).ok(), + )) + }) + .map_err(|e| FileShieldedStoreError::Storage(format!("query journal: {e}")))?; + for row in rows { + let (wallet_id, commitment, record) = + row.map_err(|e| FileShieldedStoreError::Storage(format!("read journal: {e}")))?; + let wallet_id = wallet_id.and_then(|bytes| <[u8; 32]>::try_from(bytes.as_slice()).ok()); + let read = wallet_id.and_then(|wallet_id| { + let commitment = <[u8; 32]>::try_from(commitment?.as_slice()).ok()?; + let record = PrivatePaymentRecord::from_bytes(&record?)?; + (record.commitment == commitment).then_some((wallet_id, record)) + }); + match read { + Some((wallet_id, record)) => { + self.private_payment_journal + .insert((wallet_id, record.commitment), record); + } + None => { + tracing::warn!( + "retaining a private payment journal record that does not read back; \ + its wallet's private contact request holds stay" + ); + self.unreadable_private_payment_journal.insert(wallet_id); + } + } + } + Ok(()) + } + /// Called under the coordinator's store read guard so amount and provenance /// cannot straddle a sync or a pending-spend reservation. pub(super) fn local_account_balance( @@ -174,7 +411,7 @@ impl FileBackedShieldedStore { let conn = Self::open_tuned_connection(&path)?; let tree = ClientPersistentCommitmentTree::open(conn, max_checkpoints) .map_err(|e| FileShieldedStoreError::Storage(format!("open commitment tree: {e}")))?; - let pending_conn = Self::open_tuned_connection(&path)?; + let pending_conn = Self::open_recovery_connection(&path)?; pending_conn .execute( "CREATE TABLE IF NOT EXISTS shielded_pending_spends ( @@ -215,17 +452,116 @@ impl FileBackedShieldedStore { .map_err(|e| FileShieldedStoreError::Storage(format!("upgrade pending schema: {e}")))?; } } + // A proved height at which the record's anchor was recorded, when + // known (`PendingRedrive::anchor_height`): NULL for a record saved + // before it was kept. + if !columns.iter().any(|existing| existing == "anchor_height") { + pending_conn + .execute( + "ALTER TABLE shielded_pending_spends ADD COLUMN anchor_height INTEGER", + [], + ) + .map_err(|e| { + FileShieldedStoreError::Storage(format!("upgrade pending schema: {e}")) + })?; + } + // The private contact request a record pays for, when it does. + if !columns + .iter() + .any(|existing| existing == "private_contact_payment") + { + pending_conn + .execute( + "ALTER TABLE shielded_pending_spends ADD COLUMN private_contact_payment BLOB", + [], + ) + .map_err(|e| { + FileShieldedStoreError::Storage(format!("upgrade pending schema: {e}")) + })?; + } + // The private payment journal: one record per private contact request + // payment that may have reached the network, by wallet and entry + // commitment, and the wallets whose journal is open. Never purged. + pending_conn + .execute_batch( + "CREATE TABLE IF NOT EXISTS shielded_private_payment_journal ( + wallet_id BLOB NOT NULL, + commitment BLOB NOT NULL, + record BLOB NOT NULL, + PRIMARY KEY (wallet_id, commitment) + ); + CREATE TABLE IF NOT EXISTS shielded_private_payment_journal_wallets ( + wallet_id BLOB NOT NULL PRIMARY KEY + );", + ) + .map_err(|e| { + FileShieldedStoreError::Storage(format!("create private payment journal: {e}")) + })?; + // The largest commitment tree the store has held, raised at every open + // and before every reset: never purged. + pending_conn + .execute( + "CREATE TABLE IF NOT EXISTS shielded_store_meta ( + key TEXT NOT NULL PRIMARY KEY, + value INTEGER NOT NULL + )", + [], + ) + .map_err(|e| FileShieldedStoreError::Storage(format!("create store meta: {e}")))?; let mut store = Self { tree: Mutex::new(tree), path, max_checkpoints, subwallets: BTreeMap::new(), pending_conn: Mutex::new(pending_conn), + private_contact_payments: BTreeMap::new(), + unloaded_private_contact_payments: BTreeSet::new(), + private_payment_journal: BTreeMap::new(), + private_payment_journals: BTreeSet::new(), + unreadable_private_payment_journal: BTreeSet::new(), + legacy_anchor_tree_bound: None, }; + // Every record loaded below without an anchor height was saved by an + // earlier process, from a tree no larger than the largest the store + // has held: the tree as it is now, or one a reset cleared, whose size + // the reset kept. + let size = store.tree_size()?; + let largest = store.raise_largest_tree_size(size)?; + store.legacy_anchor_tree_bound = (largest > 0).then_some(largest); store.rehydrate_pending_spends()?; + store.load_private_payment_journal()?; Ok(store) } + /// Raise the largest commitment tree size the store keeps durably to + /// `size`, returning the largest it keeps now. + fn raise_largest_tree_size(&self, size: u64) -> Result { + let size = i64::try_from(size).map_err(|_| { + FileShieldedStoreError::Storage(format!("tree size {size} past SQLite's integers")) + })?; + let conn = self + .pending_conn + .lock() + .map_err(|e| FileShieldedStoreError::Storage(format!("pending_conn mutex: {e}")))?; + conn.execute( + "INSERT INTO shielded_store_meta (key, value) VALUES ('largest_tree_size', ?1) \ + ON CONFLICT(key) DO UPDATE SET value = MAX(value, excluded.value)", + rusqlite::params![size], + ) + .map_err(|e| FileShieldedStoreError::Storage(format!("raise largest tree size: {e}")))?; + let largest: i64 = conn + .query_row( + "SELECT value FROM shielded_store_meta WHERE key = 'largest_tree_size'", + [], + |row| row.get(0), + ) + .map_err(|e| FileShieldedStoreError::Storage(format!("read largest tree size: {e}")))?; + u64::try_from(largest).map_err(|_| FileShieldedStoreError::RecoveryCorrupted { + account_index: None, + reason: format!("a negative largest tree size {largest}"), + }) + } + /// Reload every persisted [`PendingRedrive`] into the in-memory /// per-subwallet state, re-arming both the redrive record and the /// note reservations its nullifiers carry — an unconfirmed @@ -239,7 +575,8 @@ impl FileBackedShieldedStore { let mut stmt = conn .prepare( "SELECT wallet_id, account_index, activity_id, anchor, nullifiers, st_bytes, \ - attempts, identity_nonce_finalized, identity_user_abandoned FROM shielded_pending_spends", + attempts, identity_nonce_finalized, identity_user_abandoned, \ + private_contact_payment, anchor_height FROM shielded_pending_spends", ) .map_err(|e| FileShieldedStoreError::Storage(format!("prepare rehydrate: {e}")))?; let rows = stmt @@ -249,6 +586,31 @@ impl FileBackedShieldedStore { // A malformed st_bytes value remains unclassifiable and must // fail closed. let classifiable_st_bytes = row.get::<_, Vec>(5).ok(); + // The wallet, read on its own too, for a damaged record that is + // retained without being loaded. + let readable_wallet_id = row + .get::<_, Vec>(0) + .ok() + .and_then(|bytes| <[u8; 32]>::try_from(bytes.as_slice()).ok()); + // SQL NULL is a record with no association. Anything else that + // does not read back fails restoring the wallet's reservations + // rather than losing the pair it holds. + let private_contact_payment = match row.get::<_, Option>>(9) { + Ok(None) => None, + Ok(Some(bytes)) => Some( + PrivateContactPayment::from_bytes(&bytes) + .map_or(SavedPrivateContactPayment::Unreadable, |payment| { + SavedPrivateContactPayment::Readable(payment) + }), + ), + Err(_) => Some(SavedPrivateContactPayment::Unreadable), + }; + // A height that does not read is not known. + let anchor_height = row + .get::<_, Option>(10) + .ok() + .flatten() + .and_then(|height| u64::try_from(height).ok()); let decoded: rusqlite::Result<_> = (|| { Ok(( row.get::<_, Vec>(0)?, @@ -262,15 +624,26 @@ impl FileBackedShieldedStore { row.get::<_, i64>(8)?, )) })(); - Ok((classifiable_st_bytes, decoded)) + Ok(( + classifiable_st_bytes, + readable_wallet_id, + private_contact_payment, + anchor_height, + decoded, + )) }) .map_err(|e| FileShieldedStoreError::Storage(format!("query rehydrate: {e}")))?; for row in rows { - let (classifiable_st_bytes, decoded) = - row.map_err(|e| FileShieldedStoreError::RecoveryCorrupted { - account_index: None, - reason: format!("cannot decode recovery row: {e}"), - })?; + let ( + classifiable_st_bytes, + readable_wallet_id, + private_contact_payment, + anchor_height, + decoded, + ) = row.map_err(|e| FileShieldedStoreError::RecoveryCorrupted { + account_index: None, + reason: format!("cannot decode recovery row: {e}"), + })?; let note_spend_kind = classifiable_st_bytes .as_deref() .and_then(Self::non_identity_note_spend_kind); @@ -293,6 +666,11 @@ impl FileBackedShieldedStore { error = %error, "retaining but skipping a damaged shielded note-spend recovery row" ); + if private_contact_payment.is_some() || kind == PRIVATE_DOCUMENT_CREATE_KIND + { + self.unloaded_private_contact_payments + .insert(readable_wallet_id); + } continue; } return Err(FileShieldedStoreError::RecoveryCorrupted { @@ -351,6 +729,7 @@ impl FileBackedShieldedStore { nullifiers, st_bytes, attempts, + anchor_height, identity_nonce_finalized, identity_user_abandoned, }, @@ -366,15 +745,29 @@ impl FileBackedShieldedStore { reason = %error, "retaining but skipping a damaged shielded note-spend recovery row" ); + if private_contact_payment.is_some() || kind == PRIVATE_DOCUMENT_CREATE_KIND + { + self.unloaded_private_contact_payments + .insert(readable_wallet_id); + } continue; } return Err(error); } }; + if let Some(payment) = private_contact_payment { + self.private_contact_payments + .insert((id, redrive.activity_id), payment); + } let sw = self.subwallets.entry(id).or_default(); for n in &redrive.nullifiers { sw.mark_pending(n); - sw.set_pending_spend(n, redrive.anchor, redrive.activity_id); + sw.set_pending_spend( + n, + redrive.anchor, + redrive.activity_id, + redrive.anchor_height, + ); } sw.arm_redrive(redrive); } @@ -399,6 +792,9 @@ impl FileBackedShieldedStore { StateTransition::IdentityTopUpFromShieldedPool(_) => { Some("identity top up from shielded pool") } + StateTransition::PrivateDocumentCreateFromShieldedPool(_) => { + Some(PRIVATE_DOCUMENT_CREATE_KIND) + } _ => None, } } @@ -413,6 +809,27 @@ impl FileBackedShieldedStore { /// /// [`open_path`]: Self::open_path /// [`reset_commitment_tree`]: ShieldedStore::reset_commitment_tree + /// [`Self::open_tuned_connection`] committing at `synchronous=FULL`, for + /// the recovery tables: in WAL mode that syncs the WAL on every commit, + /// so a recovery record saved before a broadcast survives a crash or + /// power loss. The commitment tree's connection keeps `NORMAL`. + fn open_recovery_connection( + path: &Path, + ) -> Result { + let conn = Self::open_tuned_connection(path)?; + conn.pragma_update(None, "synchronous", "FULL") + .map_err(|e| { + FileShieldedStoreError::Storage(format!("PRAGMA synchronous=FULL: {e}")) + })?; + // On Apple platforms `synchronous=FULL` syncs with `fsync`, which does + // not flush the drive's own cache; `fullfsync` makes it `F_FULLFSYNC`, + // so a record that returned durable survives a power loss there too. + // Elsewhere SQLite ignores it. + conn.pragma_update(None, "fullfsync", "ON") + .map_err(|e| FileShieldedStoreError::Storage(format!("PRAGMA fullfsync=ON: {e}")))?; + Ok(conn) + } + fn open_tuned_connection(path: &Path) -> Result { let conn = rusqlite::Connection::open(path) .map_err(|e| FileShieldedStoreError::Storage(format!("open sqlite: {e}")))?; @@ -565,6 +982,7 @@ impl ShieldedStore for FileBackedShieldedStore { rehydrate on the next open (self-heals via reconcile/prune)" ); } + self.private_contact_payments.remove(&(id, *activity_id)); } Ok(outcome.newly_spent) } @@ -595,23 +1013,107 @@ impl ShieldedStore for FileBackedShieldedStore { rehydrate on the next open (self-heals via reconcile/prune)" ); } + self.evict_private_contact_payments(id); } Ok(removed) } + fn mark_pending_by( + &mut self, + id: SubwalletId, + nullifier: &[u8; 32], + reservation: u64, + ) -> Result { + Ok(self + .subwallets + .entry(id) + .or_default() + .mark_pending_by(nullifier, reservation)) + } + + fn clear_pending_reserved_by( + &mut self, + id: SubwalletId, + nullifier: &[u8; 32], + reservation: u64, + ) -> Result { + let Some(sw) = self.subwallets.get_mut(&id) else { + return Ok(false); + }; + let released = sw.clear_pending_reserved_by(nullifier, reservation); + if released { + // Same log-don't-abort rationale as `clear_pending`. + if let Err(e) = self.delete_redrive_rows_containing(id, nullifier) { + tracing::warn!( + error = %e, + "redrive row deletion failed after a released reservation; a stale row \ + may rehydrate on the next open (self-heals via reconcile/prune)" + ); + } + self.evict_private_contact_payments(id); + } + Ok(released) + } + fn set_pending_spend( &mut self, id: SubwalletId, nullifier: &[u8; 32], anchor: [u8; 32], activity_id: [u8; 32], + anchor_height: Option, ) -> Result<(), Self::Error> { if let Some(sw) = self.subwallets.get_mut(&id) { - sw.set_pending_spend(nullifier, anchor, activity_id); + sw.set_pending_spend(nullifier, anchor, activity_id, anchor_height); } Ok(()) } + fn note_anchor_recorded( + &mut self, + id: SubwalletId, + anchor: &[u8; 32], + height: u64, + ) -> Result<(), Self::Error> { + let Some(sw) = self.subwallets.get_mut(&id) else { + return Ok(()); + }; + // Durable first: a failure gives nothing a height, which holds. So + // does a height past SQLite's integer range. + let Ok(durable_height) = i64::try_from(height) else { + return Ok(()); + }; + let records = sw.redrives_without_anchor_height(anchor); + if !records.is_empty() { + let mut conn = self + .pending_conn + .lock() + .map_err(|e| FileShieldedStoreError::Storage(format!("pending_conn mutex: {e}")))?; + let tx = conn.transaction().map_err(|e| { + FileShieldedStoreError::Storage(format!("begin anchor height: {e}")) + })?; + for activity_id in &records { + tx.execute( + "UPDATE shielded_pending_spends SET anchor_height = ?4 \ + WHERE wallet_id = ?1 AND account_index = ?2 AND activity_id = ?3 \ + AND anchor_height IS NULL", + rusqlite::params![ + id.wallet_id.as_slice(), + id.account_index, + activity_id.as_slice(), + durable_height, + ], + ) + .map_err(|e| FileShieldedStoreError::Storage(format!("note anchor height: {e}")))?; + } + tx.commit().map_err(|e| { + FileShieldedStoreError::Storage(format!("commit anchor height: {e}")) + })?; + } + sw.note_anchor_recorded(anchor, height); + Ok(()) + } + fn stale_pending_spends(&self, id: SubwalletId) -> Result, Self::Error> { Ok(self .subwallets @@ -621,31 +1123,246 @@ impl ShieldedStore for FileBackedShieldedStore { } fn arm_redrive(&mut self, id: SubwalletId, redrive: PendingRedrive) -> Result<(), Self::Error> { + self.arm_redrive_paying_for(id, redrive, None, &[]) + } + + fn arm_private_contact_payment( + &mut self, + id: SubwalletId, + redrive: PendingRedrive, + payment: PrivateContactPayment, + entries: &[PrivatePaymentEntry], + anchor_height: u64, + store_position: Option, + ) -> Result<(), Self::Error> { + let records: Vec = entries + .iter() + .map(|entry| PrivatePaymentRecord { + account_index: id.account_index, + activity_id: redrive.activity_id, + anchor: redrive.anchor, + anchor_height: Some(anchor_height), + commitment: entry.commitment, + payment, + nullifiers: redrive.nullifiers.clone(), + entry_hash: Some(entry.entry_hash), + store_position, + }) + .collect(); + self.arm_redrive_paying_for(id, redrive, Some(payment), &records) + } + + fn private_payment_journal_open(&self, wallet_id: WalletId) -> Result { + Ok(self.private_payment_journals.contains(&wallet_id)) + } + + fn open_private_payment_journal(&mut self, wallet_id: WalletId) -> Result<(), Self::Error> { + if self.private_payment_journals.contains(&wallet_id) { + return Ok(()); + } { - let conn = self.pending_conn.lock().expect("pending_conn mutex"); - let nullifier_blob: Vec = redrive.nullifiers.iter().flatten().copied().collect(); + let conn = self + .pending_conn + .lock() + .map_err(|e| FileShieldedStoreError::Storage(format!("pending_conn mutex: {e}")))?; conn.execute( - "INSERT OR REPLACE INTO shielded_pending_spends \ - (wallet_id, account_index, activity_id, anchor, nullifiers, st_bytes, attempts, identity_nonce_finalized, identity_user_abandoned) \ - VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)", - rusqlite::params![ - id.wallet_id.as_slice(), - id.account_index, - redrive.activity_id.as_slice(), - redrive.anchor.as_slice(), - nullifier_blob, - redrive.st_bytes, - redrive.attempts, - redrive.identity_nonce_finalized, - redrive.identity_user_abandoned, - ], + "INSERT OR IGNORE INTO shielded_private_payment_journal_wallets (wallet_id) \ + VALUES (?1)", + rusqlite::params![wallet_id.as_slice()], ) - .map_err(|e| FileShieldedStoreError::Storage(format!("persist redrive: {e}")))?; + .map_err(|e| FileShieldedStoreError::Storage(format!("open payment journal: {e}")))?; } - self.subwallets.entry(id).or_default().arm_redrive(redrive); + self.private_payment_journals.insert(wallet_id); Ok(()) } + /// Fails with [`FileShieldedStoreError::RecoveryCorrupted`] when a + /// journal record of the wallet, or one whose wallet does not read, does + /// not read back: the pair it holds could not be restored. + fn private_payment_journal( + &self, + wallet_id: WalletId, + ) -> Result, Self::Error> { + if self + .unreadable_private_payment_journal + .contains(&Some(wallet_id)) + || self.unreadable_private_payment_journal.contains(&None) + { + return Err(FileShieldedStoreError::RecoveryCorrupted { + account_index: None, + reason: "a private payment journal record of the wallet does not read back" + .to_string(), + }); + } + Ok(self + .private_payment_journal + .range((wallet_id, [0u8; 32])..=(wallet_id, [u8::MAX; 32])) + .map(|(_, record)| record.clone()) + .collect()) + } + + fn journal_private_payments( + &mut self, + wallet_id: WalletId, + records: &[PrivatePaymentRecord], + ) -> Result<(), Self::Error> { + let rows = Self::journal_rows(records)?; + { + let mut conn = self + .pending_conn + .lock() + .map_err(|e| FileShieldedStoreError::Storage(format!("pending_conn mutex: {e}")))?; + let tx = conn + .transaction() + .map_err(|e| FileShieldedStoreError::Storage(format!("begin journal: {e}")))?; + Self::insert_journal_rows(&tx, wallet_id, &rows)?; + tx.commit() + .map_err(|e| FileShieldedStoreError::Storage(format!("commit journal: {e}")))?; + } + if !records.is_empty() { + self.private_payment_journals.insert(wallet_id); + } + for record in records { + self.private_payment_journal + .insert((wallet_id, record.commitment), record.clone()); + } + Ok(()) + } + + fn retire_undelivered_spend( + &mut self, + id: SubwalletId, + activity_id: &[u8; 32], + commitments: &[[u8; 32]], + ) -> Result { + if self + .subwallets + .get(&id) + .and_then(|subwallet| subwallet.redrive_attempts(activity_id)) + != Some(0) + { + return Ok(false); + } + // Durable first, in one transaction: a failure removes nothing, so the + // record and the journal records stay together, which over-holds. + { + let mut conn = self + .pending_conn + .lock() + .map_err(|e| FileShieldedStoreError::Storage(format!("pending_conn mutex: {e}")))?; + let tx = conn + .transaction() + .map_err(|e| FileShieldedStoreError::Storage(format!("begin retirement: {e}")))?; + // Only a record no re-broadcast was claimed for: the durable + // counter is written before memory's. + let retired = tx + .execute( + "DELETE FROM shielded_pending_spends \ + WHERE wallet_id = ?1 AND account_index = ?2 AND activity_id = ?3 \ + AND attempts = 0", + rusqlite::params![ + id.wallet_id.as_slice(), + id.account_index, + activity_id.as_slice(), + ], + ) + .map_err(|e| FileShieldedStoreError::Storage(format!("retire redrive: {e}")))?; + if retired != 1 { + // Dropped uncommitted: nothing is removed. + return Ok(false); + } + for commitment in commitments { + tx.execute( + "DELETE FROM shielded_private_payment_journal \ + WHERE wallet_id = ?1 AND commitment = ?2", + rusqlite::params![id.wallet_id.as_slice(), commitment.as_slice()], + ) + .map_err(|e| { + FileShieldedStoreError::Storage(format!("discharge retired payment: {e}")) + })?; + } + tx.commit() + .map_err(|e| FileShieldedStoreError::Storage(format!("commit retirement: {e}")))?; + } + if let Some(subwallet) = self.subwallets.get_mut(&id) { + subwallet.clear_redrive(activity_id); + } + self.private_contact_payments.remove(&(id, *activity_id)); + for commitment in commitments { + self.private_payment_journal + .remove(&(id.wallet_id, *commitment)); + } + Ok(true) + } + + fn discharge_private_payment( + &mut self, + wallet_id: WalletId, + commitment: &[u8; 32], + ) -> Result { + // Durable first: a failure leaves the record, which over-holds. + { + let conn = self + .pending_conn + .lock() + .map_err(|e| FileShieldedStoreError::Storage(format!("pending_conn mutex: {e}")))?; + conn.execute( + "DELETE FROM shielded_private_payment_journal \ + WHERE wallet_id = ?1 AND commitment = ?2", + rusqlite::params![wallet_id.as_slice(), commitment.as_slice()], + ) + .map_err(|e| FileShieldedStoreError::Storage(format!("discharge payment: {e}")))?; + } + Ok(self + .private_payment_journal + .remove(&(wallet_id, *commitment)) + .is_some()) + } + + /// Fails with [`FileShieldedStoreError::RecoveryCorrupted`] when a live + /// record of the wallet carries an association that does not read back, + /// or a damaged record of it retained without being loaded carries one: + /// the pair that payment holds could not be restored, so the restoration + /// fails and the wallet's holds stay. + fn private_contact_redrives_for_wallet( + &self, + wallet_id: WalletId, + ) -> Result, Self::Error> { + if self + .unloaded_private_contact_payments + .contains(&Some(wallet_id)) + || self.unloaded_private_contact_payments.contains(&None) + { + return Err(FileShieldedStoreError::RecoveryCorrupted { + account_index: None, + reason: "a damaged saved payment of the wallet carries a private contact request \ + association" + .to_string(), + }); + } + let mut payments = Vec::new(); + for (id, redrive) in self.pending_redrives_for_wallet(wallet_id)? { + match self + .private_contact_payments + .get(&(id, redrive.activity_id)) + { + None => {} + Some(SavedPrivateContactPayment::Readable(payment)) => { + payments.push((redrive, *payment)); + } + Some(SavedPrivateContactPayment::Unreadable) => { + return Err(FileShieldedStoreError::RecoveryCorrupted { + account_index: Some(id.account_index), + reason: "the private contact request a saved payment pays for does not \ + decode" + .to_string(), + }); + } + } + } + Ok(payments) + } + fn pending_redrives(&self, id: SubwalletId) -> Result, Self::Error> { Ok(self .subwallets @@ -720,6 +1437,7 @@ impl ShieldedStore for FileBackedShieldedStore { if let Some(sw) = self.subwallets.get_mut(&id) { sw.clear_redrive(activity_id); } + self.private_contact_payments.remove(&(id, *activity_id)); Ok(()) } @@ -899,6 +1617,10 @@ impl ShieldedStore for FileBackedShieldedStore { // in-memory only (`subwallets`); the commitment tree in // SQLite is chain-wide and intentionally left intact. self.subwallets.retain(|id, _| id.wallet_id != wallet_id); + self.private_contact_payments + .retain(|(id, _), _| id.wallet_id != wallet_id); + self.unloaded_private_contact_payments + .remove(&Some(wallet_id)); Ok(()) } @@ -931,6 +1653,7 @@ impl ShieldedStore for FileBackedShieldedStore { retained.arm_redrive(redrive); } } + self.evict_private_contact_payments(id); Ok(()) } @@ -946,10 +1669,21 @@ impl ShieldedStore for FileBackedShieldedStore { })?; } self.subwallets.clear(); + self.private_contact_payments.clear(); + self.unloaded_private_contact_payments.clear(); Ok(()) } + fn legacy_anchor_tree_bound(&self) -> Option { + self.legacy_anchor_tree_bound + } + fn reset_commitment_tree(&mut self) -> Result<(), Self::Error> { + // Its size kept first: a record saved before the reset, without an + // anchor height, took its anchor from a tree no larger than this one. + // A failure resets nothing. + let size = self.tree_size()?; + self.raise_largest_tree_size(size)?; // The `ClientPersistentCommitmentTree` wrapper owns its // `Connection` and exposes no public truncate (only the inner // `SqliteShardStore` has `truncate_shards`). A full reset @@ -1014,6 +1748,7 @@ impl ShieldedStore for FileBackedShieldedStore { #[cfg(test)] mod tests { use super::*; + use dpp::state_transition::shielded_transfer_transition::v0::ShieldedTransferTransitionV0; /// Unique temp path for a test tree (no `tempfile` dev-dep). fn temp_tree_path(tag: &str) -> std::path::PathBuf { @@ -1039,6 +1774,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; { let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); @@ -1083,6 +1819,164 @@ mod tests { let _ = std::fs::remove_file(&path); } + /// The private contact request a record pays for is saved with it: it + /// survives a reopen and an attempt bump, is listed only joined with its + /// live record, and goes with the record. A record armed without one is + /// not listed. + #[test] + fn should_keep_a_private_contact_payment_with_its_record_across_reopen() { + let path = temp_tree_path("private_contact_payment"); + let wallet_id = [0x5A; 32]; + let id = SubwalletId::new(wallet_id, 0); + let record = |activity: u8, nullifier: u8| PendingRedrive { + activity_id: [activity; 32], + anchor: [2u8; 32], + nullifiers: vec![[nullifier; 32]], + st_bytes: vec![0xAB; 96], + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }; + let payment = PrivateContactPayment { + sender: [0xB1; 32], + recipient: [0xA1; 32], + account_reference: 0x1000_0005, + }; + { + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); + store + .arm_private_contact_payment( + id, + record(1, 3), + payment, + &[PrivatePaymentEntry::for_commitment([0xC1; 32])], + 0, + None, + ) + .expect("arm the payment"); + store.arm_redrive(id, record(4, 6)).expect("arm a spend"); + store.bump_redrive_attempts(id, &[1u8; 32]).expect("bump"); + } + { + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("reopen"); + let listed = store + .private_contact_redrives_for_wallet(wallet_id) + .expect("listed"); + assert_eq!(listed.len(), 1, "only the payment: {listed:?}"); + assert_eq!(listed[0].0.activity_id, [1u8; 32]); + assert_eq!(listed[0].0.attempts, 1); + assert_eq!(listed[0].1, payment); + assert!(store + .private_contact_redrives_for_wallet([0x5B; 32]) + .expect("another wallet") + .is_empty()); + assert!(store.clear_pending(id, &[3u8; 32]).expect("clear")); + assert!(store + .private_contact_redrives_for_wallet(wallet_id) + .expect("listed") + .is_empty()); + assert!( + store.private_contact_payments.is_empty(), + "the association goes with its record" + ); + } + { + let store = FileBackedShieldedStore::open_path(&path, 100).expect("reopen 2"); + assert!(store + .private_contact_redrives_for_wallet(wallet_id) + .expect("listed") + .is_empty()); + assert_eq!(store.pending_redrives(id).expect("redrives").len(), 1); + } + let _ = std::fs::remove_file(&path); + } + + /// A private contact request association goes with its record on every + /// path that drops the record: a resolved spend, a cleared redrive, and + /// the purges. + #[test] + fn should_drop_a_private_contact_payment_with_its_record() { + let path = temp_tree_path("private_contact_payment_eviction"); + let wallet_id = [0x5C; 32]; + let id = SubwalletId::new(wallet_id, 0); + let other = SubwalletId::new([0x5D; 32], 0); + let record = |activity: u8, nullifier: u8| PendingRedrive { + activity_id: [activity; 32], + anchor: [2u8; 32], + nullifiers: vec![[nullifier; 32]], + st_bytes: vec![0xAB; 96], + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }; + let payment = PrivateContactPayment { + sender: [0xB1; 32], + recipient: [0xA1; 32], + account_reference: 5, + }; + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); + let arm = |store: &mut FileBackedShieldedStore, id, activity, nullifier| { + store + .arm_private_contact_payment( + id, + record(activity, nullifier), + payment, + &[PrivatePaymentEntry::for_commitment([activity; 32])], + 0, + None, + ) + .expect("armed"); + }; + + let note = ShieldedNote { + position: 0, + cmx: [1; 32], + nullifier: [11; 32], + block_height: 1, + is_spent: false, + value: 1, + note_data: vec![], + }; + store.save_note(id, ¬e).expect("a note"); + arm(&mut store, id, 1, 11); + store.mark_spent(id, &[11; 32]).expect("spent"); + assert!(store.private_contact_payments.is_empty(), "resolved spend"); + + arm(&mut store, id, 2, 12); + store.clear_redrive(id, &[2; 32]).expect("cleared"); + assert!(store.private_contact_payments.is_empty(), "cleared redrive"); + + arm(&mut store, id, 3, 13); + arm(&mut store, other, 4, 14); + store.purge_subwallet(id).expect("purged"); + assert_eq!( + store + .private_contact_payments + .keys() + .copied() + .collect::>(), + vec![(other, [4; 32])], + "subwallet purge" + ); + arm(&mut store, id, 5, 15); + store.purge_wallet(wallet_id).expect("purged"); + assert_eq!( + store + .private_contact_payments + .keys() + .copied() + .collect::>(), + vec![(other, [4; 32])], + "wallet purge" + ); + store.purge_all_subwallets().expect("purged"); + assert!(store.private_contact_payments.is_empty(), "every subwallet"); + drop(store); + let _ = std::fs::remove_file(&path); + } + #[test] fn identity_debit_guard_with_no_nullifiers_survives_reopen() { let path = temp_tree_path("identity_debit_guard"); @@ -1095,6 +1989,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; { let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); @@ -1192,6 +2087,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .unwrap(); @@ -1221,6 +2117,113 @@ mod tests { } } + /// A saved payment's private contact request association that does not + /// read back fails restoring its wallet's reservations, rather than losing + /// the pair it holds: a non-null value that does not decode on a record + /// that loads, which is kept, and one carried by a damaged note-spend + /// record retained without being loaded. SQL NULL stays a record with no + /// association, and the wallet restores again once the record goes. + #[test] + fn should_fail_restoring_a_wallet_whose_saved_association_does_not_read() { + let path = temp_tree_path("unreadable_private_contact_payment"); + let wallet_id = [0x6A; 32]; + let id = SubwalletId::new(wallet_id, 0); + let note_transition: StateTransition = ShieldedTransferTransitionV0 { + actions: vec![], + value_balance: 1_000, + anchor: [0x52; 32], + proof: vec![], + binding_signature: [0; 64], + } + .into(); + let record = PendingRedrive { + activity_id: [0x11; 32], + anchor: [0x52; 32], + nullifiers: vec![[0x13; 32]], + st_bytes: note_transition.serialize_to_bytes().unwrap(), + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + // As a spend saved by this build keeps it. + anchor_height: Some(5), + }; + let payment = PrivateContactPayment { + sender: [0xB1; 32], + recipient: [0xA1; 32], + account_reference: 5, + }; + let arm = || { + let mut store = FileBackedShieldedStore::open_path(&path, 100).unwrap(); + store + .arm_private_contact_payment( + id, + record.clone(), + payment, + &[PrivatePaymentEntry::for_commitment([0xC2; 32])], + 0, + None, + ) + .unwrap(); + }; + let set = |assignment: &str| { + rusqlite::Connection::open(&path) + .unwrap() + .execute( + &format!("UPDATE shielded_pending_spends SET {assignment}"), + [], + ) + .unwrap(); + }; + let unreadable = |store: &FileBackedShieldedStore| { + matches!( + store.private_contact_redrives_for_wallet(wallet_id), + Err(FileShieldedStoreError::RecoveryCorrupted { .. }) + ) + }; + + arm(); + set("private_contact_payment = x'01'"); + let mut store = FileBackedShieldedStore::open_path(&path, 100).unwrap(); + assert!(unreadable(&store), "an association that does not decode"); + assert_eq!(store.pending_redrives(id).unwrap(), vec![record.clone()]); + assert!(store + .private_contact_redrives_for_wallet([0x6B; 32]) + .unwrap() + .is_empty()); + store.clear_redrive(id, &record.activity_id).unwrap(); + assert!( + store + .private_contact_redrives_for_wallet(wallet_id) + .unwrap() + .is_empty(), + "the record went" + ); + drop(store); + + arm(); + set("anchor = x'01'"); + let store = FileBackedShieldedStore::open_path(&path, 100).unwrap(); + assert!(store.pending_redrives(id).unwrap().is_empty(), "not loaded"); + assert!(unreadable(&store), "a damaged record carrying one"); + drop(store); + + set( + "anchor = x'5252525252525252525252525252525252525252525252525252525252525252', \ + private_contact_payment = NULL", + ); + let store = FileBackedShieldedStore::open_path(&path, 100).unwrap(); + assert_eq!(store.pending_redrives(id).unwrap(), vec![record]); + assert!( + store + .private_contact_redrives_for_wallet(wallet_id) + .unwrap() + .is_empty(), + "no association" + ); + drop(store); + let _ = std::fs::remove_file(path); + } + #[test] fn should_skip_only_damaged_rows_proven_to_spend_shielded_notes() { use dpp::state_transition::shielded_transfer_transition::v0::ShieldedTransferTransitionV0; @@ -1255,6 +2258,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; { let mut store = FileBackedShieldedStore::open_path(&path, 100).unwrap(); @@ -1269,6 +2273,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .unwrap(); @@ -1334,6 +2339,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .unwrap(); @@ -1387,6 +2393,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .unwrap(); @@ -1420,6 +2427,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; { let mut store = FileBackedShieldedStore::open_path(&path, 100).unwrap(); @@ -1447,6 +2455,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; { let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); @@ -1496,6 +2505,7 @@ mod tests { attempts: 5, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; let note_spend = PendingRedrive { activity_id: [0x48; 32], @@ -1505,6 +2515,7 @@ mod tests { attempts: 1, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; { let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); @@ -1550,6 +2561,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; // purge_wallet is scoped: it drops A's rows, keeps B's. @@ -1627,6 +2639,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .expect("arm"); @@ -1932,7 +2945,7 @@ mod tests { store.checkpoint_tree(4).unwrap(); let wallet_depth0_mid_block = store.tree_anchor().unwrap(); - // The spend path uses exactly this anchor: `extract_spends_and_anchor` + // The spend path uses exactly this anchor: `extract_spends_and_recorded_anchor` // builds it as `witness(pos, 0).root(cmx)`. Pin that it equals the // mid-block `tree_anchor()`. let cmx0 = ExtractedNoteCommitment::from_bytes(&cmx(1)) @@ -1974,4 +2987,422 @@ mod tests { recorded set is exactly these two and the mid-block anchor is outside it" ); } + + /// A type 29 transition paying for one entry whose commitment is + /// `[commitment; 32]`, with placeholder actions, serialized. + fn private_document_create_bytes(commitment: u8) -> Vec { + use dpp::platform_value::BinaryData; + use dpp::shielded::SerializedAction; + use dpp::state_transition::private_document_create_from_shielded_pool_transition::methods::PrivateDocumentCreateFromShieldedPoolTransitionMethodsV0; + use dpp::state_transition::private_document_create_from_shielded_pool_transition::PrivateDocumentCreateFromShieldedPoolTransition; + use dpp::version::PlatformVersion; + + let action = SerializedAction { + nullifier: [1; 32], + rk: [2; 32], + cmx: [3; 32], + encrypted_note: vec![4; 216], + cv_net: [5; 32], + spend_auth_sig: [6; 64], + }; + let mut entry = vec![commitment; 32]; + entry.extend_from_slice(&[0; 557]); + PrivateDocumentCreateFromShieldedPoolTransition::try_from_bundle( + dpp::prelude::Identifier::from([0x44; 32]), + "privateContactRequest".to_string(), + vec![BinaryData::new(entry)], + vec![action.clone(), action], + 0, + [7; 32], + vec![8; 64], + [9; 64], + PlatformVersion::latest(), + ) + .expect("a type 29 transition") + .serialize_to_bytes() + .expect("serializes") + } + + /// The recovery tables commit at `synchronous=FULL`, so a record saved + /// before a broadcast survives a power loss; the commitment tree's + /// connection keeps `NORMAL`. + #[test] + fn should_commit_recovery_records_at_full_sync() { + let path = temp_tree_path("recovery_full_sync"); + let store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); + let synchronous = |conn: &rusqlite::Connection| { + conn.pragma_query_value(None, "synchronous", |row| row.get::<_, i64>(0)) + .expect("synchronous") + }; + let recovery = store.pending_conn.lock().expect("pending_conn mutex"); + assert_eq!(synchronous(&recovery), 2, "FULL"); + drop(recovery); + let tree = FileBackedShieldedStore::open_tuned_connection(&path).expect("tree conn"); + assert_eq!(synchronous(&tree), 1, "NORMAL"); + let _ = std::fs::remove_file(&path); + } + + /// A journal record is saved with its payment's redrive record, and + /// outlives it: no note release, purge or reopen removes it, only a + /// discharge does. The journal it was saved in reads as open. + #[test] + fn should_keep_a_journal_record_until_it_is_discharged() { + let path = temp_tree_path("journal_lifecycle"); + let wallet_id = [0x5A; 32]; + let id = SubwalletId::new(wallet_id, 1); + let payment = PrivateContactPayment { + sender: [0xB1; 32], + recipient: [0xA1; 32], + account_reference: 7, + }; + let redrive = PendingRedrive { + activity_id: [0x21; 32], + anchor: [0x22; 32], + nullifiers: vec![[0x23; 32], [0x24; 32]], + st_bytes: private_document_create_bytes(0xC3), + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }; + let expected = PrivatePaymentRecord { + account_index: 1, + activity_id: redrive.activity_id, + anchor: redrive.anchor, + anchor_height: Some(0), + commitment: [0xC3; 32], + payment, + nullifiers: redrive.nullifiers.clone(), + entry_hash: Some([0; 32]), + store_position: None, + }; + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); + assert!(!store + .private_payment_journal_open(wallet_id) + .expect("open?")); + for nullifier in &redrive.nullifiers { + store.mark_pending(id, nullifier).expect("reserved"); + } + store + .arm_private_contact_payment( + id, + redrive.clone(), + payment, + &[PrivatePaymentEntry::for_commitment([0xC3; 32])], + 0, + None, + ) + .expect("armed"); + assert!(store + .private_payment_journal_open(wallet_id) + .expect("open?")); + assert_eq!( + store.private_payment_journal(wallet_id).expect("journal"), + vec![expected.clone()] + ); + // A note release drops the redrive record, not the journal record. + assert!(store.clear_pending(id, &[0x23; 32]).expect("released")); + assert!(store.pending_redrives(id).expect("records").is_empty()); + store.purge_subwallet(id).expect("account purge"); + store.purge_wallet(wallet_id).expect("wallet purge"); + store.purge_all_subwallets().expect("purge all"); + drop(store); + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("reopened"); + assert!(store + .private_payment_journal_open(wallet_id) + .expect("open?")); + assert_eq!( + store.private_payment_journal(wallet_id).expect("journal"), + vec![expected] + ); + assert!(store + .private_payment_journal([0x5B; 32]) + .expect("another wallet's") + .is_empty()); + assert!(store + .discharge_private_payment(wallet_id, &[0xC3; 32]) + .expect("discharged")); + drop(store); + let store = FileBackedShieldedStore::open_path(&path, 100).expect("reopened"); + assert!(store + .private_payment_journal(wallet_id) + .expect("journal") + .is_empty()); + let _ = std::fs::remove_file(&path); + } + + /// The connection the durable records are written through syncs to the + /// drive itself on Apple platforms (`fullfsync`), not only to the OS, with + /// `synchronous=FULL`. + #[test] + fn should_open_the_recovery_connection_with_full_syncs() { + let path = temp_tree_path("recovery_pragmas"); + let conn = + FileBackedShieldedStore::open_recovery_connection(&path).expect("the connection"); + let fullfsync: i64 = conn + .pragma_query_value(None, "fullfsync", |row| row.get(0)) + .expect("fullfsync"); + let synchronous: i64 = conn + .pragma_query_value(None, "synchronous", |row| row.get(0)) + .expect("synchronous"); + assert_eq!(fullfsync, 1); + assert_eq!(synchronous, 2, "FULL"); + drop(conn); + let _ = std::fs::remove_file(&path); + } + + /// The bound on the trees that anchors named without their heights came + /// from is the largest tree the store has held: none for a store that + /// held no tree when it was opened, kept as it was at open while the tree + /// grows, and after a reset emptied the tree and a smaller one grew, the + /// size the reset kept first. + #[test] + fn should_bound_heightless_anchors_by_the_largest_tree_the_store_held() { + let path = temp_tree_path("largest_tree"); + let append = |store: &mut FileBackedShieldedStore, leaves: u8| { + for leaf in 0..leaves { + store + .append_commitment(&[leaf + 1; 32], true) + .expect("appended"); + } + }; + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); + assert_eq!(store.legacy_anchor_tree_bound(), None, "no tree at open"); + append(&mut store, 3); + assert_eq!(store.legacy_anchor_tree_bound(), None, "as it was at open"); + store.reset_commitment_tree().expect("reset"); + append(&mut store, 1); + drop(store); + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("reopened"); + assert_eq!(store.tree_size().expect("size"), 1); + assert_eq!( + store.legacy_anchor_tree_bound(), + Some(3), + "the tree the reset emptied" + ); + append(&mut store, 4); + drop(store); + let store = FileBackedShieldedStore::open_path(&path, 100).expect("reopened again"); + assert_eq!( + store.legacy_anchor_tree_bound(), + Some(5), + "the tree as reopened" + ); + let _ = std::fs::remove_file(&path); + } + + /// A never-delivered spend's saved record and its journal records are + /// retired by one durable write: after it, a reopened store holds + /// neither. A write that fails part way, here at the journal's delete, + /// removes neither, and one whose re-broadcast was claimed is refused and + /// keeps both; so after any reopen, the transition the redrive pass could + /// broadcast and the journal record that holds its pair stay together. + #[test] + fn should_retire_an_undelivered_spend_with_its_journal_records_in_one_write() { + let payment = PrivateContactPayment { + sender: [0xB1; 32], + recipient: [0xA1; 32], + account_reference: 7, + }; + let commitment = [0xC4; 32]; + for case in ["retired", "write fails", "re-broadcast claimed"] { + let path = temp_tree_path("retire_undelivered"); + let wallet_id = [0x5C; 32]; + let id = SubwalletId::new(wallet_id, 0); + let redrive = PendingRedrive { + activity_id: [0x31; 32], + anchor: [0x32; 32], + nullifiers: vec![[0x33; 32]], + st_bytes: private_document_create_bytes(0xC4), + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }; + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); + store.mark_pending(id, &[0x33; 32]).expect("reserved"); + store + .arm_private_contact_payment( + id, + redrive.clone(), + payment, + &[PrivatePaymentEntry::for_commitment(commitment)], + 0, + None, + ) + .expect("armed"); + match case { + "write fails" => store + .pending_conn + .lock() + .expect("pending_conn mutex") + .execute_batch( + "CREATE TRIGGER reject_journal_delete BEFORE DELETE ON \ + shielded_private_payment_journal BEGIN SELECT RAISE(FAIL, \ + 'injected delete failure'); END;", + ) + .expect("trigger"), + "re-broadcast claimed" => { + assert_eq!( + store + .bump_redrive_attempts(id, &redrive.activity_id) + .expect("claimed"), + 1 + ); + } + _ => {} + } + let retired = store.retire_undelivered_spend(id, &redrive.activity_id, &[commitment]); + match case { + "retired" => assert!(retired.expect("retired"), "{case}"), + "write fails" => assert!(retired.is_err(), "{case}: {retired:?}"), + _ => assert!(!retired.expect("refused"), "{case}"), + } + let kept = case != "retired"; + let both = |store: &FileBackedShieldedStore| { + ( + store.pending_redrives(id).expect("records").len(), + store + .private_payment_journal(wallet_id) + .expect("journal") + .len(), + ) + }; + let expected = if kept { (1, 1) } else { (0, 0) }; + assert_eq!(both(&store), expected, "{case}: in memory"); + drop(store); + let reopened = FileBackedShieldedStore::open_path(&path, 100).expect("reopened"); + assert_eq!(both(&reopened), expected, "{case}: reopened"); + drop(reopened); + let _ = std::fs::remove_file(&path); + } + } + + /// A journal record that does not read back stays, and fails reading + /// its wallet's journal, or every wallet's when its wallet does not read + /// either; the store still opens. + #[test] + fn should_fail_reading_a_journal_whose_record_does_not_read() { + for (damage, other_wallet_reads) in [ + ( + "UPDATE shielded_private_payment_journal SET record = x'01'", + true, + ), + ( + "UPDATE shielded_private_payment_journal SET commitment = x'02'", + true, + ), + ( + "UPDATE shielded_private_payment_journal SET wallet_id = x'03'", + false, + ), + ] { + let path = temp_tree_path("journal_damage"); + let wallet_id = [0x6A; 32]; + let id = SubwalletId::new(wallet_id, 0); + let payment = PrivateContactPayment { + sender: [0xB2; 32], + recipient: [0xA2; 32], + account_reference: 1, + }; + { + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); + store + .arm_private_contact_payment( + id, + PendingRedrive { + activity_id: [0x31; 32], + anchor: [0x32; 32], + nullifiers: vec![[0x33; 32]], + st_bytes: private_document_create_bytes(0xD4), + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }, + payment, + &[PrivatePaymentEntry::for_commitment([0xD4; 32])], + 0, + None, + ) + .expect("armed"); + store + .pending_conn + .lock() + .expect("pending_conn mutex") + .execute(damage, []) + .expect("damaged"); + } + let store = FileBackedShieldedStore::open_path(&path, 100).expect("still opens"); + assert!( + matches!( + store.private_payment_journal(wallet_id), + Err(FileShieldedStoreError::RecoveryCorrupted { .. }) + ), + "{damage}" + ); + assert_eq!( + store.private_payment_journal([0x6B; 32]).is_ok(), + other_wallet_reads, + "{damage}" + ); + let rows: i64 = store + .pending_conn + .lock() + .expect("pending_conn mutex") + .query_row( + "SELECT count(*) FROM shielded_private_payment_journal", + [], + |row| row.get(0), + ) + .expect("count"); + assert_eq!(rows, 1, "{damage}: the record stays"); + let _ = std::fs::remove_file(&path); + } + } + + /// A private document create (type 29) is a note spend: a recovery row + /// for one with damaged metadata is retained and skipped, its wallet + /// flagged so its legacy payments do not restore, and the shared store + /// still opens for every wallet. + #[test] + fn should_retain_and_skip_a_damaged_private_document_payment_row() { + let path = temp_tree_path("damaged_private_document_row"); + let wallet_id = [0x7A; 32]; + let id = SubwalletId::new(wallet_id, 0); + { + let mut store = FileBackedShieldedStore::open_path(&path, 100).expect("open"); + store + .arm_redrive( + id, + PendingRedrive { + activity_id: [0x41; 32], + anchor: [0x42; 32], + nullifiers: vec![[0x43; 32]], + st_bytes: private_document_create_bytes(0xE5), + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }, + ) + .expect("armed"); + store + .pending_conn + .lock() + .expect("pending_conn mutex") + .execute("UPDATE shielded_pending_spends SET anchor = x'01'", []) + .expect("damaged"); + } + let store = FileBackedShieldedStore::open_path(&path, 100).expect("still opens"); + assert!(store.pending_redrives(id).expect("records").is_empty()); + assert!(matches!( + store.private_contact_redrives_for_wallet(wallet_id), + Err(FileShieldedStoreError::RecoveryCorrupted { .. }) + )); + assert!(store + .private_contact_redrives_for_wallet([0x7B; 32]) + .is_ok()); + let _ = std::fs::remove_file(&path); + } } diff --git a/packages/rs-platform-wallet/src/wallet/shielded/mod.rs b/packages/rs-platform-wallet/src/wallet/shielded/mod.rs index e5c92c28be6..f66300eac15 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/mod.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/mod.rs @@ -70,7 +70,8 @@ pub use keys::{AccountViewingKeys, OrchardKeySet}; pub use prover::CachedOrchardProver; pub use seed_pool::{SeedPoolOutcome, SeedPoolProgress, DEFAULT_SEED_POOL_TARGET_NOTES}; pub use store::{ - IdentityDebitRecoveryRecord, IdentityDebitRecoveryStatus, InMemoryShieldedStore, ShieldedNote, + IdentityDebitRecoveryRecord, IdentityDebitRecoveryStatus, InMemoryShieldedStore, + PrivateContactPayment, PrivatePaymentEntry, PrivatePaymentRecord, ShieldedNote, ShieldedOutgoingNote, ShieldedStore, SubwalletId, }; pub use sync::{ShieldedSyncSummary, SyncNotesResult}; diff --git a/packages/rs-platform-wallet/src/wallet/shielded/note_selection.rs b/packages/rs-platform-wallet/src/wallet/shielded/note_selection.rs index d6fee1d7ba8..86f1b1fe593 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/note_selection.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/note_selection.rs @@ -8,9 +8,10 @@ use super::store::ShieldedNote; use crate::error::PlatformWalletError; use dpp::fee::Credits; use dpp::shielded::{ - compute_minimum_shielded_fee, compute_shielded_identity_create_fee, - compute_shielded_identity_top_up_fee, compute_shielded_unshield_fee, - compute_shielded_withdrawal_fee, is_allowed_identity_create_denomination, + compute_minimum_shielded_fee, compute_private_document_create_from_shielded_pool_fee, + compute_shielded_identity_create_fee, compute_shielded_identity_top_up_fee, + compute_shielded_unshield_fee, compute_shielded_withdrawal_fee, + is_allowed_identity_create_denomination, }; use dpp::version::PlatformVersion; use dpp::ProtocolError; @@ -50,6 +51,15 @@ pub enum ShieldedFeeKind { /// `compute_shielded_identity_top_up_fee`: IdentityTopUpFromShieldedPool (base plus the flat /// identity-balance write cost, the Unshield model with an identity as the output). IdentityTopUp, + /// `compute_private_document_create_from_shielded_pool_fee`: + /// PrivateDocumentCreateFromShieldedPool (base plus, per entry, its storage and the flat + /// processing fee). Nothing leaves the pool but the fee, so the amount selected for is 0. + PrivateDocumentCreate { + /// How many entries the transition appends. + entry_count: usize, + /// The bytes of each, the private type's `entrySize`. + entry_size: u32, + }, } impl ShieldedFeeKind { @@ -73,6 +83,15 @@ impl ShieldedFeeKind { ShieldedFeeKind::IdentityTopUp => { compute_shielded_identity_top_up_fee(num_actions, platform_version) } + ShieldedFeeKind::PrivateDocumentCreate { + entry_count, + entry_size, + } => compute_private_document_create_from_shielded_pool_fee( + num_actions, + entry_count, + entry_size, + platform_version, + ), } } } @@ -335,6 +354,34 @@ mod tests { assert!(total >= denomination); } + /// A private document create selects notes for its fee alone, the fee consensus pins for + /// its action count and its entries' number and size: one DashPay entry from two actions is + /// the 114,140,000-credit base plus the entry's storage and its processing fee. + #[test] + fn test_select_for_a_private_document_create_covers_its_fee_alone() { + let platform_version = PlatformVersion::latest(); + let kind = ShieldedFeeKind::PrivateDocumentCreate { + entry_count: 1, + entry_size: 589, + }; + let fee = kind.compute(2, platform_version).expect("the fee"); + assert_eq!( + fee, + compute_private_document_create_from_shielded_pool_fee(2, 1, 589, platform_version) + .expect("the consensus fee") + ); + assert_eq!(fee, 114_140_000 + (589 + 32) * 27_400 + 10_000_000); + + let notes = vec![test_note(fee, 0), test_note(fee - 1, 1)]; + let (selected, total, exact_fee) = + select_notes_with_fee(¬es, 0, 2, kind, platform_version).expect("covers the fee"); + assert_eq!((selected.len(), total, exact_fee), (1, fee, fee)); + assert!(matches!( + select_notes_with_fee(¬es[1..], 0, 2, kind, platform_version), + Err(PlatformWalletError::ShieldedInsufficientBalance { .. }) + )); + } + #[test] fn test_select_needs_multiple() { let notes = vec![test_note(100, 0), test_note(200, 1), test_note(150, 2)]; diff --git a/packages/rs-platform-wallet/src/wallet/shielded/operations.rs b/packages/rs-platform-wallet/src/wallet/shielded/operations.rs index 8a8f8a4b39b..c213918b251 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/operations.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/operations.rs @@ -28,14 +28,24 @@ use super::note_selection::{ ensure_allowed_denomination, ensure_positive_amount, select_notes_for_denomination, select_notes_with_fee, ShieldedFeeKind, }; -use super::store::{PendingRedrive, ShieldedNote, ShieldedStore, SubwalletId}; -use crate::broadcast_outcome::{broadcast_definitely_failed, carries_consensus_rejection}; +use super::store::{ + PendingRedrive, PrivateContactPayment, PrivatePaymentEntry, ShieldedNote, ShieldedStore, + SubwalletId, +}; +use crate::broadcast_outcome::{ + broadcast_tracking_delivery, broadcast_was_refused, carries_consensus_rejection, + BroadcastDelivery, +}; use crate::changeset::{PlatformWalletChangeSet, ShieldedChangeSet}; use crate::error::{preserve_signer_key_unavailable_or, PlatformWalletError}; +use crate::wallet::identity::network::PaymentStarted; use crate::wallet::persister::WalletPersister; use crate::wallet::platform_wallet::WalletId; +use sha2::{Digest, Sha256}; use std::collections::{BTreeMap, HashSet}; +use std::future::Future; +use std::sync::atomic::{AtomicU64, Ordering as AtomicOrdering}; use std::sync::Arc; use dash_sdk::dapi_grpc::platform::v0::ResponseMetadata; @@ -57,12 +67,15 @@ use dpp::identity::identity_nonce::{ use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; use dpp::identity::signer::Signer; use dpp::identity::{Identity, IdentityPublicKey}; -use dpp::prelude::{Identifier, IdentityNonce}; +use dpp::platform_value::BinaryData; +use dpp::prelude::{AddressNonce, Identifier, IdentityNonce}; use dpp::shielded::builder::{ build_identity_create_from_shielded_pool_transition, - build_identity_top_up_from_shielded_pool_transition, build_shield_from_identity_transition, - build_shield_transition, build_shielded_transfer_transition, - build_shielded_withdrawal_transition, build_unshield_transition, OrchardProver, SpendableNote, + build_identity_top_up_from_shielded_pool_transition, + build_private_document_create_from_shielded_pool_transition, + build_shield_from_identity_transition, build_shield_transition, + build_shielded_transfer_transition, build_shielded_withdrawal_transition, + build_unshield_transition, OrchardProver, SpendableNote, }; use dpp::shielded::compute_minimum_shielded_fee; use dpp::state_transition::proof_result::StateTransitionProofResult; @@ -278,6 +291,7 @@ fn shielded_actions(st: &StateTransition) -> &[dpp::shielded::SerializedAction] use dpp::state_transition::identity_top_up_from_shielded_pool_transition::accessors::IdentityTopUpFromShieldedPoolTransitionAccessorsV0; use dpp::state_transition::shield_from_identity_transition::accessors::ShieldFromIdentityTransitionAccessorsV0; use dpp::state_transition::unshield_transition::accessors::UnshieldTransitionAccessorsV0; + use dpp::state_transition::private_document_create_from_shielded_pool_transition::accessors::PrivateDocumentCreateFromShieldedPoolTransitionAccessorsV0; match st { StateTransition::Shield(ShieldTransition::V0(v0)) => &v0.actions, @@ -288,6 +302,7 @@ fn shielded_actions(st: &StateTransition) -> &[dpp::shielded::SerializedAction] StateTransition::IdentityCreateFromShieldedPool(t) => t.actions(), StateTransition::ShieldFromIdentity(t) => t.actions(), StateTransition::IdentityTopUpFromShieldedPool(t) => t.actions(), + StateTransition::PrivateDocumentCreateFromShieldedPool(t) => t.actions(), _ => &[], } } @@ -688,117 +703,240 @@ pub async fn shield_to, P: Orchar ) .await; - // Wait for proven execution (not just relay-ACK) so the host only - // sees success once Platform has actually included the transition. A - // DAPI-level ACK alone could otherwise mask a later Platform - // rejection. The proven result is discarded; we only need the - // confirmation. Staged like `broadcast_shielded_spend`: only a - // DEFINITIVE verdict (CheckTx rejection / refused admission) marks - // the activity row Failed — an ambiguous wait failure (timeout, - // result-proof fetch error) leaves it Pending, because the shield - // may still land and the scan's cmx-overlap confirmation will flip - // the row when its note appears on-chain. Shield takes no note - // reservation, so the ambiguous arm strands no local spend state; - // its inputs are transparent address claims guarded by on-chain - // nonces, and a host-level retry re-fetches those nonces. - let enrich = |e: &dash_sdk::Error| -> PlatformWalletError { - if let Some(rich) = addresses_not_enough_funds(e) { - let claimed = claimed_inputs - .iter() - .map(|(addr, (nonce, credits))| { - format!( - "{}=(nonce {nonce}, {credits} credits)", - addr.to_bech32m_string(network) - ) - }) - .collect::>() - .join(", "); - PlatformWalletError::ShieldedBroadcastFailed(format!( - "addresses not enough funds: required {} credits; \ - claimed inputs [{}]; platform sees [{}]", - rich.required_balance(), - claimed, - format_addresses_with_info(rich.addresses_with_info(), network), - )) - } else { - crate::error::promote_address_nonce_error(e) - .unwrap_or_else(|| PlatformWalletError::ShieldedBroadcastFailed(e.to_string())) - } + // What an endpoint's answer says, for the reason an unconfirmed shield + // reports. A funds shortfall names the claimed inputs beside what the + // endpoint says Platform sees. + let describe = |e: &dash_sdk::Error| -> String { + let Some(rich) = addresses_not_enough_funds(e) else { + return e.to_string(); + }; + let claimed = claimed_inputs + .iter() + .map(|(addr, (nonce, credits))| { + format!( + "{}=(nonce {nonce}, {credits} credits)", + addr.to_bech32m_string(network) + ) + }) + .collect::>() + .join(", "); + format!( + "addresses not enough funds: required {} credits; \ + claimed inputs [{}]; platform sees [{}]", + rich.required_balance(), + claimed, + format_addresses_with_info(rich.addresses_with_info(), network), + ) }; - match state_transition.broadcast(sdk, None).await { - Ok(()) => {} - Err(e) if broadcast_definitely_failed(&e) => { + // Broadcast keeping what every dispatch proved, then wait for the + // verified snapshot of the input addresses (not just a relay ACK). A + // shield's proof authenticates those addresses as of its block, not this + // exact shield's execution, so the host sees success only once the + // snapshot reads every input at or past the nonce this shield signed, and + // the activity row stays pending until the scan observes the note. + broadcast_shield( + sdk, + store, + persister, + wallet_id, + id, + &pending_entry, + &state_transition, + describe, + ) + .await?; + info!( + account, + credits = amount, + "Shield admitted with its input addresses proved spent; the activity row awaits \ + on-chain confirmation by the shielded scan" + ); + Ok(()) +} + +/// Broadcast the signed shield `state_transition`, keeping what every +/// dispatch proved ([`broadcast_tracking_delivery`]), wait for its result and +/// settle it ([`settle_shield`]). +#[allow(clippy::too_many_arguments)] +async fn broadcast_shield( + sdk: &Arc, + store: &Arc>, + persister: Option<&WalletPersister>, + wallet_id: WalletId, + id: SubwalletId, + pending_entry: &Option, + state_transition: &StateTransition, + describe: D, +) -> Result<(), PlatformWalletError> +where + S: ShieldedStore, + D: Fn(&dash_sdk::Error) -> String, +{ + let delivery = broadcast_tracking_delivery(sdk, state_transition).await; + // A transition that names no input is no shield from addresses: its + // result then shows nothing spent, and it settles as unconfirmed. + let no_inputs = BTreeMap::new(); + settle_shield( + store, + persister, + wallet_id, + id, + pending_entry, + state_transition.inputs().unwrap_or(&no_inputs), + delivery, + describe, + || state_transition.wait_for_affected_state::(sdk, None), + ) + .await +} + +/// What a signed shield's broadcast (`delivery`) and result wait (`wait`, run +/// only when a dispatch may have reached a node) came to, recording it on the +/// shield's activity row (`pending_entry`). `signed_inputs` are the shield's +/// input addresses with the nonces it signed, and `describe` renders an +/// endpoint's answer for the reason an unconfirmed shield reports. +/// +/// Only a transition that never left the wallet +/// ([`BroadcastDelivery::NeverDelivered`]: refused before anything was sent) +/// is a failed shield +/// ([`PlatformWalletError::ShieldedBroadcastFailed`]): nothing holds its bytes +/// but the wallet, so it can never execute, its row reads failed and the host +/// may retry. Once a dispatch may have reached a node, every outcome short +/// of a verified result that reads its inputs spent +/// ([`shield_inputs_read_spent`]) is +/// [`PlatformWalletError::ShieldedSpendUnconfirmed`]: a wait that fails, a +/// result that does not show the inputs spent, an endpoint's refusal of the +/// broadcast and a consensus verdict on either call included. The endpoint +/// that sends a verdict is unauthenticated, no proof or quorum signature +/// backs it, and one that kept or forwarded the signed transition can answer +/// with any verdict, while a retry signs a second shield with the inputs' +/// next nonces, and a shield's note can be a recipient's ([`shield_to`]). +/// +/// The row stays pending on every outcome but the failed one, a successful +/// one included, as a shield from an identity's does: the result proves the +/// input addresses as of its block, which does not bind this transition or +/// its note. The scan confirms the row when the note commitment appears on +/// chain. +/// +/// The shield takes no note reservation and keeps no record of its signed +/// transition. What shows that an unconfirmed one can no longer execute is +/// its inputs' nonces (one of them used by another transition), which +/// nothing reads for it: until then the row stays pending. +#[allow(clippy::too_many_arguments)] +async fn settle_shield( + store: &Arc>, + persister: Option<&WalletPersister>, + wallet_id: WalletId, + id: SubwalletId, + pending_entry: &Option, + signed_inputs: &BTreeMap, + delivery: BroadcastDelivery, + describe: D, + wait: W, +) -> Result<(), PlatformWalletError> +where + S: ShieldedStore, + D: Fn(&dash_sdk::Error) -> String, + W: FnOnce() -> Fut, + Fut: Future>, +{ + let broadcast_answer = match delivery { + BroadcastDelivery::Admitted => None, + BroadcastDelivery::NeverDelivered(e) => { record_activity_status( store, persister, wallet_id, id, - &pending_entry, + pending_entry, ShieldedActivityStatus::Failed, None, ) .await; - return Err(enrich(&e)); + return Err(definite_broadcast_failure(&e)); } - Err(e) => { + BroadcastDelivery::MaybeDelivered(e) => { warn!( - account, + account = id.account_index, error = %e, - "Shield broadcast returned no verdict; the transition may have been \ - admitted — falling through to the result wait" + "Shield broadcast may have been delivered; falling through to the result wait" ); + Some(describe(&e)) } - } + }; - // A shield proof authenticates the input addresses' post-state, not this - // exact shield's execution — accept the affected-state snapshot; a - // consensus rejection still surfaces as an error here. - if let Err(wait_err) = state_transition - .wait_for_affected_state::(sdk, None) - .await - { - if carries_consensus_rejection(&wait_err) { - // A consensus verdict in the result: the shield definitively - // did not execute. - record_activity_status( - store, - persister, - wallet_id, - id, - &pending_entry, - ShieldedActivityStatus::Failed, - None, - ) - .await; - return Err(enrich(&wait_err)); + // Whatever the wait comes to, the activity row stays Pending: the scan's + // confirmation pass flips it when the shielded note lands on-chain. + let unproved = match wait().await { + Ok(snapshot) => match shield_inputs_read_spent(signed_inputs, &snapshot) { + Ok(()) => return Ok(()), + Err(unproved) => { + warn!( + account = id.account_index, + reason = %unproved, + "Shield result does not read its inputs spent; leaving the activity row pending" + ); + unproved + } + }, + Err(wait_err) => { + warn!( + account = id.account_index, + error = %wait_err, + rejected = carries_consensus_rejection(&wait_err), + "Shield broadcast but its result is unconfirmed; leaving the activity row pending" + ); + describe(&wait_err) } - // Ambiguous: admitted but unconfirmed. Leave the activity row - // Pending — the scan's confirmation pass flips it when the - // shielded note lands on-chain. - warn!( - account, - error = %wait_err, - "Shield broadcast accepted but result confirmation failed; \ - leaving the activity row pending" - ); - return Err(PlatformWalletError::ShieldedSpendUnconfirmed { - operation: "shield", - reason: wait_err.to_string(), - }); - } + }; + Err(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "shield", + reason: match broadcast_answer { + Some(answer) => format!("{unproved}; its broadcast answered: {answer}"), + None => unproved, + }, + }) +} - record_activity_status( - store, - persister, - wallet_id, - id, - &pending_entry, - ShieldedActivityStatus::Confirmed, - None, - ) - .await; - info!(account, credits = amount, "Shield broadcast succeeded"); +/// Whether `snapshot`, the verified result a shield's wait returned, reads +/// every input address of the shield at or past the nonce the shield signed +/// it with (`signed_inputs`), or why it does not. +/// +/// The proof behind a shield's result authenticates its input addresses as +/// of the proof's block, not the shield's execution. An address's nonce +/// advances only when a transition signed with that nonce executes, so +/// inputs at or past their signed nonces show those nonces used. A result +/// that is no address snapshot shows nothing of the shield, and one that +/// leaves an input out, proves no state for it or reads it below its signed +/// nonce shows the shield had not executed at that block, whatever the +/// endpoint that returned it claims. +fn shield_inputs_read_spent( + signed_inputs: &BTreeMap, + snapshot: &StateTransitionProofResult, +) -> Result<(), String> { + let StateTransitionProofResult::VerifiedAddressInfos(proved) = snapshot else { + return Err(format!( + "a proof of its input addresses was expected, received {snapshot}" + )); + }; + if signed_inputs.is_empty() { + return Err("it names no input address".to_string()); + } + for (address, (signed, _)) in signed_inputs { + match proved.get(address) { + Some(Some((proved, _))) if proved >= signed => {} + Some(Some((proved, _))) => { + return Err(format!( + "its result proves an input address at nonce {proved}, below the nonce \ + {signed} it signed" + )); + } + Some(None) | None => { + return Err("its result proves no state for an input address".to_string()); + } + } + } Ok(()) } @@ -881,6 +1019,7 @@ async fn arm_identity_shield_redrive( attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .map_err(|e| PlatformWalletError::ShieldedStoreError(e.to_string()))?; @@ -1033,7 +1172,7 @@ pub(in crate::wallet) async fn shield_from_identity_to< match state_transition.broadcast(sdk, None).await { Ok(()) => {} - Err(e) if broadcast_definitely_failed(&e) => { + Err(e) if broadcast_was_refused(&e) => { // Unauthenticated verdict: settle it against the proven nonce. return Err(settle_identity_shield_failure( sdk, @@ -1399,7 +1538,7 @@ pub(in crate::wallet) async fn identity_top_up_from_pool_with_metadata< let change_addr = default_orchard_address(&views)?; let id = SubwalletId::new(wallet_id, account); - let (selected_notes, total_input, exact_fee) = + let (selected_notes, total_input, exact_fee, mut reservation) = reserve_unspent_notes(sdk, store, id, amount, 2, ShieldedFeeKind::IdentityTopUp).await?; info!( @@ -1414,7 +1553,8 @@ pub(in crate::wallet) async fn identity_top_up_from_pool_with_metadata< let mut pending_entry = None; let result = async { - let (spends, anchor) = extract_spends_and_anchor(sdk, store, &selected_notes).await?; + let (spends, anchor, anchor_height) = + extract_spends_and_recorded_anchor(sdk, store, &selected_notes).await?; let anchor_bytes = anchor.to_bytes(); let (state_transition, fee_used) = build_identity_top_up_from_shielded_pool_transition( @@ -1455,9 +1595,8 @@ pub(in crate::wallet) async fn identity_top_up_from_pool_with_metadata< }, ) .await; - arm_pending_release(store, id, anchor_bytes, &pending_entry, &selected_notes).await; - trace!("IdentityTopUpFromShieldedPool: state transition built, broadcasting..."); + trace!("IdentityTopUpFromShieldedPool: state transition built, saving and broadcasting..."); // Type 22 is classified affected state: its nullifiers are shared with any // competing spend of the same notes and the identity's balance is a // snapshot, so the strict wait would reject every success. The snapshot @@ -1470,7 +1609,9 @@ pub(in crate::wallet) async fn identity_top_up_from_pool_with_metadata< id, &pending_entry, anchor_bytes, + anchor_height, &selected_notes, + &mut reservation, &state_transition, "identity top up from shielded pool", SpendResultWait::AffectedState, @@ -1481,6 +1622,8 @@ pub(in crate::wallet) async fn identity_top_up_from_pool_with_metadata< match result { Ok((proof, metadata)) => { + // It executed: the outcome owns the notes, which it marks spent. + reservation.hand_over(); record_activity_status( store, persister, @@ -1535,141 +1678,684 @@ pub(in crate::wallet) async fn identity_top_up_from_pool_with_metadata< }; Ok((proven_balance, metadata)) } - Err(e @ PlatformWalletError::ShieldedSpendUnconfirmed { .. }) => Err(e), - Err(e) => { - record_activity_status( - store, - persister, - wallet_id, - id, - &pending_entry, - ShieldedActivityStatus::Failed, - None, - ) - .await; - cancel_pending(store, id, &selected_notes).await; - Err(e) - } + Err(failure) => Err(settle_failed_spend( + store, + persister, + wallet_id, + id, + &pending_entry, + reservation, + "identity top up from shielded pool", + failure, + ) + .await), } } // ------------------------------------------------------------------------- -// ShieldFromAssetLock: Core L1 asset lock -> shielded pool (Type 18) -// (orchestrated entry point lives in `wallet/shielded/fund_from_asset_lock.rs`) -// ------------------------------------------------------------------------- - -// ------------------------------------------------------------------------- -// Unshield: shielded pool -> platform address (Type 17) +// PrivateDocumentCreateFromShieldedPool: shielded pool -> entries of a +// private document type's store (Type 29) // ------------------------------------------------------------------------- -/// Unshield funds from `account`'s shielded notes to a -/// transparent platform address. +/// Append `entries` to the store of the private document type +/// `document_type_name` of `data_contract_id` (`PrivateDocumentCreateFromShieldedPool`, +/// type 29), paying the fee from `account`'s notes, the change going back to +/// the account. Nothing but the fee leaves the pool. Every entry must take the +/// type's `entrySize`, as `platform_encryption::seal_private_document_entry` +/// builds them. +/// +/// Waits for the spent nullifiers to be proven before marking the notes +/// spent, and returns the metadata of that proof. `payment_started` is +/// marked right before the transition is broadcast. #[allow(clippy::too_many_arguments)] -pub async fn unshield( +pub(in crate::wallet) async fn private_document_create_from_pool_with_metadata< + S: ShieldedStore, + P: OrchardProver, +>( sdk: &Arc, store: &Arc>, persister: Option<&WalletPersister>, wallet_id: WalletId, keys: &OrchardKeySet, account: u32, - to_address: &PlatformAddress, - amount: u64, + data_contract_id: Identifier, + document_type_name: &str, + entries: Vec, + private_contact: Option, + payment_started: &PaymentStarted, prover: &P, -) -> Result<(), PlatformWalletError> { +) -> Result { let views = keys.viewing_keys(); let change_addr = default_orchard_address(&views)?; let id = SubwalletId::new(wallet_id, account); + let fee_kind = ShieldedFeeKind::PrivateDocumentCreate { + entry_count: entries.len(), + entry_size: entries.first().map_or(0, |entry| entry.len() as u32), + }; - // Reserve against the 2-action floor: Orchard's BundleType::DEFAULT pads single-spend - // bundles to 2 actions, and the builder prices the fee at spends.len().max(2). Reserving - // for 1 would under-fee a single-note transition and the builder would reject it locally. - // Unshield is carved with `compute_shielded_unshield_fee` (the base fee PLUS the flat storage - // cost of the single `AddBalanceToAddress` write crediting the net to the output address), so - // reserve against `ShieldedFeeKind::Unshield` — reserving the base fee here would under-fund the - // address-write cost and the builder would reject the spend (and the `fee_used == exact_fee` - // debug assert below would fire). - let (selected_notes, total_input, exact_fee) = - reserve_unspent_notes(sdk, store, id, amount, 2, ShieldedFeeKind::Unshield).await?; + let (selected_notes, total_input, exact_fee, reservation) = + reserve_notes_covering(sdk, store, id, 0, 2, fee_kind).await?; info!( account, - credits = amount, fee = exact_fee, + entries = entries.len(), inputs = selected_notes.len(), total_input, - "Unshield" + data_contract = %data_contract_id, + document_type = document_type_name, + "PrivateDocumentCreateFromShieldedPool" ); - // From here on every error path must release the reservation taken - // by `reserve_unspent_notes` — except the ambiguous - // `ShieldedSpendUnconfirmed` one, which intentionally leaves it in - // place (see the outer match below). - // - // `pending_entry` is recorded once the transition is built (so we - // have its output cmxs) and flipped to Confirmed / Failed in the - // outer match. It lives outside the async block so the flip can see - // it. A build failure leaves it `None` and records nothing. - let mut pending_entry = None; - let result = async { - let (spends, anchor) = extract_spends_and_anchor(sdk, store, &selected_notes).await?; - // Capture the recorded anchor before the builder consumes it, so a - // broadcast-accepted-but-unconfirmed spend can be auto-released once - // this anchor is pruned from Platform's recorded set. - let anchor_bytes = anchor.to_bytes(); - - // The builder computes and returns the fee authoritatively; `exact_fee` (== the - // minimum) was already used above for note reservation. - let (state_transition, fee_used) = build_unshield_transition( - spends, - *to_address, - amount, - &change_addr, - &keys.full_viewing_key, - &keys.spend_auth_key, - anchor, - prover, - [0u8; 36], - sdk.version(), - ) - .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))?; - // The builder's fee and the wallet's reserved `exact_fee` both come from - // compute_shielded_unshield_fee with the same action count; lock that they agree. + // The journal records of a private contact request payment, keyed by + // these commitments, are discharged here only when the transition never + // left the wallet. + let journaled = private_contact.map(|_| { + entries + .iter() + .filter_map(|entry| { + entry + .as_slice() + .get(..32) + .and_then(|commitment| <[u8; 32]>::try_from(commitment).ok()) + }) + .collect::>() + }); + let built = async { + let (spends, anchor, anchor_height) = + extract_spends_and_recorded_anchor(sdk, store, &selected_notes).await?; + let (state_transition, fee_used) = + build_private_document_create_from_shielded_pool_transition( + spends, + data_contract_id, + document_type_name.to_string(), + entries, + &change_addr, + &keys.full_viewing_key, + &keys.spend_auth_key, + anchor, + prover, + sdk.version(), + ) + .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))?; debug_assert_eq!( fee_used, exact_fee, - "builder fee must match the reserved unshield fee" + "builder fee must match the reserved private document create fee" ); - - // Live activity: a confirmed Unshield is `direction out`, - // counterparty = the 21-byte serialized PlatformAddress, exact - // fee = the builder's metered fee. - pending_entry = record_pending_activity( + Ok::<_, PlatformWalletError>((state_transition, fee_used, anchor.to_bytes(), anchor_height)) + } + .await; + let (state_transition, fee_used, anchor_bytes, anchor_height) = match built { + Ok(built) => built, + Err(e) => { + // Nothing was saved or broadcast. + reservation.cancel().await; + return Err(e); + } + }; + // The spend's only outputs are change, so it records as an own spend + // with its fee and no counterparty. + let pending_entry = record_pending_activity( + store, + persister, + wallet_id, + id, + &views, + LiveEntryParams { + kind: ShieldedActivityKind::ShieldedSpend, + direction: ShieldedDirection::Out, + amount: 0, + fee: Some(fee_used), + counterparty: None, + memo: None, + actions: shielded_actions(&state_transition), + spent_notes: &selected_notes, + }, + ) + .await; + // Type 29 proves its spent nullifiers as a snapshot, which a competing + // spend of the same notes shares, as type 22's does: the affected-state + // wait accepts it (see `identity_top_up_from_pool_with_metadata`). + submit_private_document_payment( + PrivateDocumentSubmission { store, persister, wallet_id, id, - &views, - LiveEntryParams { - kind: ShieldedActivityKind::Unshield, - direction: ShieldedDirection::Out, - amount, - fee: Some(fee_used), - counterparty: Some(to_address.to_bytes()), - memo: None, - actions: shielded_actions(&state_transition), - spent_notes: &selected_notes, - }, - ) - .await; - arm_pending_release(store, id, anchor_bytes, &pending_entry, &selected_notes).await; + pending_entry, + selected_notes: &selected_notes, + reservation, + state_transition, + anchor: anchor_bytes, + anchor_height, + private_contact, + journaled: journaled.as_deref(), + payment_started, + }, + |state_transition| async move { + broadcast_shielded_spend_classified( + sdk, + &state_transition, + "private document create from shielded pool", + SpendResultWait::AffectedState, + ) + .await + }, + ) + .await +} - trace!("Unshield: state transition built, broadcasting..."); - broadcast_shielded_spend_with_redrive( - sdk, +/// A built private document create, and everything submitting it takes +/// ([`submit_private_document_payment`]). +struct PrivateDocumentSubmission<'a, S: ShieldedStore> { + store: &'a Arc>, + persister: Option<&'a WalletPersister>, + wallet_id: WalletId, + id: SubwalletId, + /// The spend's activity entry, recorded pending; it keys its records. + pending_entry: Option, + selected_notes: &'a [ShieldedNote], + reservation: NoteReservation, + state_transition: StateTransition, + anchor: [u8; 32], + /// The proved height of the recorded-anchor set `anchor` was chosen from. + anchor_height: u64, + private_contact: Option, + journaled: Option<&'a [[u8; 32]]>, + payment_started: &'a PaymentStarted, +} + +/// Record, save and broadcast a built private document create, then settle +/// its notes and saved record ([`settle_private_document_payment`]). +/// `broadcast` sends the transition and waits for its result: the production +/// flow passes the classified broadcast, a test intercepts it. +/// +/// Saved before the broadcast, not after an unconfirmed wait: a process that +/// exits once the node admitted the transition, before the wait returns, +/// still leaves the record a restart restores the request's reservation from, +/// and the redrive resolves. The payment is marked started once the record is +/// saved, with nothing awaited in between, and the notes are handed over only +/// then: a send dropped while the save waits for the store has saved and +/// broadcast nothing, and its guard releases the notes. A save that fails +/// stops the payment before the broadcast. +async fn submit_private_document_payment( + submission: PrivateDocumentSubmission<'_, S>, + broadcast: B, +) -> Result +where + S: ShieldedStore, + B: FnOnce(StateTransition) -> Fut, + Fut: Future>, +{ + let PrivateDocumentSubmission { + store, + persister, + wallet_id, + id, + pending_entry, + selected_notes, + mut reservation, + state_transition, + anchor, + anchor_height, + private_contact, + journaled, + payment_started, + } = submission; + // The wallet holds the pair before the payment is journaled, beyond its + // sender identity, until the journal records are discharged. + let mut pair_hold = JournaledPairHold::note(persister, private_contact, journaled); + let result = async { + let anchored = arm_pending_release( + store, + id, + anchor, + anchor_height, + &pending_entry, + selected_notes, + ) + .await?; + arm_redrive_before_broadcast( + store, + id, + pending_entry.as_ref().map(|entry| entry.id), + anchor, + selected_notes.iter().map(|note| note.nullifier).collect(), + &state_transition, + "private document create from shielded pool", + private_contact, + Some(payment_started), + anchor_height, + ) + .await?; + pair_hold.saved(); + if anchored { + // Each reservation carries its anchor: a pruned anchor releases it. + reservation.hand_over(); + } + trace!("PrivateDocumentCreateFromShieldedPool: state transition saved, broadcasting..."); + broadcast(state_transition).await + } + .await; + + drop(pair_hold); + settle_private_document_payment( + store, + persister, + wallet_id, + id, + &pending_entry, + reservation, + selected_notes, + journaled, + payment_started, + result.map(|(_proof, metadata)| metadata), + ) + .await +} + +/// The wallet's hold on a private contact request payment's pair, noted +/// before the payment's journal records are saved +/// ([`WalletPersister::note_journaled_private_payments`]), so the pairs held +/// cover every record the journal keeps. Dropped before [`Self::saved`], the +/// records were not saved and nothing was paid: the hold is forgotten. +struct JournaledPairHold<'a> { + persister: Option<&'a WalletPersister>, + commitments: &'a [[u8; 32]], + saved: bool, +} + +impl<'a> JournaledPairHold<'a> { + /// Hold `payment`'s pair for `commitments`, the entries it appends, on + /// `persister`. Holds nothing for a payment that is not for a private + /// contact request. + fn note( + persister: Option<&'a WalletPersister>, + payment: Option, + commitments: Option<&'a [[u8; 32]]>, + ) -> Self { + let (Some(persister), Some(payment), Some(commitments)) = (persister, payment, commitments) + else { + return Self { + persister: None, + commitments: &[], + saved: true, + }; + }; + let (sender, recipient) = ( + Identifier::from(payment.sender), + Identifier::from(payment.recipient), + ); + persister.note_journaled_private_payments( + commitments + .iter() + .map(|commitment| (*commitment, sender, recipient)), + ); + Self { + persister: Some(persister), + commitments, + saved: false, + } + } + + /// The journal records were saved: the hold stays until they are + /// discharged. + fn saved(&mut self) { + self.saved = true; + } +} + +impl Drop for JournaledPairHold<'_> { + fn drop(&mut self) { + if self.saved { + return; + } + if let Some(persister) = self.persister { + persister.forget_journaled_private_payments(self.commitments); + } + } +} + +/// Settle a private document payment's notes and saved record once its +/// broadcast and result wait returned `result`, as +/// [`private_document_create_from_pool_with_metadata`] does. +/// +/// A payment that executed marks its notes spent; one that may have executed +/// (unconfirmed) keeps them reserved and its saved record, which the redrive +/// pass resolves; one that did not execute releases them, and its record with +/// them. The private payment journal's records of a private contact request +/// payment (`journaled`, its entries' commitments) outlive all of that: they +/// are discharged here only when the transition never left the wallet +/// ([`SpendFailure::never_delivered`]), as nothing else can then execute it, +/// and `payment_started` tells the caller so +/// ([`PaymentStarted::note_never_delivered`]). Otherwise they stay until the +/// entry is read back. +/// +/// A transition that never left the wallet has its saved record, keyed by +/// its activity entry's id (`pending_entry`), retired with the journal +/// records in one durable write, under the store lock the redrive pass claims +/// each re-broadcast under ([`NoteReservation::retire_undelivered`]). One +/// whose record a redrive pass claimed a re-broadcast of meanwhile, or that +/// cannot be retired, may leave the wallet after all: it is settled as +/// unconfirmed, keeping its notes, record and journal records. +/// +/// A retirement is published at once, with nothing awaited in between: the +/// discharged commitments on `persister` and the never-delivered notice on +/// `payment_started`. The activity row is updated after, so a settlement +/// cancelled while it waits for the store still leaves the pair free. +#[allow(clippy::too_many_arguments)] +async fn settle_private_document_payment( + store: &Arc>, + persister: Option<&WalletPersister>, + wallet_id: WalletId, + id: SubwalletId, + pending_entry: &Option, + mut reservation: NoteReservation, + selected_notes: &[ShieldedNote], + journaled: Option<&[[u8; 32]]>, + payment_started: &PaymentStarted, + result: Result, +) -> Result { + match result { + Ok(metadata) => { + // It executed: the outcome owns the notes, which it marks spent. + reservation.hand_over(); + record_activity_status( + store, + persister, + wallet_id, + id, + pending_entry, + ShieldedActivityStatus::Confirmed, + None, + ) + .await; + if let Err(e) = finalize_pending(store, persister, wallet_id, id, selected_notes).await + { + warn!( + account = id.account_index, + error = %e, + "PrivateDocumentCreateFromShieldedPool broadcast succeeded but local \ + spent-state update failed; will heal on next sync" + ); + } + info!( + account = id.account_index, + "PrivateDocumentCreateFromShieldedPool broadcast succeeded" + ); + Ok(metadata) + } + Err(SpendFailure { + error: e @ PlatformWalletError::ShieldedSpendUnconfirmed { .. }, + .. + }) => { + // It may have executed: the reservation stays, released by sync. + reservation.hand_over(); + Err(e) + } + Err(SpendFailure { + error, + never_delivered: true, + }) => { + let commitments = journaled.unwrap_or_default(); + let retired = match pending_entry.as_ref().map(|entry| entry.id) { + Some(activity_id) => { + reservation + .retire_undelivered(&activity_id, commitments) + .await + } + None => { + reservation.hand_over(); + false + } + }; + if !retired { + // It may leave the wallet after all: everything stays, as for + // an unconfirmed payment. + return Err(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create from shielded pool", + reason: format!( + "its broadcast was refused before delivery ({error}), but its saved \ + transition was claimed for a re-broadcast or could not be retired" + ), + }); + } + // Published before anything is awaited: retired, nothing can + // execute it, and a settlement dropped from here on must still + // leave its pair free. + if journaled.is_some() { + if let Some(persister) = persister { + persister.note_discharged_private_entries(commitments.iter().copied()); + } + payment_started.note_never_delivered(); + } + record_activity_status( + store, + persister, + wallet_id, + id, + pending_entry, + ShieldedActivityStatus::Failed, + None, + ) + .await; + Err(error) + } + Err(SpendFailure { error, .. }) => { + // It did not execute: the guard owns the notes until they are + // released, so a drop on the way still releases them. + reservation.reclaim(); + record_activity_status( + store, + persister, + wallet_id, + id, + pending_entry, + ShieldedActivityStatus::Failed, + None, + ) + .await; + reservation.cancel().await; + Err(error) + } + } +} + +/// How the broadcast of [`pay_private_document_with_outcome`]'s payment ends. +#[cfg(test)] +#[derive(Clone, Copy, Debug)] +pub(crate) enum TestBroadcastOutcome { + /// Refused before anything was delivered. + RefusedBeforeDelivery, + /// Delivered, its result wait timed out. + Unconfirmed, +} + +/// A private document payment from `notes` whose broadcast ends as `outcome`, +/// saved and settled as the private flow does +/// ([`submit_private_document_payment`]): for tests outside this module that +/// drive a settlement through a contact request's pair. +#[cfg(test)] +#[allow(clippy::too_many_arguments)] +pub(crate) async fn pay_private_document_with_outcome( + store: &Arc>, + persister: Option<&WalletPersister>, + wallet_id: WalletId, + id: SubwalletId, + notes: &[ShieldedNote], + pending_entry: super::activity::ShieldedActivityEntry, + state_transition: StateTransition, + private_contact: PrivateContactPayment, + payment_started: &PaymentStarted, + outcome: TestBroadcastOutcome, +) -> Result { + // Reserved and recorded pending, as the private flow does before it + // submits. + let reservation = { + let mut locked = store.write().await; + locked + .save_activity(id, &pending_entry) + .map_err(|e| PlatformWalletError::ShieldedStoreError(e.to_string()))?; + mark_notes_pending(&mut *locked, store, id, notes)? + }; + let journaled = private_document_commitments(&state_transition).ok_or_else(|| { + PlatformWalletError::ShieldedBuildError("the payment's entries do not read".to_string()) + })?; + submit_private_document_payment( + PrivateDocumentSubmission { + store, + persister, + wallet_id, + id, + pending_entry: Some(pending_entry), + selected_notes: notes, + reservation, + state_transition, + anchor: [7; 32], + anchor_height: 0, + private_contact: Some(private_contact), + journaled: Some(&journaled), + payment_started, + }, + move |_| { + std::future::ready(Err(match outcome { + TestBroadcastOutcome::RefusedBeforeDelivery => SpendFailure { + error: PlatformWalletError::ShieldedBroadcastFailed( + "refused before delivery".to_string(), + ), + never_delivered: true, + }, + TestBroadcastOutcome::Unconfirmed => SpendFailure { + error: PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create from shielded pool", + reason: "the result wait timed out".to_string(), + }, + never_delivered: false, + }, + })) + }, + ) + .await +} + +// ------------------------------------------------------------------------- +// ShieldFromAssetLock: Core L1 asset lock -> shielded pool (Type 18) +// (orchestrated entry point lives in `wallet/shielded/fund_from_asset_lock.rs`) +// ------------------------------------------------------------------------- + +// ------------------------------------------------------------------------- +// Unshield: shielded pool -> platform address (Type 17) +// ------------------------------------------------------------------------- + +/// Unshield funds from `account`'s shielded notes to a +/// transparent platform address. +#[allow(clippy::too_many_arguments)] +pub async fn unshield( + sdk: &Arc, + store: &Arc>, + persister: Option<&WalletPersister>, + wallet_id: WalletId, + keys: &OrchardKeySet, + account: u32, + to_address: &PlatformAddress, + amount: u64, + prover: &P, +) -> Result<(), PlatformWalletError> { + let views = keys.viewing_keys(); + let change_addr = default_orchard_address(&views)?; + let id = SubwalletId::new(wallet_id, account); + + // Reserve against the 2-action floor: Orchard's BundleType::DEFAULT pads single-spend + // bundles to 2 actions, and the builder prices the fee at spends.len().max(2). Reserving + // for 1 would under-fee a single-note transition and the builder would reject it locally. + // Unshield is carved with `compute_shielded_unshield_fee` (the base fee PLUS the flat storage + // cost of the single `AddBalanceToAddress` write crediting the net to the output address), so + // reserve against `ShieldedFeeKind::Unshield` — reserving the base fee here would under-fund the + // address-write cost and the builder would reject the spend (and the `fee_used == exact_fee` + // debug assert below would fire). + let (selected_notes, total_input, exact_fee, mut reservation) = + reserve_unspent_notes(sdk, store, id, amount, 2, ShieldedFeeKind::Unshield).await?; + + info!( + account, + credits = amount, + fee = exact_fee, + inputs = selected_notes.len(), + total_input, + "Unshield" + ); + + // From here on an error before the spend's record is saved releases the + // reservation taken by `reserve_unspent_notes`; once it is saved, only a + // transition that never left the wallet does (`settle_failed_spend`). + // + // `pending_entry` is recorded once the transition is built (so we + // have its output cmxs) and flipped to Confirmed / Failed in the + // outer match. It lives outside the async block so the flip can see + // it. A build failure leaves it `None` and records nothing. + let mut pending_entry = None; + let result = async { + let (spends, anchor, anchor_height) = + extract_spends_and_recorded_anchor(sdk, store, &selected_notes).await?; + // Capture the recorded anchor before the builder consumes it, so a + // broadcast-accepted-but-unconfirmed spend can be auto-released once + // this anchor is pruned from Platform's recorded set. + let anchor_bytes = anchor.to_bytes(); + + // The builder computes and returns the fee authoritatively; `exact_fee` (== the + // minimum) was already used above for note reservation. + let (state_transition, fee_used) = build_unshield_transition( + spends, + *to_address, + amount, + &change_addr, + &keys.full_viewing_key, + &keys.spend_auth_key, + anchor, + prover, + [0u8; 36], + sdk.version(), + ) + .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))?; + // The builder's fee and the wallet's reserved `exact_fee` both come from + // compute_shielded_unshield_fee with the same action count; lock that they agree. + debug_assert_eq!( + fee_used, exact_fee, + "builder fee must match the reserved unshield fee" + ); + + // Live activity: a confirmed Unshield is `direction out`, + // counterparty = the 21-byte serialized PlatformAddress, exact + // fee = the builder's metered fee. + pending_entry = record_pending_activity( + store, + persister, + wallet_id, + id, + &views, + LiveEntryParams { + kind: ShieldedActivityKind::Unshield, + direction: ShieldedDirection::Out, + amount, + fee: Some(fee_used), + counterparty: Some(to_address.to_bytes()), + memo: None, + actions: shielded_actions(&state_transition), + spent_notes: &selected_notes, + }, + ) + .await; + + trace!("Unshield: state transition built, saving and broadcasting..."); + broadcast_shielded_spend_with_redrive( + sdk, store, id, &pending_entry, anchor_bytes, + anchor_height, &selected_notes, + &mut reservation, &state_transition, "unshield", SpendResultWait::ExecutionProved, @@ -1680,6 +2366,8 @@ pub async fn unshield( match result { Ok(_) => { + // It executed: the outcome owns the notes, which it marks spent. + reservation.hand_over(); record_activity_status( store, persister, @@ -1702,9 +2390,9 @@ pub async fn unshield( // scan runs the note is re-selected and a second spend is // built + proven, then rejected at broadcast with a // nullifier-already-used error — wasted ~30 s proof, never - // fund loss. (`pending_nullifiers` is in-memory only, so it - // does not protect across a process restart in this window; - // the on-chain set does.) + // fund loss. (A restart restores the reservation only while + // the spend's saved record is still there; the on-chain set + // protects either way.) if let Err(e) = finalize_pending(store, persister, wallet_id, id, &selected_notes).await { warn!( @@ -1717,36 +2405,25 @@ pub async fn unshield( info!(account, credits = amount, "Unshield broadcast succeeded"); Ok(()) } - // The broadcast was accepted but its execution result couldn't be - // confirmed: the spend may well have executed, so do NOT release - // the reservation. `pending_nullifiers` is in-memory only — if the - // spend landed, the next nullifier sync's `mark_spent` promotes the - // notes to spent (clearing the reservation); if it never landed, an - // app restart drops the reservation and frees the notes. Releasing - // them now would invite re-selecting notes whose nullifiers may - // already be consumed on chain. - // - // Activity entry: leave it `Pending`. Like the note reservation, - // the outcome is genuinely unknown here — a later scan that finds - // the spend will flip the row to Confirmed (its id matches), and - // until then surfacing it as Pending is honest. - Err(e @ PlatformWalletError::ShieldedSpendUnconfirmed { .. }) => Err(e), - Err(e) => { - // Definitive failure: the spend never executed. Mark the - // activity row Failed (upsert by id) before releasing notes. - record_activity_status( - store, - persister, - wallet_id, - id, - &pending_entry, - ShieldedActivityStatus::Failed, - None, - ) - .await; - cancel_pending(store, id, &selected_notes).await; - Err(e) - } + // A spend that may have reached a node keeps its reservation, its + // saved record and its `Pending` activity row: a later scan that + // finds the spend marks the notes spent and flips the row to + // Confirmed (its id matches), and the saved record restores the + // reservation after a restart. Releasing the notes would invite + // re-selecting notes whose nullifiers may already be consumed on + // chain. Only a spend that failed before its record was saved, or + // whose transition never left the wallet, releases them. + Err(failure) => Err(settle_failed_spend( + store, + persister, + wallet_id, + id, + &pending_entry, + reservation, + "unshield", + failure, + ) + .await), } } @@ -1776,7 +2453,7 @@ pub async fn transfer( // ShieldedTransfer is carved with the base `compute_minimum_shielded_fee`, so reserve // against `ShieldedFeeKind::Base`. - let (selected_notes, total_input, exact_fee) = + let (selected_notes, total_input, exact_fee, mut reservation) = reserve_unspent_notes(sdk, store, id, amount, 2, ShieldedFeeKind::Base).await?; info!( @@ -1790,7 +2467,8 @@ pub async fn transfer( let mut pending_entry = None; let result = async { - let (spends, anchor) = extract_spends_and_anchor(sdk, store, &selected_notes).await?; + let (spends, anchor, anchor_height) = + extract_spends_and_recorded_anchor(sdk, store, &selected_notes).await?; // Capture the recorded anchor before the builder consumes it, so a // broadcast-accepted-but-unconfirmed spend can be auto-released once // this anchor is pruned from Platform's recorded set. @@ -1839,16 +2517,17 @@ pub async fn transfer( }, ) .await; - arm_pending_release(store, id, anchor_bytes, &pending_entry, &selected_notes).await; - trace!("Shielded transfer: state transition built, broadcasting..."); + trace!("Shielded transfer: state transition built, saving and broadcasting..."); broadcast_shielded_spend_with_redrive( sdk, store, id, &pending_entry, anchor_bytes, + anchor_height, &selected_notes, + &mut reservation, &state_transition, "transfer", SpendResultWait::ExecutionProved, @@ -1859,6 +2538,8 @@ pub async fn transfer( match result { Ok(_) => { + // It executed: the outcome owns the notes, which it marks spent. + reservation.hand_over(); record_activity_status( store, persister, @@ -1886,24 +2567,18 @@ pub async fn transfer( ); Ok(()) } - // Ambiguous post-broadcast confirmation failure: leave the - // reservation (and the Pending activity row) in place — a later - // scan flips it to Confirmed (see `unshield`'s outer match). - Err(e @ PlatformWalletError::ShieldedSpendUnconfirmed { .. }) => Err(e), - Err(e) => { - record_activity_status( - store, - persister, - wallet_id, - id, - &pending_entry, - ShieldedActivityStatus::Failed, - None, - ) - .await; - cancel_pending(store, id, &selected_notes).await; - Err(e) - } + // See `unshield`'s outer match. + Err(failure) => Err(settle_failed_spend( + store, + persister, + wallet_id, + id, + &pending_entry, + reservation, + "transfer", + failure, + ) + .await), } } @@ -1938,7 +2613,7 @@ pub async fn withdraw( // `ShieldedFeeKind::Withdrawal` — reserving the base fee here would under-fund the document // cost and the builder would reject the spend (and the `fee_used == exact_fee` debug assert // below would fire). - let (selected_notes, total_input, exact_fee) = + let (selected_notes, total_input, exact_fee, mut reservation) = reserve_unspent_notes(sdk, store, id, amount, 2, ShieldedFeeKind::Withdrawal).await?; info!( @@ -1957,7 +2632,8 @@ pub async fn withdraw( let mut pending_entry = None; let result = async { - let (spends, anchor) = extract_spends_and_anchor(sdk, store, &selected_notes).await?; + let (spends, anchor, anchor_height) = + extract_spends_and_recorded_anchor(sdk, store, &selected_notes).await?; // Capture the recorded anchor before the builder consumes it, so a // broadcast-accepted-but-unconfirmed spend can be auto-released once // this anchor is pruned from Platform's recorded set. @@ -2008,16 +2684,17 @@ pub async fn withdraw( }, ) .await; - arm_pending_release(store, id, anchor_bytes, &pending_entry, &selected_notes).await; - trace!("Shielded withdrawal: state transition built, broadcasting..."); + trace!("Shielded withdrawal: state transition built, saving and broadcasting..."); broadcast_shielded_spend_with_redrive( sdk, store, id, &pending_entry, anchor_bytes, + anchor_height, &selected_notes, + &mut reservation, &state_transition, "withdraw", SpendResultWait::ExecutionProved, @@ -2028,6 +2705,8 @@ pub async fn withdraw( match result { Ok(_) => { + // It executed: the outcome owns the notes, which it marks spent. + reservation.hand_over(); record_activity_status( store, persister, @@ -2055,24 +2734,18 @@ pub async fn withdraw( ); Ok(()) } - // Ambiguous post-broadcast confirmation failure: leave the - // reservation (and the Pending activity row) in place — a later - // scan flips it to Confirmed (see `unshield`'s outer match). - Err(e @ PlatformWalletError::ShieldedSpendUnconfirmed { .. }) => Err(e), - Err(e) => { - record_activity_status( - store, - persister, - wallet_id, - id, - &pending_entry, - ShieldedActivityStatus::Failed, - None, - ) - .await; - cancel_pending(store, id, &selected_notes).await; - Err(e) - } + // See `unshield`'s outer match. + Err(failure) => Err(settle_failed_spend( + store, + persister, + wallet_id, + id, + &pending_entry, + reservation, + "withdraw", + failure, + ) + .await), } } @@ -2131,7 +2804,7 @@ where // — the fee is metered FROM the denomination at execution). The reservation also gates on // `denomination > predicted_fee` so the new identity can't be created with a non-positive // balance. Orchard's BundleType::DEFAULT pads single-spend bundles to a 2-action floor. - let (selected_notes, total_input, predicted_fee) = + let (selected_notes, total_input, predicted_fee, mut reservation) = reserve_unspent_notes_for_denomination(sdk, store, id, denomination, 2, num_keys).await?; info!( @@ -2154,16 +2827,19 @@ where .map(|(key, _)| (key.id(), key.clone())) .collect(); - // From here on every error path must release the reservation taken above — except the - // ambiguous `ShieldedBroadcastUnconfirmed` one, which intentionally leaves it in place - // (see the outer match below). + // From here on an error before the create's record is saved releases the reservation taken + // above; once it is saved, only a transition that never left the wallet does + // (`settle_failed_spend`). // // `pending_entry` is recorded once the bundle is built (so we know the // identity id + output cmxs) and flipped to Confirmed / Failed in the - // outer match; it lives here so the flip can see it. + // outer match; it lives here so the flip can see it. So does + // `derived_identity_id`, which an unconfirmed create reports. let mut pending_entry = None; + let mut derived_identity_id = None; let result = async { - let (spends, anchor) = extract_spends_and_anchor(sdk, store, &selected_notes).await?; + let (spends, anchor, anchor_height) = + extract_spends_and_recorded_anchor(sdk, store, &selected_notes).await?; // Capture the recorded anchor before the builder consumes it, so a // broadcast-accepted-but-unconfirmed create can be auto-released once // this anchor is pruned from Platform's recorded set. @@ -2187,6 +2863,7 @@ where .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))?; let identity_id = build.identity_id; + derived_identity_id = Some(identity_id); // Live activity: IdentityCreate carries the created identity id. // The display amount is the denomination LESS the metered fee (the @@ -2214,19 +2891,11 @@ where }, ) .await; - arm_pending_release(store, id, anchor_bytes, &pending_entry, &selected_notes).await; - - trace!("IdentityCreateFromShieldedPool: built, broadcasting via SDK..."); - // Stage the broadcast and the result-wait SEPARATELY (instead of one `broadcast_and_wait`) - // so the two failure shapes can be told apart: - // - a broadcast-time rejection (relay/CheckTx refused the tx) means it never executed, so - // releasing the note reservations is correct; - // - a post-broadcast wait failure is AMBIGUOUS — the relay accepted the tx and it may well - // have executed; treating it as "unregistered" + releasing the notes is the - // orphaned-identity + double-spend hazard this split exists to avoid. + // The transition is built once from the PoP-signed keys + bundle params (preserving the // per-key signatures); the binding signature already committed `identity_id`, the - // denomination, and the full key set. + // denomination, and the full key set. It is built before its record is saved, which + // keeps these exact bytes. let st = sdk .identity_create_from_shielded_pool_transition( build.public_keys, @@ -2236,160 +2905,28 @@ where ) .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))?; - // Broadcast (relay-ACK only). Definitive failures — a consensus-verdict CheckTx - // rejection, or a transport failure that proves nothing was delivered (see - // `broadcast_definitely_failed`; connect-refused/offline is the common case) — map to - // `ShieldedBroadcastFailed` and let the outer match release the reservation, exactly as - // before. No-verdict failures (`AlreadyExists` proves the transition IS already in the - // mempool or on chain after a lost-ACK retry; timeouts merely allow it) fall through to - // the result wait below, whose ambiguous arm already owns the fetch-by-derived-id - // fallback — so the in-flight tx gets confirmed (or held as unconfirmed) instead of - // being reported as failed. - match st.broadcast(sdk, None).await { - Ok(()) => {} - Err(e) if broadcast_definitely_failed(&e) => { - return Err(PlatformWalletError::ShieldedBroadcastFailed(e.to_string())); - } - Err(e) => { - warn!( - derived_id = %identity_id, - error = %e, - "IdentityCreateFromShieldedPool: broadcast returned no verdict; the \ - transition may have been admitted — falling through to the result wait" - ); - } - } - - // Wait for proven execution. Classify the failure: - // - `StateTransitionBroadcastError` WITH a consensus `cause` = Platform DEFINITIVELY - // reported the transition's own execution error (it ran and was rejected on its - // merits; the serialized consensus error is the verdict). The identity does not - // exist; keep today's behavior (release the reservation via - // `ShieldedBroadcastFailed`). - // - any other error (DriveProofError / Proof / InvalidProvedResponse / TimeoutReached / - // DapiClientError / …) = AMBIGUOUS: the broadcast was accepted and the transition may - // have executed even though we couldn't fetch/verify its result proof. That includes - // cause-less `StateTransitionBroadcastError`s — DAPI encodes its own wait-side failures - // (timeouts, internal errors) that way, with empty consensus data. Fall back to - // fetching the identity by its pre-derived id before deciding it doesn't exist. - // An identity-create-from-shielded-pool proof authenticates the spent - // nullifiers and resulting identity as a snapshot; it cannot bind the - // complete Orchard request, so accept the affected-state outcome. - let proof_result = match st - .wait_for_affected_state::(sdk, None) - .await - { - Ok(result) => result, - Err(dash_sdk::Error::StateTransitionBroadcastError(e)) if e.cause.is_some() => { - return Err(PlatformWalletError::ShieldedBroadcastFailed(e.to_string())); - } - Err(wait_err) => { - warn!( - derived_id = %identity_id, - error = %wait_err, - "IdentityCreateFromShieldedPool: broadcast accepted but result confirmation \ - failed; falling back to fetching the identity by its derived id" - ); - // Fetch the identity directly. The id is committed in the sighash and derived - // deterministically from the spent nullifiers, so if the transition landed the row - // is queryable. A freshly-included identity can take a moment to index on the DAPI - // node we hit, so retry a few times with a short, fixed backoff before concluding - // it's truly absent — long enough to ride out routine indexing/replica lag, short - // enough not to wedge the caller's UI for minutes. - match fetch_identity_with_retries(sdk, identity_id).await { - Some(mut identity) => { - info!( - derived_id = %identity_id, - "IdentityCreateFromShieldedPool: result confirmation failed but the \ - identity was found on chain by its derived id; treating as success" - ); - // Same defensive empty-`public_keys` fill as the proven-result path below, - // so downstream auth-key checks see the committed key set immediately. - if identity.public_keys().is_empty() { - identity.set_public_keys(submitted_public_keys.clone()); - } - return Ok::<(Identifier, Identity), PlatformWalletError>(( - identity.id(), - identity, - )); - } - None => { - // Arm the persisted re-drive before surfacing the - // ambiguity: the sync-time pass re-checks the - // nullifiers, then re-broadcasts this - // byte-identical transition up to - // MAX_REDRIVE_ATTEMPTS times. - arm_redrive_record( - store, - id, - &pending_entry, - anchor_bytes, - &selected_notes, - &st, - "identity_create", - ) - .await; - return Err(PlatformWalletError::ShieldedBroadcastUnconfirmed { - identity_id, - reason: wait_err.to_string(), - }); - } - } - } - }; - - // Pull the verified `Identity` out of the proof result. The expected variant is - // `VerifiedIdentityWithShieldedNullifiers`; if drive-abci ever returns a different one the - // broadcast still SUCCEEDED, so we don't turn it into an error — we synthesize the identity - // from the derived id + submitted keys (the binding signature committed both) and warn, so - // the local row is still created. - let identity = match proof_result { - StateTransitionProofResult::VerifiedIdentityWithShieldedNullifiers( - mut identity, - _nullifiers, - ) => { - // The proof-verified id is authoritative: it's recomputed from the proven nullifier - // set, while `identity_id` was derived pre-broadcast. They should match (the derived - // id is committed in the sighash), but trust the verified one. - if identity.id() != identity_id { - warn!( - derived_id = %identity_id, - verified_id = %identity.id(), - "IdentityCreateFromShieldedPool: derived id differs from proof-verified id; \ - using the proof-verified id" - ); - } - // Defensive: a proof result can hand back an identity whose `public_keys` map is - // empty. Fill it from the submitted set so downstream auth-key checks see the keys - // immediately without waiting for the next identity-fetch round (the transition - // committed exactly these keys, so id reproducibility is preserved). - if identity.public_keys().is_empty() { - identity.set_public_keys(submitted_public_keys); - } - identity - } - other => { - warn!( - derived_id = %identity_id, - result = %other, - "IdentityCreateFromShieldedPool: unexpected proof-result variant; synthesizing \ - the identity from the derived id + submitted keys so the local row still lands" - ); - Identity::new_with_id_and_keys( - identity_id, - submitted_public_keys, - sdk.version(), - ) - .map_err(|e| PlatformWalletError::ShieldedBuildError(e.to_string()))? - } - }; - - Ok::<(Identifier, Identity), PlatformWalletError>((identity.id(), identity)) + trace!("IdentityCreateFromShieldedPool: built, saving and broadcasting via SDK..."); + broadcast_identity_create_with_redrive( + sdk, + store, + id, + &pending_entry, + anchor_bytes, + anchor_height, + &selected_notes, + &mut reservation, + &st, + identity_id, + submitted_public_keys, + ) + .await } .await; match result { Ok((identity_id, identity)) => { + // It executed: the outcome owns the notes, which it marks spent. + reservation.hand_over(); record_activity_status( store, persister, @@ -2421,52 +2958,225 @@ where ); Ok((identity_id, identity)) } - // The broadcast was accepted but its result couldn't be confirmed and the identity wasn't - // found by a direct fetch. Do NOT `cancel_pending` here: `pending_nullifiers` is in-memory - // only (see `SubwalletState`, "never persisted; the next sync after a crash reconciles"), - // and `mark_spent` during nullifier sync clears matching reservations. So if the transition - // actually executed, the next sync promotes these notes to spent; if it truly never landed, - // an app restart drops the in-memory reservation and frees them. Releasing them now would - // invite double-spend attempts against notes that may already be consumed on chain — the - // very hazard this variant exists to prevent. The activity row likewise stays `Pending` - // (a later scan that finds the identity's change note flips it to Confirmed). - Err(e @ PlatformWalletError::ShieldedBroadcastUnconfirmed { .. }) => Err(e), - Err(e) => { - if error_releases_note_reservation(&e) { - // Definitive failure: the identity was never created. Mark - // the activity row Failed (upsert by id) before releasing. - record_activity_status( - store, - persister, - wallet_id, - id, - &pending_entry, - ShieldedActivityStatus::Failed, - None, - ) - .await; - cancel_pending(store, id, &selected_notes).await; + // A create that may have reached a node keeps its reservation, its saved record and its + // `Pending` activity row (see `unshield`'s outer match), and reports the derived id: the + // identity may already exist on chain, so the caller holds its registration slot. + Err(failure) => { + let error = settle_failed_spend( + store, + persister, + wallet_id, + id, + &pending_entry, + reservation, + IDENTITY_CREATE_OPERATION, + failure, + ) + .await; + Err(identity_create_failure(error, derived_identity_id)) + } + } +} + +/// The error an identity create reports for `error`, what [`settle_failed_spend`] settled its +/// failure as. A create settled as unconfirmed carries the derived `identity_id` +/// ([`PlatformWalletError::ShieldedBroadcastUnconfirmed`]): the identity may already exist on +/// chain, so the caller must hold its registration slot rather than read a failed create. +fn identity_create_failure( + error: PlatformWalletError, + identity_id: Option, +) -> PlatformWalletError { + match (error, identity_id) { + (PlatformWalletError::ShieldedSpendUnconfirmed { reason, .. }, Some(identity_id)) => { + PlatformWalletError::ShieldedBroadcastUnconfirmed { + identity_id, + reason, } - Err(e) } + (error, _) => error, } } -/// Whether a failed identity-create should release the notes reserved for it. +/// Save the built identity create `st`'s recovery record durably, then +/// broadcast it and wait for its result ([`save_spend_then_broadcast`], +/// [`broadcast_identity_create`]): the identity create's counterpart of +/// [`broadcast_shielded_spend_with_redrive_with_metadata`]. +#[allow(clippy::too_many_arguments)] +async fn broadcast_identity_create_with_redrive( + sdk: &Arc, + store: &Arc>, + id: SubwalletId, + pending_entry: &Option, + anchor: [u8; 32], + anchor_height: u64, + notes: &[ShieldedNote], + reservation: &mut NoteReservation, + st: &StateTransition, + identity_id: Identifier, + submitted_public_keys: BTreeMap, +) -> Result<(Identifier, Identity), SpendFailure> { + save_spend_then_broadcast( + store, + id, + pending_entry, + anchor, + anchor_height, + notes, + reservation, + st, + IDENTITY_CREATE_OPERATION, + || broadcast_identity_create(sdk, st, identity_id, submitted_public_keys), + ) + .await +} + +/// What an identity create is named in the errors its record's save and its +/// settlement report. +const IDENTITY_CREATE_OPERATION: &str = "identity create from shielded pool"; + +/// Broadcast the built identity create `st`, whose record is already saved +/// ([`save_spend_then_broadcast`]), and wait for its result. /// -/// `false` ONLY for [`PlatformWalletError::ShieldedBroadcastUnconfirmed`]: the broadcast was -/// accepted and the transition may have executed, so the reservation must be retained. Releasing it -/// now would invite double-spend attempts against notes that may already be consumed on chain — the -/// very hazard that variant exists to prevent. `pending_nullifiers` is in-memory only (see -/// `SubwalletState`, "never persisted; the next sync after a crash reconciles") and `mark_spent` -/// during nullifier sync clears matching reservations, so if the transition actually executed the -/// next sync promotes these notes to spent; if it truly never landed, an app restart drops the -/// in-memory reservation and frees them. +/// The broadcast and the result wait are staged separately so the two failure shapes can be +/// told apart: +/// - a transition that never left the wallet ([`BroadcastDelivery::NeverDelivered`]: refused +/// before anything was sent) can never execute, so its record is retired and its notes are +/// released ([`SpendFailure::never_delivered`]); +/// - every other failure may have delivered it. It falls through to the result wait, and a +/// wait that fails falls back to fetching the identity by its pre-derived id before the +/// create is reported unconfirmed ([`PlatformWalletError::ShieldedBroadcastUnconfirmed`]), +/// its notes and record kept. That includes a `StateTransitionBroadcastError` with a +/// consensus `cause`: the endpoint that reports it is unauthenticated, no proof or quorum +/// signature backs it, and one that kept or forwarded the transition can answer with any +/// verdict. It also includes cause-less ones, as DAPI encodes its own wait-side failures +/// (timeouts, internal errors) that way. /// -/// Everything else is a definitive pre-execution / build / rejection failure: the spend never -/// happened, so the reservation must be released. -fn error_releases_note_reservation(e: &PlatformWalletError) -> bool { - !matches!(e, PlatformWalletError::ShieldedBroadcastUnconfirmed { .. }) +/// Nothing here reports a failed create once a dispatch may have reached a node: a create +/// reported failed while it may still execute is the orphaned-identity hazard this staging +/// exists to avoid. +async fn broadcast_identity_create( + sdk: &Arc, + st: &StateTransition, + identity_id: Identifier, + submitted_public_keys: BTreeMap, +) -> Result<(Identifier, Identity), SpendFailure> { + let unconfirmed = |reason: String| { + SpendFailure::from(PlatformWalletError::ShieldedBroadcastUnconfirmed { + identity_id, + reason, + }) + }; + + match broadcast_tracking_delivery(sdk, st).await { + BroadcastDelivery::Admitted => {} + BroadcastDelivery::NeverDelivered(e) => { + return Err(SpendFailure { + error: definite_broadcast_failure(&e), + never_delivered: true, + }); + } + BroadcastDelivery::MaybeDelivered(e) => { + warn!( + derived_id = %identity_id, + error = %e, + "IdentityCreateFromShieldedPool: broadcast may have been delivered; falling \ + through to the result wait" + ); + } + } + + // An identity-create-from-shielded-pool proof authenticates the spent + // nullifiers and resulting identity as a snapshot; it cannot bind the + // complete Orchard request, so accept the affected-state outcome. + let proof_result = match st + .wait_for_affected_state::(sdk, None) + .await + { + Ok(result) => result, + Err(wait_err) => { + warn!( + derived_id = %identity_id, + error = %wait_err, + "IdentityCreateFromShieldedPool: broadcast accepted but result confirmation \ + failed; falling back to fetching the identity by its derived id" + ); + // Fetch the identity directly. The id is committed in the sighash and derived + // deterministically from the spent nullifiers, so if the transition landed the row + // is queryable. A freshly-included identity can take a moment to index on the DAPI + // node we hit, so retry a few times with a short, fixed backoff before concluding + // it's truly absent: long enough to ride out routine indexing/replica lag, short + // enough not to wedge the caller's UI for minutes. + return match fetch_identity_with_retries(sdk, identity_id).await { + Some(mut identity) => { + info!( + derived_id = %identity_id, + "IdentityCreateFromShieldedPool: result confirmation failed but the \ + identity was found on chain by its derived id; treating as success" + ); + // Same defensive empty-`public_keys` fill as the proven-result path below, + // so downstream auth-key checks see the committed key set immediately. + if identity.public_keys().is_empty() { + identity.set_public_keys(submitted_public_keys); + } + Ok((identity.id(), identity)) + } + // The saved record resolves it: the sync-time pass re-checks the nullifiers, + // then re-broadcasts this byte-identical transition up to + // MAX_REDRIVE_ATTEMPTS times. + None => Err(unconfirmed(wait_err.to_string())), + }; + } + }; + + // Pull the verified `Identity` out of the proof result. The expected variant is + // `VerifiedIdentityWithShieldedNullifiers`; if drive-abci ever returns a different one the + // broadcast still SUCCEEDED, so we don't turn it into a failed create: we synthesize the + // identity from the derived id + submitted keys (the binding signature committed both) and + // warn, so the local row is still created. + let identity = match proof_result { + StateTransitionProofResult::VerifiedIdentityWithShieldedNullifiers( + mut identity, + _nullifiers, + ) => { + // The proof-verified id is authoritative: it's recomputed from the proven nullifier + // set, while `identity_id` was derived pre-broadcast. They should match (the derived + // id is committed in the sighash), but trust the verified one. + if identity.id() != identity_id { + warn!( + derived_id = %identity_id, + verified_id = %identity.id(), + "IdentityCreateFromShieldedPool: derived id differs from proof-verified id; \ + using the proof-verified id" + ); + } + // Defensive: a proof result can hand back an identity whose `public_keys` map is + // empty. Fill it from the submitted set so downstream auth-key checks see the keys + // immediately without waiting for the next identity-fetch round (the transition + // committed exactly these keys, so id reproducibility is preserved). + if identity.public_keys().is_empty() { + identity.set_public_keys(submitted_public_keys); + } + identity + } + other => { + warn!( + derived_id = %identity_id, + result = %other, + "IdentityCreateFromShieldedPool: unexpected proof-result variant; synthesizing \ + the identity from the derived id + submitted keys so the local row still lands" + ); + // The create executed. An identity that cannot be synthesized leaves it + // unconfirmed, its notes and record kept for the next sync, never failed. + Identity::new_with_id_and_keys(identity_id, submitted_public_keys, sdk.version()) + .map_err(|e| { + unconfirmed(format!( + "its result was proved, but the identity could not be read from it: {e}" + )) + })? + } + }; + + Ok((identity.id(), identity)) } /// Number of times [`identity_create_from_shielded_pool`] re-fetches the new identity by its @@ -2558,11 +3268,15 @@ const MAX_ANCHOR_PROBE_DEPTH: usize = 100; /// recorded root it returns the retryable /// [`PlatformWalletError::ShieldedNoRecordedAnchor`] rather than broadcasting a /// spend Platform is guaranteed to reject. -async fn extract_spends_and_anchor( +/// +/// Returns the proved height of the recorded anchor set the anchor was chosen +/// from too: the anchor was in the set at that height, so a set proved at or +/// above it that lacks the anchor shows it pruned rather than newer. +async fn extract_spends_and_recorded_anchor( sdk: &Arc, store: &Arc>, notes: &[ShieldedNote], -) -> Result<(Vec, Anchor), PlatformWalletError> { +) -> Result<(Vec, Anchor, u64), PlatformWalletError> { // Nothing selected — fail before the network round-trip. if notes.is_empty() { return Err(PlatformWalletError::ShieldedBuildError( @@ -2573,8 +3287,8 @@ async fn extract_spends_and_anchor( // Fetch the recorded anchor set OUTSIDE the store lock so the network // round-trip doesn't serialize with other store users, and so the lock is // held only for the mutually-consistent depth/witness probe below. - let dash_sdk::query_types::ShieldedAnchors(recorded_anchors) = - dash_sdk::query_types::ShieldedAnchors::fetch_current(sdk).await?; + let (dash_sdk::query_types::ShieldedAnchors(recorded_anchors), metadata) = + dash_sdk::query_types::ShieldedAnchors::fetch_current_with_metadata(sdk).await?; let recorded: HashSet<[u8; 32]> = recorded_anchors.into_iter().collect(); // Hold a single read lock across the whole probe so the checkpoint depths @@ -2583,6 +3297,7 @@ async fn extract_spends_and_anchor( // under us. let store = store.read().await; select_recorded_spends(&*store, notes, &recorded) + .map(|(spends, anchor)| (spends, anchor, metadata.height)) } /// Pick the shallowest checkpoint depth whose tree root is in `recorded`, @@ -2781,11 +3496,13 @@ async fn mark_notes_spent( /// and proceed to build a duplicate proof that's only rejected /// ~30 s later at broadcast time. /// -/// The reservation is in-memory only — see -/// [`ShieldedStore::mark_pending`] for the crash-recovery note. -/// Callers must pair this with [`finalize_pending`] (on -/// broadcast success) or [`cancel_pending`] (on failure) so the -/// reservation is always released. +/// The reservation is held in memory until the spend saves its record +/// ([`save_spend_then_broadcast`]), which restores it after a restart: see +/// [`ShieldedStore::mark_pending`]. Callers must pair this with +/// [`finalize_pending`] (on proven execution) or [`settle_failed_spend`] +/// (on failure); until the notes are handed over +/// ([`NoteReservation::hand_over`]), the returned guard releases them when +/// the spend is dropped. async fn reserve_unspent_notes( sdk: &Arc, store: &Arc>, @@ -2793,22 +3510,191 @@ async fn reserve_unspent_notes( amount: u64, outputs: usize, fee_kind: ShieldedFeeKind, -) -> Result<(Vec, u64, u64), PlatformWalletError> { +) -> Result<(Vec, u64, u64, NoteReservation), PlatformWalletError> { // All amount-based spends reject zero before waiting on a concurrent sync's store lock. ensure_positive_amount(amount)?; + reserve_notes_covering(sdk, store, id, amount, outputs, fee_kind).await +} - let mut store = store.write().await; - let unspent = store +/// Select and reserve, in one write-locked critical section, notes covering +/// `amount` plus the fee of `fee_kind`, which [`reserve_unspent_notes`] does +/// for a positive amount. A spend paying only its fee (an +/// `PrivateDocumentCreateFromShieldedPool`) reserves with an `amount` of 0. +/// Callers must pair this with [`finalize_pending`] / [`NoteReservation::cancel`], and +/// hand the guard over once they own the reservation. +async fn reserve_notes_covering( + sdk: &Arc, + store: &Arc>, + id: SubwalletId, + amount: u64, + outputs: usize, + fee_kind: ShieldedFeeKind, +) -> Result<(Vec, u64, u64, NoteReservation), PlatformWalletError> { + let mut guard = store.write().await; + let unspent = guard .get_unspent_notes(id) .map_err(|e| PlatformWalletError::ShieldedStoreError(e.to_string()))?; let (selected, total_input, exact_fee) = select_notes_with_fee(&unspent, amount, outputs, fee_kind, sdk.version())?.into_owned(); - for note in &selected { - store - .mark_pending(id, ¬e.nullifier) - .map_err(|e| PlatformWalletError::ShieldedStoreError(e.to_string()))?; + let reservation = mark_notes_pending(&mut *guard, store, id, &selected)?; + Ok((selected, total_input, exact_fee, reservation)) +} + +/// Mark `notes` pending under the held store lock, returning the guard that +/// releases them unless handed over. A failure part way releases those +/// already marked. +fn mark_notes_pending( + locked: &mut S, + store: &Arc>, + id: SubwalletId, + notes: &[ShieldedNote], +) -> Result, PlatformWalletError> { + let reservation = next_note_reservation(); + let mut marked = Vec::with_capacity(notes.len()); + for note in notes { + if let Err(e) = locked.mark_pending_by(id, ¬e.nullifier, reservation) { + release_reserved_notes(locked, id, &marked, reservation); + return Err(PlatformWalletError::ShieldedStoreError(e.to_string())); + } + marked.push(note.nullifier); + } + Ok(NoteReservation { + store: Arc::clone(store), + id, + nullifiers: marked, + reservation, + handed_over: false, + }) +} + +/// A spend attempt's reservation id, unique in the process: what its note +/// reservations are owned by ([`ShieldedStore::mark_pending_by`]). +fn next_note_reservation() -> u64 { + static NEXT: AtomicU64 = AtomicU64::new(1); + NEXT.fetch_add(1, AtomicOrdering::Relaxed) +} + +/// Notes one spend reserved ([`ShieldedStore::mark_pending`]), released when +/// dropped before the spend hands them over ([`Self::hand_over`]): a spend +/// future dropped before its notes have an owner that frees them (an anchor +/// on each reservation, which a pruned anchor releases, or the outcome +/// handling that finalizes or cancels them) leaves them spendable again, as +/// [`NoteReservation::cancel`] would, rather than excluded for the rest of the +/// session. The release takes the store lock when it is free, and otherwise +/// runs on a spawned task once it frees; outside a runtime the notes stay +/// reserved until restart. +pub(super) struct NoteReservation { + store: Arc>, + id: SubwalletId, + nullifiers: Vec<[u8; 32]>, + /// The attempt that owns the reservations: a release clears a note + /// only while it still holds it, so a cleanup that runs after a purge, + /// a rebind or a wallet's replacement never releases a newer attempt's + /// notes or deletes its records. + reservation: u64, + handed_over: bool, +} + +impl NoteReservation { + /// The spend owns the reservation from now on. + pub(super) fn hand_over(&mut self) { + self.handed_over = true; + } + + /// Own the reservation again, for a spend now known not to have executed: dropped from + /// here on, the guard releases the notes, whatever owned them before. + pub(super) fn reclaim(&mut self) { + self.handed_over = false; + } + + /// For a spend whose transition never left the wallet: retire its saved + /// record `activity_id` with the journal records of `commitments` in one + /// durable write ([`ShieldedStore::retire_undelivered_spend`]), and + /// release the notes under the same store guard. Returns whether it was + /// retired. + /// + /// When it was not (a redrive pass claimed a re-broadcast of the record, + /// the record is gone, or the write failed), nothing changed and the + /// notes stay reserved, handed over to the spend's resolution. So do they + /// when the call is dropped while it waits for the store: the record may + /// still be saved, and a note released under a saved transition could be + /// spent twice. + pub(super) async fn retire_undelivered( + mut self, + activity_id: &[u8; 32], + commitments: &[[u8; 32]], + ) -> bool { + self.handed_over = true; + let mut store = self.store.write().await; + match store.retire_undelivered_spend(self.id, activity_id, commitments) { + Ok(true) => { + release_reserved_notes(&mut *store, self.id, &self.nullifiers, self.reservation); + self.nullifiers.clear(); + true + } + Ok(false) => false, + Err(e) => { + warn!( + error = %e, + "a never-delivered spend's record was not retired; it is kept with its notes" + ); + false + } + } + } + + /// Release the notes now, for a spend that did not execute. + /// The guard owns them until the release is done: a spend dropped while it waits for the + /// store lock still releases them on drop. + pub(super) async fn cancel(mut self) { + self.handed_over = false; + let mut store = self.store.write().await; + release_reserved_notes(&mut *store, self.id, &self.nullifiers, self.reservation); + self.nullifiers.clear(); + } +} + +impl Drop for NoteReservation { + fn drop(&mut self) { + if self.handed_over || self.nullifiers.is_empty() { + return; + } + let (id, reservation) = (self.id, self.reservation); + let nullifiers = std::mem::take(&mut self.nullifiers); + if let Ok(mut store) = self.store.try_write() { + release_reserved_notes(&mut *store, id, &nullifiers, reservation); + return; + } + let Ok(runtime) = tokio::runtime::Handle::try_current() else { + warn!( + "a dropped spend's notes were reserved outside a runtime; they stay until restart" + ); + return; + }; + let store = Arc::clone(&self.store); + runtime.spawn(async move { + let mut store = store.write().await; + release_reserved_notes(&mut *store, id, &nullifiers, reservation); + }); + } +} + +/// Clear the reservations of `nullifiers` the spend attempt `reservation` +/// still holds ([`ShieldedStore::clear_pending_reserved_by`]). +fn release_reserved_notes( + store: &mut S, + id: SubwalletId, + nullifiers: &[[u8; 32]], + reservation: u64, +) { + for nullifier in nullifiers { + if let Err(e) = store.clear_pending_reserved_by(id, nullifier, reservation) { + warn!( + error = %e, + "releasing a dropped spend's note failed; the next note scan will reconcile" + ); + } } - Ok((selected, total_input, exact_fee)) } /// Exact-equality sibling of [`reserve_unspent_notes`] for @@ -2816,7 +3702,8 @@ async fn reserve_unspent_notes( /// (the fee is metered FROM the denomination, not added to the target) in one write-locked /// critical section, gating on `denomination > predicted_fee` via /// [`select_notes_for_denomination`]. Returns the selected notes, total input value, and the -/// predicted fee. Callers must pair this with [`finalize_pending`] / [`cancel_pending`]. +/// predicted fee. Callers must pair this with [`finalize_pending`] / [`NoteReservation::cancel`], and +/// hand the guard over once they own the reservation. async fn reserve_unspent_notes_for_denomination( sdk: &Arc, store: &Arc>, @@ -2824,12 +3711,12 @@ async fn reserve_unspent_notes_for_denomination( denomination: u64, min_actions: usize, num_keys: usize, -) -> Result<(Vec, u64, u64), PlatformWalletError> { +) -> Result<(Vec, u64, u64, NoteReservation), PlatformWalletError> { // Reject zero or any other non-member before waiting on a concurrent sync's store lock. ensure_allowed_denomination(denomination, sdk.version())?; - let mut store = store.write().await; - let unspent = store + let mut guard = store.write().await; + let unspent = guard .get_unspent_notes(id) .map_err(|e| PlatformWalletError::ShieldedStoreError(e.to_string()))?; let (selected, total_input, predicted_fee) = select_notes_for_denomination( @@ -2840,12 +3727,8 @@ async fn reserve_unspent_notes_for_denomination( sdk.version(), )? .into_owned(); - for note in &selected { - store - .mark_pending(id, ¬e.nullifier) - .map_err(|e| PlatformWalletError::ShieldedStoreError(e.to_string()))?; - } - Ok((selected, total_input, predicted_fee)) + let reservation = mark_notes_pending(&mut *guard, store, id, &selected)?; + Ok((selected, total_input, predicted_fee, reservation)) } /// Promote a successful broadcast: mark the notes spent (which @@ -2862,25 +3745,6 @@ async fn finalize_pending( mark_notes_spent(store, persister, wallet_id, id, notes).await } -/// Roll back a reservation when the broadcast / wait fails. -/// Best-effort and doesn't surface its own errors — the caller -/// is already returning the broadcast error. -async fn cancel_pending( - store: &Arc>, - id: SubwalletId, - notes: &[ShieldedNote], -) { - let mut store = store.write().await; - for note in notes { - if let Err(e) = store.clear_pending(id, ¬e.nullifier) { - tracing::warn!( - error = %e, - "cancel_pending: clear_pending failed; the next note scan will reconcile" - ); - } - } -} - /// Record the recorded `anchor` the spend was built against and the /// linked activity entry on every selected note's reservation, so a /// spend that ends broadcast-accepted-but-unconfirmed can be released @@ -2889,47 +3753,50 @@ async fn cancel_pending( /// /// No-op when no activity entry was recorded (an output-less bundle — /// unreachable for our own builders, which always carry a visible -/// output). Best-effort: a store write failure only means the -/// reservation won't self-release on a pruned anchor (it still frees -/// on the next restart), so it must never abort a spend about to -/// broadcast. A success (`finalize_pending`) or a definite failure -/// (`cancel_pending`) removes the entry, so only an ambiguous +/// output). A success (`finalize_pending`) or a definite failure +/// (`NoteReservation::cancel`) removes the entry, so only an ambiguous /// unconfirmed outcome leaves it carrying the anchor. +/// +/// Returns whether every reservation now carries the anchor, with +/// `anchor_height`, the proved height of the anchor set it was read from, so +/// an anchor proven pruned releases each. A store write that fails stops the spend before it +/// is broadcast ([`PlatformWalletError::ShieldedStoreError`]): the caller's +/// reservation guard still owns the notes, so they are released, rather +/// than a spend that may execute leaving reservations no pruned anchor +/// frees. async fn arm_pending_release( store: &Arc>, id: SubwalletId, anchor: [u8; 32], + anchor_height: u64, pending_entry: &Option, notes: &[ShieldedNote], -) { +) -> Result { let Some(entry) = pending_entry else { - return; + return Ok(false); }; let mut store = store.write().await; for note in notes { - if let Err(e) = store.set_pending_spend(id, ¬e.nullifier, anchor, entry.id) { - warn!( - error = %e, - "set_pending_spend failed; this reservation won't self-release on a pruned \ - anchor (it still frees on the next restart)" - ); - } + store + .set_pending_spend(id, ¬e.nullifier, anchor, entry.id, Some(anchor_height)) + .map_err(|e| { + PlatformWalletError::ShieldedStoreError(format!( + "the spend's note reservation could not carry its anchor, so it is not \ + broadcast: {e}" + )) + })?; } + Ok(true) } -/// Maximum sync-time re-broadcast attempts for a -/// broadcast-accepted-but-unconfirmed spend before the re-drive stops -/// and the anchor-prune release backstop owns the reservation. +/// Maximum sync-time re-broadcast attempts for a spend whose outcome is +/// not known before the re-drive stops and the anchor-prune release +/// backstop owns the reservation. pub(super) const MAX_REDRIVE_ATTEMPTS: u32 = 3; -/// Broadcast a built shielded spend and, on the AMBIGUOUS outcome only -/// (`ShieldedSpendUnconfirmed` — accepted broadcast, failed result -/// wait), persist a [`PendingRedrive`] so the sync-time re-drive can -/// resolve the ambiguity actively: the next scan detects a landing via -/// the nullifiers; otherwise the byte-identical transition is -/// re-broadcast up to [`MAX_REDRIVE_ATTEMPTS`] times (fund-safe — -/// identical nullifiers cannot double-spend); only if every attempt -/// stays silent does the anchor-prune release backstop take over. +/// Save a built shielded spend's recovery record, broadcast it and wait for +/// its result ([`broadcast_shielded_spend_with_redrive_with_metadata`]), +/// returning the proven result without its metadata. #[allow(clippy::too_many_arguments)] async fn broadcast_shielded_spend_with_redrive( sdk: &Arc, @@ -2937,18 +3804,22 @@ async fn broadcast_shielded_spend_with_redrive( id: SubwalletId, pending_entry: &Option, anchor: [u8; 32], + anchor_height: u64, notes: &[ShieldedNote], + reservation: &mut NoteReservation, state_transition: &StateTransition, operation: &'static str, wait: SpendResultWait, -) -> Result { +) -> Result { broadcast_shielded_spend_with_redrive_with_metadata( sdk, store, id, pending_entry, anchor, + anchor_height, notes, + reservation, state_transition, operation, wait, @@ -2957,6 +3828,17 @@ async fn broadcast_shielded_spend_with_redrive( .map(|(result, _)| result) } +/// Save a built shielded spend's recovery record ([`PendingRedrive`]) +/// durably, then broadcast it and wait for its result +/// ([`save_spend_then_broadcast`], [`broadcast_shielded_spend_classified`]). +/// +/// The record is what resolves a spend whose outcome is not known: the next +/// scan detects a landing via the nullifiers; otherwise the byte-identical +/// transition is re-broadcast up to [`MAX_REDRIVE_ATTEMPTS`] times +/// (identical nullifiers cannot be spent twice); only if every attempt stays +/// silent does the anchor-prune release backstop take over. Saved before the +/// first dispatch, it also covers a process that exits during the dispatches +/// or the result wait: a restart restores the notes' reservation from it. #[allow(clippy::too_many_arguments)] async fn broadcast_shielded_spend_with_redrive_with_metadata( sdk: &Arc, @@ -2964,77 +3846,351 @@ async fn broadcast_shielded_spend_with_redrive_with_metadata( id: SubwalletId, pending_entry: &Option, anchor: [u8; 32], + anchor_height: u64, notes: &[ShieldedNote], + reservation: &mut NoteReservation, state_transition: &StateTransition, operation: &'static str, wait: SpendResultWait, -) -> Result<(StateTransitionProofResult, ResponseMetadata), PlatformWalletError> { - let result = broadcast_shielded_spend(sdk, state_transition, operation, wait).await; - if matches!( - &result, - Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) - ) { - arm_redrive_record( +) -> Result<(StateTransitionProofResult, ResponseMetadata), SpendFailure> { + save_spend_then_broadcast( + store, + id, + pending_entry, + anchor, + anchor_height, + notes, + reservation, + state_transition, + operation, + || broadcast_shielded_spend_classified(sdk, state_transition, operation, wait), + ) + .await +} + +/// Save the recovery record of the built note-consuming spend +/// `state_transition` durably, hand its notes over, and only then run +/// `broadcast`, which sends it and waits for its result: the production flows +/// pass their classified broadcast, a test intercepts it. +/// +/// Each of `notes`' reservations first carries the spend's `anchor` +/// ([`arm_pending_release`]), so a pruned anchor releases it; the record is +/// then saved, keyed by `pending_entry` ([`arm_redrive_before_broadcast`]). A +/// spend with no entry to key its record by, or whose record cannot be saved, +/// is refused with nothing broadcast, and `reservation` still owns the notes: +/// the caller releases them ([`settle_failed_spend`]), and so does a spend +/// dropped while a save waits for the store. +/// +/// Once the record is saved the notes are handed over, with nothing awaited +/// in between: from then on they belong to the spend's resolution, whatever +/// happens to this call. An exit or a drop during the dispatches or the +/// result wait leaves the reservation and the record, which a restart +/// restores and the redrive pass resolves. +#[allow(clippy::too_many_arguments)] +async fn save_spend_then_broadcast( + store: &Arc>, + id: SubwalletId, + pending_entry: &Option, + anchor: [u8; 32], + anchor_height: u64, + notes: &[ShieldedNote], + reservation: &mut NoteReservation, + state_transition: &StateTransition, + operation: &'static str, + broadcast: B, +) -> Result +where + S: ShieldedStore, + B: FnOnce() -> Fut, + Fut: Future>, +{ + arm_pending_release(store, id, anchor, anchor_height, pending_entry, notes).await?; + arm_redrive_before_broadcast( + store, + id, + pending_entry.as_ref().map(|entry| entry.id), + anchor, + notes.iter().map(|note| note.nullifier).collect(), + state_transition, + operation, + None, + None, + anchor_height, + ) + .await?; + // Saved: the notes are the spend's resolution's from here on. + reservation.hand_over(); + broadcast().await +} + +/// Settle the notes, saved record and activity row of a note-consuming spend +/// (transfer, unshield, withdrawal, identity top-up, identity create) that +/// ended with `failure`, and return the error it reports. +/// +/// - Its transition never left the wallet ([`SpendFailure::never_delivered`]: +/// refused before anything was sent), so nothing can execute it: its record +/// is retired and its notes are released under one store guard +/// ([`NoteReservation::retire_undelivered`]), and the activity row reads +/// failed. When the record cannot be retired (a redrive pass claimed a +/// re-broadcast of it meanwhile, or the write failed), the transition may +/// leave the wallet after all: everything stays and the spend reads as +/// unconfirmed. +/// - Its record was saved (`reservation` is handed over, +/// [`save_spend_then_broadcast`]) and a dispatch may have reached a node: +/// it may execute. The notes stay reserved and the record stays, for the +/// scan and the redrive pass to resolve, and the activity row stays +/// pending. It reads as unconfirmed, whatever error ended it. +/// - It failed before its record was saved: nothing was broadcast. The notes +/// are released and the activity row reads failed. +#[allow(clippy::too_many_arguments)] +async fn settle_failed_spend( + store: &Arc>, + persister: Option<&WalletPersister>, + wallet_id: WalletId, + id: SubwalletId, + pending_entry: &Option, + mut reservation: NoteReservation, + operation: &'static str, + failure: SpendFailure, +) -> PlatformWalletError { + let SpendFailure { + error, + never_delivered, + } = failure; + if never_delivered { + let retired = match pending_entry.as_ref().map(|entry| entry.id) { + Some(activity_id) => reservation.retire_undelivered(&activity_id, &[]).await, + None => { + reservation.hand_over(); + false + } + }; + if !retired { + return PlatformWalletError::ShieldedSpendUnconfirmed { + operation, + reason: format!( + "its broadcast was refused before delivery ({error}), but its saved \ + transition was claimed for a re-broadcast or could not be retired" + ), + }; + } + record_activity_status( store, + persister, + wallet_id, id, pending_entry, - anchor, - notes, - state_transition, - operation, + ShieldedActivityStatus::Failed, + None, ) .await; + return error; + } + if reservation.handed_over { + return match error { + unconfirmed @ (PlatformWalletError::ShieldedSpendUnconfirmed { .. } + | PlatformWalletError::ShieldedBroadcastUnconfirmed { .. }) => unconfirmed, + other => { + // The reported error keeps the cause's text alone: its type + // goes to the log. + warn!( + account = id.account_index, + operation, + cause = ?other, + "Shielded spend ended with its record saved; reporting it unconfirmed" + ); + PlatformWalletError::ShieldedSpendUnconfirmed { + operation, + reason: other.to_string(), + } + } + }; } - result + // The guard owns the notes until they are released, so a drop on the + // way still releases them. + record_activity_status( + store, + persister, + wallet_id, + id, + pending_entry, + ShieldedActivityStatus::Failed, + None, + ) + .await; + reservation.cancel().await; + error } -/// Persist the re-drivable record for an ambiguous spend. Best-effort: -/// a failure here only demotes the resolution path to the anchor-prune -/// backstop (plus restart-loss of the reservation), never fails the -/// spend call itself — the ambiguity already happened. -async fn arm_redrive_record( +/// Save the re-drivable record of a spend durably before it is broadcast, +/// as identity-funded shields arm theirs: an exit after the node admitted +/// the transition, before its result returns, leaves the record. The record +/// is keyed by the spend's `activity_id` and carries its `nullifiers`, and +/// the private contact request the spend pays for when it does. A spend +/// paying for one is a private document create (type 29), and the private +/// payment journal keeps a record of each entry it appends, read from the +/// transition, in the same durable write ([`ShieldedStore::arm_private_contact_payment`]). +/// A spend whose record cannot be saved, or whose entries do not read, is +/// refused before anything is broadcast, as the unknown outcome could then +/// not be recovered. `payment_started`, when given, is marked right after +/// the record is saved, under the same store lock: dropped while it waits +/// for the lock, the spend leaves neither a record nor a mark. +/// `anchor_recorded_at` is the proved height of the recorded-anchor set the +/// spend's anchor was chosen from, kept in the journal record: an expiry +/// proof needs the anchor absent from a set proved at or above it. +#[allow(clippy::too_many_arguments)] +pub(crate) async fn arm_redrive_before_broadcast( store: &Arc>, id: SubwalletId, - pending_entry: &Option, + activity_id: Option<[u8; 32]>, anchor: [u8; 32], - notes: &[ShieldedNote], + nullifiers: Vec<[u8; 32]>, state_transition: &StateTransition, operation: &'static str, -) { + private_contact: Option, + payment_started: Option<&PaymentStarted>, + anchor_recorded_at: u64, +) -> Result<(), PlatformWalletError> { use dpp::serialization::PlatformSerializable; - let Some(entry) = pending_entry else { - return; - }; - let st_bytes = match state_transition.serialize_to_bytes() { - Ok(b) => b, - Err(e) => { - warn!( - operation, - error = %e, - "failed to serialize the unconfirmed transition; re-drive disabled for this \ - spend (prune backstop still applies)" - ); - return; - } + let activity_id = activity_id.ok_or_else(|| { + PlatformWalletError::ShieldedBuildError(format!( + "{operation}: no activity entry keys the record of this spend, so it is not \ + broadcast" + )) + })?; + let st_bytes = state_transition.serialize_to_bytes().map_err(|e| { + PlatformWalletError::ShieldedBuildError(format!( + "{operation}: the transition does not serialize for its record, so it is not \ + broadcast: {e}" + )) + })?; + let journal = match private_contact { + Some(payment) => Some(( + payment, + private_document_entries(state_transition).ok_or_else(|| { + PlatformWalletError::ShieldedBuildError(format!( + "{operation}: the entries this private contact request payment appends do \ + not read, so it is not broadcast" + )) + })?, + )), + None => None, }; let redrive = PendingRedrive { - activity_id: entry.id, + activity_id, anchor, - nullifiers: notes.iter().map(|n| n.nullifier).collect(), + nullifiers, st_bytes, attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: Some(anchor_recorded_at), }; - if let Err(e) = store.write().await.arm_redrive(id, redrive) { - warn!( - operation, - error = %e, - "failed to persist the redrive record; re-drive disabled for this spend (prune \ - backstop still applies)" - ); + let mut store = store.write().await; + match journal { + Some((payment, entries)) => store.arm_private_contact_payment( + id, + redrive, + payment, + &entries, + anchor_recorded_at, + payment_started.and_then(PaymentStarted::store_position), + ), + None => store.arm_redrive(id, redrive), + } + .map_err(|e| { + PlatformWalletError::ShieldedStoreError(format!( + "{operation}: the record of this spend could not be saved, so it is not broadcast: \ + {e}" + )) + })?; + if let Some(payment_started) = payment_started { + payment_started.mark(); + } + Ok(()) +} + +/// Discharge `wallet_id`'s journal records of the private contact request +/// entries a private sync read back and recorded durably, as `persister` +/// noted them (`WalletPersister::note_read_back_private_entries`). One whose +/// discharge fails is noted again for the next call. +pub(crate) fn discharge_read_back_private_payments( + store: &mut S, + persister: &WalletPersister, + wallet_id: WalletId, +) { + let mut kept = Vec::new(); + let mut discharged = Vec::new(); + for commitment in persister.take_read_back_private_entries() { + match store.discharge_private_payment(wallet_id, &commitment) { + Ok(_) => discharged.push(commitment), + Err(e) => { + warn!( + error = %e, + "a read-back private payment's journal record was not discharged; retried \ + later" + ); + kept.push(commitment); + } + } + } + persister.note_discharged_private_entries(discharged); + if !kept.is_empty() { + persister.note_read_back_private_entries(kept); + } +} + +/// [`private_document_commitments`], each with the SHA-256 of its whole entry, +/// as a private contact request payment's journal records keep them. +pub(crate) fn private_document_entries( + state_transition: &StateTransition, +) -> Option> { + use dpp::state_transition::private_document_create_from_shielded_pool_transition::accessors::PrivateDocumentCreateFromShieldedPoolTransitionAccessorsV0; + + let StateTransition::PrivateDocumentCreateFromShieldedPool(transition) = state_transition + else { + return None; + }; + let commitments = private_document_commitments(state_transition)?; + Some( + commitments + .into_iter() + .zip(transition.entries()) + .map(|(commitment, entry)| PrivatePaymentEntry { + commitment, + entry_hash: Sha256::digest(entry.as_slice()).into(), + }) + .collect(), + ) +} + +/// The commitments of the entries the private document create (type 29) +/// `state_transition` appends, each entry's first 32 bytes; `None` for +/// another transition, one appending no entry, or an entry shorter than its +/// commitment. +pub(crate) fn private_document_commitments( + state_transition: &StateTransition, +) -> Option> { + use dpp::state_transition::private_document_create_from_shielded_pool_transition::accessors::PrivateDocumentCreateFromShieldedPoolTransitionAccessorsV0; + + let StateTransition::PrivateDocumentCreateFromShieldedPool(transition) = state_transition + else { + return None; + }; + if transition.entries().is_empty() { + return None; } + transition + .entries() + .iter() + .map(|entry| { + entry + .as_slice() + .get(..32) + .and_then(|commitment| <[u8; 32]>::try_from(commitment).ok()) + }) + .collect() } /// Whether an SDK error is Platform's `NullifierAlreadySpentError` — @@ -3071,9 +4227,9 @@ enum RedriveBroadcastOutcome { /// `NullifierAlreadySpent`: the ORIGINAL broadcast executed — a /// success signal, never a failure. AlreadyExecuted, - /// Any other consensus verdict: the transition can never execute. - DefinitiveRejection, - /// Transport noise / `AlreadyExists` / anything non-definitive. + /// Any other outcome, a consensus verdict included: the original's + /// broadcast was ambiguous, so a refusal of the re-broadcast does not + /// prove it can never execute. Inconclusive, } @@ -3081,7 +4237,6 @@ fn classify_redrive_broadcast(result: &Result<(), dash_sdk::Error>) -> RedriveBr match result { Ok(()) => RedriveBroadcastOutcome::Accepted, Err(e) if is_nullifier_already_spent(e) => RedriveBroadcastOutcome::AlreadyExecuted, - Err(e) if carries_consensus_rejection(e) => RedriveBroadcastOutcome::DefinitiveRejection, Err(_) => RedriveBroadcastOutcome::Inconclusive, } } @@ -3109,6 +4264,45 @@ async fn bump_redrive_attempts_logged( } } +/// Claim one re-broadcast of `redrive`, durably, from the record as it is now, +/// under the store write lock a never-delivered spend's retirement takes +/// ([`ShieldedStore::retire_undelivered_spend`]): the attempt is counted +/// before the broadcast starts, so a retirement after the claim sees it and +/// refuses. A record retired, armed again with other bytes, or out of attempts +/// since `redrive` was read is not claimed, and not broadcast. Returns the +/// attempt count, or `None` when nothing was claimed: a counter that fails to +/// persist claims nothing. +async fn claim_redrive_attempt( + store: &Arc>, + id: SubwalletId, + redrive: &PendingRedrive, +) -> Option { + let mut store = store.write().await; + let live = store.pending_redrives(id).is_ok_and(|current| { + current.iter().any(|record| { + record.activity_id == redrive.activity_id + && record.st_bytes == redrive.st_bytes + && record.attempts < MAX_REDRIVE_ATTEMPTS + }) + }); + if !live { + debug!("redrive: the record was retired or changed since it was read; not re-broadcast"); + return None; + } + match store.bump_redrive_attempts(id, &redrive.activity_id) { + Ok(attempts) if attempts > 0 => Some(attempts), + Ok(_) => None, + Err(e) => { + warn!( + error = %e, + "redrive: the attempt could not be counted, so it is not re-broadcast; the next \ + pass retries" + ); + None + } + } +} + /// Re-broadcast every unresolved ShieldFromIdentity transition for `wallet_id`. /// These records have no nullifiers or spending anchor, so they must not depend /// on the note-spend stranded-release pass. Exact-byte retries remain safe even @@ -3232,11 +4426,16 @@ pub(super) async fn redrive_pending_identity_shields( /// - accepted / inconclusive → count the attempt; wait for the next scan; /// - `NullifierAlreadySpent` → the original executed; the next scan /// confirms — touch nothing; -/// - any other consensus verdict → provably dead NOW: release the -/// reservation and flip the activity row to Failed, hours before the -/// prune backstop would; +/// - any other consensus verdict → inconclusive too: a node refusing the +/// re-broadcast does not show that no other node holds the original, +/// whose broadcast was ambiguous, so the notes stay reserved; /// - pruned anchor / exhausted attempts → leave it to the -/// prune-backstop release pass. +/// prune-backstop release pass, which releases the notes once the +/// anchor is pruned and the spend can never execute. +/// +/// A record whose transition does not decode is kept, never dropped: it +/// may be the only evidence of a payment that can still execute. Its notes +/// stay reserved until the spend lands or the prune backstop releases them. /// /// Runs after the scan's spent-note reconcile (a landed spend's record /// was already dropped by the `mark_spent` hook, so anything still @@ -3244,8 +4443,6 @@ pub(super) async fn redrive_pending_identity_shields( pub(super) async fn redrive_pending_spends( sdk: &Arc, store: &Arc>, - persister: Option<&WalletPersister>, - wallet_id: WalletId, id: SubwalletId, recorded: &std::collections::HashSet<[u8; 32]>, cancel: &CancellationToken, @@ -3285,15 +4482,15 @@ pub(super) async fn redrive_pending_spends( Err(e) => { warn!( error = %e, - "redrive: stored transition failed to deserialize; dropping the record \ - (the prune backstop still frees the notes)" + "redrive: stored transition failed to deserialize; keeping the record \ + without re-broadcasting it (the prune backstop still frees the notes)" ); - if let Err(e) = store.write().await.clear_redrive(id, &redrive.activity_id) { - warn!(error = %e, "redrive: clear_redrive failed"); - } continue; } }; + let Some(attempts) = claim_redrive_attempt(store, id, &redrive).await else { + continue; + }; let broadcast_result = st.broadcast(sdk, None).await; let err_display = broadcast_result .as_ref() @@ -3302,7 +4499,6 @@ pub(super) async fn redrive_pending_spends( .unwrap_or_default(); match classify_redrive_broadcast(&broadcast_result) { RedriveBroadcastOutcome::Accepted => { - let attempts = bump_redrive_attempts_logged(store, id, &redrive.activity_id).await; info!( attempts, max = MAX_REDRIVE_ATTEMPTS, @@ -3310,12 +4506,11 @@ pub(super) async fn redrive_pending_spends( ); } RedriveBroadcastOutcome::AlreadyExecuted => { - // Success signal — but still consume an attempt: the scan + // Success signal, but the attempt still counts: the scan // normally confirms the landing and drops the record, and // if it lags, this arm must not re-broadcast unboundedly // on every pass. The cap parks the record for the scan / // prune passes to settle. - let attempts = bump_redrive_attempts_logged(store, id, &redrive.activity_id).await; info!( attempts, max = MAX_REDRIVE_ATTEMPTS, @@ -3323,37 +4518,10 @@ pub(super) async fn redrive_pending_spends( the notes spent" ); } - RedriveBroadcastOutcome::DefinitiveRejection => { - warn!( - error = %err_display, - "redrive: definitive consensus rejection; the spend can never execute — \ - releasing the reservation" - ); - { - let mut guard = store.write().await; - for n in &redrive.nullifiers { - // Also drops the redrive record via the - // clear_pending hook. - if let Err(e) = guard.clear_pending(id, n) { - warn!(error = %e, "redrive: clear_pending failed"); - } - } - } - record_activity_status_by_id( - store, - persister, - wallet_id, - id, - &redrive.activity_id, - ShieldedActivityStatus::Failed, - ) - .await; - } RedriveBroadcastOutcome::Inconclusive => { // `AlreadyExists` (still in a mempool after a lost-ACK // retry) or transport noise: inconclusive; counts toward // the cap. - let attempts = bump_redrive_attempts_logged(store, id, &redrive.activity_id).await; debug!( attempts, max = MAX_REDRIVE_ATTEMPTS, @@ -3365,36 +4533,8 @@ pub(super) async fn redrive_pending_spends( } } -/// Broadcast a built shielded spend transition (unshield / transfer / -/// withdraw) and wait for proven execution, staging the two SDK calls -/// separately so the caller's reservation rollback only runs when the -/// spend DEFINITIVELY did not happen: -/// -/// - a definitive `broadcast()` failure ([`broadcast_definitely_failed`]: -/// a consensus-verdict CheckTx rejection, or a transport failure that -/// proves nothing was delivered), or a wait-stage consensus rejection -/// (Platform ran the transition and rejected it on its merits — see -/// [`carries_consensus_rejection`]), means the spend never executed → -/// [`PlatformWalletError::ShieldedBroadcastFailed`], and the caller -/// releases the note reservations via [`cancel_pending`]; -/// - a no-verdict `broadcast()` failure (`AlreadyExists` proves the tx IS -/// in the mempool after a lost-ACK retry; timeouts merely allow it) -/// falls through to the result wait, which either proves execution or -/// classifies the residual ambiguity; -/// - any other wait failure (transport error, timeout, result-proof -/// fetch/verify error, …) is AMBIGUOUS — the relay accepted (or may -/// have accepted) the tx and it may well have executed → -/// [`PlatformWalletError::ShieldedSpendUnconfirmed`], and the caller -/// must leave the reservations in place (each spend flow's outer -/// match has a dedicated arm for this). -/// -/// Mirrors the staging in [`identity_create_from_shielded_pool`], minus -/// its fetch-by-derived-id fallback: a spend leaves no artifact as -/// cheaply queryable as an identity row, so ambiguity is surfaced -/// directly and reconciled by the next nullifier sync. The proven -/// result is discarded; only the confirmation matters. -/// How [`broadcast_shielded_spend`] waits for an already-broadcast spend's -/// result, mirroring the verifier's classification of the family. +/// How [`broadcast_shielded_spend_classified`] waits for an already-broadcast +/// spend's result, mirroring the verifier's classification of the family. #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum SpendResultWait { /// The family is classified execution-proving (transfer, unshield, @@ -3407,24 +4547,66 @@ enum SpendResultWait { AffectedState, } -async fn broadcast_shielded_spend( +/// A failed note-consuming spend: the error it reports, and whether its +/// transition never left the wallet. Every failure before the broadcast, and +/// every one after a dispatch that may have reached a node, is built from its +/// error alone ([`From`]), with `never_delivered` false. +struct SpendFailure { + error: PlatformWalletError, + /// The broadcast proved nothing was delivered + /// ([`BroadcastDelivery::NeverDelivered`]): nothing holds the transition's + /// bytes but the wallet, so it can never execute. + never_delivered: bool, +} + +impl From for SpendFailure { + fn from(error: PlatformWalletError) -> Self { + Self { + error, + never_delivered: false, + } + } +} + +/// Broadcast a built shielded spend transition and wait for its proven +/// result, telling a failure whose transition never left the wallet from one +/// that may have reached the network: +/// +/// - refused before anything was sent ([`BroadcastDelivery::NeverDelivered`]): +/// [`PlatformWalletError::ShieldedBroadcastFailed`], with +/// [`SpendFailure::never_delivered`] set, so the caller retires the saved +/// record and releases the notes; +/// - any dispatch that may have reached a node falls through to the result +/// wait, which either proves the outcome or leaves it unknown; +/// - any wait failure, a consensus verdict included +/// ([`classify_spend_wait_failure`]): +/// [`PlatformWalletError::ShieldedSpendUnconfirmed`], and the caller leaves +/// the reservations and the saved record in place. +/// +/// A spend leaves no artifact as cheaply queryable as the identity row +/// [`broadcast_identity_create`] falls back to, so an unknown outcome is +/// surfaced directly and resolved by the next nullifier sync and the redrive +/// pass. +async fn broadcast_shielded_spend_classified( sdk: &Arc, state_transition: &StateTransition, operation: &'static str, wait: SpendResultWait, -) -> Result<(StateTransitionProofResult, ResponseMetadata), PlatformWalletError> { - match state_transition.broadcast(sdk, None).await { - Ok(()) => {} - Err(e) if broadcast_definitely_failed(&e) => { - return Err(crate::error::promote_address_nonce_error(&e) - .unwrap_or_else(|| PlatformWalletError::ShieldedBroadcastFailed(e.to_string()))); +) -> Result<(StateTransitionProofResult, ResponseMetadata), SpendFailure> { + match broadcast_tracking_delivery(sdk, state_transition).await { + BroadcastDelivery::Admitted => {} + BroadcastDelivery::NeverDelivered(e) => { + return Err(SpendFailure { + error: definite_broadcast_failure(&e), + never_delivered: true, + }); } - Err(e) => { + BroadcastDelivery::MaybeDelivered(e) => { warn!( operation, error = %e, - "Shielded spend broadcast returned no verdict; the transition may have been \ - admitted — falling through to the result wait" + "Shielded spend broadcast may have been delivered; falling through to the \ + result wait" ); } } @@ -3445,42 +4627,48 @@ async fn broadcast_shielded_spend( .await } }; - waited.map_err(|wait_err| classify_spend_wait_failure(operation, &wait_err)) + waited + .map_err(|wait_err| classify_spend_wait_failure(operation, &wait_err)) + .map_err(SpendFailure::from) +} + +/// The error a spend whose transition never left the wallet +/// ([`BroadcastDelivery::NeverDelivered`], refused before anything was sent) +/// is reported as: a failed broadcast. Its notes are released. Every +/// broadcast that reached an endpoint waits for its result instead, and +/// reads as unconfirmed when that wait fails. +fn definite_broadcast_failure(e: &dash_sdk::Error) -> PlatformWalletError { + PlatformWalletError::ShieldedBroadcastFailed(e.to_string()) } /// Classify a `wait_for_response` failure for an already-broadcast -/// shielded spend (see [`broadcast_shielded_spend`]). +/// shielded spend (see [`broadcast_shielded_spend_classified`]): unconfirmed, whatever +/// it is, the notes staying reserved. /// -/// Only a consensus verdict ([`carries_consensus_rejection`]) proves -/// Platform executed the transition and rejected it on its merits — the -/// serialized consensus error is the verdict. DAPI encodes its own +/// A consensus verdict on the wait ([`carries_consensus_rejection`]) is no +/// proof either: the endpoint that sends it is unauthenticated, no proof or +/// quorum signature backs it, and one that kept or forwarded the signed +/// transition can answer with any verdict. DAPI also encodes its own /// wait-side failures (timeouts, internal errors; see /// `build_wait_for_state_transition_error_response` in rs-dapi) as -/// `StateTransitionBroadcastError`s with EMPTY consensus data, which -/// the SDK surfaces as `cause: None` — those are ambiguous, not -/// rejections, and must keep the note reservations. Erring this way is -/// the safe direction: misreading a rejection as ambiguous only delays -/// note release until the next sync or restart, while misreading a -/// timeout as a rejection re-frees notes whose nullifiers may already -/// be consumed on chain. +/// `StateTransitionBroadcastError`s with EMPTY consensus data. A spend +/// reported failed while it may still execute could be paid again with other +/// notes; one that never executes is released by the redrive and prune +/// passes once its anchor is pruned. fn classify_spend_wait_failure( operation: &'static str, wait_err: &dash_sdk::Error, ) -> PlatformWalletError { - if carries_consensus_rejection(wait_err) { - crate::error::promote_address_nonce_error(wait_err) - .unwrap_or_else(|| PlatformWalletError::ShieldedBroadcastFailed(wait_err.to_string())) - } else { - warn!( - operation, - error = %wait_err, - "Shielded spend broadcast accepted but result confirmation failed; \ - leaving the note reservations in place" - ); - PlatformWalletError::ShieldedSpendUnconfirmed { - operation, - reason: wait_err.to_string(), - } + warn!( + operation, + error = %wait_err, + rejected = carries_consensus_rejection(wait_err), + "Shielded spend broadcast but its result is unconfirmed; leaving the note reservations \ + in place" + ); + PlatformWalletError::ShieldedSpendUnconfirmed { + operation, + reason: wait_err.to_string(), } } @@ -3633,14 +4821,34 @@ mod shield_recipient_tests { #[cfg(test)] mod redrive_tests { use super::*; + use crate::broadcast_outcome::test_sdks::{sdk_refusing_connections, sdk_without_addresses}; + use crate::wallet::identity::network::PaymentStarted; + use crate::wallet::shielded::activity::ShieldedActivityEntry; use crate::wallet::shielded::store::InMemoryShieldedStore; + use crate::wallet::shielded::FileBackedShieldedStore; + use dash_sdk::dpp::dashcore::Network; + use dash_sdk::dpp::prelude::CoreBlockHeight; + use dash_sdk::error::ContextProviderError; use dash_sdk::error::StateTransitionBroadcastError; + use dash_sdk::platform::ContextProvider; + use dash_sdk::sdk::AddressList; use dpp::consensus::state::shielded::nullifier_already_spent_error::NullifierAlreadySpentError; use dpp::consensus::state::state_error::StateError; use dpp::consensus::ConsensusError; - use dpp::platform_value::BinaryData; + use dpp::data_contract::{DataContract, TokenConfiguration}; use dpp::serialization::PlatformSerializable; + use dpp::shielded::SerializedAction; + use dpp::state_transition::private_document_create_from_shielded_pool_transition::methods::PrivateDocumentCreateFromShieldedPoolTransitionMethodsV0; + use dpp::state_transition::private_document_create_from_shielded_pool_transition::PrivateDocumentCreateFromShieldedPoolTransition; use dpp::state_transition::shield_from_identity_transition::v0::ShieldFromIdentityTransitionV0; + use dpp::state_transition::shield_transition::v0::ShieldTransitionV0; + use dpp::state_transition::shielded_transfer_transition::v0::ShieldedTransferTransitionV0; + use dpp::state_transition::state_transitions::shielded::identity_create_from_shielded_pool_transition::v0::IdentityCreateFromShieldedPoolTransitionV0; + use dpp::version::PlatformVersion; + use futures::{poll, FutureExt}; + use grovedb_commitment_tree::ProvingKey; + use std::str::FromStr; + use std::task::Poll; fn identity_shield_transition(identity_id: [u8; 32], nonce: u64) -> StateTransition { ShieldFromIdentityTransitionV0 { @@ -3674,6 +4882,7 @@ mod redrive_tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: true, + anchor_height: None, }; store.arm_redrive(id, archived.clone()).unwrap(); assert!(!has_unresolved_identity_shield(&store, wallet_id, identity_id).unwrap()); @@ -3724,6 +4933,7 @@ mod redrive_tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .unwrap(); @@ -3796,6 +5006,7 @@ mod redrive_tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .expect("redrive should arm"); @@ -3824,6 +5035,7 @@ mod redrive_tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .expect("redrive should arm"); @@ -3885,184 +5097,2373 @@ mod redrive_tests { "already-spent must classify as success BEFORE the generic rejection arm" ); - let other_rejection = ConsensusError::BasicError( - dpp::consensus::basic::BasicError::ProtocolVersionParsingError( - dpp::consensus::basic::decode::ProtocolVersionParsingError::new( - "bad version".to_string(), - ), - ), - ); - let rejection_err = + let other_rejection = ConsensusError::BasicError( + dpp::consensus::basic::BasicError::ProtocolVersionParsingError( + dpp::consensus::basic::decode::ProtocolVersionParsingError::new( + "bad version".to_string(), + ), + ), + ); + let rejection_err = + dash_sdk::Error::StateTransitionBroadcastError(StateTransitionBroadcastError { + code: 1, + message: "state error".to_string(), + cause: Some(other_rejection), + }); + assert_eq!( + classify_redrive_broadcast(&Err(rejection_err)), + RedriveBroadcastOutcome::Inconclusive, + "a refused re-broadcast does not prove the original never executes" + ); + + let timeout = dash_sdk::Error::TimeoutReached( + std::time::Duration::from_secs(1), + "waiting".to_string(), + ); + assert_eq!( + classify_redrive_broadcast(&Err(timeout)), + RedriveBroadcastOutcome::Inconclusive + ); + } + + #[tokio::test] + async fn identity_redrive_ignores_spend_anchor_and_attempt_limit() { + let sdk = Arc::new(dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk")); + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let wallet_id = [0x45; 32]; + let previous_account = SubwalletId::new(wallet_id, 7); + let activity_id = [0x67; 32]; + let transition = identity_shield_transition([0x89; 32], 11); + store + .write() + .await + .arm_redrive( + previous_account, + PendingRedrive { + activity_id, + anchor: [0xAB; 32], + nullifiers: vec![], + st_bytes: transition.serialize_to_bytes().expect("serialize"), + attempts: MAX_REDRIVE_ATTEMPTS, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }, + ) + .expect("arm identity guard"); + + redrive_pending_identity_shields(&sdk, &store, wallet_id, &CancellationToken::new()).await; + + let retained = store + .read() + .await + .pending_redrives(previous_account) + .expect("retained redrive"); + assert_eq!( + retained.len(), + 1, + "an endpoint error cannot clear the guard" + ); + assert_eq!( + retained[0].attempts, + MAX_REDRIVE_ATTEMPTS + 1, + "identity retries stay live beyond the note-spend attempt budget" + ); + } + + /// The production payment flow saves a private contact request payment + /// durably before its broadcast runs: intercepting the broadcast, a second + /// handle on the store's file reads its journal record and redrive record, + /// and the payment is marked started. A payment whose save fails is never + /// broadcast, is not marked started, and releases its notes. + #[tokio::test] + async fn should_save_a_private_payment_durably_before_its_broadcast() { + use std::sync::atomic::{AtomicBool, Ordering}; + + let sdk = Arc::new(dash_sdk::Sdk::new_mock()); + let action = SerializedAction { + nullifier: [1; 32], + rk: [2; 32], + cmx: [3; 32], + encrypted_note: vec![4; 216], + cv_net: [5; 32], + spend_auth_sig: [6; 64], + }; + let payment = PrivateContactPayment { + sender: [0xB1; 32], + recipient: [0xA1; 32], + account_reference: 5, + }; + let wallet_id = [0x68; 32]; + let id = SubwalletId::new(wallet_id, 0); + for save_fails in [false, true] { + let dir = tempfile::tempdir().expect("a directory"); + let path = dir.path().join("tree.sqlite"); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(&path, 100).expect("the store"), + )); + let note = ShieldedNote { + position: 0, + cmx: [1; 32], + nullifier: [0x5F; 32], + block_height: 1, + is_spent: false, + value: 1_000_000_000_000, + note_data: vec![], + }; + store.write().await.save_note(id, ¬e).expect("a note"); + let (selected, _, _, reservation) = + reserve_notes_covering(&sdk, &store, id, 1, 2, ShieldedFeeKind::Base) + .await + .expect("reserved"); + if save_fails { + rusqlite::Connection::open(&path) + .expect("the store's file") + .execute_batch( + "CREATE TRIGGER reject_redrive_insert BEFORE INSERT ON \ + shielded_pending_spends BEGIN SELECT RAISE(FAIL, 'injected'); END;", + ) + .expect("the trigger"); + } + let transition = PrivateDocumentCreateFromShieldedPoolTransition::try_from_bundle( + Identifier::from([0x44; 32]), + "privateContactRequest".to_string(), + vec![BinaryData::new(vec![9; 589])], + vec![action.clone(), action.clone()], + 0, + [7; 32], + vec![8; 64], + [9; 64], + PlatformVersion::latest(), + ) + .expect("a type 29 transition"); + let started = PaymentStarted::default(); + let broadcast = AtomicBool::new(false); + let submitted = submit_private_document_payment( + PrivateDocumentSubmission { + store: &store, + persister: None, + wallet_id, + id, + pending_entry: Some(ShieldedActivityEntry { + id: [0x77; 32], + kind: ShieldedActivityKind::ShieldedSpend, + direction: ShieldedDirection::Out, + amount: 0, + fee: Some(0), + counterparty: None, + memo: None, + block_height: None, + status: ShieldedActivityStatus::Pending, + created_at_ms: 1, + min_note_position: None, + note_cmxs: vec![], + spent_nullifiers: vec![], + }), + selected_notes: &selected, + reservation, + state_transition: transition, + anchor: [7; 32], + anchor_height: 0, + private_contact: Some(payment), + journaled: Some(&[[9; 32]]), + payment_started: &started, + }, + |_| { + broadcast.store(true, Ordering::SeqCst); + let durable = + FileBackedShieldedStore::open_path(&path, 100).expect("a second handle"); + assert_eq!( + durable + .private_payment_journal(wallet_id) + .expect("the journal") + .len(), + 1, + "the journal record is on the file" + ); + assert_eq!( + durable + .private_contact_redrives_for_wallet(wallet_id) + .expect("the records") + .len(), + 1, + "the redrive record and its association are on the file" + ); + assert!(started.is_marked(), "marked once saved"); + std::future::ready(Err(SpendFailure { + error: PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create from shielded pool", + reason: "intercepted".to_string(), + }, + never_delivered: false, + })) + }, + ) + .await; + let unspent = store + .read() + .await + .get_unspent_notes(id) + .expect("notes") + .len(); + if save_fails { + assert!( + matches!(submitted, Err(PlatformWalletError::ShieldedStoreError(_))), + "{submitted:?}" + ); + assert!(!broadcast.load(Ordering::SeqCst), "never broadcast"); + assert!(!started.is_marked(), "never marked"); + assert_eq!(unspent, 1, "the notes are released"); + assert!(store + .read() + .await + .private_payment_journal(wallet_id) + .expect("the journal") + .is_empty()); + } else { + assert!( + matches!( + submitted, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{submitted:?}" + ); + assert!(broadcast.load(Ordering::SeqCst)); + assert_eq!(unspent, 0, "the notes stay reserved"); + } + } + } + + /// A payment dropped while its recovery save waits for the store has saved + /// and broadcast nothing, and its note guard releases the notes once the + /// store frees: the notes are handed over only after the save. + #[tokio::test] + async fn should_release_the_notes_of_a_payment_dropped_while_its_save_waits() { + use std::future::Future; + use std::task::{Context, Poll, Waker}; + + let sdk = Arc::new(dash_sdk::Sdk::new_mock()); + let action = SerializedAction { + nullifier: [1; 32], + rk: [2; 32], + cmx: [3; 32], + encrypted_note: vec![4; 216], + cv_net: [5; 32], + spend_auth_sig: [6; 64], + }; + let wallet_id = [0x69; 32]; + let id = SubwalletId::new(wallet_id, 0); + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let note = ShieldedNote { + position: 0, + cmx: [1; 32], + nullifier: [0x5E; 32], + block_height: 1, + is_spent: false, + value: 1_000_000_000_000, + note_data: vec![], + }; + store.write().await.save_note(id, ¬e).expect("a note"); + let (selected, _, _, reservation) = + reserve_notes_covering(&sdk, &store, id, 1, 2, ShieldedFeeKind::Base) + .await + .expect("reserved"); + let transition = PrivateDocumentCreateFromShieldedPoolTransition::try_from_bundle( + Identifier::from([0x44; 32]), + "privateContactRequest".to_string(), + vec![BinaryData::new(vec![9; 589])], + vec![action.clone(), action], + 0, + [7; 32], + vec![8; 64], + [9; 64], + PlatformVersion::latest(), + ) + .expect("a type 29 transition"); + let started = PaymentStarted::default(); + let mut cx = Context::from_waker(Waker::noop()); + + let held = store.write().await; + let mut submitted = Box::pin(submit_private_document_payment( + PrivateDocumentSubmission { + store: &store, + persister: None, + wallet_id, + id, + pending_entry: Some(ShieldedActivityEntry { + id: [0x78; 32], + kind: ShieldedActivityKind::ShieldedSpend, + direction: ShieldedDirection::Out, + amount: 0, + fee: Some(0), + counterparty: None, + memo: None, + block_height: None, + status: ShieldedActivityStatus::Pending, + created_at_ms: 1, + min_note_position: None, + note_cmxs: vec![], + spent_nullifiers: vec![], + }), + selected_notes: &selected, + reservation, + state_transition: transition, + anchor: [7; 32], + anchor_height: 0, + private_contact: Some(PrivateContactPayment { + sender: [0xB1; 32], + recipient: [0xA1; 32], + account_reference: 5, + }), + journaled: Some(&[[9; 32]]), + payment_started: &started, + }, + |_| async { panic!("never broadcast") }, + )); + // The submission waits for the store before its anchor step. + assert!(submitted.as_mut().poll(&mut cx).is_pending()); + // Freed, the lock goes to the submission first; this request queues + // behind it, so the submission's next one, the save, waits for it. + drop(held); + let mut ours = Box::pin(store.write()); + assert!(ours.as_mut().poll(&mut cx).is_pending()); + assert!(submitted.as_mut().poll(&mut cx).is_pending()); + let Poll::Ready(held) = ours.as_mut().poll(&mut cx) else { + panic!("the store is ours once the submission's anchor step is done"); + }; + // Dropped while the save waits. + drop(submitted); + assert!(!started.is_marked(), "nothing was saved"); + drop(held); + for _ in 0..50 { + if !store + .read() + .await + .get_unspent_notes(id) + .expect("notes") + .is_empty() + { + break; + } + tokio::time::sleep(std::time::Duration::from_millis(10)).await; + } + assert_eq!( + store + .read() + .await + .get_unspent_notes(id) + .expect("notes") + .len(), + 1, + "the guard released the notes" + ); + assert!(store + .read() + .await + .private_payment_journal(wallet_id) + .expect("the journal") + .is_empty()); + } + + /// A stale spend attempt's detached cleanup, delayed until after an + /// account purge and rebind (or the wallet's replacement) let a newer + /// attempt reserve the same notes and save its payment, releases nothing: + /// the newer attempt's notes stay reserved, and its redrive record, + /// association and journal record stay. + #[tokio::test] + async fn should_not_release_a_newer_attempt_s_notes_from_a_stale_cleanup() { + let sdk = Arc::new(dash_sdk::Sdk::new_mock()); + let wallet_id = [0x6A; 32]; + let id = SubwalletId::new(wallet_id, 0); + let note = ShieldedNote { + position: 0, + cmx: [1; 32], + nullifier: [0x5D; 32], + block_height: 1, + is_spent: false, + value: 1_000_000_000_000, + note_data: vec![], + }; + let payment = PrivateContactPayment { + sender: [0xB1; 32], + recipient: [0xA1; 32], + account_reference: 5, + }; + for wallet_replaced in [false, true] { + let dir = tempfile::tempdir().expect("a directory"); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(dir.path().join("tree.sqlite"), 100) + .expect("the store"), + )); + store.write().await.save_note(id, ¬e).expect("a note"); + let (_, _, _, stale) = + reserve_notes_covering(&sdk, &store, id, 1, 2, ShieldedFeeKind::Base) + .await + .expect("reserved"); + // Dropped while the store is busy: its cleanup waits on a task. + let mut held = store.write().await; + drop(stale); + if wallet_replaced { + held.purge_wallet(wallet_id).expect("the wallet's purge"); + } else { + held.purge_subwallet(id).expect("the account's purge"); + } + held.save_note(id, ¬e).expect("the note again"); + assert!(held + .mark_pending_by(id, ¬e.nullifier, u64::MAX) + .expect("reserved by the newer attempt")); + held.arm_private_contact_payment( + id, + PendingRedrive { + activity_id: [0x79; 32], + anchor: [7; 32], + nullifiers: vec![note.nullifier], + st_bytes: vec![0xAB; 96], + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }, + payment, + &[PrivatePaymentEntry::for_commitment([0xC4; 32])], + 0, + None, + ) + .expect("the newer payment saved"); + drop(held); + // The stale cleanup gets the store now. + for _ in 0..10 { + tokio::task::yield_now().await; + tokio::time::sleep(std::time::Duration::from_millis(5)).await; + } + let store = store.read().await; + let context = format!("wallet replaced: {wallet_replaced}"); + assert!( + store.get_unspent_notes(id).expect("notes").is_empty(), + "{context}: the newer attempt's note stays reserved" + ); + assert_eq!( + store.pending_redrives(id).expect("records").len(), + 1, + "{context}" + ); + assert_eq!( + store + .private_contact_redrives_for_wallet(wallet_id) + .expect("associations") + .len(), + 1, + "{context}" + ); + assert_eq!( + store + .private_payment_journal(wallet_id) + .expect("the journal") + .len(), + 1, + "{context}" + ); + } + } + + /// A pending activity entry keyed `id`, as a spend records before it + /// broadcasts. + fn pending_entry(id: [u8; 32]) -> ShieldedActivityEntry { + ShieldedActivityEntry { + id, + kind: ShieldedActivityKind::ShieldedSpend, + direction: ShieldedDirection::Out, + amount: 0, + fee: Some(0), + counterparty: None, + memo: None, + block_height: None, + status: ShieldedActivityStatus::Pending, + created_at_ms: 1, + min_note_position: None, + note_cmxs: vec![], + spent_nullifiers: vec![], + } + } + + /// A private contact request payment's journal record outlives its notes' + /// and redrive record whatever the spend's outcome, except a transition + /// that provably never left the wallet. Settled unconfirmed (its + /// broadcast may have been delivered and the result wait failed), the + /// notes stay reserved and the record, association and journal record + /// survive a reopen. Rejected after delivery, the notes and record are + /// released, the journal record stays. Never delivered, the record and + /// the journal record are retired together and the payment reads as not + /// reaching the network; unless the redrive pass claimed a re-broadcast + /// of the record meanwhile, when it may leave the wallet after all and is + /// settled as unconfirmed, keeping everything. + #[tokio::test] + async fn should_keep_a_private_payment_s_journal_record_unless_it_never_left() { + let sdk = Arc::new(dash_sdk::Sdk::new_mock()); + let action = SerializedAction { + nullifier: [1; 32], + rk: [2; 32], + cmx: [3; 32], + encrypted_note: vec![4; 216], + cv_net: [5; 32], + spend_auth_sig: [6; 64], + }; + let entry = BinaryData::new(vec![9; 589]); + let commitment = [9u8; 32]; + let transition = PrivateDocumentCreateFromShieldedPoolTransition::try_from_bundle( + Identifier::from([0x44; 32]), + "privateContactRequest".to_string(), + vec![entry], + vec![action.clone(), action], + 0, + [7; 32], + vec![8; 64], + [9; 64], + PlatformVersion::latest(), + ) + .expect("a type 29 transition"); + let payment = PrivateContactPayment { + sender: [0xB1; 32], + recipient: [0xA1; 32], + account_reference: 5, + }; + let wallet_id = [0x67; 32]; + let id = SubwalletId::new(wallet_id, 0); + let failure = |outcome: &str| match outcome { + "unconfirmed" => SpendFailure { + error: PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "private document create from shielded pool", + reason: "the result wait timed out".to_string(), + }, + never_delivered: false, + }, + "rejected after delivery" => SpendFailure { + error: PlatformWalletError::ShieldedBroadcastFailed( + "rejected on its merits".to_string(), + ), + never_delivered: false, + }, + _ => SpendFailure { + error: PlatformWalletError::ShieldedBroadcastFailed( + "refused at the door".to_string(), + ), + never_delivered: true, + }, + }; + for outcome in [ + "unconfirmed", + "rejected after delivery", + "never delivered", + "never delivered, re-broadcast claimed", + ] { + let dir = tempfile::tempdir().expect("a directory"); + let path = dir.path().join("tree.sqlite"); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(&path, 100).expect("the store"), + )); + let note = ShieldedNote { + position: 0, + cmx: [1; 32], + nullifier: [0x5F; 32], + block_height: 1, + is_spent: false, + value: 1_000_000_000_000, + note_data: vec![], + }; + store.write().await.save_note(id, ¬e).expect("a note"); + let (selected, _, _, reservation) = + reserve_notes_covering(&sdk, &store, id, 1, 2, ShieldedFeeKind::Base) + .await + .expect("reserved"); + let started = PaymentStarted::default(); + arm_redrive_before_broadcast( + &store, + id, + Some([0x77; 32]), + [7; 32], + selected.iter().map(|note| note.nullifier).collect(), + &transition, + "private document create from shielded pool", + Some(payment), + Some(&started), + 0, + ) + .await + .expect("saved before the broadcast"); + assert_eq!( + store + .read() + .await + .private_payment_journal(wallet_id) + .expect("journal") + .len(), + 1, + "{outcome}: journaled before the broadcast" + ); + + if outcome == "never delivered, re-broadcast claimed" { + store + .write() + .await + .bump_redrive_attempts(id, &[0x77; 32]) + .expect("claimed"); + } + let settled = settle_private_document_payment( + &store, + None, + wallet_id, + id, + &Some(pending_entry([0x77; 32])), + reservation, + &selected, + Some(&[commitment]), + &started, + Err(failure(outcome)), + ) + .await; + assert!(settled.is_err(), "{outcome}: {settled:?}"); + let unspent = store + .read() + .await + .get_unspent_notes(id) + .expect("notes") + .len(); + drop(store); + let reopened = FileBackedShieldedStore::open_path(&path, 100).expect("reopened"); + let journal = reopened + .private_payment_journal(wallet_id) + .expect("journal"); + let saved = reopened + .private_contact_redrives_for_wallet(wallet_id) + .expect("listed"); + match outcome { + "unconfirmed" | "never delivered, re-broadcast claimed" => { + assert!( + matches!( + settled, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "{outcome}: {settled:?}" + ); + assert_eq!(unspent, 0, "the notes stay reserved"); + assert_eq!(saved.len(), 1, "the record and its association stay"); + assert_eq!(journal.len(), 1, "the journal record stays"); + assert!(started.may_have_reached_network()); + } + "rejected after delivery" => { + assert_eq!(unspent, 1, "the notes are released"); + assert!(saved.is_empty(), "the record goes with them"); + assert_eq!(journal.len(), 1, "the journal record stays"); + assert_eq!(journal[0].commitment, commitment); + assert_eq!(journal[0].payment, payment); + assert!(started.may_have_reached_network()); + } + _ => { + assert_eq!(unspent, 1, "the notes are released"); + assert!(saved.is_empty(), "the record goes with them"); + assert!(journal.is_empty(), "the journal record is discharged"); + assert!(!started.may_have_reached_network()); + } + } + } + } + + /// A spend that failed before anything was broadcast, here a private document payment + /// whose anchor fetch the mock refuses, and is dropped while its rollback waits for the + /// store lock another task holds, still releases its notes: the guard owns them until the + /// rollback has cleared them. + #[tokio::test] + async fn should_release_the_notes_of_a_spend_dropped_during_its_failure_rollback() { + struct UnreachableProver; + impl OrchardProver for UnreachableProver { + fn proving_key(&self) -> &ProvingKey { + panic!("nothing is proved") + } + } + + let sdk = Arc::new( + dash_sdk::SdkBuilder::new_mock() + .with_version(PlatformVersion::latest()) + .build() + .expect("a mock SDK"), + ); + let wallet_id = [0x65; 32]; + let id = SubwalletId::new(wallet_id, 0); + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let note = ShieldedNote { + position: 0, + cmx: [1; 32], + nullifier: [0x5E; 32], + block_height: 1, + is_spent: false, + value: 1_000_000_000_000, + note_data: vec![], + }; + store.write().await.save_note(id, ¬e).expect("a note"); + let keys = OrchardKeySet::from_seed(&[0x42; 64], Network::Testnet, 0).expect("keys"); + let started = PaymentStarted::default(); + + // The spend waits for the store behind this task; this task's next acquisition waits + // behind the spend, so the lock passes to it right after the spend's reservation. + let held = store.write().await; + let mut spend = Box::pin(private_document_create_from_pool_with_metadata( + &sdk, + &store, + None, + wallet_id, + &keys, + 0, + Identifier::from([0x44; 32]), + "privateContactRequest", + vec![BinaryData::new(vec![1; 589])], + None, + &started, + &UnreachableProver, + )); + assert!(poll!(&mut spend).is_pending(), "waits to reserve"); + let mut again = Box::pin(store.write()); + assert!(poll!(&mut again).is_pending(), "queued behind the spend"); + drop(held); + // Reserved, refused by the anchor fetch, and waiting to roll back behind `again`. + assert!( + poll!(&mut spend).is_pending(), + "the rollback waits for the store" + ); + let Poll::Ready(contended) = poll!(&mut again) else { + panic!("the lock passes on after the reservation"); + }; + assert!( + contended.get_unspent_notes(id).expect("notes").is_empty(), + "reserved while the rollback waits" + ); + drop(spend); + drop(contended); + for _ in 0..100 { + if !store + .read() + .await + .get_unspent_notes(id) + .expect("notes") + .is_empty() + { + break; + } + tokio::task::yield_now().await; + } + assert_eq!( + store + .read() + .await + .get_unspent_notes(id) + .expect("notes") + .iter() + .map(|note| note.nullifier) + .collect::>(), + vec![note.nullifier], + "the note is spendable again" + ); + assert!(!started.is_marked()); + } + + /// A reservation dropped while the store is locked is released once the + /// lock frees, on a spawned task; one handed over stays. + #[tokio::test] + async fn should_release_a_dropped_reservation_once_the_store_frees() { + let sdk = Arc::new(dash_sdk::Sdk::new_mock()); + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let id = SubwalletId::new([0x64; 32], 0); + let note = ShieldedNote { + position: 0, + cmx: [1; 32], + nullifier: [0x5B; 32], + block_height: 1, + is_spent: false, + value: 1_000_000_000_000, + note_data: vec![], + }; + store.write().await.save_note(id, ¬e).expect("a note"); + let unspent = || async { + store + .read() + .await + .get_unspent_notes(id) + .expect("notes") + .len() + }; + + let (_, _, _, reservation) = + reserve_notes_covering(&sdk, &store, id, 1, 2, ShieldedFeeKind::Base) + .await + .expect("reserved"); + assert_eq!(unspent().await, 0); + let held = store.write().await; + drop(reservation); + drop(held); + for _ in 0..100 { + if unspent().await == 1 { + break; + } + tokio::task::yield_now().await; + } + assert_eq!(unspent().await, 1, "released once the lock freed"); + + let (_, _, _, mut kept) = + reserve_notes_covering(&sdk, &store, id, 1, 2, ShieldedFeeKind::Base) + .await + .expect("reserved"); + kept.hand_over(); + drop(kept); + assert_eq!(unspent().await, 0, "the spend owns it"); + } + + /// A spend dropped while it fetches the anchors, before its notes have an + /// owner that frees them, leaves them spendable again: here a private + /// document payment whose anchor fetch goes to a node that accepts the + /// connection and never answers. + #[tokio::test] + async fn should_release_the_notes_of_a_spend_dropped_during_its_anchor_fetch() { + struct NoKeys; + impl ContextProvider for NoKeys { + fn get_data_contract( + &self, + _id: &Identifier, + _platform_version: &PlatformVersion, + ) -> Result>, ContextProviderError> { + Ok(None) + } + fn get_token_configuration( + &self, + _token_id: &Identifier, + ) -> Result, ContextProviderError> { + Ok(None) + } + fn get_quorum_public_key( + &self, + _quorum_type: u32, + _quorum_hash: [u8; 32], + _core_chain_locked_height: u32, + ) -> Result<[u8; 48], ContextProviderError> { + Err(ContextProviderError::Generic("no quorum keys".to_string())) + } + fn get_platform_activation_height( + &self, + ) -> Result { + Ok(1) + } + } + struct UnreachableProver; + impl OrchardProver for UnreachableProver { + fn proving_key(&self) -> &ProvingKey { + panic!("nothing is proved") + } + } + + /// A loopback node that accepts connections and never answers. Dropped, + /// even while a failed assertion unwinds, it stops accepting, closes + /// what it accepted and joins its thread. + struct SilentNode { + address: std::net::SocketAddr, + shutdown: Arc, + thread: Option>, + } + impl SilentNode { + fn start() -> Self { + let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("a loopback port"); + listener.set_nonblocking(true).expect("non-blocking accept"); + let address = listener.local_addr().expect("its address"); + let shutdown = Arc::new(std::sync::atomic::AtomicBool::new(false)); + let stop = Arc::clone(&shutdown); + let thread = std::thread::spawn(move || { + let mut held = Vec::new(); + while !stop.load(std::sync::atomic::Ordering::Acquire) { + match listener.accept() { + Ok((stream, _)) => held.push(stream), + Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => { + std::thread::sleep(std::time::Duration::from_millis(5)); + } + Err(_) => break, + } + } + drop(held); + }); + Self { + address, + shutdown, + thread: Some(thread), + } + } + } + impl Drop for SilentNode { + fn drop(&mut self) { + self.shutdown + .store(true, std::sync::atomic::Ordering::Release); + if let Some(thread) = self.thread.take() { + let _ = thread.join(); + } + } + } + + let node = SilentNode::start(); + let address = node.address; + let sdk = Arc::new( + dash_sdk::SdkBuilder::new( + AddressList::from_str(&format!("http://{address}")).expect("an address"), + ) + .with_network(Network::Testnet) + .with_version(PlatformVersion::latest()) + .with_context_provider(NoKeys) + .build() + .expect("a network SDK"), + ); + + let wallet_id = [0x63; 32]; + let id = SubwalletId::new(wallet_id, 0); + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let note = ShieldedNote { + position: 0, + cmx: [1; 32], + nullifier: [0x5A; 32], + block_height: 1, + is_spent: false, + value: 1_000_000_000_000, + note_data: vec![], + }; + store.write().await.save_note(id, ¬e).expect("a note"); + let keys = OrchardKeySet::from_seed(&[0x42; 64], Network::Testnet, 0).expect("keys"); + let started = PaymentStarted::default(); + + let paid = tokio::time::timeout( + std::time::Duration::from_millis(500), + private_document_create_from_pool_with_metadata( + &sdk, + &store, + None, + wallet_id, + &keys, + 0, + Identifier::from([0x44; 32]), + "privateContactRequest", + vec![BinaryData::new(vec![1; 589])], + None, + &started, + &UnreachableProver, + ), + ) + .await; + assert!(paid.is_err(), "dropped during the anchor fetch: {paid:?}"); + assert!(!started.is_marked()); + let unspent = store.read().await.get_unspent_notes(id).expect("notes"); + assert_eq!( + unspent + .iter() + .map(|note| note.nullifier) + .collect::>(), + vec![note.nullifier], + "the note is spendable again" + ); + } + + /// A private payment is marked started only once its record is saved: + /// dropped while the save waits for the store, the spend has saved + /// nothing and is not marked, so its contact request's reservation is + /// released rather than kept for a payment that never left. Once the + /// lock frees, a save marks it. + #[tokio::test] + async fn should_mark_a_payment_started_only_once_its_record_is_saved() { + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let id = SubwalletId::new([0x62; 32], 0); + let transition = identity_shield_transition([0xBB; 32], 4); + let started = PaymentStarted::default(); + + let held = store.write().await; + let save = arm_redrive_before_broadcast( + &store, + id, + Some([0x78; 32]), + [7; 32], + vec![[2; 32]], + &transition, + "test spend", + None, + Some(&started), + 0, + ); + let mut save = Box::pin(save); + assert!( + (&mut save).now_or_never().is_none(), + "the save waits for the store" + ); + drop(save); + drop(held); + assert!(!started.is_marked(), "dropped before its record was saved"); + assert!(store + .read() + .await + .pending_redrives(id) + .expect("redrives") + .is_empty()); + + arm_redrive_before_broadcast( + &store, + id, + Some([0x78; 32]), + [7; 32], + vec![[2; 32]], + &transition, + "test spend", + None, + Some(&started), + 0, + ) + .await + .expect("saved"); + assert!(started.is_marked()); + assert_eq!( + store + .read() + .await + .pending_redrives(id) + .expect("redrives") + .len(), + 1 + ); + } + + /// A spend's record is saved before its broadcast, keyed by its + /// activity entry; one with no entry to key it by is refused, nothing + /// saved. + #[tokio::test] + async fn should_save_a_spends_record_before_its_broadcast() { + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let id = SubwalletId::new([0x61; 32], 0); + let transition = identity_shield_transition([0xBA; 32], 3); + + let refused = arm_redrive_before_broadcast( + &store, + id, + None, + [7; 32], + vec![[1; 32]], + &transition, + "test spend", + None, + None, + 0, + ) + .await; + assert!( + matches!(refused, Err(PlatformWalletError::ShieldedBuildError(_))), + "{refused:?}" + ); + assert!(store + .read() + .await + .pending_redrives(id) + .expect("redrives") + .is_empty()); + + arm_redrive_before_broadcast( + &store, + id, + Some([0x77; 32]), + [7; 32], + vec![[1; 32]], + &transition, + "test spend", + None, + None, + 0, + ) + .await + .expect("saved"); + let saved = store.read().await.pending_redrives(id).expect("redrives"); + assert_eq!(saved.len(), 1); + assert_eq!(saved[0].activity_id, [0x77; 32]); + assert_eq!(saved[0].nullifiers, vec![[1; 32]]); + } + + #[tokio::test] + async fn ordinary_redrive_pass_leaves_identity_guard_untouched() { + let sdk = Arc::new(dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk")); + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let wallet_id = [0x54; 32]; + let id = SubwalletId::new(wallet_id, 0); + let anchor = [0x76; 32]; + let activity_id = [0x98; 32]; + store + .write() + .await + .arm_redrive( + id, + PendingRedrive { + activity_id, + anchor, + nullifiers: vec![], + st_bytes: identity_shield_transition([0xBA; 32], 3) + .serialize_to_bytes() + .expect("serialize"), + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }, + ) + .expect("arm identity guard"); + let recorded = [anchor].into_iter().collect(); + + redrive_pending_spends(&sdk, &store, id, &recorded, &CancellationToken::new()).await; + + let retained = store.read().await.pending_redrives(id).expect("guard"); + assert_eq!(retained.len(), 1); + assert_eq!( + retained[0].attempts, 0, + "the anchor-gated spend pass must not consume identity retry state" + ); + } + + /// Decision paths that must NOT touch the network (the mock SDK has + /// no broadcast expectation, so any attempt would error into the + /// inconclusive arm and bump the counter): a pruned anchor belongs + /// to the release backstop, an exhausted budget stays parked, and a + /// corrupt stored transition is kept without a broadcast, as it may be + /// the only evidence of a payment that can still execute. + #[tokio::test] + async fn should_skip_pruned_exhausted_and_undecodable_redrives_keeping_each() { + let sdk = Arc::new(dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk")); + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let wallet_id = [5u8; 32]; + let id = SubwalletId::new(wallet_id, 0); + + let rec = |activity: u8, anchor: u8, attempts: u32| PendingRedrive { + activity_id: [activity; 32], + anchor: [anchor; 32], + nullifiers: vec![[activity ^ 0xFF; 32]], + st_bytes: vec![0xDE, 0xAD], // never deserializes + attempts, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }; + { + let mut guard = store.write().await; + // Pruned anchor (10 not in recorded set) → untouched. + guard.arm_redrive(id, rec(1, 10, 0)).unwrap(); + // Recorded anchor but attempts exhausted → untouched. + guard + .arm_redrive(id, rec(2, 11, MAX_REDRIVE_ATTEMPTS)) + .unwrap(); + // Recorded anchor, budget left, garbage bytes → kept, with no + // broadcast. + guard.arm_redrive(id, rec(3, 12, 0)).unwrap(); + } + let recorded: std::collections::HashSet<[u8; 32]> = + [[11u8; 32], [12u8; 32]].into_iter().collect(); + + redrive_pending_spends(&sdk, &store, id, &recorded, &CancellationToken::new()).await; + + let left = store.read().await.pending_redrives(id).unwrap(); + let ids: Vec<[u8; 32]> = left.iter().map(|r| r.activity_id).collect(); + assert!(ids.contains(&[1u8; 32]), "pruned-anchor record left alone"); + assert!(ids.contains(&[2u8; 32]), "exhausted record left alone"); + assert!( + ids.contains(&[3u8; 32]), + "corrupt record kept without a broadcast attempt" + ); + assert_eq!( + left.iter().map(|r| r.attempts).max(), + Some(MAX_REDRIVE_ATTEMPTS), + "no attempt counters were bumped — nothing touched the network" + ); + } + + /// A record retired while the redrive pass holds a snapshot that still + /// has it is not re-broadcast: the pass claims each re-broadcast under + /// the store write lock, from the record as it is then. Here the pass is + /// held at its claim of an earlier record while the retirement queues for + /// the lock, so it reaches the retired record with its stale snapshot. + #[tokio::test] + async fn should_not_rebroadcast_a_record_retired_after_the_pass_read_it() { + use dash_sdk::platform::transition::broadcast_request::BroadcastRequestForStateTransition; + use dpp::serialization::PlatformSerializable; + use std::future::Future; + use std::task::{Context, Waker}; + + let mut sdk = dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk"); + let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); + let id = SubwalletId::new([0x5D; 32], 0); + let anchor = [0x6D; 32]; + let earlier = identity_shield_transition([0xA1; 32], 3); + let retired = identity_shield_transition([0xA2; 32], 4); + let record = |activity: u8, transition: &StateTransition| PendingRedrive { + activity_id: [activity; 32], + anchor, + nullifiers: vec![[activity ^ 0xFF; 32]], + st_bytes: transition.serialize_to_bytes().expect("serializes"), + attempts: 0, + identity_nonce_finalized: false, + identity_user_abandoned: false, + anchor_height: None, + }; + { + let mut guard = store.write().await; + guard.arm_redrive(id, record(1, &earlier)).expect("armed"); + guard.arm_redrive(id, record(2, &retired)).expect("armed"); + } + let recorded: std::collections::HashSet<[u8; 32]> = [anchor].into_iter().collect(); + let sdk_handle = Arc::new(sdk.clone()); + let cancel = CancellationToken::new(); + + let mut cx = Context::from_waker(Waker::noop()); + let held = store.read().await; + let mut pass = Box::pin(redrive_pending_spends( + &sdk_handle, + &store, + id, + &recorded, + &cancel, + )); + assert!( + pass.as_mut().poll(&mut cx).is_pending(), + "the pass read both records and waits to claim the first" + ); + let mut retire = Box::pin(async { + store + .write() + .await + .retire_undelivered_spend(id, &[2; 32], &[]) + }); + assert!( + retire.as_mut().poll(&mut cx).is_pending(), + "the retirement queues behind the claim" + ); + drop(held); + let ((), retirement) = tokio::join!(pass, retire); + assert!( + retirement.expect("retired"), + "no re-broadcast was claimed for it" + ); + + let request = |transition: &StateTransition| { + transition + .broadcast_request_for_state_transition() + .expect("serializes") + }; + assert!( + sdk.mock().request_count(&request(&earlier)).await > 0, + "the earlier record is re-broadcast" + ); + assert_eq!( + sdk.mock().request_count(&request(&retired)).await, + 0, + "the retired record is not" + ); + let left = store.read().await.pending_redrives(id).expect("records"); + assert_eq!(left.len(), 1); + assert_eq!(left[0].activity_id, [1; 32]); + assert_eq!(left[0].attempts, 1, "claimed once, before its broadcast"); + } + + // ── Note-consuming spends: saved before the first dispatch ───────── + + /// The anchor the tests' spends are built on, and the proved height of + /// the anchor set it was read from. + const SPEND_ANCHOR: [u8; 32] = [0x6E; 32]; + const SPEND_ANCHOR_HEIGHT: u64 = 5; + + /// The identity the tests' identity create derives. + const CREATED_IDENTITY: [u8; 32] = [0x33; 32]; + + fn spend_action() -> SerializedAction { + SerializedAction { + nullifier: [1; 32], + rk: [2; 32], + cmx: [3; 32], + encrypted_note: vec![4; 216], + cv_net: [5; 32], + spend_auth_sig: [6; 64], + } + } + + /// The note the tests' spends consume. + fn spend_note() -> ShieldedNote { + ShieldedNote { + position: 0, + cmx: [1; 32], + nullifier: [0x5C; 32], + block_height: 1, + is_spent: false, + value: 1_000_000_000_000, + note_data: vec![], + } + } + + /// The note-consuming spends, by the code that saves, broadcasts and + /// waits for them. + #[derive(Clone, Copy, Debug)] + enum SpendPath { + /// Transfer, unshield, withdrawal and identity top-up + /// ([`broadcast_shielded_spend_with_redrive_with_metadata`]): here a + /// transfer. + Shared, + /// Identity create ([`broadcast_identity_create_with_redrive`]). + IdentityCreate, + } + + impl SpendPath { + /// A signed transition of the path, as it saves and broadcasts one. + fn transition(self) -> StateTransition { + match self { + Self::Shared => ShieldedTransferTransitionV0 { + actions: vec![spend_action(), spend_action()], + value_balance: 1_000, + anchor: SPEND_ANCHOR, + proof: vec![8; 64], + binding_signature: [9; 64], + } + .into(), + Self::IdentityCreate => IdentityCreateFromShieldedPoolTransitionV0 { + public_keys: vec![], + denomination: 1_000_000, + actions: vec![spend_action(), spend_action()], + anchor: SPEND_ANCHOR, + proof: vec![8; 64], + binding_signature: [9; 64], + send_to_address_on_creation_failure: PlatformAddress::P2pkh([7; 20]), + identity_id: Identifier::from(CREATED_IDENTITY), + } + .into(), + } + } + + /// Save, broadcast and wait for the path's transition on `sdk`, as + /// its production flow does once the transition is built. + async fn broadcast( + self, + sdk: &Arc, + spend: &mut ReservedSpend, + id: SubwalletId, + ) -> Result<(), SpendFailure> { + let transition = self.transition(); + match self { + Self::Shared => broadcast_shielded_spend_with_redrive_with_metadata( + sdk, + &spend.store, + id, + &spend.entry, + SPEND_ANCHOR, + SPEND_ANCHOR_HEIGHT, + &spend.notes, + &mut spend.reservation, + &transition, + "transfer", + SpendResultWait::ExecutionProved, + ) + .await + .map(|_| ()), + Self::IdentityCreate => broadcast_identity_create_with_redrive( + sdk, + &spend.store, + id, + &spend.entry, + SPEND_ANCHOR, + SPEND_ANCHOR_HEIGHT, + &spend.notes, + &mut spend.reservation, + &transition, + Identifier::from(CREATED_IDENTITY), + BTreeMap::new(), + ) + .await + .map(|_| ()), + } + } + + /// Settle the path's failed spend, as its production flow does, and + /// return the error it reports. + async fn settle( + self, + spend: ReservedSpend, + wallet_id: WalletId, + id: SubwalletId, + failure: SpendFailure, + ) -> PlatformWalletError { + let ReservedSpend { + store, + reservation, + entry, + .. + } = spend; + match self { + Self::Shared => { + settle_failed_spend( + &store, + None, + wallet_id, + id, + &entry, + reservation, + "transfer", + failure, + ) + .await + } + Self::IdentityCreate => identity_create_failure( + settle_failed_spend( + &store, + None, + wallet_id, + id, + &entry, + reservation, + IDENTITY_CREATE_OPERATION, + failure, + ) + .await, + Some(Identifier::from(CREATED_IDENTITY)), + ), + } + } + + /// Whether `error` is the path's report of a spend whose outcome is + /// not known. + fn reads_unconfirmed(self, error: &PlatformWalletError) -> bool { + match self { + Self::Shared => matches!( + error, + PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "transfer", + .. + } + ), + Self::IdentityCreate => matches!( + error, + PlatformWalletError::ShieldedBroadcastUnconfirmed { identity_id, .. } + if *identity_id == Identifier::from(CREATED_IDENTITY) + ), + } + } + } + + /// A spend right before it saves its record: its note reserved in a + /// file-backed store, and its pending activity entry recorded. + struct ReservedSpend { + store: Arc>, + notes: Vec, + reservation: NoteReservation, + entry: Option, + } + + impl ReservedSpend { + async fn at(path: &std::path::Path, id: SubwalletId, activity_id: [u8; 32]) -> Self { + let sdk = Arc::new(dash_sdk::Sdk::new_mock()); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(path, 100).expect("the store"), + )); + store + .write() + .await + .save_note(id, &spend_note()) + .expect("a note"); + let (notes, _, _, reservation) = + reserve_notes_covering(&sdk, &store, id, 1, 2, ShieldedFeeKind::Base) + .await + .expect("reserved"); + let entry = pending_entry(activity_id); + store + .write() + .await + .save_activity(id, &entry) + .expect("the pending row"); + Self { + store, + notes, + reservation, + entry: Some(entry), + } + } + } + + /// Make the store at `path` refuse to save a spend's record. + fn refuse_record_saves(path: &std::path::Path) { + rusqlite::Connection::open(path) + .expect("the store's file") + .execute_batch( + "CREATE TRIGGER reject_redrive_insert BEFORE INSERT ON \ + shielded_pending_spends BEGIN SELECT RAISE(FAIL, 'injected'); END;", + ) + .expect("the trigger"); + } + + /// The store at `path` as a restart opens it, the wallet's note loaded + /// into it again. + fn restarted_store(path: &std::path::Path, id: SubwalletId) -> FileBackedShieldedStore { + let mut store = FileBackedShieldedStore::open_path(path, 100).expect("reopened"); + store + .save_note(id, &spend_note()) + .expect("the note, loaded again"); + store + } + + /// How many notes of `id` a spend can select, and the status of the + /// activity row `activity_id`. + async fn spendable_and_status( + store: &Arc>, + id: SubwalletId, + activity_id: &[u8; 32], + ) -> (usize, ShieldedActivityStatus) { + let store = store.read().await; + ( + store.get_unspent_notes(id).expect("notes").len(), + store + .get_activity_by_entry_id(id, activity_id) + .expect("the row reads") + .expect("the row") + .status, + ) + } + + /// A note-consuming spend saves its record durably before its first + /// dispatch, and hands its notes over only then. So a process that exits + /// between the broadcast and the result (here the spend is dropped while + /// its result wait is pending, and nothing settles it) leaves the record: + /// the store a restart opens holds the notes' reservation and the exact + /// signed transition, the redrive pass re-broadcasts it, and the scan + /// that sees its nullifier spent resolves it. + #[tokio::test] + async fn should_restore_a_spend_that_exited_between_its_broadcast_and_its_result() { + use dash_sdk::platform::transition::broadcast_request::BroadcastRequestForStateTransition; + use std::task::{Context, Waker}; + + let mut sdk = dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk"); + let sdk_handle = Arc::new(sdk.clone()); + let id = SubwalletId::new([0x71; 32], 0); + let activity_id = [0x7A; 32]; + let dir = tempfile::tempdir().expect("a directory"); + let path = dir.path().join("tree.sqlite"); + let ReservedSpend { + store, + notes, + mut reservation, + entry, + } = ReservedSpend::at(&path, id, activity_id).await; + let transition = SpendPath::Shared.transition(); + let signed = transition.serialize_to_bytes().expect("serializes"); + + let mut cx = Context::from_waker(Waker::noop()); + let mut spend = Box::pin(save_spend_then_broadcast( + &store, + id, + &entry, + SPEND_ANCHOR, + SPEND_ANCHOR_HEIGHT, + ¬es, + &mut reservation, + &transition, + "transfer", + || { + // Nothing is dispatched before the record is on the file. + let durable = + FileBackedShieldedStore::open_path(&path, 100).expect("a second handle"); + let saved = durable.pending_redrives(id).expect("the records"); + assert_eq!(saved.len(), 1, "saved before the first dispatch"); + assert_eq!(saved[0].st_bytes, signed); + // Dispatched; its result never comes. + std::future::pending::>() + }, + )); + assert!( + spend.as_mut().poll(&mut cx).is_pending(), + "broadcast, waiting for its result" + ); + // The process exits here: the spend never returns, nothing settles it. + drop(spend); + drop(reservation); + assert!( + store + .read() + .await + .get_unspent_notes(id) + .expect("notes") + .is_empty(), + "the dropped spend's notes stay reserved" + ); + drop(store); + + let restarted = Arc::new(RwLock::new(restarted_store(&path, id))); + { + let store = restarted.read().await; + assert!( + store.get_unspent_notes(id).expect("notes").is_empty(), + "the reservation is restored from the record" + ); + let saved = store.pending_redrives(id).expect("the records"); + assert_eq!(saved.len(), 1); + assert_eq!(saved[0].st_bytes, signed, "the exact signed transition"); + assert_eq!(saved[0].nullifiers, vec![spend_note().nullifier]); + assert_eq!(saved[0].anchor, SPEND_ANCHOR); + assert_eq!(saved[0].anchor_height, Some(SPEND_ANCHOR_HEIGHT)); + assert_eq!(saved[0].attempts, 0); + } + + let recorded = [SPEND_ANCHOR].into_iter().collect(); + redrive_pending_spends( + &sdk_handle, + &restarted, + id, + &recorded, + &CancellationToken::new(), + ) + .await; + let request = transition + .broadcast_request_for_state_transition() + .expect("serializes"); + assert!( + sdk.mock().request_count(&request).await > 0, + "the redrive pass re-broadcasts the saved transition" + ); + assert_eq!( + restarted + .read() + .await + .pending_redrives(id) + .expect("records")[0] + .attempts, + 1 + ); + + // The next scan sees the spend's nullifier on chain. + assert!(restarted + .write() + .await + .mark_spent(id, &spend_note().nullifier) + .expect("marked")); + drop(restarted); + assert!( + FileBackedShieldedStore::open_path(&path, 100) + .expect("reopened") + .pending_redrives(id) + .expect("records") + .is_empty(), + "resolved for good" + ); + } + + /// A failed spend is settled by what is known about its transition. One + /// that never left the wallet has its record retired and its notes + /// released together, unless a redrive pass claimed a re-broadcast of the + /// record meanwhile: it may then leave the wallet after all, and is kept + /// as unconfirmed. One whose record was saved and that may have reached a + /// node keeps its notes and its record whatever error ended it, and reads + /// as unconfirmed. One whose record could not be saved was never + /// dispatched, and releases its notes. + #[tokio::test] + async fn should_release_a_failed_spend_s_notes_only_when_its_transition_cannot_execute() { + use std::sync::atomic::{AtomicBool, Ordering}; + + let wallet_id = [0x72; 32]; + let id = SubwalletId::new(wallet_id, 0); + let activity_id = [0x7B; 32]; + let transition = SpendPath::Shared.transition(); + let never_delivered = || SpendFailure { + error: PlatformWalletError::ShieldedBroadcastFailed("no address".to_string()), + never_delivered: true, + }; + for outcome in [ + "never delivered", + "never delivered, re-broadcast claimed", + "unconfirmed", + "failed after its record was saved", + "its record could not be saved", + ] { + let dir = tempfile::tempdir().expect("a directory"); + let path = dir.path().join("tree.sqlite"); + let mut spend = ReservedSpend::at(&path, id, activity_id).await; + if outcome == "its record could not be saved" { + refuse_record_saves(&path); + } + let dispatched = AtomicBool::new(false); + let store = Arc::clone(&spend.store); + let result: Result<(), SpendFailure> = save_spend_then_broadcast( + &spend.store, + id, + &spend.entry, + SPEND_ANCHOR, + SPEND_ANCHOR_HEIGHT, + &spend.notes, + &mut spend.reservation, + &transition, + "transfer", + || async { + dispatched.store(true, Ordering::SeqCst); + Err(match outcome { + "never delivered" => never_delivered(), + "never delivered, re-broadcast claimed" => { + // A redrive pass re-broadcast the saved record + // while the spend's own broadcast ran. + store + .write() + .await + .bump_redrive_attempts(id, &activity_id) + .expect("claimed"); + never_delivered() + } + "unconfirmed" => PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "transfer", + reason: "the result wait timed out".to_string(), + } + .into(), + _ => PlatformWalletError::ShieldedBuildError( + "its proved result did not read".to_string(), + ) + .into(), + }) + }, + ) + .await; + let failure = result.expect_err("the spend failed"); + let store = Arc::clone(&spend.store); + let settled = SpendPath::Shared + .settle(spend, wallet_id, id, failure) + .await; + let (spendable, status) = spendable_and_status(&store, id, &activity_id).await; + drop(store); + let saved = FileBackedShieldedStore::open_path(&path, 100) + .expect("reopened") + .pending_redrives(id) + .expect("records"); + match outcome { + "never delivered" => { + assert!( + matches!(settled, PlatformWalletError::ShieldedBroadcastFailed(_)), + "{outcome}: {settled:?}" + ); + assert_eq!(spendable, 1, "{outcome}: the notes are released"); + assert!(saved.is_empty(), "{outcome}: the record is retired"); + assert_eq!(status, ShieldedActivityStatus::Failed, "{outcome}"); + } + "its record could not be saved" => { + assert!( + matches!(settled, PlatformWalletError::ShieldedStoreError(_)), + "{outcome}: {settled:?}" + ); + assert!(!dispatched.load(Ordering::SeqCst), "never dispatched"); + assert_eq!(spendable, 1, "{outcome}: the notes are released"); + assert!(saved.is_empty(), "{outcome}"); + assert_eq!(status, ShieldedActivityStatus::Failed, "{outcome}"); + } + _ => { + assert!( + SpendPath::Shared.reads_unconfirmed(&settled), + "{outcome}: {settled:?}" + ); + assert_eq!(spendable, 0, "{outcome}: the notes stay reserved"); + assert_eq!(saved.len(), 1, "{outcome}: the record stays"); + assert_eq!(status, ShieldedActivityStatus::Pending, "{outcome}"); + } + } + } + } + + /// Each note-consuming spend path, on an SDK whose node answers every + /// request with an error: a dispatch may have reached the node, so the + /// spend is unconfirmed, never failed. Its notes stay reserved and its + /// record stays, across a restart too, where the redrive pass + /// re-broadcasts the exact signed transition and the scan that sees its + /// nullifier spent resolves it. + #[tokio::test(start_paused = true)] + async fn should_keep_a_spend_that_may_have_reached_a_node_until_it_resolves() { + use dash_sdk::platform::transition::broadcast_request::BroadcastRequestForStateTransition; + + let wallet_id = [0x73; 32]; + let id = SubwalletId::new(wallet_id, 0); + let activity_id = [0x7C; 32]; + for spend_path in [SpendPath::Shared, SpendPath::IdentityCreate] { + let mut sdk = dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk"); + let sdk_handle = Arc::new(sdk.clone()); + let dir = tempfile::tempdir().expect("a directory"); + let path = dir.path().join("tree.sqlite"); + let mut spend = ReservedSpend::at(&path, id, activity_id).await; + let transition = spend_path.transition(); + let request = transition + .broadcast_request_for_state_transition() + .expect("serializes"); + + let failure = spend_path + .broadcast(&sdk_handle, &mut spend, id) + .await + .expect_err("its result is not proved"); + assert!(!failure.never_delivered, "{spend_path:?}"); + let dispatches = sdk.mock().request_count(&request).await; + assert!(dispatches > 0, "{spend_path:?}: it was dispatched"); + let store = Arc::clone(&spend.store); + let settled = spend_path.settle(spend, wallet_id, id, failure).await; + assert!( + spend_path.reads_unconfirmed(&settled), + "{spend_path:?}: {settled:?}" + ); + assert_eq!( + spendable_and_status(&store, id, &activity_id).await, + (0, ShieldedActivityStatus::Pending), + "{spend_path:?}: the notes stay reserved, the row pending" + ); + drop(store); + + let restarted = Arc::new(RwLock::new(restarted_store(&path, id))); + { + let store = restarted.read().await; + assert!( + store.get_unspent_notes(id).expect("notes").is_empty(), + "{spend_path:?}: the reservation is restored from the record" + ); + let saved = store.pending_redrives(id).expect("the records"); + assert_eq!(saved.len(), 1, "{spend_path:?}"); + assert_eq!( + saved[0].st_bytes, + transition.serialize_to_bytes().expect("serializes"), + "{spend_path:?}: the exact signed transition" + ); + } + let recorded = [SPEND_ANCHOR].into_iter().collect(); + redrive_pending_spends( + &sdk_handle, + &restarted, + id, + &recorded, + &CancellationToken::new(), + ) + .await; + assert!( + sdk.mock().request_count(&request).await > dispatches, + "{spend_path:?}: the redrive pass re-broadcasts it" + ); + assert!(restarted + .write() + .await + .mark_spent(id, &spend_note().nullifier) + .expect("marked")); + assert!( + restarted + .read() + .await + .pending_redrives(id) + .expect("records") + .is_empty(), + "{spend_path:?}: resolved once its nullifier is seen spent" + ); + } + } + + /// Each note-consuming spend path, on an SDK with no address to send to: + /// the transition never left the wallet. Its record was saved before the + /// dispatch that was refused; the settlement retires it and frees the + /// notes, and the spend reads as failed. + #[tokio::test] + async fn should_retire_the_record_of_a_spend_that_never_left_the_wallet() { + let wallet_id = [0x74; 32]; + let id = SubwalletId::new(wallet_id, 0); + let activity_id = [0x7D; 32]; + for spend_path in [SpendPath::Shared, SpendPath::IdentityCreate] { + let sdk = Arc::new(sdk_without_addresses()); + let dir = tempfile::tempdir().expect("a directory"); + let path = dir.path().join("tree.sqlite"); + let mut spend = ReservedSpend::at(&path, id, activity_id).await; + + let failure = spend_path + .broadcast(&sdk, &mut spend, id) + .await + .expect_err("nothing to send it to"); + assert!( + failure.never_delivered, + "{spend_path:?}: {:?}", + failure.error + ); + let store = Arc::clone(&spend.store); + assert_eq!( + store + .read() + .await + .pending_redrives(id) + .expect("records") + .len(), + 1, + "{spend_path:?}: its record was saved before its dispatch" + ); + let settled = spend_path.settle(spend, wallet_id, id, failure).await; + assert!( + matches!(settled, PlatformWalletError::ShieldedBroadcastFailed(_)), + "{spend_path:?}: {settled:?}" + ); + assert_eq!( + spendable_and_status(&store, id, &activity_id).await, + (1, ShieldedActivityStatus::Failed), + "{spend_path:?}: the notes are free, the row failed" + ); + drop(store); + assert!( + FileBackedShieldedStore::open_path(&path, 100) + .expect("reopened") + .pending_redrives(id) + .expect("records") + .is_empty(), + "{spend_path:?}: no record is left" + ); + } + } + + /// Each note-consuming spend path whose record cannot be saved dispatches + /// nothing: the spend is refused, and its notes are released. + #[tokio::test] + async fn should_not_dispatch_a_spend_whose_record_cannot_be_saved() { + use dash_sdk::platform::transition::broadcast_request::BroadcastRequestForStateTransition; + + let wallet_id = [0x75; 32]; + let id = SubwalletId::new(wallet_id, 0); + let activity_id = [0x7E; 32]; + for spend_path in [SpendPath::Shared, SpendPath::IdentityCreate] { + let mut sdk = dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk"); + let sdk_handle = Arc::new(sdk.clone()); + let dir = tempfile::tempdir().expect("a directory"); + let path = dir.path().join("tree.sqlite"); + let mut spend = ReservedSpend::at(&path, id, activity_id).await; + refuse_record_saves(&path); + + let failure = spend_path + .broadcast(&sdk_handle, &mut spend, id) + .await + .expect_err("its record is not saved"); + assert!( + matches!(failure.error, PlatformWalletError::ShieldedStoreError(_)), + "{spend_path:?}: {:?}", + failure.error + ); + let request = spend_path + .transition() + .broadcast_request_for_state_transition() + .expect("serializes"); + assert_eq!( + sdk.mock().request_count(&request).await, + 0, + "{spend_path:?}: nothing was dispatched" + ); + let store = Arc::clone(&spend.store); + let settled = spend_path.settle(spend, wallet_id, id, failure).await; + assert!( + matches!(settled, PlatformWalletError::ShieldedStoreError(_)), + "{spend_path:?}: {settled:?}" + ); + assert_eq!( + spendable_and_status(&store, id, &activity_id).await, + (1, ShieldedActivityStatus::Failed), + "{spend_path:?}: the notes are free, the row failed" + ); + } + } + + // ── Shields from Platform addresses ──────────────────────────────── + + /// A signed shield from a Platform address (type 15). + fn shield_transition() -> StateTransition { + ShieldTransitionV0 { + inputs: BTreeMap::from([(SHIELD_INPUT, (SHIELD_NONCE, 2_000_000))]), + actions: vec![spend_action(), spend_action()], + amount: 1_000_000, + anchor: SPEND_ANCHOR, + proof: vec![8; 64], + binding_signature: [9; 64], + fee_strategy: vec![AddressFundsFeeStrategyStep::DeductFromInput(0)], + user_fee_increase: 0, + input_witnesses: vec![], + } + .into() + } + + /// A node's refusal of a dispatch, as an offline or overloaded endpoint + /// answers one. + fn unavailable() -> dash_sdk::Error { + use dash_sdk::dapi_client::transport::TransportError; + use dash_sdk::dapi_client::DapiClientError; + use dash_sdk::dapi_grpc::tonic::{Code, Status}; + + dash_sdk::Error::DapiClientError(DapiClientError::Transport(TransportError::Grpc( + Status::new(Code::Unavailable, "test"), + ))) + } + + /// A stale-nonce verdict on the shield's input, as a broadcast or as the + /// result wait returns one. + fn nonce_verdict(on_the_wait: bool) -> dash_sdk::Error { + use dpp::consensus::state::address_funds::AddressInvalidNonceError; + + let verdict = ConsensusError::StateError(StateError::AddressInvalidNonceError( + AddressInvalidNonceError::new(PlatformAddress::P2pkh([7; 20]), 1, 2), + )); + if on_the_wait { dash_sdk::Error::StateTransitionBroadcastError(StateTransitionBroadcastError { code: 1, - message: "state error".to_string(), - cause: Some(other_rejection), - }); - assert_eq!( - classify_redrive_broadcast(&Err(rejection_err)), - RedriveBroadcastOutcome::DefinitiveRejection - ); + message: "rejected".to_string(), + cause: Some(verdict), + }) + } else { + dash_sdk::Error::Protocol(dpp::ProtocolError::ConsensusError(Box::new(verdict))) + } + } - let timeout = dash_sdk::Error::TimeoutReached( - std::time::Duration::from_secs(1), - "waiting".to_string(), - ); - assert_eq!( - classify_redrive_broadcast(&Err(timeout)), - RedriveBroadcastOutcome::Inconclusive - ); + fn wait_timeout() -> dash_sdk::Error { + dash_sdk::Error::TimeoutReached(std::time::Duration::from_secs(80), "waiting".to_string()) } - #[tokio::test] - async fn identity_redrive_ignores_spend_anchor_and_attempt_limit() { - let sdk = Arc::new(dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk")); + /// The input address of [`shield_transition`] and the nonce it signed. + const SHIELD_INPUT: PlatformAddress = PlatformAddress::P2pkh([7; 20]); + const SHIELD_NONCE: AddressNonce = 1; + + /// What [`shield_transition`] signed: its input addresses and nonces. + fn shield_inputs() -> BTreeMap { + shield_transition() + .inputs() + .expect("a shield spends from addresses") + .clone() + } + + /// A verified result reading the shield's input address at `nonce`, or + /// with no state when `None`. + fn input_snapshot(nonce: Option) -> StateTransitionProofResult { + StateTransitionProofResult::VerifiedAddressInfos(BTreeMap::from([( + SHIELD_INPUT, + nonce.map(|nonce| (nonce, 1_000_000)), + )])) + } + + /// An in-memory store holding the pending activity row `activity_id` of a + /// shield of `id`, and the row's entry. + async fn recorded_shield( + id: SubwalletId, + activity_id: [u8; 32], + ) -> ( + Arc>, + Option, + ) { let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); - let wallet_id = [0x45; 32]; - let previous_account = SubwalletId::new(wallet_id, 7); - let activity_id = [0x67; 32]; - let transition = identity_shield_transition([0x89; 32], 11); + let entry = pending_entry(activity_id); store .write() .await - .arm_redrive( - previous_account, - PendingRedrive { - activity_id, - anchor: [0xAB; 32], - nullifiers: vec![], - st_bytes: transition.serialize_to_bytes().expect("serialize"), - attempts: MAX_REDRIVE_ATTEMPTS, - identity_nonce_finalized: false, - identity_user_abandoned: false, - }, - ) - .expect("arm identity guard"); - - redrive_pending_identity_shields(&sdk, &store, wallet_id, &CancellationToken::new()).await; + .save_activity(id, &entry) + .expect("the pending row"); + (store, Some(entry)) + } - let retained = store + async fn shield_status( + store: &Arc>, + id: SubwalletId, + activity_id: &[u8; 32], + ) -> ShieldedActivityStatus { + store .read() .await - .pending_redrives(previous_account) - .expect("retained redrive"); - assert_eq!( - retained.len(), - 1, - "an endpoint error cannot clear the guard" + .get_activity_by_entry_id(id, activity_id) + .expect("the row reads") + .expect("the row") + .status + } + + /// Once a dispatch may have reached a node, a shield whose result is not + /// proved is unconfirmed and its row stays pending, never failed: a node's + /// refusal of the broadcast and a consensus verdict on either call + /// included (here a stale nonce, which used to read as a retryable nonce + /// mismatch), as no proof backs an endpoint's answer and a retry signs a + /// second shield. The reason keeps what the broadcast was answered with. + #[tokio::test] + async fn should_report_a_shield_unconfirmed_once_a_dispatch_may_have_reached_a_node() { + let wallet_id = [0x76; 32]; + let id = SubwalletId::new(wallet_id, 0); + let activity_id = [0x7F; 32]; + let cases = [ + ( + "a node refused the broadcast, the wait timed out", + BroadcastDelivery::MaybeDelivered(unavailable()), + wait_timeout(), + ), + ( + "the broadcast was answered with a consensus verdict", + BroadcastDelivery::MaybeDelivered(nonce_verdict(false)), + wait_timeout(), + ), + ( + "admitted, the wait was answered with a consensus verdict", + BroadcastDelivery::Admitted, + nonce_verdict(true), + ), + ( + "admitted, the wait timed out", + BroadcastDelivery::Admitted, + wait_timeout(), + ), + ]; + for (case, delivery, wait_error) in cases { + let (store, entry) = recorded_shield(id, activity_id).await; + let broadcast_answer = match &delivery { + BroadcastDelivery::MaybeDelivered(e) => Some(e.to_string()), + _ => None, + }; + let settled = settle_shield( + &store, + None, + wallet_id, + id, + &entry, + &shield_inputs(), + delivery, + |e: &dash_sdk::Error| e.to_string(), + || std::future::ready(Err(wait_error)), + ) + .await; + let Err(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "shield", + reason, + }) = settled + else { + panic!("{case}: {settled:?}"); + }; + if let Some(answer) = broadcast_answer { + assert!(reason.contains(&answer), "{case}: {reason}"); + } + assert_eq!( + shield_status(&store, id, &activity_id).await, + ShieldedActivityStatus::Pending, + "{case}" + ); + } + } + + /// Only a shield whose transition never left the wallet is failed, its + /// row with it, and nothing waits for its result. + #[tokio::test] + async fn should_report_a_shield_failed_only_when_nothing_was_sent() { + use dash_sdk::dapi_client::DapiClientError; + use std::cell::Cell; + + let wallet_id = [0x77; 32]; + let id = SubwalletId::new(wallet_id, 0); + let activity_id = [0x80; 32]; + let (store, entry) = recorded_shield(id, activity_id).await; + let waited = Cell::new(false); + let settled = settle_shield( + &store, + None, + wallet_id, + id, + &entry, + &shield_inputs(), + BroadcastDelivery::NeverDelivered(dash_sdk::Error::DapiClientError( + DapiClientError::NoAvailableAddresses, + )), + |e: &dash_sdk::Error| e.to_string(), + || { + waited.set(true); + std::future::ready(Err(wait_timeout())) + }, + ) + .await; + assert!( + matches!( + settled, + Err(PlatformWalletError::ShieldedBroadcastFailed(_)) + ), + "{settled:?}" ); + assert!(!waited.get(), "nothing was sent, so nothing is waited for"); assert_eq!( - retained[0].attempts, - MAX_REDRIVE_ATTEMPTS + 1, - "identity retries stay live beyond the note-spend attempt budget" + shield_status(&store, id, &activity_id).await, + ShieldedActivityStatus::Failed ); } + /// A shield succeeds once its verified result reads every input address + /// at or past the nonce it signed, whatever its broadcast was answered + /// with. Its row stays pending: the result proves the input addresses, + /// not this shield or its note, which the scan confirms. #[tokio::test] - async fn ordinary_redrive_pass_leaves_identity_guard_untouched() { - let sdk = Arc::new(dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk")); - let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); - let wallet_id = [0x54; 32]; + async fn should_accept_a_shield_whose_inputs_read_spent_and_leave_its_row_to_the_scan() { + let wallet_id = [0x78; 32]; let id = SubwalletId::new(wallet_id, 0); - let anchor = [0x76; 32]; - let activity_id = [0x98; 32]; - store - .write() + let activity_id = [0x81; 32]; + for (delivery, proved_nonce) in [ + (BroadcastDelivery::Admitted, SHIELD_NONCE), + (BroadcastDelivery::Admitted, SHIELD_NONCE + 1), + ( + BroadcastDelivery::MaybeDelivered(unavailable()), + SHIELD_NONCE, + ), + ( + BroadcastDelivery::MaybeDelivered(nonce_verdict(false)), + SHIELD_NONCE, + ), + ] { + let (store, entry) = recorded_shield(id, activity_id).await; + settle_shield( + &store, + None, + wallet_id, + id, + &entry, + &shield_inputs(), + delivery, + |e: &dash_sdk::Error| e.to_string(), + || std::future::ready(Ok(input_snapshot(Some(proved_nonce)))), + ) .await - .arm_redrive( + .expect("its inputs read spent"); + assert_eq!( + shield_status(&store, id, &activity_id).await, + ShieldedActivityStatus::Pending, + "nonce {proved_nonce}" + ); + } + } + + /// A verified result that does not read the shield's inputs spent shows + /// the shield had not executed at its block, whatever the endpoint that + /// returned it claims: a result of another kind, one that leaves an input + /// out or proves no state for it, and an input still below the nonce the + /// shield signed leave it unconfirmed, its row pending. + #[tokio::test] + async fn should_report_a_shield_unconfirmed_when_its_result_does_not_read_its_inputs_spent() { + let wallet_id = [0x7A; 32]; + let id = SubwalletId::new(wallet_id, 0); + let activity_id = [0x83; 32]; + let cases = [ + ( + "a result of another kind", + StateTransitionProofResult::VerifiedTokenBalanceAbsence(Identifier::from([1; 32])), + ), + ( + "an input left out", + StateTransitionProofResult::VerifiedAddressInfos(BTreeMap::from([( + PlatformAddress::P2pkh([8; 20]), + Some((SHIELD_NONCE, 1_000_000)), + )])), + ), + ("an input with no state", input_snapshot(None)), + ( + "an input below its signed nonce", + input_snapshot(Some(SHIELD_NONCE - 1)), + ), + ]; + for (case, snapshot) in cases { + let (store, entry) = recorded_shield(id, activity_id).await; + let settled = settle_shield( + &store, + None, + wallet_id, id, - PendingRedrive { - activity_id, - anchor, - nullifiers: vec![], - st_bytes: identity_shield_transition([0xBA; 32], 3) - .serialize_to_bytes() - .expect("serialize"), - attempts: 0, - identity_nonce_finalized: false, - identity_user_abandoned: false, - }, + &entry, + &shield_inputs(), + BroadcastDelivery::Admitted, + |e: &dash_sdk::Error| e.to_string(), + || std::future::ready(Ok(snapshot)), ) - .expect("arm identity guard"); - let recorded = [anchor].into_iter().collect(); + .await; + assert!( + matches!( + settled, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "shield", + .. + }) + ), + "{case}: {settled:?}" + ); + assert_eq!( + shield_status(&store, id, &activity_id).await, + ShieldedActivityStatus::Pending, + "{case}" + ); + } - redrive_pending_spends( - &sdk, + // A transition that names no input shows nothing spent. + let (store, entry) = recorded_shield(id, activity_id).await; + let settled = settle_shield( &store, None, wallet_id, id, - &recorded, - &CancellationToken::new(), + &entry, + &BTreeMap::new(), + BroadcastDelivery::Admitted, + |e: &dash_sdk::Error| e.to_string(), + || std::future::ready(Ok(input_snapshot(Some(SHIELD_NONCE)))), ) .await; - - let retained = store.read().await.pending_redrives(id).expect("guard"); - assert_eq!(retained.len(), 1); - assert_eq!( - retained[0].attempts, 0, - "the anchor-gated spend pass must not consume identity retry state" + assert!( + matches!( + settled, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { .. }) + ), + "no input: {settled:?}" ); } - /// Decision paths that must NOT touch the network (the mock SDK has - /// no broadcast expectation, so any attempt would error into the - /// inconclusive arm and bump the counter): a pruned anchor belongs - /// to the release backstop, an exhausted budget stays parked, and a - /// corrupt stored transition is dropped so it can't wedge the pass. + /// The broadcast of a signed shield through a network SDK: a node that + /// refuses the connection leaves it unconfirmed and its row pending, as a + /// transport failure cannot show that nothing was sent, and an SDK with + /// no address to send to leaves it failed. #[tokio::test] - async fn redrive_skips_pruned_and_exhausted_and_drops_garbage() { - let sdk = Arc::new(dash_sdk::SdkBuilder::new_mock().build().expect("mock sdk")); - let store = Arc::new(RwLock::new(InMemoryShieldedStore::new())); - let wallet_id = [5u8; 32]; + async fn should_report_a_shield_unconfirmed_when_its_node_refuses_the_connection() { + let wallet_id = [0x79; 32]; let id = SubwalletId::new(wallet_id, 0); + let activity_id = [0x82; 32]; + let transition = shield_transition(); - let rec = |activity: u8, anchor: u8, attempts: u32| PendingRedrive { - activity_id: [activity; 32], - anchor: [anchor; 32], - nullifiers: vec![[activity ^ 0xFF; 32]], - st_bytes: vec![0xDE, 0xAD], // never deserializes - attempts, - identity_nonce_finalized: false, - identity_user_abandoned: false, - }; - { - let mut guard = store.write().await; - // Pruned anchor (10 not in recorded set) → untouched. - guard.arm_redrive(id, rec(1, 10, 0)).unwrap(); - // Recorded anchor but attempts exhausted → untouched. - guard - .arm_redrive(id, rec(2, 11, MAX_REDRIVE_ATTEMPTS)) - .unwrap(); - // Recorded anchor, budget left, garbage bytes → dropped - // before any broadcast. - guard.arm_redrive(id, rec(3, 12, 0)).unwrap(); - } - let recorded: std::collections::HashSet<[u8; 32]> = - [[11u8; 32], [12u8; 32]].into_iter().collect(); - - redrive_pending_spends( - &sdk, + let (store, entry) = recorded_shield(id, activity_id).await; + let (refusing, _port) = sdk_refusing_connections(); + let refused = broadcast_shield( + &Arc::new(refusing), &store, None, wallet_id, id, - &recorded, - &CancellationToken::new(), + &entry, + &transition, + |e: &dash_sdk::Error| e.to_string(), ) .await; + assert!( + matches!( + refused, + Err(PlatformWalletError::ShieldedSpendUnconfirmed { + operation: "shield", + .. + }) + ), + "{refused:?}" + ); + assert_eq!( + shield_status(&store, id, &activity_id).await, + ShieldedActivityStatus::Pending + ); - let left = store.read().await.pending_redrives(id).unwrap(); - let ids: Vec<[u8; 32]> = left.iter().map(|r| r.activity_id).collect(); - assert!(ids.contains(&[1u8; 32]), "pruned-anchor record left alone"); - assert!(ids.contains(&[2u8; 32]), "exhausted record left alone"); + let (store, entry) = recorded_shield(id, activity_id).await; + let never_sent = broadcast_shield( + &Arc::new(sdk_without_addresses()), + &store, + None, + wallet_id, + id, + &entry, + &transition, + |e: &dash_sdk::Error| e.to_string(), + ) + .await; assert!( - !ids.contains(&[3u8; 32]), - "corrupt record dropped without a broadcast attempt" + matches!( + never_sent, + Err(PlatformWalletError::ShieldedBroadcastFailed(_)) + ), + "{never_sent:?}" ); assert_eq!( - left.iter().map(|r| r.attempts).max(), - Some(MAX_REDRIVE_ATTEMPTS), - "no attempt counters were bumped — nothing touched the network" + shield_status(&store, id, &activity_id).await, + ShieldedActivityStatus::Failed ); } } @@ -4083,16 +7484,18 @@ mod classify_spend_wait_failure_tests { }) } + /// A broadcast error carrying a consensus cause comes from an + /// unauthenticated endpoint, with no proof behind it: the spend stays + /// unconfirmed and its reservation stays. #[test] - fn consensus_cause_is_a_definitive_rejection() { + fn should_read_a_wait_stage_consensus_verdict_as_unconfirmed() { let cause = ConsensusError::BasicError(BasicError::ProtocolVersionParsingError( ProtocolVersionParsingError::new("bad version".to_string()), )); let err = classify_spend_wait_failure("unshield", &broadcast_err(Some(cause))); assert!( - matches!(err, PlatformWalletError::ShieldedBroadcastFailed(_)), - "a broadcast error carrying a consensus cause means Platform ran and \ - rejected the transition; the caller may release the reservation" + matches!(err, PlatformWalletError::ShieldedSpendUnconfirmed { .. }), + "{err:?}" ); } @@ -4144,18 +7547,19 @@ mod classify_spend_wait_failure_tests { dash_sdk::Error::Protocol(dpp::ProtocolError::ConsensusError(Box::new(cause))) } - /// A CheckTx consensus rejection surfacing from `broadcast()` IS - /// definitive: the transition was evaluated and refused, it sits in no - /// mempool, and the caller may release the reservations and retry. + /// A consensus rejection surfacing from `broadcast()` reads as a refusal + /// (`broadcast_was_refused`), which proves nothing: the one flow that + /// reads it, the shield from an identity, reports unconfirmed either + /// way. On a note spend's wait the same verdict reads as unconfirmed: + /// no proof backs it. #[test] - fn broadcast_consensus_rejection_is_definitive() { - assert!(broadcast_definitely_failed(&consensus_metadata_rejection())); - // The same verdict shape is definitive on the wait stage too. + fn should_read_a_consensus_rejection_as_a_refusal_and_never_as_a_failed_spend() { + assert!(broadcast_was_refused(&consensus_metadata_rejection())); let err = classify_spend_wait_failure("transfer", &consensus_metadata_rejection()); - assert!(matches!( - err, - PlatformWalletError::ShieldedBroadcastFailed(_) - )); + assert!( + matches!(err, PlatformWalletError::ShieldedSpendUnconfirmed { .. }), + "{err:?}" + ); } fn grpc_err(code: dash_sdk::dapi_grpc::tonic::Code) -> dash_sdk::Error { @@ -4167,49 +7571,38 @@ mod classify_spend_wait_failure_tests { } /// Connection-establishment failures and non-consensus server - /// rejections of `broadcast()` ARE definitive: nothing was admitted to - /// a mempool. The offline case (connect refused → `Unavailable`) in - /// particular must release the notes immediately rather than strand - /// them until restart. + /// rejections of `broadcast()` read as refusals: the shield from an + /// identity then skips its result wait for a proven nonce read. None of + /// them proves the transition was left out of every mempool. #[test] - fn broadcast_connection_failures_and_rejections_are_definitive() { + fn should_read_connection_failures_and_rejections_of_a_broadcast_as_refusals() { use dash_sdk::dapi_grpc::tonic::Code; - assert!(broadcast_definitely_failed(&grpc_err(Code::Unavailable))); + assert!(broadcast_was_refused(&grpc_err(Code::Unavailable))); // Mempool full / malformed request: server verdicts refusing admission. - assert!(broadcast_definitely_failed(&grpc_err( - Code::ResourceExhausted - ))); - assert!(broadcast_definitely_failed(&grpc_err( - Code::InvalidArgument - ))); + assert!(broadcast_was_refused(&grpc_err(Code::ResourceExhausted))); + assert!(broadcast_was_refused(&grpc_err(Code::InvalidArgument))); } - /// No-response shapes of the `broadcast()` call itself are NOT - /// definitive: the dapi-client retries across addresses, so the request + /// No-response shapes of the `broadcast()` call itself are not + /// refusals: the dapi-client retries across addresses, so the request /// may have been delivered to a node whose ACK was lost. The caller - /// falls through to the result wait instead of releasing the - /// reservations (which would let a retry select other unreserved notes - /// and double-send if the original broadcast landed). + /// falls through to the result wait. #[test] fn broadcast_no_response_shapes_are_inconclusive() { use dash_sdk::dapi_grpc::tonic::Code; - assert!(!broadcast_definitely_failed(&grpc_err( - Code::DeadlineExceeded - ))); + assert!(!broadcast_was_refused(&grpc_err(Code::DeadlineExceeded))); // DAPI maps its own tenderdash-side failures (which can postdate // delivery) to Internal. - assert!(!broadcast_definitely_failed(&grpc_err(Code::Internal))); - assert!(!broadcast_definitely_failed( - &dash_sdk::Error::TimeoutReached( - std::time::Duration::from_secs(30), - "broadcast".to_string(), - ) - )); - assert!(!broadcast_definitely_failed(&dash_sdk::Error::Generic( + assert!(!broadcast_was_refused(&grpc_err(Code::Internal))); + assert!(!broadcast_was_refused(&dash_sdk::Error::TimeoutReached( + std::time::Duration::from_secs(30), + "broadcast".to_string(), + ))); + assert!(!broadcast_was_refused(&dash_sdk::Error::Generic( "transport error: connection reset".to_string() ))); // …including as the terminal error of an exhausted retry loop. - assert!(!broadcast_definitely_failed( + assert!(!broadcast_was_refused( &dash_sdk::Error::NoAvailableAddressesToRetry(Box::new(grpc_err( Code::DeadlineExceeded ))) @@ -4222,9 +7615,9 @@ mod classify_spend_wait_failure_tests { /// — the spend is in flight and the result wait will confirm it. #[test] fn broadcast_already_exists_is_in_flight() { - assert!(!broadcast_definitely_failed( - &dash_sdk::Error::AlreadyExists("state transition already in mempool".to_string()) - )); + assert!(!broadcast_was_refused(&dash_sdk::Error::AlreadyExists( + "state transition already in mempool".to_string() + ))); } /// A consensus verdict wrapped in the dapi-client's `NoAvailableAddressesToRetry` @@ -4248,11 +7641,11 @@ mod classify_spend_wait_failure_tests { assert!(!carries_consensus_rejection(&wrapped)); } - /// A nonce rejection wrapped in the retry envelope must reach - /// `promote_address_nonce_error` and surface as the typed - /// `AddressNonceMismatch`, not fall through to `ShieldedSpendUnconfirmed`. + /// A nonce rejection on a note spend's wait, wrapped in the retry + /// envelope, is an unauthenticated verdict too: unconfirmed, the notes + /// kept, never a typed refusal a host could retry on. #[test] - fn wrapped_nonce_rejection_promotes_to_typed_mismatch() { + fn should_read_a_wrapped_nonce_rejection_on_the_wait_as_unconfirmed() { use dpp::address_funds::PlatformAddress; use dpp::consensus::state::address_funds::AddressInvalidNonceError; use dpp::consensus::state::state_error::StateError; @@ -4264,18 +7657,11 @@ mod classify_spend_wait_failure_tests { let inner = dash_sdk::Error::Protocol(dpp::ProtocolError::ConsensusError(Box::new(cause))); let wrapped = dash_sdk::Error::NoAvailableAddressesToRetry(Box::new(inner)); - match classify_spend_wait_failure("withdraw", &wrapped) { - PlatformWalletError::AddressNonceMismatch { - address: got, - provided_nonce, - expected_nonce, - } => { - assert_eq!(got, address); - assert_eq!(provided_nonce, 7); - assert_eq!(expected_nonce, 8); - } - other => panic!("expected AddressNonceMismatch, got {other:?}"), - } + let err = classify_spend_wait_failure("withdraw", &wrapped); + assert!( + matches!(err, PlatformWalletError::ShieldedSpendUnconfirmed { .. }), + "{err:?}" + ); } } @@ -4382,44 +7768,6 @@ mod reserve_shield_fee_tests { } } -#[cfg(test)] -mod note_reservation_release_tests { - use super::*; - - /// `ShieldedBroadcastUnconfirmed` is the one failure that must NOT release the reservation: the - /// broadcast was accepted and the transition may have executed, so freeing the notes invites a - /// double-spend against notes that may already be consumed on chain. The next nullifier sync - /// reconciles them. - #[test] - fn unconfirmed_broadcast_retains_reservation() { - let e = PlatformWalletError::ShieldedBroadcastUnconfirmed { - identity_id: Identifier::from([7u8; 32]), - reason: "result proof unavailable".to_string(), - }; - assert!( - !error_releases_note_reservation(&e), - "ShieldedBroadcastUnconfirmed must retain the note reservation" - ); - } - - /// Every other failure is a definitive pre-execution / build / rejection failure — the spend - /// never happened, so the reservation must be released. - #[test] - fn definitive_failures_release_reservation() { - let releasing: Vec = vec![ - PlatformWalletError::ShieldedBroadcastFailed("rejected on merits".to_string()), - PlatformWalletError::ShieldedBuildError("note selection failed".to_string()), - PlatformWalletError::ShieldedStoreError("store write failed".to_string()), - ]; - for e in &releasing { - assert!( - error_releases_note_reservation(e), - "{e:?} must release the note reservation" - ); - } - } -} - #[cfg(test)] mod record_activity_status_tests { use super::*; diff --git a/packages/rs-platform-wallet/src/wallet/shielded/store.rs b/packages/rs-platform-wallet/src/wallet/shielded/store.rs index 8efd0acfdcb..b2672e56d00 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/store.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/store.rs @@ -127,11 +127,12 @@ pub struct ShieldedOutgoingNote { } /// A pending reservation that carries a recorded anchor: -/// `(nullifier, anchor, activity_id)`. Yielded by -/// [`ShieldedStore::stale_pending_spends`] for the sync reconcile, -/// which releases the reservation once `anchor` is no longer in -/// Platform's recorded set (the spend can then never execute). -pub type StalePendingSpend = ([u8; 32], [u8; 32], Option<[u8; 32]>); +/// `(nullifier, anchor, activity_id, anchor_height)`, `anchor_height` being a +/// proved height at which `anchor` was in Platform's recorded set, when known. +/// Yielded by [`ShieldedStore::stale_pending_spends`] for the sync +/// reconcile, which releases the reservation once `anchor` is proven pruned +/// (the spend can then never execute). +pub type StalePendingSpend = ([u8; 32], [u8; 32], Option<[u8; 32]>, Option); /// An unresolved signed transition and its durable retry guard: the signed /// transition bytes plus everything the sync-time re-drive needs to @@ -142,12 +143,15 @@ pub type StalePendingSpend = ([u8; 32], [u8; 32], Option<[u8; 32]>); /// /// Identity-funded shields arm this record before broadcast and have no input /// nullifiers. Their guard survives even after rebroadcasting stops. Note spends -/// arm it only on the ambiguous outcome (`ShieldedSpendUnconfirmed`): -/// the broadcast was accepted but the result wait failed, so the spend -/// may or may not have executed. Re-broadcasting the byte-identical -/// transition is fund-safe — identical nullifiers cannot double-spend — -/// and converts silence into either a confirmation (next scan sees the -/// nullifiers spent) or a definitive consensus verdict. +/// arm it before their first dispatch too, and keep it unless the transition +/// never left the wallet ([`ShieldedStore::retire_undelivered_spend`]): a +/// spend that may have reached a node may or may not have executed, and a +/// process that exits during its broadcast or its result wait leaves the +/// record to restore its notes' reservation from. Re-broadcasting the +/// byte-identical transition is fund-safe (identical nullifiers cannot be +/// spent twice) and converts silence into a confirmation (next scan sees the +/// nullifiers spent); a spend that never lands keeps its notes held until its +/// anchor is proven pruned. #[derive(Debug, Clone, PartialEq, Eq)] pub struct PendingRedrive { /// Activity-entry id of the spend (sha256 of visible output cmxs); @@ -162,6 +166,16 @@ pub struct PendingRedrive { pub st_bytes: Vec, /// Re-broadcast attempts made so far. pub attempts: u32, + /// A proved height at which [`Self::anchor`] was in Platform's recorded + /// anchor set: the height of the set the spend's anchor was read from, or + /// of a later set seen holding it + /// ([`ShieldedStore::note_anchor_recorded`]). A set proved at or above it + /// that lacks the anchor shows it pruned rather than newer. `None` for a + /// record saved without it, by a build before heights were kept: its + /// anchor is proven pruned only once a set is seen holding it, or by a + /// proved pool count reaching the store's bound on the trees its anchors + /// were taken from ([`ShieldedStore::legacy_anchor_tree_bound`]). + pub anchor_height: Option, /// A proven identity nonce has made this exact debit impossible to execute /// again. Stop broadcasting, but keep its unresolved-payment guard until /// the scan confirms the outputs. Always false for note-spend redrives. @@ -173,6 +187,251 @@ pub struct PendingRedrive { pub identity_user_abandoned: bool, } +/// The DashPay private contact request a saved spend pays for: which identity +/// sends it to which, and its account reference. Kept with the spend's +/// record, so a restart restores the pair's reservation from the record +/// without the keys that open its entry. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct PrivateContactPayment { + /// The identity sending the request. + pub sender: [u8; 32], + /// The identity it is to. + pub recipient: [u8; 32], + /// The request's account reference, whose version tells a rotation from + /// the request it rotates. + pub account_reference: u32, +} + +impl PrivateContactPayment { + /// The bytes the file store keeps it as: sender, recipient, then the + /// account reference little-endian. + pub(super) fn to_bytes(self) -> [u8; 68] { + let mut bytes = [0u8; 68]; + bytes[..32].copy_from_slice(&self.sender); + bytes[32..64].copy_from_slice(&self.recipient); + bytes[64..].copy_from_slice(&self.account_reference.to_le_bytes()); + bytes + } + + /// The payment [`Self::to_bytes`] wrote, or `None` for other bytes. + pub(super) fn from_bytes(bytes: &[u8]) -> Option { + if bytes.len() != 68 { + return None; + } + Some(Self { + sender: bytes.get(..32)?.try_into().ok()?, + recipient: bytes.get(32..64)?.try_into().ok()?, + account_reference: u32::from_le_bytes(bytes.get(64..)?.try_into().ok()?), + }) + } +} + +/// One private contact request payment the wallet may have broadcast, as the +/// shielded store's private payment journal keeps it: the request it pays +/// for, the commitment of the entry it appends and the nullifiers its spend +/// consumes. Saved durably before the payment can reach the network +/// ([`ShieldedStore::arm_private_contact_payment`]) and kept until the +/// payment provably resolved ([`ShieldedStore::discharge_private_payment`]), +/// whatever happens to the spend's notes and redrive record: the pair it +/// holds is restored from it after a restart. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PrivatePaymentRecord { + /// The account whose notes pay for it. + pub account_index: u32, + /// The spend's activity id, which keys its redrive record. + pub activity_id: [u8; 32], + /// The recorded anchor the spend was built against: once Platform no + /// longer records it, the spend can never execute, which with an input + /// note still unspent and the entry absent from the store proves the + /// payment expired. + pub anchor: [u8; 32], + /// The proved height of the recorded-anchor set `anchor` was chosen from: + /// the anchor was recorded then, so only its absence from a set proved at + /// or above this height shows it pruned. `None` when not known, as for a + /// payment saved before the journal or the redrive record kept it, whose + /// expiry is then proven only by a proved pool count reaching the store's + /// bound on the trees its anchors were taken from + /// ([`ShieldedStore::legacy_anchor_tree_bound`]). Kept as `u64::MAX` in + /// the record's bytes ([`Self::to_bytes`]). + pub anchor_height: Option, + /// The commitment of the entry it appends, which keys the record. + pub commitment: [u8; 32], + /// The request it pays for. + pub payment: PrivateContactPayment, + /// The nullifiers of the notes its spend consumes; never empty. + pub nullifiers: Vec<[u8; 32]>, + /// SHA-256 of the whole entry it appends: the expiry's read of the store + /// takes the payment as executed only for an entry that hashes to it, not + /// for any entry that merely starts with [`Self::commitment`], which + /// anyone who saw the commitment can append. `None` for a record saved + /// before it was kept (format version 3), which matches on the commitment. + pub entry_hash: Option<[u8; 32]>, + /// The sender identity's private store read position when the payment was + /// made: its entry is appended at or after it, so the expiry's read of the + /// store starts there. `None` for a record saved before it was kept, or + /// with no position known, which is read from the store's start. + pub store_position: Option, +} + +/// An entry a private contact request payment appends, as its journal record +/// keeps it ([`ShieldedStore::arm_private_contact_payment`]). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct PrivatePaymentEntry { + /// The entry's first 32 bytes, which key its record. + pub commitment: [u8; 32], + /// SHA-256 of the whole entry ([`PrivatePaymentRecord::entry_hash`]). + pub entry_hash: [u8; 32], +} + +impl PrivatePaymentEntry { + /// An entry of `commitment` with a placeholder hash, for tests whose + /// expiry never reads the store. + #[cfg(test)] + pub(crate) fn for_commitment(commitment: [u8; 32]) -> Self { + Self { + commitment, + entry_hash: [0; 32], + } + } +} + +impl PrivatePaymentRecord { + /// How an unknown [`Self::anchor_height`] is kept in the record's bytes: + /// no proved height reaches it. + const UNKNOWN_ANCHOR_HEIGHT: u64 = u64::MAX; + + /// The format version [`Self::to_bytes`] writes. Versions 1 and 2, written + /// before the anchor and its height were kept, do not read back: their + /// wallet's holds stay. Version 3, written before the entry's hash and the + /// store position were kept, reads back with neither. + const FORMAT_VERSION: u8 = 4; + /// The version before [`Self::FORMAT_VERSION`], still read. + const FORMAT_VERSION_WITHOUT_ENTRY_HASH: u8 = 3; + /// The bytes before the nullifiers: version, account index, activity id, + /// anchor, anchor height, commitment, sender, recipient, account reference + /// and nullifier count. + const HEADER_LEN: usize = 1 + 4 + 32 + 32 + 8 + 32 + 32 + 32 + 4 + 2; + + /// The bytes the file store keeps it as: [`Self::FORMAT_VERSION`], the + /// account index little-endian, the activity id, the anchor, the anchor + /// height little-endian, the commitment, the sender, the recipient, the + /// account reference little-endian, the nullifier count as a + /// little-endian `u16`, the nullifiers, then the entry's hash and the + /// store position, each a presence byte (0 or 1) and, when present, the + /// 32 bytes or the position little-endian. `None` when it has no + /// nullifier or more than a `u16` counts. + pub(super) fn to_bytes(&self) -> Option> { + let count = u16::try_from(self.nullifiers.len()).ok()?; + if count == 0 { + return None; + } + let mut bytes = Vec::with_capacity(Self::HEADER_LEN + 32 * self.nullifiers.len()); + bytes.push(Self::FORMAT_VERSION); + bytes.extend_from_slice(&self.account_index.to_le_bytes()); + bytes.extend_from_slice(&self.activity_id); + bytes.extend_from_slice(&self.anchor); + bytes.extend_from_slice( + &self + .anchor_height + .unwrap_or(Self::UNKNOWN_ANCHOR_HEIGHT) + .to_le_bytes(), + ); + bytes.extend_from_slice(&self.commitment); + bytes.extend_from_slice(&self.payment.sender); + bytes.extend_from_slice(&self.payment.recipient); + bytes.extend_from_slice(&self.payment.account_reference.to_le_bytes()); + bytes.extend_from_slice(&count.to_le_bytes()); + for nullifier in &self.nullifiers { + bytes.extend_from_slice(nullifier); + } + match &self.entry_hash { + Some(hash) => { + bytes.push(1); + bytes.extend_from_slice(hash); + } + None => bytes.push(0), + } + match self.store_position { + Some(position) => { + bytes.push(1); + bytes.extend_from_slice(&position.to_le_bytes()); + } + None => bytes.push(0), + } + Some(bytes) + } + + /// The record [`Self::to_bytes`] wrote, or one of version 3, or `None` + /// for any other bytes: another version, a length that does not match the + /// count, or no nullifier. + pub(super) fn from_bytes(bytes: &[u8]) -> Option { + let (&version, rest) = bytes.split_first()?; + if version != Self::FORMAT_VERSION && version != Self::FORMAT_VERSION_WITHOUT_ENTRY_HASH { + return None; + } + let (account_index, rest) = rest.split_first_chunk::<4>()?; + let (activity_id, rest) = rest.split_first_chunk::<32>()?; + let (anchor, rest) = rest.split_first_chunk::<32>()?; + let (anchor_height, rest) = rest.split_first_chunk::<8>()?; + let (commitment, rest) = rest.split_first_chunk::<32>()?; + let (sender, rest) = rest.split_first_chunk::<32>()?; + let (recipient, rest) = rest.split_first_chunk::<32>()?; + let (account_reference, rest) = rest.split_first_chunk::<4>()?; + let (count, rest) = rest.split_first_chunk::<2>()?; + let count = usize::from(u16::from_le_bytes(*count)); + let (nullifiers, rest) = rest.split_at_checked(32 * count)?; + let (nullifiers, remainder) = nullifiers.as_chunks::<32>(); + if count == 0 || nullifiers.len() != count || !remainder.is_empty() { + return None; + } + let (entry_hash, store_position) = if version == Self::FORMAT_VERSION { + let (&has_hash, rest) = rest.split_first()?; + let (entry_hash, rest) = match has_hash { + 0 => (None, rest), + 1 => { + let (hash, rest) = rest.split_first_chunk::<32>()?; + (Some(*hash), rest) + } + _ => return None, + }; + let (&has_position, rest) = rest.split_first()?; + let (store_position, rest) = match has_position { + 0 => (None, rest), + 1 => { + let (position, rest) = rest.split_first_chunk::<8>()?; + (Some(u64::from_le_bytes(*position)), rest) + } + _ => return None, + }; + if !rest.is_empty() { + return None; + } + (entry_hash, store_position) + } else { + if !rest.is_empty() { + return None; + } + (None, None) + }; + Some(Self { + account_index: u32::from_le_bytes(*account_index), + activity_id: *activity_id, + anchor: *anchor, + anchor_height: Some(u64::from_le_bytes(*anchor_height)) + .filter(|height| *height != Self::UNKNOWN_ANCHOR_HEIGHT), + commitment: *commitment, + payment: PrivateContactPayment { + sender: *sender, + recipient: *recipient, + account_reference: u32::from_le_bytes(*account_reference), + }, + nullifiers: nullifiers.to_vec(), + entry_hash, + store_position, + }) + } +} + /// What the wallet knows about an identity debit's local recovery state. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum IdentityDebitRecoveryStatus { @@ -219,7 +478,10 @@ pub(super) struct MarkSpentOutcome { /// /// All mutating methods take `&mut self` so implementations can /// batch writes without interior mutability. -pub trait ShieldedStore: Send + Sync { +/// +/// A store is `'static`: a spend dropped before it hands its notes over +/// releases their reservation on a spawned task when the store is locked. +pub trait ShieldedStore: Send + Sync + 'static { /// The error type returned by storage operations. type Error: StdError + Send + Sync + 'static; @@ -248,12 +510,13 @@ pub trait ShieldedStore: Send + Sync { /// Returns `true` if the nullifier was newly added to the /// pending set, `false` if it was already pending. /// - /// Pending state is **in-memory only** — it does not survive - /// a process restart. The crash-during-broadcast case is - /// reconciled by the next note-scan pass after the transition - /// lands (scan-based spend detection marks the spent note via - /// its nullifier), or, on rejection, leaves the notes - /// observable as unspent again on the next launch. + /// The reservation itself is held in memory. A spend saves a redrive + /// record before its first dispatch ([`Self::arm_redrive`]), which + /// carries its nullifiers: a store that persists records restores the + /// reservation from it on reopen, so a process that exits during a + /// broadcast keeps the notes reserved. A reservation with no saved + /// record (its spend exited before saving one, so before anything was + /// dispatched) does not survive a restart. /// /// `unspent_notes` skips notes whose nullifier is in the /// pending set, so a successful `mark_pending` immediately @@ -265,27 +528,79 @@ pub trait ShieldedStore: Send + Sync { /// got removed; `false` is a no-op (paired clear from the /// rollback path on a transition that never marked pending, /// or a stale clear after the spend already promoted to - /// `mark_spent`). + /// `mark_spent`). Clears whoever holds it: for a resolution of the + /// spend (a pruned anchor). A spend attempt releases its own with + /// [`Self::clear_pending_reserved_by`]. fn clear_pending(&mut self, id: SubwalletId, nullifier: &[u8; 32]) -> Result; - /// Attach the recorded `anchor` the spend was built against, and - /// the linked `activity_id`, to `id`'s pending reservation for - /// `nullifier` (taken earlier by [`Self::mark_pending`]). No-op - /// if the nullifier is no longer pending. The sync reconcile uses - /// the stored anchor to detect a stranded spend whose anchor - /// Platform has pruned (see [`Self::stale_pending_spends`]). + /// [`Self::mark_pending`] for the spend attempt `reservation`, which owns + /// the reservation: only [`Self::clear_pending_reserved_by`] with the + /// same attempt, or a resolution of the spend, clears it. + fn mark_pending_by( + &mut self, + id: SubwalletId, + nullifier: &[u8; 32], + reservation: u64, + ) -> Result; + + /// Release `id`'s reservation of `nullifier`, and the redrive records + /// carrying it, only while the spend attempt `reservation` still holds + /// it ([`Self::mark_pending_by`]), compared and cleared in one call + /// under the store lock: a stale attempt's cleanup never releases a + /// newer attempt's notes or deletes its records. Returns whether it was + /// released. + fn clear_pending_reserved_by( + &mut self, + id: SubwalletId, + nullifier: &[u8; 32], + reservation: u64, + ) -> Result; + + /// Attach the recorded `anchor` the spend was built against, the proved + /// height of the anchor set it was read from (`anchor_height`), and the + /// linked `activity_id`, to `id`'s pending reservation for `nullifier` + /// (taken earlier by [`Self::mark_pending`]). No-op if the nullifier is + /// no longer pending. The sync reconcile uses the stored anchor and its + /// height to detect a stranded spend whose anchor Platform has pruned + /// (see [`Self::stale_pending_spends`]). fn set_pending_spend( &mut self, id: SubwalletId, nullifier: &[u8; 32], anchor: [u8; 32], activity_id: [u8; 32], + anchor_height: Option, ) -> Result<(), Self::Error>; + /// Note that `anchor` was in Platform's recorded set proved at `height`: + /// each of `id`'s reservations built on it and each of its records that + /// carry no anchor height get `height`, a record's durably. A set proved + /// at or above it that lacks the anchor then shows it pruned. One that + /// already carries a height keeps it. + fn note_anchor_recorded( + &mut self, + id: SubwalletId, + anchor: &[u8; 32], + height: u64, + ) -> Result<(), Self::Error>; + + /// An upper bound on the size of the commitment tree any record this store + /// loaded at open without an anchor height took its anchor from: the + /// largest tree the store has held, kept durably across resets. Such a + /// record was saved by an earlier process, whose spends were built on + /// roots of its local tree, which only holds proved commitments. So once + /// a proved pool count at or below an anchor set's height reaches this + /// bound, the anchor was recorded by then, and the set's lack of it shows + /// it pruned rather than newer (`PrunedAnchorEvidence::proves_pruned`). + /// `None` when the store keeps no such bound: such records stay held. + fn legacy_anchor_tree_bound(&self) -> Option { + None + } + /// Pending reservations for `id` that carry a recorded anchor — - /// `(nullifier, anchor, activity_id)` per built-but-unconfirmed - /// spend. Empty when `id` has no anchored reservations (the common + /// `(nullifier, anchor, activity_id, anchor_height)` per + /// built-but-unconfirmed spend. Empty when `id` has no anchored reservations (the common /// case, which lets the sync reconcile skip its network round-trip). /// The reconcile checks each anchor against Platform's recorded set /// and releases the reservation via [`Self::clear_pending`] when the @@ -294,8 +609,8 @@ pub trait ShieldedStore: Send + Sync { // ── Re-drivable unconfirmed spends (per-subwallet) ───────────────── - /// Persist a re-drivable record for a broadcast-accepted spend whose - /// result wait failed ambiguously. Keyed by `redrive.activity_id`; + /// Persist the re-drivable record of a spend, saved before its first + /// dispatch. Keyed by `redrive.activity_id`; /// re-arming the same id overwrites. Unlike the bare `mark_pending` /// reservations, redrive records survive a restart where the backend /// persists them (the file store does): on reopen both the record @@ -304,6 +619,96 @@ pub trait ShieldedStore: Send + Sync { /// continue across relaunches. fn arm_redrive(&mut self, id: SubwalletId, redrive: PendingRedrive) -> Result<(), Self::Error>; + /// [`Self::arm_redrive`] for a spend paying for the DashPay private + /// contact request `payment`, which is kept with the record and dropped + /// with it, and the private payment journal's record of each entry the + /// spend appends (`entries`, each with the hash of the whole entry), + /// which outlives it ([`PrivatePaymentRecord`]), with the sender's private + /// store read position when it paid (`store_position`). All of it is saved + /// in one write that is durable once this returns, across a crash or power + /// loss too: the spend is broadcast only after it. A store that cannot + /// keep all of it durably fails, and the payment is refused. + /// `anchor_height` is the proved height of the recorded-anchor set the + /// spend's anchor was chosen from ([`PrivatePaymentRecord::anchor_height`]). + fn arm_private_contact_payment( + &mut self, + id: SubwalletId, + redrive: PendingRedrive, + payment: PrivateContactPayment, + entries: &[PrivatePaymentEntry], + anchor_height: u64, + store_position: Option, + ) -> Result<(), Self::Error>; + + /// The armed records of `wallet_id` that pay for a private contact + /// request, each with the request ([`Self::arm_private_contact_payment`]). + /// Fails when one of them carries an association that does not read. + fn private_contact_redrives_for_wallet( + &self, + wallet_id: WalletId, + ) -> Result, Self::Error>; + + // ── Private payment journal (per-wallet) ─────────────────────────── + + /// Whether `wallet_id`'s private payment journal is open + /// ([`Self::open_private_payment_journal`]): then it is authoritative for + /// the wallet's private payments, so one marked unresolved with no record + /// in it has resolved or was never broadcast. A journal not open yet, as + /// in a store that was deleted or replaced, cannot tell. + fn private_payment_journal_open(&self, wallet_id: WalletId) -> Result; + + /// Open `wallet_id`'s private payment journal, durably: called once a + /// restoration of the wallet's private payments from it succeeded, before + /// the wallet can pay. Saving a journal record opens it too. + fn open_private_payment_journal(&mut self, wallet_id: WalletId) -> Result<(), Self::Error>; + + /// Every journal record of `wallet_id`'s private payments. Fails when one + /// of the wallet's records, or one whose wallet does not read, does not + /// read back. + fn private_payment_journal( + &self, + wallet_id: WalletId, + ) -> Result, Self::Error>; + + /// Add `records` to `wallet_id`'s journal durably, for payments whose + /// redrive record was saved before the journal kept them. + fn journal_private_payments( + &mut self, + wallet_id: WalletId, + records: &[PrivatePaymentRecord], + ) -> Result<(), Self::Error>; + + /// Remove `wallet_id`'s journal record of the entry `commitment`, once + /// its payment provably resolved: the entry was read back, or the payment + /// is proven expired (its anchor pruned and its entry absent from the + /// store). Returns whether there was one. Only this call and + /// [`Self::retire_undelivered_spend`] remove a journal record: not a note + /// release, a redrive's removal or a purge. + fn discharge_private_payment( + &mut self, + wallet_id: WalletId, + commitment: &[u8; 32], + ) -> Result; + + /// Retire the saved record of `id`'s spend `activity_id`, whose + /// transition never left the wallet, together with the journal records of + /// `commitments` in `id`'s wallet, the entries it would have appended. One + /// durable write removes them all (the file store commits it on its + /// recovery connection, at `synchronous=FULL`), so no restart finds the + /// journal discharged while the signed transition is still saved, or the + /// other way round. + /// + /// Returns false, changing nothing, when no such record is saved, or when + /// a re-broadcast of it was claimed ([`PendingRedrive::attempts`] above + /// 0): the transition may then have left the wallet. The notes the spend + /// reserved are the caller's to release. + fn retire_undelivered_spend( + &mut self, + id: SubwalletId, + activity_id: &[u8; 32], + commitments: &[[u8; 32]], + ) -> Result; + /// Every armed redrive record for `id`. fn pending_redrives(&self, id: SubwalletId) -> Result, Self::Error>; @@ -540,8 +945,8 @@ pub trait ShieldedStore: Send + Sync { /// stranded (broadcast-accepted-but-never-landed) spend: once that anchor /// is pruned from Platform's recorded set the spend can never execute, and /// with the nullifier still unspent the reservation is provably dead and -/// its note can be freed. All in-memory only — a restart drops every -/// reservation regardless. +/// its note can be freed. Held in memory: a restart keeps the reservations +/// a saved [`PendingRedrive`] restores, and drops the others. #[derive(Debug, Clone, Default)] pub(super) struct PendingSpend { /// The recorded anchor the spend was built against, once known. @@ -550,6 +955,14 @@ pub(super) struct PendingSpend { /// The linked activity-log entry id, so a released reservation can /// flip its "Pending" row to "Failed" instead of stranding it. pub activity_id: Option<[u8; 32]>, + /// The spend attempt that reserved the note + /// ([`ShieldedStore::mark_pending_by`]), whose release clears it only + /// while it still holds it. `None` for a reservation restored from a + /// redrive record, which only a resolution of its spend clears. + pub reservation: Option, + /// A proved height at which `anchor` was in Platform's recorded set + /// ([`PendingRedrive::anchor_height`]), when known. + pub anchor_height: Option, } /// Per-subwallet note + sync state used by both the in-memory and @@ -572,11 +985,12 @@ pub(super) struct SubwalletState { /// transition, mapped to the [`PendingSpend`] bookkeeping the /// sync reconcile needs. Excluded from `unspent_notes()` so /// concurrent callers can't double-select. Held in memory; a - /// pre-broadcast reservation dies with the process, but a - /// reservation belonging to an armed [`PendingRedrive`] is - /// rehydrated on file-store open (the redrive row carries its - /// nullifiers), so an unconfirmed broadcast keeps its notes - /// reserved across restarts. + /// reservation whose spend has saved no record yet dies with the + /// process, but a reservation belonging to an armed + /// [`PendingRedrive`], which a spend saves before its first + /// dispatch, is rehydrated on file-store open (the redrive row + /// carries its nullifiers), so a spend that may have been broadcast + /// keeps its notes reserved across restarts. pub pending_nullifiers: BTreeMap<[u8; 32], PendingSpend>, /// Armed re-drivable unconfirmed spends, keyed by activity id. /// See [`PendingRedrive`]. Kept consistent with @@ -694,6 +1108,42 @@ impl SubwalletState { } } + /// [`Self::mark_pending`] for the spend attempt `reservation`, which owns + /// the reservation from now on. + pub(super) fn mark_pending_by(&mut self, nullifier: &[u8; 32], reservation: u64) -> bool { + match self.pending_nullifiers.entry(*nullifier) { + std::collections::btree_map::Entry::Vacant(e) => { + e.insert(PendingSpend { + reservation: Some(reservation), + ..PendingSpend::default() + }); + true + } + std::collections::btree_map::Entry::Occupied(_) => false, + } + } + + /// Release the reservation of `nullifier` only while the spend attempt + /// `reservation` holds it ([`Self::mark_pending_by`]), with the redrive + /// records it carries, as [`Self::clear_pending`] does. Returns whether + /// it was released: another attempt's reservation, or one restored from + /// a redrive record, stays. + pub(super) fn clear_pending_reserved_by( + &mut self, + nullifier: &[u8; 32], + reservation: u64, + ) -> bool { + if self + .pending_nullifiers + .get(nullifier) + .is_some_and(|pending| pending.reservation == Some(reservation)) + { + self.clear_pending(nullifier) + } else { + false + } + } + /// Attach the built spend's recorded `anchor` and linked /// `activity_id` to an existing reservation for `nullifier`. /// No-op if the nullifier is no longer pending (e.g. the @@ -703,11 +1153,43 @@ impl SubwalletState { nullifier: &[u8; 32], anchor: [u8; 32], activity_id: [u8; 32], + anchor_height: Option, ) { if let Some(pending) = self.pending_nullifiers.get_mut(nullifier) { pending.anchor = Some(anchor); pending.activity_id = Some(activity_id); + pending.anchor_height = anchor_height; + } + } + + /// Give `height` to each reservation built on `anchor`, and each record + /// on it, that carries no anchor height + /// ([`ShieldedStore::note_anchor_recorded`]). Returns the activity ids of + /// the records given it. + pub(super) fn note_anchor_recorded(&mut self, anchor: &[u8; 32], height: u64) -> Vec<[u8; 32]> { + for pending in self.pending_nullifiers.values_mut() { + if pending.anchor == Some(*anchor) && pending.anchor_height.is_none() { + pending.anchor_height = Some(height); + } + } + let mut noted = Vec::new(); + for redrive in self.redrives.values_mut() { + if redrive.anchor == *anchor && redrive.anchor_height.is_none() { + redrive.anchor_height = Some(height); + noted.push(redrive.activity_id); + } } + noted + } + + /// The activity ids of the records built on `anchor` that carry no anchor + /// height. + pub(super) fn redrives_without_anchor_height(&self, anchor: &[u8; 32]) -> Vec<[u8; 32]> { + self.redrives + .values() + .filter(|redrive| redrive.anchor == *anchor && redrive.anchor_height.is_none()) + .map(|redrive| redrive.activity_id) + .collect() } /// Reservations that carry a recorded anchor — i.e. built, @@ -722,7 +1204,7 @@ impl SubwalletState { .filter_map(|(nullifier, spend)| { spend .anchor - .map(|anchor| (*nullifier, anchor, spend.activity_id)) + .map(|anchor| (*nullifier, anchor, spend.activity_id, spend.anchor_height)) }) .collect() } @@ -856,6 +1338,13 @@ pub struct InMemoryShieldedStore { checkpoints: Vec, /// Placeholder anchor; production stores compute the real Sinsemilla root. anchor: [u8; 32], + /// The private contact request each armed record pays for, by subwallet + /// and activity id, read joined with the live records. + private_contact_payments: BTreeMap<(SubwalletId, [u8; 32]), PrivateContactPayment>, + /// The private payment journal's records, by wallet and commitment. + private_payment_journal: BTreeMap<(WalletId, [u8; 32]), PrivatePaymentRecord>, + /// The wallets whose private payment journal is open. + private_payment_journals: BTreeSet, } impl InMemoryShieldedStore { @@ -927,15 +1416,54 @@ impl ShieldedStore for InMemoryShieldedStore { .unwrap_or(false)) } + fn mark_pending_by( + &mut self, + id: SubwalletId, + nullifier: &[u8; 32], + reservation: u64, + ) -> Result { + Ok(self + .subwallets + .entry(id) + .or_default() + .mark_pending_by(nullifier, reservation)) + } + + fn clear_pending_reserved_by( + &mut self, + id: SubwalletId, + nullifier: &[u8; 32], + reservation: u64, + ) -> Result { + let released = self + .subwallets + .get_mut(&id) + .is_some_and(|sw| sw.clear_pending_reserved_by(nullifier, reservation)); + Ok(released) + } + fn set_pending_spend( &mut self, id: SubwalletId, nullifier: &[u8; 32], anchor: [u8; 32], activity_id: [u8; 32], + anchor_height: Option, ) -> Result<(), Self::Error> { if let Some(sw) = self.subwallets.get_mut(&id) { - sw.set_pending_spend(nullifier, anchor, activity_id); + sw.set_pending_spend(nullifier, anchor, activity_id, anchor_height); + } + Ok(()) + } + + fn note_anchor_recorded( + &mut self, + id: SubwalletId, + anchor: &[u8; 32], + height: u64, + ) -> Result<(), Self::Error> { + if let Some(sw) = self.subwallets.get_mut(&id) { + sw.note_anchor_recorded(anchor, height); } Ok(()) } @@ -949,10 +1477,139 @@ impl ShieldedStore for InMemoryShieldedStore { } fn arm_redrive(&mut self, id: SubwalletId, redrive: PendingRedrive) -> Result<(), Self::Error> { + self.private_contact_payments + .remove(&(id, redrive.activity_id)); + self.subwallets.entry(id).or_default().arm_redrive(redrive); + Ok(()) + } + + fn arm_private_contact_payment( + &mut self, + id: SubwalletId, + redrive: PendingRedrive, + payment: PrivateContactPayment, + entries: &[PrivatePaymentEntry], + anchor_height: u64, + store_position: Option, + ) -> Result<(), Self::Error> { + if redrive.nullifiers.is_empty() { + return Err(InMemoryStoreError( + "a private payment's record spends no note".to_string(), + )); + } + if !entries.is_empty() { + self.private_payment_journals.insert(id.wallet_id); + } + for entry in entries { + self.private_payment_journal.insert( + (id.wallet_id, entry.commitment), + PrivatePaymentRecord { + account_index: id.account_index, + activity_id: redrive.activity_id, + anchor: redrive.anchor, + anchor_height: Some(anchor_height), + commitment: entry.commitment, + payment, + nullifiers: redrive.nullifiers.clone(), + entry_hash: Some(entry.entry_hash), + store_position, + }, + ); + } + self.private_contact_payments + .insert((id, redrive.activity_id), payment); self.subwallets.entry(id).or_default().arm_redrive(redrive); Ok(()) } + fn private_contact_redrives_for_wallet( + &self, + wallet_id: WalletId, + ) -> Result, Self::Error> { + Ok(self + .pending_redrives_for_wallet(wallet_id)? + .into_iter() + .filter_map(|(id, redrive)| { + self.private_contact_payments + .get(&(id, redrive.activity_id)) + .map(|payment| (redrive, *payment)) + }) + .collect()) + } + + fn private_payment_journal_open(&self, wallet_id: WalletId) -> Result { + Ok(self.private_payment_journals.contains(&wallet_id)) + } + + fn open_private_payment_journal(&mut self, wallet_id: WalletId) -> Result<(), Self::Error> { + self.private_payment_journals.insert(wallet_id); + Ok(()) + } + + fn private_payment_journal( + &self, + wallet_id: WalletId, + ) -> Result, Self::Error> { + Ok(self + .private_payment_journal + .range((wallet_id, [0u8; 32])..=(wallet_id, [u8::MAX; 32])) + .map(|(_, record)| record.clone()) + .collect()) + } + + fn journal_private_payments( + &mut self, + wallet_id: WalletId, + records: &[PrivatePaymentRecord], + ) -> Result<(), Self::Error> { + if records.iter().any(|record| record.nullifiers.is_empty()) { + return Err(InMemoryStoreError( + "a private payment's record spends no note".to_string(), + )); + } + if !records.is_empty() { + self.private_payment_journals.insert(wallet_id); + } + for record in records { + self.private_payment_journal + .insert((wallet_id, record.commitment), record.clone()); + } + Ok(()) + } + + fn discharge_private_payment( + &mut self, + wallet_id: WalletId, + commitment: &[u8; 32], + ) -> Result { + Ok(self + .private_payment_journal + .remove(&(wallet_id, *commitment)) + .is_some()) + } + + fn retire_undelivered_spend( + &mut self, + id: SubwalletId, + activity_id: &[u8; 32], + commitments: &[[u8; 32]], + ) -> Result { + let Some(subwallet) = self + .subwallets + .get_mut(&id) + .filter(|subwallet| subwallet.redrive_attempts(activity_id) == Some(0)) + else { + return Ok(false); + }; + subwallet.clear_redrive(activity_id); + self.private_contact_payments.remove(&(id, *activity_id)); + for commitment in commitments { + self.private_payment_journal + .remove(&(id.wallet_id, *commitment)); + } + Ok(true) + } + fn pending_redrives(&self, id: SubwalletId) -> Result, Self::Error> { Ok(self .subwallets @@ -1115,7 +1772,11 @@ impl ShieldedStore for InMemoryShieldedStore { } fn purge_wallet(&mut self, wallet_id: WalletId) -> Result<(), Self::Error> { + // The private payment journal outlives the purge: the payments it + // keeps may still execute. self.subwallets.retain(|id, _| id.wallet_id != wallet_id); + self.private_contact_payments + .retain(|(id, _), _| id.wallet_id != wallet_id); Ok(()) } @@ -1137,6 +1798,7 @@ impl ShieldedStore for InMemoryShieldedStore { fn purge_all_subwallets(&mut self) -> Result<(), Self::Error> { self.subwallets.clear(); + self.private_contact_payments.clear(); Ok(()) } @@ -1372,6 +2034,7 @@ mod tests { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; // Landing path: mark_spent on one nullifier drops the record. @@ -1553,18 +2216,18 @@ mod tests { "newly reserved" ); store - .set_pending_spend(id, &nullifier, anchor, activity_id) + .set_pending_spend(id, &nullifier, anchor, activity_id, Some(10)) .unwrap(); assert_eq!( store.stale_pending_spends(id).unwrap(), - vec![(nullifier, anchor, Some(activity_id))], + vec![(nullifier, anchor, Some(activity_id), Some(10))], "an armed reservation surfaces as an anchored (stale-checkable) spend" ); // Anchor IS still recorded → retain. let recorded: HashSet<[u8; 32]> = [anchor].into_iter().collect(); - for (n, a, _) in store.stale_pending_spends(id).unwrap() { + for (n, a, _, _) in store.stale_pending_spends(id).unwrap() { if !recorded.contains(&a) { store.clear_pending(id, &n).unwrap(); } @@ -1580,6 +2243,97 @@ mod tests { ); } + /// A journal record's unknown anchor height is `None` in memory and + /// `u64::MAX` only in its bytes, as format 3 keeps it; a known one reads + /// back as it was. + #[test] + fn should_keep_an_unknown_journal_anchor_height_as_none_across_its_bytes() { + let record = |anchor_height| PrivatePaymentRecord { + account_index: 2, + activity_id: [0x61; 32], + anchor: [0x62; 32], + anchor_height, + commitment: [0x63; 32], + payment: PrivateContactPayment { + sender: [0x64; 32], + recipient: [0x65; 32], + account_reference: 3, + }, + nullifiers: vec![[0x66; 32]], + entry_hash: None, + store_position: None, + }; + for anchor_height in [None, Some(0), Some(41)] { + let bytes = record(anchor_height).to_bytes().expect("encodes"); + let height_at = 1 + 4 + 32 + 32; + assert_eq!( + bytes[height_at..height_at + 8], + anchor_height.unwrap_or(u64::MAX).to_le_bytes(), + "{anchor_height:?}" + ); + assert_eq!( + PrivatePaymentRecord::from_bytes(&bytes), + Some(record(anchor_height)), + "{anchor_height:?}" + ); + } + } + + /// A format 4 journal record keeps its entry's hash and its store + /// position across its bytes, each present or not; a format 3 record, + /// which kept neither, reads back with neither. A presence byte other than + /// 0 or 1, or bytes past the last field, do not read. + #[test] + fn should_keep_a_journal_record_s_entry_hash_and_position_across_its_bytes() { + let record = |entry_hash, store_position| PrivatePaymentRecord { + account_index: 2, + activity_id: [0x61; 32], + anchor: [0x62; 32], + anchor_height: Some(41), + commitment: [0x63; 32], + payment: PrivateContactPayment { + sender: [0x64; 32], + recipient: [0x65; 32], + account_reference: 3, + }, + nullifiers: vec![[0x66; 32], [0x68; 32]], + entry_hash, + store_position, + }; + for (entry_hash, store_position) in [ + (None, None), + (Some([0x67; 32]), None), + (None, Some(9)), + (Some([0x67; 32]), Some(u64::MAX - 1)), + ] { + let bytes = record(entry_hash, store_position) + .to_bytes() + .expect("encodes"); + assert_eq!( + PrivatePaymentRecord::from_bytes(&bytes), + Some(record(entry_hash, store_position)), + "{entry_hash:?} {store_position:?}" + ); + let mut longer = bytes; + longer.push(0); + assert_eq!(PrivatePaymentRecord::from_bytes(&longer), None); + } + // Format 3: the fields up to the nullifiers. + let mut format_3 = record(None, None).to_bytes().expect("encodes"); + format_3.truncate(format_3.len() - 2); + format_3[0] = 3; + assert_eq!( + PrivatePaymentRecord::from_bytes(&format_3), + Some(record(None, None)) + ); + format_3.push(0); + assert_eq!(PrivatePaymentRecord::from_bytes(&format_3), None); + let mut unknown_presence = record(None, None).to_bytes().expect("encodes"); + let at = unknown_presence.len() - 2; + unknown_presence[at] = 2; + assert_eq!(PrivatePaymentRecord::from_bytes(&unknown_presence), None); + } + /// The fund-safe release: once the anchor is pruned (absent from the /// recorded set) the spend can never execute, so the reservation is /// released and the freed note becomes spendable again. @@ -1598,13 +2352,13 @@ mod tests { .unwrap(); store.mark_pending(id, &nullifier).unwrap(); store - .set_pending_spend(id, &nullifier, anchor, activity_id) + .set_pending_spend(id, &nullifier, anchor, activity_id, Some(10)) .unwrap(); assert!(store.get_unspent_notes(id).unwrap().is_empty()); // Anchor is ABSENT from the recorded set (pruned) → release. let recorded: HashSet<[u8; 32]> = [[0xEE; 32]].into_iter().collect(); - for (n, a, _) in store.stale_pending_spends(id).unwrap() { + for (n, a, _, _) in store.stale_pending_spends(id).unwrap() { if !recorded.contains(&a) { assert!(store.clear_pending(id, &n).unwrap()); } @@ -1677,6 +2431,7 @@ mod tests { attempts: 7, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; let note_spend = PendingRedrive { activity_id: [0x44; 32], @@ -1686,6 +2441,7 @@ mod tests { attempts: 1, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }; store.arm_redrive(id, identity_guard.clone()).unwrap(); store.arm_redrive(id, note_spend).unwrap(); diff --git a/packages/rs-platform-wallet/src/wallet/shielded/sync.rs b/packages/rs-platform-wallet/src/wallet/shielded/sync.rs index 7d4cb149951..1fbbc4e4418 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/sync.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/sync.rs @@ -153,6 +153,15 @@ pub struct MultiSyncNotesResult { /// subwallet. The caller decides whether to queue it on the /// shared `WalletPersister`. pub changeset: ShieldedChangeSet, + /// The highest proved height this pass's scan covers: every action + /// appended at or below it, and so every nullifier spent there, was + /// scanned, by this pass or an earlier one, and replayed against the + /// notes. It is the height of a batch in the run scanned without a gap + /// from the pass's start whose proof, and every proof read before it, + /// shows the commitment tree ending within that run (the batch's + /// `total_count` is the highest seen). `None` when no batch shows that: + /// a proof of a longer tree than the run reached. + pub covered_height: Option, } impl MultiSyncNotesResult { @@ -471,6 +480,12 @@ where // The stream lives in this block so it — and the up-to-`max_concurrent` // network fetches it holds in flight — is dropped before the finalize // below runs, whether the loop ran to the end or was cancelled. + // What this pass's scan covers (`MultiSyncNotesResult::covered_height`): + // the end of the run of positions scanned without a gap from + // `aligned_start`, and the highest proved height of a batch in it whose + // proof shows the tree ending within it. + let mut scanned_to = aligned_start; + let mut covered_height: Option = None; let cancelled = { let stream = make_stream(aligned_start, tree_size); futures::pin_mut!(stream); @@ -501,6 +516,13 @@ where // it. Stays 0 (indeterminate) only if no batch is ever produced. total_target = total_target.max(batch.total_count); total_notes_scanned += batch.notes.len() as u64; + if batch.start_index <= scanned_to { + let end = batch.start_index.saturating_add(batch.notes.len() as u64); + scanned_to = scanned_to.max(end); + if end >= batch.total_count { + covered_height = covered_height.max(Some(batch.block_height)); + } + } if !batch.notes.is_empty() { last_nonempty = Some((batch.start_index, batch.is_partial)); } @@ -839,6 +861,7 @@ where per_subwallet_newly_spent: newly_spent_per_subwallet, total_scanned: scanned_volume, changeset, + covered_height, }) } diff --git a/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs b/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs index a683da2d53c..8c89aeb5c1a 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs @@ -1,4 +1,5 @@ -//! Cancellation of a note-sync pass (dashpay/platform#5200). +//! Cancellation of a note-sync pass (dashpay/platform#5200), and the +//! height a completed pass covers. //! //! Feeds `sync_notes_from_stream` a synthetic batch stream so the //! cancel path runs without a network. The stream yields real-shaped @@ -351,3 +352,61 @@ async fn should_return_while_waiting_for_the_store_lock_when_cancelled() { let _ = std::fs::remove_file(&path); } + +/// A batch of `len` notes at `start_index`, proved at `block_height`, whose +/// proof (with every one read before it) shows `total_count` notes. +fn proved_batch( + start_index: u64, + len: u64, + total_count: u64, + block_height: u64, +) -> ShieldedChunkBatch { + ShieldedChunkBatch { + block_height, + ..batch(start_index, len, total_count) + } +} + +/// A completed pass covers the proved height of the last batch of its run +/// whose proof shows the tree ending within that run, and no height when +/// every proof shows a longer tree than the run reached. +#[tokio::test] +async fn should_report_the_height_a_completed_scan_covers() { + let cases: [(&str, Vec, Option); 4] = [ + ( + "the last batch ends the tree", + vec![proved_batch(0, 4, 6, 1_000), proved_batch(4, 2, 6, 1_004)], + Some(1_004), + ), + ( + "a proof of a longer tree than the run reached", + vec![proved_batch(0, 4, 9, 1_000), proved_batch(4, 2, 9, 1_004)], + None, + ), + ( + "an empty chunk past a full one, at a later height", + vec![proved_batch(0, 4, 4, 1_000), proved_batch(4, 0, 4, 1_005)], + Some(1_005), + ), + ( + "a batch past a gap in the run", + vec![proved_batch(0, 4, 4, 1_000), proved_batch(8, 0, 4, 1_009)], + Some(1_000), + ), + ]; + for (case, batches, covered) in cases { + let path = temp_tree_path("covered"); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(&path, 100).expect("open store"), + )); + let result = run( + &store, + &one_subwallet(), + &CancellationToken::new(), + futures::stream::iter(batches.into_iter().map(Ok)), + ) + .await; + assert_eq!(result.covered_height, covered, "{case}"); + let _ = std::fs::remove_file(&path); + } +} diff --git a/packages/rs-platform-wallet/src/wallet/shielded/viewing_key_bind_tests.rs b/packages/rs-platform-wallet/src/wallet/shielded/viewing_key_bind_tests.rs index fb1d107e6fa..dd0c190a281 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/viewing_key_bind_tests.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/viewing_key_bind_tests.rs @@ -528,6 +528,7 @@ async fn bind_persists_viewing_keys_and_restart_rebinds_seedlessly() { attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .expect("persist pending reservation"); @@ -1080,6 +1081,7 @@ async fn should_keep_wallet_and_coordinator_keys_when_guarded_registration_is_re attempts: 0, identity_nonce_finalized: false, identity_user_abandoned: false, + anchor_height: None, }, ) .unwrap(); diff --git a/packages/rs-sdk-ffi/src/mnemonic_resolver_core_signer.rs b/packages/rs-sdk-ffi/src/mnemonic_resolver_core_signer.rs index 5418123ad43..67eb8702f24 100644 --- a/packages/rs-sdk-ffi/src/mnemonic_resolver_core_signer.rs +++ b/packages/rs-sdk-ffi/src/mnemonic_resolver_core_signer.rs @@ -60,7 +60,17 @@ use std::ffi::c_void; use std::os::raw::c_char; use async_trait::async_trait; +use dash_sdk::dpp::data_contract::DataContract; +use dash_sdk::dpp::identity::{Identity, KeyID}; +use dash_sdk::dpp::platform_value::BinaryData; +use dash_sdk::dpp::prelude::Identifier; use dash_sdk::dpp::secp256k1; +use dash_sdk::dpp::version::PlatformVersion; +use dash_sdk::platform::dashpay::{ + seal_private_contact_request, PrivateContactRequest, PrivateContactRequestSender, +}; +use dash_sdk::platform::private_document_entries::PrivateDocumentEntries; +use dash_sdk::platform::private_document_scan::{PrivateDocumentScan, PrivateDocumentScanKeys}; use key_wallet::bip32::{ChildNumber, DerivationPath, ExtendedPrivKey, ExtendedPubKey}; use key_wallet::dashcore::ecdsa::{EcdsaError, EcdsaPublicKey, EcdsaSecretKey, EcdsaSignature}; use key_wallet::dip9::{ @@ -70,6 +80,7 @@ use key_wallet::dip9::{ }; use key_wallet::signer::{ExtendedPubKeySigner, Signer, SignerMethod}; use key_wallet::Network; +use platform_encryption::PrivateDocumentTarget; use thiserror::Error; use zeroize::Zeroizing; @@ -166,6 +177,13 @@ pub enum MnemonicResolverSignerError { /// Decoding the generated recoverable signature failed. #[error("ECDSA signature conversion failed: {0}")] SignatureConversion(#[source] EcdsaError), + + /// The SDK refused to seal a private contact request with the derived + /// key: a malformed request, a key the identity does not hold, a + /// signature that is not the signing key's, or a contract without the + /// private type. + #[error("private contact request: {0}")] + PrivateContactRequest(dash_sdk::Error), } /// `key_wallet::signer::Signer` implementation that derives ECDSA @@ -242,36 +260,36 @@ impl MnemonicResolverCoreSigner { } } - /// Resolve the mnemonic from the Swift-side callback, derive the BIP-32 - /// extended private key at `path`, and hand it *by reference* to - /// `extract`, returning whatever `extract` produces. + /// Resolve the mnemonic from the Swift-side callback, build the BIP-32 + /// master `ExtendedPrivKey`, and hand it *by reference* to `use_master`, + /// returning whatever `use_master` produces. An operation that needs keys + /// at several paths derives them all from this one resolve. /// /// This is the single entry-point for all private-key material in this /// signer. It handles the full stack: resolver FFI call → result-code /// mapping → UTF-8 + word-list validation → BIP-39 seed → master - /// `ExtendedPrivKey` → child `ExtendedPrivKey` at `path`. + /// `ExtendedPrivKey`. /// /// # Zeroization contract /// - /// Both the `master` and `derived` extended keys wipe their secret - /// material when they leave this scope — [`ExtendedPrivKey`] zeroizes on - /// `Drop` and is not `Copy`, so each move is a real move that leaves no - /// bitwise duplicate behind. The - /// key never crosses the call boundary — `extract` only borrows it — so it - /// cannot outlive the derivation. `extract` returns public material - /// (`ExtendedPubKey`) or a `Zeroizing` scalar copy; the caller wipes the - /// latter on its own drop. The mnemonic and seed buffers are plain arrays - /// and ride [`Zeroizing`] wrappers for the same guarantee. + /// The `master` extended key wipes its secret material when it leaves + /// this scope, as does every child `use_master` derives from it: + /// [`ExtendedPrivKey`] zeroizes on `Drop` and is not `Copy`, so each move + /// is a real move that leaves no bitwise duplicate behind. The master key + /// never crosses the call boundary (`use_master` only borrows it), so it + /// cannot outlive the operation. `use_master` returns public material, a + /// product of the keys, or a `Zeroizing` scalar copy the caller wipes on + /// its own drop. The mnemonic and seed buffers are plain arrays and ride + /// [`Zeroizing`] wrappers for the same guarantee. /// /// # Errors /// /// Propagates [`MnemonicResolverSignerError`] for every failure mode: - /// null handle, resolver FFI errors, encoding/parse failures, and BIP-32 - /// derivation errors. - fn resolve_and_derive( + /// null handle, resolver FFI errors, encoding/parse failures, BIP-32 + /// derivation errors, and whatever `use_master` returns. + fn resolve_master( &self, - path: &DerivationPath, - extract: impl FnOnce(&ExtendedPrivKey) -> T, + use_master: impl FnOnce(&ExtendedPrivKey) -> Result, ) -> Result { if self.resolver_addr == 0 { return Err(MnemonicResolverSignerError::NullHandle); @@ -331,11 +349,25 @@ impl MnemonicResolverCoreSigner { let master = ExtendedPrivKey::new_master(self.network, seed.as_ref()) .map_err(|e| MnemonicResolverSignerError::DerivationFailed(format!("master: {e}")))?; - let derived = master - .derive_priv(path) - .map_err(|e| MnemonicResolverSignerError::DerivationFailed(format!("path: {e}")))?; - Ok(extract(&derived)) + use_master(&master) + } + + /// Resolve the mnemonic, derive the BIP-32 extended private key at + /// `path`, and hand it *by reference* to `extract`, returning whatever + /// `extract` produces. The derived key self-wipes on `Drop` when this + /// returns; see [`Self::resolve_master`] for the full contract. + fn resolve_and_derive( + &self, + path: &DerivationPath, + extract: impl FnOnce(&ExtendedPrivKey) -> T, + ) -> Result { + self.resolve_master(|master| { + let derived = master + .derive_priv(path) + .map_err(|e| MnemonicResolverSignerError::DerivationFailed(format!("path: {e}")))?; + Ok(extract(&derived)) + }) } /// Resolve the mnemonic and derive the raw 32-byte scalar at `path`. @@ -583,6 +615,127 @@ impl MnemonicResolverCoreSigner { private_data, }) } + + /// Sort `page`, read from `start_position` of the store of the private + /// document type `document_type_name` of `data_contract_id`, with the + /// wallet's keys ([`PrivateDocumentScanKeys::scan_page`]). `recipients` + /// are the identities entries may be sealed to, each with the paths of + /// its keys by key id; `senders` the identities that may have sealed + /// entries, each with the id and path of an encryption key whose + /// outgoing viewing key recovers what it sent. The mnemonic is resolved + /// once and every key is derived from it here; the SDK builds the scan + /// keys from them ([`PrivateDocumentScanKeys::derive`]) and wipes them. + /// Only the sorted entries return. + pub fn scan_private_document_page( + &self, + recipients: &[(Identifier, Vec<(KeyID, DerivationPath)>)], + senders: &[(Identifier, KeyID, DerivationPath)], + data_contract_id: Identifier, + document_type_name: &str, + start_position: u64, + page: &PrivateDocumentEntries, + ) -> Result { + let target = PrivateDocumentTarget { + contract_id: data_contract_id.to_buffer(), + document_type_name, + }; + self.resolve_master(|master| { + // `secret_key_at` hands back a wiping guard; the copy it yields + // is wiped by `derive` once used. + let keys = PrivateDocumentScanKeys::derive(recipients, senders, |path| { + secret_key_at(master, path).map(|secret| secret.0) + })?; + Ok(keys.scan_page(&target, start_position, page)) + }) + } + + /// [`Self::scan_private_document_page`] for several pages of one store, + /// each with the position it was read from: the mnemonic is resolved once + /// for the batch and the scan keys are derived once, then each page is + /// sorted with them, in order. A wallet scanning many pages at once reads + /// the Keychain once per batch, not once per page. + pub fn scan_private_document_pages( + &self, + recipients: &[(Identifier, Vec<(KeyID, DerivationPath)>)], + senders: &[(Identifier, KeyID, DerivationPath)], + data_contract_id: Identifier, + document_type_name: &str, + pages: &[(u64, &PrivateDocumentEntries)], + ) -> Result, MnemonicResolverSignerError> { + let target = PrivateDocumentTarget { + contract_id: data_contract_id.to_buffer(), + document_type_name, + }; + self.resolve_master(|master| { + // As for one page: `derive` wipes each copy `secret_key_at` + // yields once used. + let keys = PrivateDocumentScanKeys::derive(recipients, senders, |path| { + secret_key_at(master, path).map(|secret| secret.0) + })?; + Ok(pages + .iter() + .map(|(start_position, page)| keys.scan_page(&target, *start_position, page)) + .collect()) + }) + } + + /// Seal `request` from `sender`, whose encryption key + /// `sender_encryption_key_id` is the one at `sender_encryption_key_path`, + /// to the key `recipient_key_id` of `recipient`, with `signature`, the + /// signature of the request by the sender's key `signing_key_id` + /// ([`seal_private_contact_request`]). The signature comes from the + /// identity signer, as a transition's does; this signs nothing. + /// `esk_seed` is 32 fresh random bytes, never reused. The encryption key, + /// and the outgoing viewing key the SDK derives from it, stay here; only + /// the sealed entry returns. + #[allow(clippy::too_many_arguments)] + pub fn seal_private_contact_request( + &self, + sender_encryption_key_path: &DerivationPath, + dashpay_contract: &DataContract, + sender: &Identity, + sender_encryption_key_id: KeyID, + signing_key_id: KeyID, + signature: &[u8; 65], + recipient: &Identity, + recipient_key_id: KeyID, + request: &PrivateContactRequest, + esk_seed: &[u8; 32], + platform_version: &PlatformVersion, + ) -> Result { + let secret = + self.resolve_master(|master| secret_key_at(master, sender_encryption_key_path))?; + seal_private_contact_request( + dashpay_contract, + &PrivateContactRequestSender { + identity: sender, + encryption_key_id: sender_encryption_key_id, + encryption_secret_key: &secret.0, + signing_key_id, + signature, + }, + recipient, + recipient_key_id, + request, + esk_seed, + platform_version, + ) + .map_err(MnemonicResolverSignerError::PrivateContactRequest) + } +} + +/// The secp256k1 secret key at `path` below `master`, wiped on drop. The +/// child `ExtendedPrivKey` self-wipes when this returns. +fn secret_key_at( + master: &ExtendedPrivKey, + path: &DerivationPath, +) -> Result { + let derived = master + .derive_priv(path) + .map_err(|e| MnemonicResolverSignerError::DerivationFailed(format!("path: {e}")))?; + let secret = secp256k1::SecretKey::from_secret_bytes(*derived.private_key.to_bytes()) + .map_err(|e| MnemonicResolverSignerError::InvalidScalar(e.to_string()))?; + Ok(WipingSecretKey(secret)) } /// Result of [`MnemonicResolverCoreSigner::contact_info_seal`]. @@ -1226,4 +1379,705 @@ mod tests { assert_eq!(methods.len(), 1); assert!(matches!(methods[0], SignerMethod::Digest)); } + + mod private_contact_requests { + use super::*; + use dash_sdk::dpp::data_contract::accessors::v0::DataContractV0Getters; + use dash_sdk::dpp::identity::accessors::IdentityGettersV0; + use dash_sdk::dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; + use dash_sdk::dpp::identity::identity_public_key::v0::IdentityPublicKeyV0; + use dash_sdk::dpp::identity::{ + IdentityPublicKey, IdentityV0, KeyType, Purpose, SecurityLevel, + }; + use dash_sdk::dpp::system_data_contracts::{load_system_data_contract, SystemDataContract}; + use dash_sdk::dpp::version::PlatformVersion; + use dash_sdk::platform::dashpay::{ + private_contact_request_identities, private_contact_request_outgoing_viewing_key, + private_contact_request_signature, private_contact_request_signing_data, + private_contact_requests_from_scan, ProvedIdentity, + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + }; + use dash_sdk::platform::private_document_entries::PrivateDocumentEntry; + use key_wallet::mnemonic::Mnemonic; + use key_wallet::wallet::initialization::WalletAccountCreationOptions; + use key_wallet::wallet::Wallet; + use simple_signer::SingleKeySigner; + use std::collections::BTreeMap; + use std::sync::atomic::{AtomicUsize, Ordering}; + + const SENDER_ID: [u8; 32] = [0xA0; 32]; + const RECIPIENT_ID: [u8; 32] = [0xB0; 32]; + /// Two identities of another wallet, whose entry the scan passes over. + const OUTSIDER_ID: [u8; 32] = [0xC0; 32]; + const CAROL_ID: [u8; 32] = [0xD0; 32]; + /// The authentication key a sender signs its requests with. + const SIGNING_KEY_ID: KeyID = 0; + const SENDER_KEY_ID: KeyID = 1; + const RECIPIENT_KEY_ID: KeyID = 2; + const BLOCK_TIME_MS: u64 = 1_700_000_000_000; + + /// The sender's DashPay encryption key, in the test wallet. + fn sender_key_path() -> DerivationPath { + DerivationPath::from_str("m/9'/1'/5'/0'/0'/0'/1'").expect("valid path") + } + + /// The recipient's DashPay decryption key, in the test wallet. + fn recipient_key_path() -> DerivationPath { + DerivationPath::from_str("m/9'/1'/5'/0'/0'/1'/2'").expect("valid path") + } + + /// The secret key a resident wallet of `ENGLISH_PHRASE` holds at `path`. + fn seed_secret_key(path: &DerivationPath) -> secp256k1::SecretKey { + let seed = Mnemonic::from_phrase(ENGLISH_PHRASE) + .expect("valid mnemonic") + .to_seed(""); + let wallet = Wallet::from_seed_bytes( + *seed, + Network::Testnet, + WalletAccountCreationOptions::None, + ) + .expect("seeded wallet"); + let xprv = wallet + .derive_extended_private_key(path) + .expect("wallet derives the private key at path"); + secp256k1::SecretKey::from_secret_bytes(*xprv.private_key.to_bytes()) + .expect("a valid scalar") + } + + fn fixed_secret_key(byte: u8) -> secp256k1::SecretKey { + secp256k1::SecretKey::from_secret_bytes([byte; 32]).expect("a valid scalar") + } + + /// The sender's signing key, which the identity signer holds, not the + /// resolver. + fn sender_signing_secret_key() -> secp256k1::SecretKey { + fixed_secret_key(0x51) + } + + fn outsider_secret_key() -> secp256k1::SecretKey { + fixed_secret_key(0x41) + } + + fn outsider_signing_secret_key() -> secp256k1::SecretKey { + fixed_secret_key(0x52) + } + + fn key( + id: KeyID, + purpose: Purpose, + security_level: SecurityLevel, + secret_key: &secp256k1::SecretKey, + ) -> IdentityPublicKey { + IdentityPublicKey::V0(IdentityPublicKeyV0 { + id, + purpose, + security_level, + contract_bounds: None, + key_type: KeyType::ECDSA_SECP256K1, + read_only: false, + data: BinaryData::new( + secp256k1::PublicKey::from_secret_key(secret_key) + .serialize() + .to_vec(), + ), + disabled_at: None, + }) + } + + /// A `HIGH` authentication key, which may sign DashPay's documents. + fn signing_key(secret_key: &secp256k1::SecretKey) -> IdentityPublicKey { + key( + SIGNING_KEY_ID, + Purpose::AUTHENTICATION, + SecurityLevel::HIGH, + secret_key, + ) + } + + fn identity(id: [u8; 32], keys: Vec) -> Identity { + Identity::V0(IdentityV0 { + id: Identifier::from(id), + public_keys: keys.into_iter().map(|key| (key.id(), key)).collect(), + balance: 0, + revision: 0, + }) + } + + fn sender() -> Identity { + identity( + SENDER_ID, + vec![ + signing_key(&sender_signing_secret_key()), + key( + SENDER_KEY_ID, + Purpose::ENCRYPTION, + SecurityLevel::MEDIUM, + &seed_secret_key(&sender_key_path()), + ), + ], + ) + } + + fn recipient() -> Identity { + identity( + RECIPIENT_ID, + vec![key( + RECIPIENT_KEY_ID, + Purpose::DECRYPTION, + SecurityLevel::MEDIUM, + &seed_secret_key(&recipient_key_path()), + )], + ) + } + + fn outsider() -> Identity { + identity( + OUTSIDER_ID, + vec![ + signing_key(&outsider_signing_secret_key()), + key( + SENDER_KEY_ID, + Purpose::ENCRYPTION, + SecurityLevel::MEDIUM, + &outsider_secret_key(), + ), + ], + ) + } + + fn carol() -> Identity { + identity( + CAROL_ID, + vec![key( + RECIPIENT_KEY_ID, + Purpose::DECRYPTION, + SecurityLevel::MEDIUM, + &fixed_secret_key(0x42), + )], + ) + } + + fn dashpay() -> DataContract { + load_system_data_contract(SystemDataContract::Dashpay, PlatformVersion::latest()) + .expect("DashPay loads at the latest version") + } + + fn target(contract: &DataContract) -> PrivateDocumentTarget<'static> { + PrivateDocumentTarget { + contract_id: contract.id().to_buffer(), + document_type_name: PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + } + } + + fn request() -> PrivateContactRequest { + PrivateContactRequest { + account_reference: 7, + extended_public_key: [0x33; platform_encryption::COMPACT_XPUB_LEN], + account_label: Some("Alice".to_string()), + auto_accept_proof: None, + shielded_address: Some([0x55; 43]), + } + } + + /// The signature of `request()` from `sender`'s encryption key to the + /// decryption key of `recipient`, as the wallet gets it: an identity + /// signer holding `signing_secret_key` signs the request's signing + /// data with `sender`'s signing key, as it signs a transition. + async fn signature( + contract: &DataContract, + sender: &Identity, + recipient: &Identity, + signing_secret_key: &secp256k1::SecretKey, + ) -> [u8; 65] { + let signing_key = sender + .get_public_key_by_id(SIGNING_KEY_ID) + .expect("the sender has a signing key") + .clone(); + let signer = SingleKeySigner::new_from_slice( + &signing_secret_key.to_secret_bytes(), + Network::Testnet, + ) + .expect("a valid signing key"); + let signing_data = private_contact_request_signing_data( + contract, + sender, + SENDER_KEY_ID, + recipient, + RECIPIENT_KEY_ID, + &request(), + PlatformVersion::latest(), + ) + .expect("the keys check"); + private_contact_request_signature(&signer, &signing_key, &signing_data) + .await + .expect("the identity signer signs") + } + + /// `request` sealed by `sender` with `secret_key`, the encryption key + /// a resident wallet holds, and `signature`, to the decryption key of + /// `recipient`. + fn seed_sealed( + contract: &DataContract, + sender: &Identity, + secret_key: &secp256k1::SecretKey, + signature: &[u8; 65], + recipient: &Identity, + esk_seed: u8, + ) -> BinaryData { + seal_private_contact_request( + contract, + &PrivateContactRequestSender { + identity: sender, + encryption_key_id: SENDER_KEY_ID, + encryption_secret_key: secret_key, + signing_key_id: SIGNING_KEY_ID, + signature, + }, + recipient, + RECIPIENT_KEY_ID, + &request(), + &[esk_seed; 32], + PlatformVersion::latest(), + ) + .expect("the request seals") + } + + /// The test entry: the sender's request to the recipient. + async fn sent_to_recipient(contract: &DataContract, esk_seed: u8) -> BinaryData { + let signature = signature( + contract, + &sender(), + &recipient(), + &sender_signing_secret_key(), + ) + .await; + seed_sealed( + contract, + &sender(), + &seed_secret_key(&sender_key_path()), + &signature, + &recipient(), + esk_seed, + ) + } + + /// Another wallet's entry: the outsider's request to carol. + async fn sent_to_carol(contract: &DataContract, esk_seed: u8) -> BinaryData { + let signature = signature( + contract, + &outsider(), + &carol(), + &outsider_signing_secret_key(), + ) + .await; + seed_sealed( + contract, + &outsider(), + &outsider_secret_key(), + &signature, + &carol(), + esk_seed, + ) + } + + fn page(entries: Vec) -> PrivateDocumentEntries { + PrivateDocumentEntries { + chunk_power: None, + total_count: entries.len() as u64, + entries: entries + .into_iter() + .zip(0u64..) + .map(|(data, position)| PrivateDocumentEntry { + position, + block_height: 10 + position, + block_time_ms: BLOCK_TIME_MS, + data: data.to_vec(), + }) + .collect(), + } + } + + /// The wallet's recipient key paths: the recipient's decryption key. + fn recipient_paths() -> Vec<(Identifier, Vec<(KeyID, DerivationPath)>)> { + vec![( + Identifier::from(RECIPIENT_ID), + vec![(RECIPIENT_KEY_ID, recipient_key_path())], + )] + } + + /// The wallet's sender key paths: the sender's encryption key. + fn sender_paths() -> Vec<(Identifier, KeyID, DerivationPath)> { + vec![( + Identifier::from(SENDER_ID), + SENDER_KEY_ID, + sender_key_path(), + )] + } + + /// The scan keys a resident wallet of the same seed builds. + fn seed_scan_keys() -> PrivateDocumentScanKeys { + PrivateDocumentScanKeys::new() + .with_recipient( + Identifier::from(RECIPIENT_ID), + &[(RECIPIENT_KEY_ID, seed_secret_key(&recipient_key_path()))], + ) + .with_sender( + Identifier::from(SENDER_ID), + SENDER_KEY_ID, + private_contact_request_outgoing_viewing_key(&seed_secret_key( + &sender_key_path(), + )), + ) + } + + unsafe extern "C" fn counting_resolve( + ctx: *const c_void, + wallet_id_bytes: *const u8, + out_buf: *mut c_char, + out_capacity: usize, + out_len: *mut usize, + ) -> i32 { + (*(ctx as *const AtomicUsize)).fetch_add(1, Ordering::SeqCst); + english_resolve(ctx, wallet_id_bytes, out_buf, out_capacity, out_len) + } + + /// The entry the signer seals with the identity signer's signature is + /// byte for byte the one a resident wallet seals with the encryption + /// key at the same path, so a request sent through the Keychain opens + /// and authenticates for every client. + #[tokio::test] + async fn should_seal_the_entry_a_seed_derived_sender_key_seals() { + let contract = dashpay(); + let signature = signature( + &contract, + &sender(), + &recipient(), + &sender_signing_secret_key(), + ) + .await; + let resolver = make_resolver(english_resolve); + let signer = + unsafe { MnemonicResolverCoreSigner::new(resolver, [0u8; 32], Network::Testnet) }; + + let sealed = signer + .seal_private_contact_request( + &sender_key_path(), + &contract, + &sender(), + SENDER_KEY_ID, + SIGNING_KEY_ID, + &signature, + &recipient(), + RECIPIENT_KEY_ID, + &request(), + &[7; 32], + PlatformVersion::latest(), + ) + .expect("the signer seals the request"); + assert_eq!(sealed, sent_to_recipient(&contract, 7).await); + + unsafe { dash_sdk_mnemonic_resolver_destroy(resolver) }; + } + + /// A page scanned through the signer sorts as with a resident wallet's + /// scan keys: the request to the recipient, and the same request + /// recovered as sent by the sender's outgoing viewing key, while + /// another wallet's entry is passed over. Both read as the sender's + /// signed request, which needs no secret key. + #[tokio::test] + async fn should_scan_a_page_as_seed_derived_scan_keys_do() { + let contract = dashpay(); + let target = target(&contract); + let page = page(vec![ + sent_to_carol(&contract, 1).await, + sent_to_recipient(&contract, 2).await, + ]); + let resolver = make_resolver(english_resolve); + let signer = + unsafe { MnemonicResolverCoreSigner::new(resolver, [0u8; 32], Network::Testnet) }; + + let scan = signer + .scan_private_document_page( + &recipient_paths(), + &sender_paths(), + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + 0, + &page, + ) + .expect("the signer scans the page"); + assert_eq!(scan, seed_scan_keys().scan_page(&target, 0, &page)); + assert_eq!(scan.received.len(), 1, "the request to the recipient"); + assert_eq!(scan.sent.len(), 1, "the request the sender sent"); + assert!(scan.rejected.is_empty()); + assert!(scan.is_complete()); + + let needed = private_contact_request_identities(&scan); + assert_eq!( + needed.keys().copied().collect::>(), + vec![sender().id(), recipient().id()], + "the read checks the sender and the recipient" + ); + // Each identity as a proof at the height the read needs shows it. + let identities: BTreeMap<_, _> = [sender(), recipient()] + .into_iter() + .map(|identity| { + let proved_at_height = needed[&identity.id()]; + ( + identity.id(), + ProvedIdentity { + identity: Some(identity), + proved_at_height, + }, + ) + }) + .collect(); + let read = private_contact_requests_from_scan( + &contract, + scan, + &identities, + PlatformVersion::latest(), + ) + .expect("the requests read"); + assert!(read.rejected.is_empty(), "rejected: {:?}", read.rejected); + assert_eq!(read.received.len(), 1); + assert_eq!(read.received[0].sender_id, sender().id()); + assert_eq!(read.received[0].sender_key_id, SENDER_KEY_ID); + assert_eq!(read.received[0].recipient_key_id, RECIPIENT_KEY_ID); + assert_eq!(read.received[0].request, request()); + assert_eq!(read.sent.len(), 1); + assert_eq!(read.sent[0].sender_key_id, SENDER_KEY_ID); + assert_eq!(read.sent[0].recipient_id, recipient().id()); + + unsafe { dash_sdk_mnemonic_resolver_destroy(resolver) }; + } + + /// Every key a scan needs comes from one Keychain read, not one per + /// key, and a seal reads the Keychain once. + #[tokio::test] + async fn should_resolve_the_mnemonic_once_per_scan_and_once_per_seal() { + let contract = dashpay(); + let page = page(vec![sent_to_recipient(&contract, 3).await]); + let signature = signature( + &contract, + &sender(), + &recipient(), + &sender_signing_secret_key(), + ) + .await; + let resolves = AtomicUsize::new(0); + let resolver = unsafe { + dash_sdk_mnemonic_resolver_create( + &resolves as *const AtomicUsize as *mut c_void, + counting_resolve, + noop_destroy, + ) + }; + let signer = + unsafe { MnemonicResolverCoreSigner::new(resolver, [0u8; 32], Network::Testnet) }; + // Two keys for the recipient and one sender: three derivations. + let recipients = vec![( + Identifier::from(RECIPIENT_ID), + vec![ + (RECIPIENT_KEY_ID, recipient_key_path()), + ( + 3, + DerivationPath::from_str("m/9'/1'/5'/0'/0'/1'/3'").expect("valid path"), + ), + ], + )]; + + signer + .scan_private_document_page( + &recipients, + &sender_paths(), + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + 0, + &page, + ) + .expect("the signer scans the page"); + assert_eq!(resolves.load(Ordering::SeqCst), 1); + + signer + .seal_private_contact_request( + &sender_key_path(), + &contract, + &sender(), + SENDER_KEY_ID, + SIGNING_KEY_ID, + &signature, + &recipient(), + RECIPIENT_KEY_ID, + &request(), + &[4; 32], + PlatformVersion::latest(), + ) + .expect("the signer seals the request"); + assert_eq!(resolves.load(Ordering::SeqCst), 2); + + unsafe { dash_sdk_mnemonic_resolver_destroy(resolver) }; + } + + /// A path that is not the sender's encryption key derives a key the + /// SDK refuses to seal with, and the refusal reaches the caller typed. + #[tokio::test] + async fn should_refuse_to_seal_with_a_key_the_sender_does_not_hold() { + let contract = dashpay(); + let signature = signature( + &contract, + &sender(), + &recipient(), + &sender_signing_secret_key(), + ) + .await; + let resolver = make_resolver(english_resolve); + let signer = + unsafe { MnemonicResolverCoreSigner::new(resolver, [0u8; 32], Network::Testnet) }; + + let err = signer + .seal_private_contact_request( + &recipient_key_path(), + &contract, + &sender(), + SENDER_KEY_ID, + SIGNING_KEY_ID, + &signature, + &recipient(), + RECIPIENT_KEY_ID, + &request(), + &[7; 32], + PlatformVersion::latest(), + ) + .expect_err("the key at that path is not the sender's"); + assert!( + matches!(err, MnemonicResolverSignerError::PrivateContactRequest(_)), + "expected the SDK's refusal, got: {err:?}" + ); + assert!( + err.to_string().contains("secret key"), + "refused for the encryption key, got: {err}" + ); + + unsafe { dash_sdk_mnemonic_resolver_destroy(resolver) }; + } + + /// The signer seals only what the identity signer signed: a + /// signature by a key other than the signing key it names is the + /// SDK's refusal, not an entry. + #[tokio::test] + async fn should_refuse_to_seal_a_signature_by_another_key() { + let contract = dashpay(); + let forged = signature( + &contract, + &sender(), + &recipient(), + &outsider_signing_secret_key(), + ) + .await; + let resolver = make_resolver(english_resolve); + let signer = + unsafe { MnemonicResolverCoreSigner::new(resolver, [0u8; 32], Network::Testnet) }; + + let err = signer + .seal_private_contact_request( + &sender_key_path(), + &contract, + &sender(), + SENDER_KEY_ID, + SIGNING_KEY_ID, + &forged, + &recipient(), + RECIPIENT_KEY_ID, + &request(), + &[7; 32], + PlatformVersion::latest(), + ) + .expect_err("the signature is not the signing key's"); + assert!( + matches!(err, MnemonicResolverSignerError::PrivateContactRequest(_)), + "expected the SDK's refusal, got: {err:?}" + ); + assert!( + err.to_string().contains("signature"), + "refused for the signature, got: {err}" + ); + + unsafe { dash_sdk_mnemonic_resolver_destroy(resolver) }; + } + + /// A batch of pages scanned through the signer reads the Keychain once + /// and sorts each page as scanning it alone does. + #[tokio::test] + async fn should_resolve_the_mnemonic_once_per_batch_of_pages() { + let contract = dashpay(); + let first = page(vec![ + sent_to_carol(&contract, 5).await, + sent_to_recipient(&contract, 6).await, + ]); + let mut second = page(vec![sent_to_recipient(&contract, 8).await]); + for entry in &mut second.entries { + entry.position += 2; + } + second.total_count = 3; + let resolves = AtomicUsize::new(0); + let resolver = unsafe { + dash_sdk_mnemonic_resolver_create( + &resolves as *const AtomicUsize as *mut c_void, + counting_resolve, + noop_destroy, + ) + }; + let signer = + unsafe { MnemonicResolverCoreSigner::new(resolver, [0u8; 32], Network::Testnet) }; + + let scans = signer + .scan_private_document_pages( + &recipient_paths(), + &sender_paths(), + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + &[(0, &first), (2, &second)], + ) + .expect("the signer scans the batch"); + assert_eq!(resolves.load(Ordering::SeqCst), 1, "one Keychain read"); + let target = target(&contract); + assert_eq!( + scans, + vec![ + seed_scan_keys().scan_page(&target, 0, &first), + seed_scan_keys().scan_page(&target, 2, &second), + ] + ); + assert_eq!(scans[1].received.len(), 1); + assert_eq!(scans[1].next_position, 3); + + unsafe { dash_sdk_mnemonic_resolver_destroy(resolver) }; + } + + #[test] + fn should_report_a_missing_mnemonic_from_a_scan() { + let contract = dashpay(); + let resolver = make_resolver(missing_resolve); + let signer = + unsafe { MnemonicResolverCoreSigner::new(resolver, [0u8; 32], Network::Testnet) }; + + let err = signer + .scan_private_document_page( + &recipient_paths(), + &sender_paths(), + contract.id(), + PRIVATE_CONTACT_REQUEST_DOCUMENT_TYPE_NAME, + 0, + &page(Vec::new()), + ) + .expect_err("no mnemonic, no keys"); + assert!( + matches!(err, MnemonicResolverSignerError::NotFound), + "error should be NotFound, got: {err:?}" + ); + + unsafe { dash_sdk_mnemonic_resolver_destroy(resolver) }; + } + } } diff --git a/packages/rs-sdk/src/mock/sdk.rs b/packages/rs-sdk/src/mock/sdk.rs index f7c15fafc47..75da6f48760 100644 --- a/packages/rs-sdk/src/mock/sdk.rs +++ b/packages/rs-sdk/src/mock/sdk.rs @@ -48,6 +48,16 @@ pub struct MockDashPlatformSdk { /// The block time the metadata of a response answered from an expectation reports /// ([Self::set_response_time_ms]); 0 unless set. response_time_ms: u64, + /// The block height the metadata of a response answered from an expectation reports + /// ([Self::set_response_height]); 0 unless set. + response_height: u64, + /// The block height the metadata of a response of one type answered from an expectation + /// reports, by the type's name ([Self::set_response_height_of]), over `response_height`. + response_heights_of: BTreeMap<&'static str, u64>, + /// The block height the metadata of the response to one request answered from an + /// expectation reports, by the request's key ([Self::set_response_height_for]), over + /// `response_heights_of`. + response_heights_for: BTreeMap, } impl MockDashPlatformSdk { @@ -80,6 +90,9 @@ impl MockDashPlatformSdk { dapi, sdk: ArcSwapOption::new(None), response_time_ms: 0, + response_height: 0, + response_heights_of: BTreeMap::new(), + response_heights_for: BTreeMap::new(), } } @@ -90,6 +103,36 @@ impl MockDashPlatformSdk { self } + /// Sets the block height the metadata of every response answered from an expectation + /// reports, for code under test that reads the height a response was proved at. + pub fn set_response_height(&mut self, height: u64) -> &mut Self { + self.response_height = height; + self + } + + /// Sets the block height the metadata of every response of type `O` answered from an + /// expectation reports, over [Self::set_response_height]: for code under test that reads + /// two kinds of responses proved at different heights. + pub fn set_response_height_of(&mut self, height: u64) -> &mut Self { + self.response_heights_of + .insert(std::any::type_name::(), height); + self + } + + /// Sets the block height the metadata of the response to `query`, a fetch of `O` answered + /// from an expectation, reports, over [Self::set_response_height_of]: for code under test + /// that reads responses of one type proved at different heights. + pub fn set_response_height_for::Query>>( + &mut self, + query: Q, + height: u64, + ) -> &mut Self { + let (rich, _) = self + .encode_rich_to_wire::::Query, ::Request>(query, identity); + self.response_heights_for.insert(Key::new(&rich), height); + self + } + pub(crate) fn set_sdk(&mut self, sdk: Sdk) { self.sdk.store(Some(Arc::new(sdk))); } @@ -614,6 +657,12 @@ impl MockDashPlatformSdk { ResponseMetadata { protocol_version: dpp::version::LATEST_VERSION, time_ms: self.response_time_ms, + height: self + .response_heights_for + .get(&key) + .or_else(|| self.response_heights_of.get(std::any::type_name::())) + .copied() + .unwrap_or(self.response_height), ..Default::default() }, Proof::default(), diff --git a/packages/rs-sdk/src/platform/dashpay/contact_request.rs b/packages/rs-sdk/src/platform/dashpay/contact_request.rs index 2e3fe81e91c..0859c649f01 100644 --- a/packages/rs-sdk/src/platform/dashpay/contact_request.rs +++ b/packages/rs-sdk/src/platform/dashpay/contact_request.rs @@ -2,7 +2,9 @@ //! //! Implements DIP-15 DashPay contact request functionality -use crate::platform::transition::put_document::PutDocument; +use crate::platform::transition::broadcast::{wait_after_broadcast, BroadcastStateTransition}; +use crate::platform::transition::put_document::prepare_document_state_transition; +use crate::platform::transition::waitable::Waitable; use crate::platform::Document; use crate::{Error, Sdk}; use dpp::data_contract::accessors::v0::DataContractV0Getters; @@ -18,6 +20,7 @@ use dpp::prelude::Identifier; use dpp::secp256k1::rand::rngs::StdRng; use dpp::secp256k1::rand::{Rng, RngCore, SeedableRng}; use dpp::secp256k1::{PublicKey, SecretKey}; +use dpp::state_transition::StateTransition; use platform_encryption::{ derive_shared_key_ecdh, encrypt_account_label, encrypt_extended_public_key, COMPACT_XPUB_LEN, }; @@ -148,6 +151,20 @@ pub struct SendContactRequestResult { pub account_reference: u32, } +/// A contact request signed and not yet broadcast +/// ([`Sdk::sign_contact_request`]). +#[derive(Debug, Clone)] +pub struct SignedContactRequest { + /// The signed `contactRequest` create transition. Broadcasting these same + /// bytes again is a retry of this request, never a second one: the + /// transition carries its identity contract nonce. + pub state_transition: StateTransition, + /// The recipient's identity ID + pub recipient_id: Identifier, + /// The account reference + pub account_reference: u32, +} + /// Whether `purpose` is acceptable for the `senderKeyIndex` key of a contact /// request **we are about to mint**. The sender always references its own /// ENCRYPTION key. @@ -494,6 +511,52 @@ impl Sdk { ecdh_provider: EcdhProvider, get_extended_public_key: H, ) -> Result + where + F: FnOnce(&IdentityPublicKey, u32) -> Fut, + Fut: std::future::Future>, + G: FnOnce(&PublicKey) -> Gut, + Gut: std::future::Future>, + H: FnOnce(u32) -> Hut, + Hut: std::future::Future, Error>>, + { + let SignedContactRequest { + state_transition, + recipient_id, + account_reference, + } = self + .sign_contact_request(input, ecdh_provider, get_extended_public_key) + .await?; + + // Submit the document to the platform, and wait for the proof of the + // same signed transition. + let broadcast = state_transition.broadcast(self, None).await; + let platform_document = wait_after_broadcast( + broadcast, + ::wait_for_response(self, state_transition, None), + ) + .await?; + + // Return the result with recipient ID and account reference we saved earlier + Ok(SendContactRequestResult { + document: platform_document, + recipient_id, + account_reference, + }) + } + + /// Sign a contact request without broadcasting it: what + /// [`Self::send_contact_request`] submits, for a caller that keeps the + /// signed transition so that a retry broadcasts the same bytes again + /// rather than signing a second request. + /// + /// The transition takes the sender's next identity contract nonce for + /// DashPay, as a send does. + pub async fn sign_contact_request, F, Fut, G, Gut, H, Hut>( + &self, + input: SendContactRequestInput, + ecdh_provider: EcdhProvider, + get_extended_public_key: H, + ) -> Result where F: FnOnce(&IdentityPublicKey, u32) -> Fut, Fut: std::future::Future>, @@ -550,22 +613,20 @@ impl Sdk { moderated_by: None, }); - // Submit the document to the platform - let platform_document = document - .put_to_platform_and_wait_for_response( - self, - contact_request_document_type.to_owned_document_type(), - Some(entropy.0), - input.identity_public_key, - None, // token payment info - &input.signer, - None, // settings - ) - .await?; - - // Return the result with recipient ID and account reference we saved earlier - Ok(SendContactRequestResult { - document: platform_document, + let state_transition = prepare_document_state_transition( + &document, + self, + contact_request_document_type.to_owned_document_type(), + Some(entropy.0), + input.identity_public_key, + None, // token payment info + &input.signer, + None, // settings + ) + .await?; + + Ok(SignedContactRequest { + state_transition, recipient_id, account_reference, }) diff --git a/packages/rs-sdk/src/platform/dashpay/mod.rs b/packages/rs-sdk/src/platform/dashpay/mod.rs index 4c663a40376..83352890a63 100644 --- a/packages/rs-sdk/src/platform/dashpay/mod.rs +++ b/packages/rs-sdk/src/platform/dashpay/mod.rs @@ -15,6 +15,7 @@ pub use contact_request::{ recipient_key_purpose_is_acceptable_on_receive, recipient_key_purpose_is_valid, sender_key_purpose_is_acceptable_on_receive, ContactRequestInput, ContactRequestResult, EcdhProvider, RecipientIdentity, SendContactRequestInput, SendContactRequestResult, + SignedContactRequest, }; pub use contact_request_queries::{ContactRequestDocuments, ResumableContactRequests}; pub use invitation::{ diff --git a/packages/rs-sdk/src/platform/private_document_scan.rs b/packages/rs-sdk/src/platform/private_document_scan.rs index d34ecebd882..165df66a837 100644 --- a/packages/rs-sdk/src/platform/private_document_scan.rs +++ b/packages/rs-sdk/src/platform/private_document_scan.rs @@ -14,8 +14,10 @@ //! decode and validate. `crate::platform::dashpay` does both for DashPay's private contact //! requests. +use std::collections::BTreeMap; use std::future::Future; use std::pin::Pin; +use std::sync::{Arc, Mutex, PoisonError}; use crate::error::StaleNodeError; use crate::platform::private_document_entries::{ @@ -436,8 +438,27 @@ pub struct PrivateDocumentPage { pub entries: PrivateDocumentEntries, } +/// The heights of the proofs of the reads a page of +/// [`Sdk::private_document_pages_with_heights`] holds: one read, or a read and those completing +/// it from where an older snapshot of the store ended. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct PrivateDocumentPageHeights { + /// The lowest: every read the page holds was proved at or above it, so the store held at + /// least the page's entries by then, and an entry absent from it was not appended by then. + pub min: u64, + /// The highest: no read the page holds was proved above it, so every entry it holds was + /// appended at or below it. + pub max: u64, +} + type PageFuture = Pin> + Send>>; type PageStream = Pin> + Send>>; +/// A page read with the height of the proof it was read with. +type HeightedPageFuture = + Pin> + Send>>; +type HeightedPageStream = Pin< + Box> + Send>, +>; /// Where a walk over a store's pages is. enum PageWalk { @@ -573,6 +594,64 @@ where ) } +/// [`private_document_page_walk`] over `fetch`, which reads a page with the height of its +/// proof, each page yielded with the lowest and highest heights of the reads it holds: the read +/// from its start, and those completing it from where an older snapshot ended +/// ([`whole_chunk_pages`]). A start fetched again keeps the height of its last read, the one +/// the walk kept. +fn private_document_page_walk_with_heights( + fetch: F, + start_position: u64, + max_concurrent: usize, +) -> impl Stream> + Send +where + F: Fn(u64) -> HeightedPageFuture + Clone + Send + Sync + 'static, +{ + // The height of the last read from each start, until the page holding + // that start is yielded. Pages hold disjoint ranges of positions, and + // every read a page holds starts inside its range. + let heights: Arc>> = Arc::default(); + let read_heights = Arc::clone(&heights); + let fetch = move |start: u64| -> PageFuture { + let fetch = fetch.clone(); + let heights = Arc::clone(&read_heights); + Box::pin(async move { + let (entries, height) = fetch(start).await?; + heights + .lock() + .unwrap_or_else(PoisonError::into_inner) + .insert(start, height); + Ok(entries) + }) + }; + private_document_page_walk(fetch, start_position, max_concurrent).map(move |page| { + let page = page?; + let start = page.start_position; + let end = start + .saturating_add(page.entries.entries.len() as u64) + .max(start.saturating_add(1)); + let mut heights = heights.lock().unwrap_or_else(PoisonError::into_inner); + let mut read = heights.split_off(&start); + let mut later = read.split_off(&end); + heights.append(&mut later); + drop(heights); + let heights = read + .contains_key(&start) + .then(|| { + let min = read.values().min().copied()?; + let max = read.values().max().copied()?; + Some(PrivateDocumentPageHeights { min, max }) + }) + .flatten() + .ok_or_else(|| { + Error::Generic(format!( + "no proved height for the private document page from position {start}" + )) + })?; + Ok((page, heights)) + }) +} + /// How many more times a page whose snapshot of the store ends at or before its start is /// fetched before the walk gives up on it ([`fetch_ahead_of`]). const BEHIND_PAGE_REFETCHES: usize = 2; @@ -754,6 +833,67 @@ impl Sdk { }) } + /// [`Self::private_document_pages`], with the heights each page's proofs were made at, from + /// the response metadata verified with them ([`PrivateDocumentPageHeights`]). A page + /// completed from more than one read, the first from a node behind, carries the lowest and + /// the highest of their heights: the lowest for a caller that must show every page, and the + /// store's end the first page reports, at or above a height; the highest for one that must + /// know a height no entry of the page was appended above. The pages and the walk are those + /// of [`Self::private_document_pages`]. + pub fn private_document_pages_with_heights( + &self, + data_contract_id: Identifier, + document_type_name: &str, + start_position: u64, + max_concurrent: usize, + ) -> impl Stream> + Send + { + let sdk = self.clone(); + let document_type_name = document_type_name.to_string(); + let resolve = { + let sdk = sdk.clone(); + let document_type_name = document_type_name.clone(); + async move { + sdk.fetch_private_document_contract(data_contract_id, &document_type_name) + .await + } + }; + stream::once(resolve).flat_map(move |resolved| -> HeightedPageStream { + match resolved { + Err(error) => Box::pin(stream::once(async move { Err(error) })), + Ok(_) => { + let sdk = sdk.clone(); + let document_type_name = document_type_name.clone(); + let fetch = move |start: u64| -> HeightedPageFuture { + let sdk = sdk.clone(); + let query = PrivateDocumentEntriesQuery::new( + data_contract_id, + document_type_name.clone(), + start, + ); + Box::pin(async move { + let (entries, metadata) = + PrivateDocumentEntries::fetch_with_metadata(&sdk, query, None) + .await?; + let entries = entries.ok_or_else(|| { + Error::Generic(format!( + "no page of the private document type of contract \ + {data_contract_id} from position {start}" + )) + })?; + Ok((entries, metadata.height)) + }) + }; + Box::pin(private_document_page_walk_with_heights( + fetch, + start_position, + max_concurrent, + )) + } + } + }) + } + /// Fetches the proved page of the store of the private type `document_type_name` of /// `data_contract_id` from `start_position`, and sorts its entries with `keys`. The context /// provider is given the contract with the type first when it lacks it @@ -1438,6 +1578,79 @@ mod tests { assert_eq!(positions, (0..30).collect::>()); } + /// A page completed from where an older snapshot ended carries the lower height of its two + /// reads as its lowest and the higher as its highest; every other page, the height of its + /// own as both. + #[tokio::test] + async fn should_yield_a_completed_page_with_the_lowest_and_highest_heights_of_its_reads() { + let fetch = |start: u64| -> HeightedPageFuture { + Box::pin(async move { + // The node answering the page from 12 is behind, at height 7: its store held + // 14 entries. The rest of that chunk, and every other page, come at height 9. + if start == 12 { + return Ok((drive_page(4, 14, start), 7)); + } + Ok((drive_page(4, 30, start), 9)) + }) + }; + let pages: Vec<(PrivateDocumentPage, PrivateDocumentPageHeights)> = + private_document_page_walk_with_heights( + fetch, + 0, + MAX_CONCURRENT_PRIVATE_DOCUMENT_PAGE_FETCHES, + ) + .map(|page| page.expect("every page reads")) + .collect() + .await; + let mut positions = Vec::new(); + for (page, heights) in &pages { + let expected = if page.start_position == 12 { + PrivateDocumentPageHeights { min: 7, max: 9 } + } else { + PrivateDocumentPageHeights { min: 9, max: 9 } + }; + assert_eq!(*heights, expected, "page from {}", page.start_position); + positions.extend(page.entries.entries.iter().map(|entry| entry.position)); + } + assert_eq!(positions, (0..30).collect::>()); + } + + /// A page fetched again, its first read from a node behind that held no entry from its + /// start, carries the height of the read the walk kept. + #[tokio::test] + async fn should_yield_a_page_fetched_again_at_the_height_of_its_kept_read() { + let behind_once = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(true)); + let fetch = move |start: u64| -> HeightedPageFuture { + let behind_once = std::sync::Arc::clone(&behind_once); + Box::pin(async move { + if start == 8 && behind_once.swap(false, std::sync::atomic::Ordering::SeqCst) { + return Ok((drive_page(4, 8, start), 5)); + } + Ok((drive_page(4, 30, start), 9)) + }) + }; + let pages: Vec<(PrivateDocumentPage, PrivateDocumentPageHeights)> = + private_document_page_walk_with_heights( + fetch, + 0, + MAX_CONCURRENT_PRIVATE_DOCUMENT_PAGE_FETCHES, + ) + .map(|page| page.expect("every page reads")) + .collect() + .await; + assert!( + pages + .iter() + .all(|(_, heights)| *heights == PrivateDocumentPageHeights { min: 9, max: 9 }), + "{:?}", + pages + .iter() + .map(|(page, heights)| (page.start_position, *heights)) + .collect::>() + ); + assert_eq!(pages.len(), 8); + } + /// A fetch of Drive's pages of a store of 30 entries in chunks of 4 where the fetch from /// `behind` is answered, its first `times` times, by a node whose store held `behind` /// entries: no entry from there. @@ -1688,6 +1901,111 @@ mod tests { ); } + /// Through the SDK, a page completed from where a node behind ended its snapshot carries the + /// height of that read as its lowest and the completing read's as its highest. + #[cfg(feature = "mocks")] + #[tokio::test] + async fn should_stream_a_completed_page_with_the_heights_of_both_its_reads() { + use crate::platform::private_document_entries::held_contract_provider::HeldContractProvider; + use crate::SdkBuilder; + use dpp::version::PlatformVersion; + + let mut sdk: Sdk = SdkBuilder::new_mock() + .with_version(PlatformVersion::latest()) + .with_context_provider(HeldContractProvider::new( + Some(contract_with_the_private_type()), + false, + )) + .build() + .expect("expected a mock sdk"); + let contract_id = Identifier::from(CONTRACT_ID); + // The node answering the page from 12 is a block behind, at height 8, within the SDK's + // tolerance: its store held 14 entries. The rest of that chunk, and every other page, + // come at height 9. + let query = |start| PrivateDocumentEntriesQuery::new(contract_id, TYPE_NAME, start); + for start in [0, 4, 8, 12, 14, 16, 20, 24, 28] { + let total = if start == 12 { 14 } else { 30 }; + sdk.mock() + .expect_fetch(query(start), Some(drive_page(4, total, start))) + .await + .expect("expected to register the page"); + } + sdk.mock() + .set_response_height(9) + .set_response_height_for::(query(12), 8); + let pages: Vec<(PrivateDocumentPage, PrivateDocumentPageHeights)> = sdk + .private_document_pages_with_heights(contract_id, TYPE_NAME, 0, 3) + .map(|page| page.expect("every page reads")) + .collect() + .await; + let mut positions = Vec::new(); + for (page, heights) in &pages { + let expected = if page.start_position == 12 { + PrivateDocumentPageHeights { min: 8, max: 9 } + } else { + PrivateDocumentPageHeights { min: 9, max: 9 } + }; + assert_eq!(*heights, expected, "page from {}", page.start_position); + positions.extend(page.entries.entries.iter().map(|entry| entry.position)); + } + assert_eq!(positions, (0..30).collect::>()); + } + + /// The pages read with their proved heights are those of the plain stream, in its order, + /// each with the height of the response its proof came with. + #[cfg(feature = "mocks")] + #[tokio::test] + async fn should_stream_each_page_with_its_proved_height() { + use crate::platform::private_document_entries::held_contract_provider::HeldContractProvider; + use crate::SdkBuilder; + use dpp::version::PlatformVersion; + + let mut sdk: Sdk = SdkBuilder::new_mock() + .with_version(PlatformVersion::latest()) + .with_context_provider(HeldContractProvider::new( + Some(contract_with_the_private_type()), + false, + )) + .build() + .expect("expected a mock sdk"); + let contract_id = Identifier::from(CONTRACT_ID); + for start in [2, 4, 8, 12] { + sdk.mock() + .expect_fetch( + PrivateDocumentEntriesQuery::new(contract_id, TYPE_NAME, start), + Some(drive_page(4, 14, start)), + ) + .await + .expect("expected to register the page"); + } + let plain: Vec = sdk + .private_document_pages(contract_id, TYPE_NAME, 2, 3) + .map(|page| page.expect("every page reads")) + .collect() + .await; + let with_heights: Vec<(PrivateDocumentPage, PrivateDocumentPageHeights)> = sdk + .private_document_pages_with_heights(contract_id, TYPE_NAME, 2, 3) + .map(|page| page.expect("every page reads")) + .collect() + .await; + assert_eq!( + with_heights + .iter() + .map(|(page, _)| page.clone()) + .collect::>(), + plain + ); + // The mock answers every page with the same response metadata. + let heights: Vec = + with_heights.iter().map(|(_, heights)| *heights).collect(); + assert_eq!(heights.len(), 4); + assert!(heights.iter().all(|heights| heights.min == heights.max)); + assert!( + heights.windows(2).all(|pair| pair[0] == pair[1]), + "{heights:?}" + ); + } + /// DashPay as the latest version has it, under the test contract's id: a contract that /// declares the private type the test entries are sealed for. #[cfg(feature = "mocks")] diff --git a/packages/rs-sdk/src/platform/transition/broadcast.rs b/packages/rs-sdk/src/platform/transition/broadcast.rs index 8cb64874b68..387989b8ae2 100644 --- a/packages/rs-sdk/src/platform/transition/broadcast.rs +++ b/packages/rs-sdk/src/platform/transition/broadcast.rs @@ -299,7 +299,7 @@ fn finish_broadcast( } /// Check the SAME signed transition after possible submission. No replacement is built here. -pub(super) async fn wait_after_broadcast( +pub(crate) async fn wait_after_broadcast( broadcast: Result<(), Error>, wait: impl Future>, ) -> Result { diff --git a/packages/rs-sdk/src/platform/transition/outcome/judge.rs b/packages/rs-sdk/src/platform/transition/outcome/judge.rs index 4fc68998213..c5b21af3bec 100644 --- a/packages/rs-sdk/src/platform/transition/outcome/judge.rs +++ b/packages/rs-sdk/src/platform/transition/outcome/judge.rs @@ -12,7 +12,8 @@ //! //! So a free input read at height `h` proves the transition had not executed by `h`, and a //! consumed one read at `h` proves it cannot execute after `h`. No read says which transition -//! took a consumed input, so none proves this one executed. +//! took a consumed input, so none proves this one executed; a read of what it would have +//! written, at or above that `h`, does. /// One proven read of one input: whether it is consumed, and the height the proof was signed at. #[derive(Debug, Clone, Copy, PartialEq, Eq)] @@ -27,7 +28,10 @@ pub(super) struct InputRead { #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub(super) enum Consumption { /// Every input is consumed. - All, + All { + /// The lowest height among the reads: the transition cannot execute after it. + consumed_by: u64, + }, /// An input was consumed while another was still free, as of a read at or after the read /// that showed it consumed. The transition consumes all of its inputs at once, so it did not /// execute, and the consumed input keeps it from ever executing. @@ -35,7 +39,11 @@ pub(super) enum Consumption { /// Some inputs are consumed and others free, but every free one was read at a lower height /// than every consumed one. The transition may have executed between the reads; it cannot /// execute any more. - Unordered, + Unordered { + /// The lowest height among the reads that showed an input consumed: the transition + /// cannot execute after it. + consumed_by: u64, + }, /// No input is consumed: the transition had not executed by `free_at`, the highest read. None { /// The highest height among the reads. @@ -57,9 +65,9 @@ pub(super) fn consumption(reads: &[InputRead]) -> Consumption { .map(|read| read.height) .max(); match (lowest_consumed, highest_free) { - (Some(_), None) => Consumption::All, + (Some(consumed_by), None) => Consumption::All { consumed_by }, (Some(consumed), Some(free)) if consumed <= free => Consumption::Partial, - (Some(_), Some(_)) => Consumption::Unordered, + (Some(consumed_by), Some(_)) => Consumption::Unordered { consumed_by }, (None, free) => Consumption::None { free_at: free.unwrap_or_default(), }, @@ -71,7 +79,11 @@ pub(super) fn consumption(reads: &[InputRead]) -> Consumption { pub(super) enum InputsVerdict { /// Every input is consumed, or the inputs are consumed in an order the reads cannot place: /// it can no longer execute, and the reads do not show whether it did. - ConsumedUnattributed, + ConsumedUnattributed { + /// The lowest height of a read that showed an input consumed: the transition cannot + /// execute after it. + consumed_by: u64, + }, /// An input another transition took: it never executed and never will. InputUsed, /// A shielded spend's anchor, proven recorded by an earlier height, is gone from its pool, @@ -110,9 +122,10 @@ pub(super) fn judge_shielded( match consumption(nullifiers) { // Every note it spends is spent, but other transitions can spend the same notes, all // together or each on its own, so the reads do not say this one executed. - Consumption::All => InputsVerdict::ConsumedUnattributed, + Consumption::All { consumed_by } | Consumption::Unordered { consumed_by } => { + InputsVerdict::ConsumedUnattributed { consumed_by } + } Consumption::Partial => InputsVerdict::InputUsed, - Consumption::Unordered => InputsVerdict::ConsumedUnattributed, Consumption::None { free_at } => { // A missing anchor proves pruned only from a read at or above a height by which the // anchor was recorded: a node below that height may simply not have recorded it yet, @@ -146,7 +159,9 @@ pub(super) fn judge_shielded( /// whether this transition took it. `reads` must not be empty. pub(super) fn judge_nonces(reads: &[InputRead]) -> InputsVerdict { match consumption(reads) { - Consumption::All | Consumption::Unordered => InputsVerdict::ConsumedUnattributed, + Consumption::All { consumed_by } | Consumption::Unordered { consumed_by } => { + InputsVerdict::ConsumedUnattributed { consumed_by } + } Consumption::Partial => InputsVerdict::InputUsed, Consumption::None { free_at } => InputsVerdict::NotYet { checked_at: free_at, @@ -227,7 +242,10 @@ mod tests { #[test] fn should_report_all_consumed_when_every_read_shows_its_input_taken() { - assert_eq!(consumption(&[consumed(10), consumed(12)]), Consumption::All); + assert_eq!( + consumption(&[consumed(10), consumed(12)]), + Consumption::All { consumed_by: 10 } + ); } #[test] @@ -255,7 +273,7 @@ mod tests { // Free at 10, consumed at 11: this transition may have taken both at 11. assert_eq!( consumption(&[free(10), consumed(11)]), - Consumption::Unordered + Consumption::Unordered { consumed_by: 11 } ); } @@ -264,7 +282,7 @@ mod tests { // Other transitions may have spent the same notes, together or one by one. assert_eq!( judge_shielded(&[consumed(20), consumed(20)], &[pruned(30)], Some(10)), - InputsVerdict::ConsumedUnattributed + InputsVerdict::ConsumedUnattributed { consumed_by: 20 } ); } @@ -284,7 +302,7 @@ mod tests { &[recorded(19), recorded(19)], None ), - InputsVerdict::ConsumedUnattributed + InputsVerdict::ConsumedUnattributed { consumed_by: 21 } ); } @@ -350,7 +368,7 @@ mod tests { // A paid failure consumes the nonce too, and so does any other transition signed with it. assert_eq!( judge_nonces(&[consumed(5)]), - InputsVerdict::ConsumedUnattributed + InputsVerdict::ConsumedUnattributed { consumed_by: 5 } ); } diff --git a/packages/rs-sdk/src/platform/transition/outcome/mod.rs b/packages/rs-sdk/src/platform/transition/outcome/mod.rs index 6c447727d56..cd954d2d070 100644 --- a/packages/rs-sdk/src/platform/transition/outcome/mod.rs +++ b/packages/rs-sdk/src/platform/transition/outcome/mod.rs @@ -92,8 +92,14 @@ pub enum TransitionOutcome { /// For a shielded spend every nullifier is spent; for a transition that takes nonces every /// nonce is used. /// - /// Never retry or release anything on this answer: it may be this very transition. - ExecutedOrSuperseded, + /// Never retry or release anything on this answer alone: it may be this very transition. + /// What it would have written, proved absent by a read at or above `consumed_by_height`, + /// shows it did not execute, or failed with a paid error. + ExecutedOrSuperseded { + /// The lowest height of a read that showed one of its inputs consumed: it cannot + /// execute after this height. + consumed_by_height: u64, + }, /// It did not execute and never will, for the given reason. CannotExecute(CannotExecuteReason), /// It had not executed when last read, and it may still execute. @@ -323,7 +329,11 @@ struct Reads { /// The answer the reads of one transition give. fn outcome_from(reads: Reads) -> Result { Ok(match reads.verdict { - InputsVerdict::ConsumedUnattributed => TransitionOutcome::ExecutedOrSuperseded, + InputsVerdict::ConsumedUnattributed { consumed_by } => { + TransitionOutcome::ExecutedOrSuperseded { + consumed_by_height: consumed_by, + } + } InputsVerdict::InputUsed => { TransitionOutcome::CannotExecute(CannotExecuteReason::InputUsed) } @@ -776,7 +786,10 @@ mod sdk_tests { .state_transition_outcome(&shielded_transfer(), OutcomeEvidence::default()) .await .expect("expected an outcome"); - assert_eq!(outcome, TransitionOutcome::ExecutedOrSuperseded); + assert!( + matches!(outcome, TransitionOutcome::ExecutedOrSuperseded { .. }), + "{outcome:?}" + ); assert!(outcome.is_final()); assert!(!outcome.proves_not_executed()); } @@ -937,7 +950,10 @@ mod sdk_tests { .state_transition_outcome(&credit_transfer(5), OutcomeEvidence::default()) .await .expect("expected an outcome"); - assert_eq!(outcome, TransitionOutcome::ExecutedOrSuperseded); + assert!( + matches!(outcome, TransitionOutcome::ExecutedOrSuperseded { .. }), + "{outcome:?}" + ); assert!(outcome.is_final()); assert!(!outcome.proves_not_executed()); } @@ -1037,7 +1053,10 @@ mod sdk_tests { .state_transition_outcome(&address_transfer(), OutcomeEvidence::default()) .await .expect("expected an outcome"); - assert_eq!(outcome, TransitionOutcome::ExecutedOrSuperseded); + assert!( + matches!(outcome, TransitionOutcome::ExecutedOrSuperseded { .. }), + "{outcome:?}" + ); } #[tokio::test] @@ -1133,16 +1152,24 @@ mod sdk_tests { ); } + /// The answer carries the height of the read that showed the nonce used, so a read of the + /// document at or above it can tell whether this batch wrote it. #[tokio::test] async fn should_not_attribute_a_document_batch_whose_contract_nonce_is_used() { let mut sdk = mock_sdk(); expect_contract_nonce(&mut sdk, 17).await; + sdk.mock().set_response_height(42); let outcome = sdk .state_transition_outcome(&document_batch(), OutcomeEvidence::default()) .await .expect("expected an outcome"); - assert_eq!(outcome, TransitionOutcome::ExecutedOrSuperseded); + assert_eq!( + outcome, + TransitionOutcome::ExecutedOrSuperseded { + consumed_by_height: 42 + } + ); } } diff --git a/packages/rs-sdk/src/platform/transition/put_document.rs b/packages/rs-sdk/src/platform/transition/put_document.rs index a3fb0a34ddb..665b51b8c2f 100644 --- a/packages/rs-sdk/src/platform/transition/put_document.rs +++ b/packages/rs-sdk/src/platform/transition/put_document.rs @@ -310,7 +310,7 @@ fn ensure_entropy_matches_document_id( /// Construct and sign once; dispatch is chosen by the calling API. #[allow(clippy::too_many_arguments)] -async fn prepare_document_state_transition>( +pub(crate) async fn prepare_document_state_transition>( document: &Document, sdk: &Sdk, document_type: DocumentType, diff --git a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerMasternodes.swift b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerMasternodes.swift index e0a072611b5..fc148865ad5 100644 --- a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerMasternodes.swift +++ b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerMasternodes.swift @@ -286,11 +286,12 @@ extension PlatformWalletManager { /// `ownerKeyIndexHint`: as on `masternodeWithdrawalKeys` — verified, not /// trusted. /// - /// Outcomes: a definitive rejection throws an ordinary error and may be - /// retried. An AMBIGUOUS outcome — broadcast accepted (or its ACK lost) - /// and the result wait failed — throws + /// Outcomes: only a failure before anything was sent throws an ordinary + /// error and may be retried. Once the withdrawal may have reached a node, + /// any outcome short of the proved balance (a failed result wait, a + /// node's refusal or a consensus verdict) throws /// `PlatformWalletError.masternodeWithdrawalUnconfirmed`: the claim may - /// have executed and the identity nonce was consumed, so callers must + /// have executed and a retry signs a second withdrawal, so callers must /// NOT retry until they have re-read the claimable balance. /// /// Pure bridge — the whole orchestration (masternode lookup, identity diff --git a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift index 617c00d1160..a6feb022840 100644 --- a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift +++ b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift @@ -2,13 +2,14 @@ import Foundation import DashSDKFFI /// Thrown by `shieldedIdentityCreateFromPool` when the Type-20 -/// transition was broadcast and ACCEPTED by the relay, but the SDK -/// could not confirm its execution result and a direct fetch of the -/// derived id also came back empty (the Rust side already retried). +/// transition may have reached a node (a broadcast a node accepted, a +/// send attempt that may have delivered it, a node's refusal or verdict), +/// its result is not proved, and a direct fetch of the derived id also +/// came back empty (the Rust side already retried). /// /// This is NOT a registration failure: the identity may already exist -/// on chain (the broadcast landed; only the result-proof confirmation -/// failed — e.g. a transient DAPI/proof error). The caller MUST hold +/// on chain or may still be created (its result is not proved, e.g. after +/// a transient DAPI/proof error or a node's refusal). The caller MUST hold /// the slot against re-submission and surface the pending identity /// rather than treating it as unregistered — re-registering the same /// keys while the identity is live would fail the registered-key-hash @@ -676,11 +677,12 @@ extension PlatformWalletManager { /// stays resident between spends (the launch-time bind is /// viewing-grade only). /// - /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` when the - /// broadcast was accepted but its execution result couldn't be - /// confirmed — the spend may already be on chain, so the caller - /// must NOT retry (the spent notes stay reserved Rust-side; the - /// next shielded sync reconciles them). + /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` once the + /// spend may have reached a node and its result is not proved (a + /// failed result wait, a node's refusal or consensus verdict + /// included): it may already be on chain or may still execute, so the + /// caller must NOT retry (the spent notes stay reserved Rust-side + /// until a later shielded sync resolves them). public func shieldedTransfer( walletId: Data, resolver: MnemonicResolver, @@ -848,12 +850,12 @@ extension PlatformWalletManager { /// Heavy CPU work (Halo 2 proof + per-input signing) runs on a /// detached task so the caller's actor isn't blocked. /// - /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` when the - /// broadcast was accepted but its execution result couldn't be - /// confirmed — the shield may already be on chain, so the caller - /// must NOT retry (a retry would rebuild the bundle and could - /// double-shield; the next sync reconciles the outcome). A shield - /// spends no notes, so nothing is reserved wallet-side. + /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` once the + /// shield may have reached a node and its result is not proved (a + /// node's refusal or consensus verdict, stale nonce included): it may + /// already be on chain, so the caller must NOT retry (a retry signs a + /// second transition). Its activity row stays pending until the + /// shielded scan sees its note; nothing is reserved wallet-side. public func shieldedShield( walletId: Data, shieldedAccount: UInt32 = 0, @@ -918,10 +920,11 @@ extension PlatformWalletManager { /// Heavy CPU work (Halo 2 proof + the identity signature) runs on a /// detached task so the caller's actor isn't blocked. /// - /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` when the - /// broadcast was accepted but its execution result couldn't be - /// confirmed: the shield may already be on chain, so the caller must - /// NOT retry (a retry would rebuild the bundle and could double-shield; + /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` once the + /// shield may have reached a node and its result is not proved (a + /// node's refusal or consensus verdict included): it may already be on + /// chain or may still execute, so the caller must + /// NOT retry (a retry signs a second transition; /// the next sync reconciles the outcome). Like every shield it spends /// no notes. An unresolved debit blocks a fresh shield from that identity /// with `.shieldedIdentityDebitPending`. Inspect durable records with @@ -1006,12 +1009,12 @@ extension PlatformWalletManager { /// or Rust rejects it. The 36-byte on-chain encoding is done on the /// Rust side. /// - /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` when the - /// broadcast was accepted but its execution result couldn't be - /// confirmed — the shield may already be on chain, so the caller - /// must NOT retry (a retry would rebuild the bundle and could - /// double-pay; the next sync reconciles the outcome). A shield - /// spends no notes, so nothing is reserved wallet-side. + /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` once the + /// shield may have reached a node and its result is not proved (a + /// node's refusal or consensus verdict, stale nonce included): it may + /// already be on chain, so the caller must NOT retry (a retry signs a + /// second transition). Its activity row stays pending until the + /// shielded scan sees its note; nothing is reserved wallet-side. public func shieldedShieldToRecipient( walletId: Data, shieldedAccount: UInt32 = 0, @@ -1086,11 +1089,12 @@ extension PlatformWalletManager { /// `resolver` supplies the per-operation Orchard spend authority /// (see [`shieldedTransfer`]). /// - /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` when the - /// broadcast was accepted but its execution result couldn't be - /// confirmed — the spend may already be on chain, so the caller - /// must NOT retry (the spent notes stay reserved Rust-side; the - /// next shielded sync reconciles them). + /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` once the + /// spend may have reached a node and its result is not proved (a + /// failed result wait, a node's refusal or consensus verdict + /// included): it may already be on chain or may still execute, so the + /// caller must NOT retry (the spent notes stay reserved Rust-side + /// until a later shielded sync resolves them). public func shieldedUnshield( walletId: Data, resolver: MnemonicResolver, @@ -1152,11 +1156,12 @@ extension PlatformWalletManager { /// supplies per operation (see [`shieldedTransfer`]), exactly as for /// [`shieldedUnshield`]. /// - /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` when the - /// broadcast was accepted but its execution result couldn't be - /// confirmed: the spend may already be on chain, so the caller must - /// NOT retry (the spent notes stay reserved Rust-side; the next - /// shielded sync reconciles them). + /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` once the + /// spend may have reached a node and its result is not proved (a + /// failed result wait, a node's refusal or consensus verdict + /// included): it may already be on chain or may still execute, so the + /// caller must NOT retry (the spent notes stay reserved Rust-side + /// until a later shielded sync resolves them). public func shieldedIdentityTopUpFromPool( walletId: Data, resolver: MnemonicResolver, @@ -1220,11 +1225,12 @@ extension PlatformWalletManager { /// `resolver` supplies the per-operation Orchard spend authority /// (see [`shieldedTransfer`]). /// - /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` when the - /// broadcast was accepted but its execution result couldn't be - /// confirmed — the spend may already be on chain, so the caller - /// must NOT retry (the spent notes stay reserved Rust-side; the - /// next shielded sync reconciles them). + /// Throws `PlatformWalletError.shieldedSpendUnconfirmed` once the + /// spend may have reached a node and its result is not proved (a + /// failed result wait, a node's refusal or consensus verdict + /// included): it may already be on chain or may still execute, so the + /// caller must NOT retry (the spent notes stay reserved Rust-side + /// until a later shielded sync resolves them). public func shieldedWithdraw( walletId: Data, resolver: MnemonicResolver, @@ -1412,9 +1418,9 @@ extension PlatformWalletManager { // would construct a second wrapper over the same struct and // double-free). Inspect the typed code directly: // - success: return the derived id. - // - unconfirmed: the broadcast landed but its result couldn't be - // confirmed; Rust filled `outIdentityId` with the derived id on - // THIS code (and only this code). Throw the typed + // - unconfirmed: the transition may have reached a node and its + // result is not proved; Rust filled `outIdentityId` with the + // derived id on THIS code (and only this code). Throw the typed // `ShieldedIdentityCreateUnconfirmedError` so the caller holds // the slot instead of treating it as failed. // - any other non-success: throw the regular typed error. diff --git a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift index 83f7c619202..6df07747d37 100644 --- a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift +++ b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletResult.swift @@ -21,23 +21,27 @@ public enum PlatformWalletResultCode: Int32, Sendable { case errorArithmeticOverflow = 13 case errorNoSelectableInputs = 14 case errorWalletAlreadyExists = 15 - /// Definitive shielded-broadcast failure: the shielded transition - /// (identity-create, unshield, transfer, or withdrawal) was not executed - /// (relay/CheckTx rejection or a platform-reported execution error), the - /// spent notes were released, and the caller may retry. + /// Definitive shielded-broadcast failure: the shielded transition never + /// left the wallet (refused before anything was sent: no node address, or + /// the SDK's own refusal), so it can never execute. Any reserved notes + /// were released and the caller may retry. A node's refusal or consensus + /// verdict is unconfirmed instead (18, or 17 for identity-create). case errorShieldedBroadcastFailed = 16 - /// Shielded broadcast accepted but its execution result could not be - /// confirmed; the identity may already exist on chain. The FFI also fills - /// the derived id into `outIdentityId` on this code, so the caller can - /// hold the slot rather than treat the registration as failed. + /// An identity create from the pool may have reached a node (accepted, a + /// send attempt that may have delivered it, a node's refusal or verdict), + /// its result is not proved and a direct fetch of the derived id came + /// back empty. The wallet keeps the notes reserved and the saved + /// transition. The identity may already exist on chain: do not treat it + /// as unregistered or re-submit. The FFI fills the derived id into + /// `outIdentityId` on this code, so the caller can hold the slot. case errorShieldedBroadcastUnconfirmed = 17 - /// A shielded operation (shield / unshield / transfer / withdrawal) was - /// accepted by the relay but its execution result could not be - /// confirmed. It may have executed on chain; for the spend-based - /// operations the wallet keeps the notes reserved (a shield reserves - /// nothing) until the next sync (or app restart) reconciles the - /// outcome. Do NOT auto-retry — a retry would rebuild the bundle and - /// could double-execute if the original landed. + /// A shielded operation (shield from Platform addresses, unshield / + /// transfer / withdrawal) may have reached a node and its result is not + /// proved: a failed result wait, a node's refusal or a consensus verdict + /// (a stale address nonce included). It may have executed. Spends keep + /// their notes reserved and the saved transition for the wallet to + /// resolve; a shield's activity row stays pending until the scan sees its + /// note. Do NOT auto-retry: a retry signs a second transition. case errorShieldedSpendUnconfirmed = 18 /// A shielded spend could not be built against a Platform-recorded anchor: /// the wallet's commitment tree isn't synced to a checkpoint Platform has @@ -51,12 +55,12 @@ public enum PlatformWalletResultCode: Int32, Sendable { /// before another submission. Core input protections do not apply to /// Platform state transitions. Do NOT auto-retry. case errorTransactionBroadcastUnconfirmed = 20 - /// A masternode (evonode) identity credit withdrawal was broadcast and - /// accepted, but its execution result could not be confirmed — it may - /// already have executed, and the identity nonce was consumed for it, so - /// a blind retry could submit a SECOND withdrawal. Do NOT retry; re-read - /// the claimable balance and reconcile first. Definitive rejections keep - /// their ordinary codes and stay retryable. + /// A masternode (evonode) identity credit withdrawal may have reached a + /// node and its remaining balance is not proved (a failed result wait, a + /// node's refusal or a consensus verdict included). It may have executed; + /// a retry signs a second withdrawal with the next identity nonce. Do NOT + /// retry; re-read the claimable balance first. Only a withdrawal that + /// failed before anything was sent keeps an ordinary, retryable code. case errorMasternodeWithdrawalUnconfirmed = 42 /// The deterministic masternode list isn't available yet (SPV not /// running or masternode sync incomplete), so a list-backed query such @@ -64,13 +68,13 @@ public enum PlatformWalletResultCode: Int32, Sendable { /// `spvProgress.masternodes` reports the list synced. /// (46 — 43/44/45 are held by the shielded-invite error trio, #4313.) case errorMasternodeListUnavailable = 46 - /// Definitively-failed address-nonce race: Platform rejected an - /// address-funds transition (shield, or identity top-up-from-addresses) - /// because the submitted address nonce raced Platform's expected value - /// (a lagging DAPI replica read). The transition did NOT execute and any - /// notes were released (a shield reserves none) — safe to retry; the retry - /// re-fetches the nonce and self-heals. The submitted/expected nonce values - /// travel in the message string, not as structured fields. + /// Address-nonce race: Platform rejected an address-funds transition (a + /// transfer or withdrawal from Platform addresses, or an identity + /// registration or top-up from them) because the submitted address nonce + /// raced Platform's expected value (a lagging DAPI replica read). Safe to + /// retry; the retry re-fetches the nonce and self-heals. A shield does not + /// return it (see `errorShieldedSpendUnconfirmed`). The submitted/expected + /// nonce values travel in the message string, not as structured fields. case errorAddressNonceMismatch = 21 /// Atomic Core selection found no or insufficient unreserved UTXOs. case errorCoreInsufficientFunds = 22 @@ -599,22 +603,25 @@ public enum PlatformWalletError: LocalizedError { /// recipient was recorded carry none and accept the caller's. case assetLockRecipientMismatch(String) case walletAlreadyExists(String) - /// Definitive shielded-broadcast failure: the shielded transition - /// (identity-create or a spend — unshield / transfer / withdrawal) was - /// not executed and the spent notes were released; safe to retry. + /// Definitive shielded-broadcast failure: the shielded transition never + /// left the wallet (refused before anything was sent), so it cannot + /// execute; any reserved notes were released and a retry is safe. case shieldedBroadcastFailed(String) - /// Shielded broadcast accepted but its execution result could not be - /// confirmed; the identity may already exist on chain. Callers that need - /// the derived id should special-case the + /// An identity create from the pool may have reached a node (a node's + /// refusal or verdict included), its result is not proved and a direct + /// fetch of the derived id came back empty. The wallet keeps the notes + /// reserved and the saved transition; the identity may already exist on + /// chain, so do not treat it as unregistered or re-submit. Callers that + /// need the derived id should special-case the /// `.errorShieldedBroadcastUnconfirmed` result code (which carries - /// `outIdentityId`) before falling back to this error — see + /// `outIdentityId`) before falling back to this error: see /// `ShieldedIdentityCreateUnconfirmedError`. case shieldedBroadcastUnconfirmed(String) - /// A shielded operation (shield / unshield / transfer / withdrawal) - /// was accepted by the relay but its execution result could not be - /// confirmed. It may have executed; spend-based operations keep their - /// notes reserved wallet-side (a shield reserves nothing) until the - /// next sync reconciles the outcome. Do NOT auto-retry. + /// A shielded operation (shield from Platform addresses, unshield / + /// transfer / withdrawal) may have reached a node and its result is not + /// proved (a node's refusal or consensus verdict included). It may have + /// executed; spends keep their notes reserved, a shield stays pending + /// until the scan sees its note. Do NOT auto-retry. case shieldedSpendUnconfirmed(String) /// A shielded spend could not be built against a Platform-recorded anchor — /// the wallet's commitment tree isn't synced to a checkpoint Platform has @@ -634,10 +641,10 @@ public enum PlatformWalletError: LocalizedError { /// protections; Platform state transitions have no Core UTXO reservation. /// Do NOT auto-retry. Sibling of `shieldedSpendUnconfirmed`. case transactionBroadcastUnconfirmed(String) - /// A masternode (evonode) credit withdrawal was broadcast and accepted - /// but its result could not be confirmed. It may already have executed - /// and the identity nonce was consumed — do NOT retry; re-read the - /// claimable balance first (`.errorMasternodeWithdrawalUnconfirmed`). + /// A masternode (evonode) credit withdrawal may have reached a node and + /// its result is not proved (a node's refusal or verdict included). It may + /// have executed and a retry signs a second withdrawal: do NOT retry; + /// re-read the claimable balance first (`.errorMasternodeWithdrawalUnconfirmed`). case masternodeWithdrawalUnconfirmed(String) /// The masternode list hasn't synced yet, so there is nothing to look a /// masternode up in (`.errorMasternodeListUnavailable`). Retry after @@ -646,12 +653,12 @@ public enum PlatformWalletError: LocalizedError { /// Core definitively rejected the transaction and its input reservation /// was released. Unlike `transactionBroadcastUnconfirmed`, retry is safe. case transactionBroadcastRejected(String) - /// Definitively-failed address-nonce race (shield, or identity - /// top-up-from-addresses): Platform rejected the transition because the - /// submitted address nonce raced its expected value. The transition did - /// NOT execute and any notes were released (a shield reserves none) — safe - /// to retry, and the retry re-fetches the address nonce so the mismatch - /// self-heals. The submitted/expected nonce values are in the message. + /// Address-nonce race (transfer or withdrawal from Platform addresses, or + /// identity registration / top-up from them): Platform rejected the + /// transition because the submitted address nonce raced its expected + /// value. Safe to retry: the retry re-fetches the address nonce so the + /// mismatch self-heals. A shield does not return it. The submitted and + /// expected nonce values are in the message. case addressNonceMismatch(String) /// A quiesce/drain barrier (Clear / reset / sync-stop) timed out with a /// sync pass still in flight. The operation failed closed — retry once diff --git a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/ViewModels/SendViewModel.swift b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/ViewModels/SendViewModel.swift index d86c0f13e05..8304a48e2d1 100644 --- a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/ViewModels/SendViewModel.swift +++ b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/ViewModels/SendViewModel.swift @@ -831,11 +831,11 @@ class SendViewModel: ObservableObject { } catch PlatformWalletError.shieldedSpendUnconfirmed { // The shielded operation (shield / unshield / transfer / withdraw) - // was broadcast and accepted, but its execution result couldn't be - // confirmed — it may already be on chain. Rust intentionally KEEPS - // any spent notes' reservations, so this must NOT be presented as a - // retryable failure: retrying would rebuild the bundle and could - // double-execute if the original landed. Surface it through the + // may have reached a node and its result is not proved (a node's + // refusal or verdict included), so it may already be on chain. Rust + // intentionally KEEPS any spent notes' reservations, so this must + // NOT be presented as a retryable failure: a retry signs a second + // transition. Surface it through the // non-error (success) path so the UI doesn't invite a retry; the // next shielded sync reconciles the outcome. successMessage = "Transaction may have gone through — waiting for " diff --git a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/MasternodeDetailView.swift b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/MasternodeDetailView.swift index e1cf8cdbf17..7cfc03cc01c 100644 --- a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/MasternodeDetailView.swift +++ b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Core/Views/MasternodeDetailView.swift @@ -433,13 +433,13 @@ struct MasternodeDetailView: View { // Reflect the new (reduced) balance. await fetchClaimableBalance() } catch PlatformWalletError.masternodeWithdrawalUnconfirmed(let detail) { - // Ambiguous: the claim may have executed and the nonce was - // consumed — never re-submit blindly. Confirm stays disabled + // Ambiguous: the claim may have executed and its nonce may have + // been taken, so never re-submit blindly. Confirm stays disabled // until the balance is refreshed. claiming = false claimOutcomeUnconfirmed = true - claimError = "The withdrawal was submitted but its result couldn't be confirmed — " - + "it may have gone through. Refresh the balance before trying again. (\(detail))" + claimError = "The withdrawal may have reached the network, but its result couldn't be " + + "confirmed: it may have gone through. Refresh the balance before trying again. (\(detail))" } catch { claiming = false claimError = error.localizedDescription diff --git a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Services/IdentityRegistrationController.swift b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Services/IdentityRegistrationController.swift index 86ee5b1898a..414be98a59d 100644 --- a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Services/IdentityRegistrationController.swift +++ b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Services/IdentityRegistrationController.swift @@ -53,11 +53,11 @@ final class IdentityRegistrationController: ObservableObject { /// the coordinator's map until the user dismisses it /// manually. case failed(String) - /// Broadcast-succeeded-but-confirmation-failed terminal state - /// (shielded Type-20 only). The transition was relayed and - /// accepted, but its execution-result proof couldn't be - /// confirmed and a direct fetch of the derived id also came - /// back empty (Rust already retried). The identity at + /// Unconfirmed terminal state (shielded Type-20 only). The + /// transition may have reached a node (a node's refusal or + /// verdict included), its result is not proved, and a direct + /// fetch of the derived id also came back empty (Rust already + /// retried). The identity at /// `identityId` MAY already be live on chain. /// /// This is NOT a red failure: treating it as unregistered is @@ -85,7 +85,7 @@ final class IdentityRegistrationController: ObservableObject { /// which the identity-slot anti-join already covers. /// `.failed` is NOT active either: the user is expected /// to retry, so the lock should resurface for selection. - /// `.unconfirmed` IS active: the identity is probably live on + /// `.unconfirmed` IS active: the identity may be live on /// chain, so the slot must stay held to block a re-submission /// that would burn funds against the registered-key-hash check. var isActive: Bool { @@ -102,10 +102,11 @@ final class IdentityRegistrationController: ObservableObject { /// `RegistrationProgressView` can attribute the red marker to the /// right step. Only meaningful for `fundingKind == .shieldedPool`. /// - /// Deliberately only ONE case: `.broadcastRejected` is the single + /// Deliberately only ONE case: `.broadcastNotSent` is the single /// failure shape we can attribute with confidence (a typed - /// `PlatformWalletError.shieldedBroadcastFailed`). We cannot honestly - /// claim a "before broadcast" stage by elimination — Rust build/proof + /// `PlatformWalletError.shieldedBroadcastFailed`: the transition was + /// refused before anything was sent). We cannot honestly claim a + /// "before broadcast" stage by elimination: Rust build/proof /// errors arrive as a generic `.walletOperation`, indistinguishable at /// this layer from an invalid handle, a marshalling failure, or any other /// non-broadcast error. So `failureStage` is left `nil` for everything @@ -113,10 +114,10 @@ final class IdentityRegistrationController: ObservableObject { /// Extensible: add a case here only when a new typed error actually lets /// us attribute the stage with certainty. enum FailureStage { - /// Platform definitively rejected the broadcast transition (a - /// `PlatformWalletError.shieldedBroadcastFailed`). Attributed to - /// the "Broadcasting transition" step. - case broadcastRejected + /// The transition was refused before anything was sent (a + /// `PlatformWalletError.shieldedBroadcastFailed`), so it never left + /// the wallet. Attributed to the "Broadcasting transition" step. + case broadcastNotSent } /// Current phase. Updates flow: @@ -126,7 +127,7 @@ final class IdentityRegistrationController: ObservableObject { /// Stage attribution for a shielded `.failed` phase. `nil` means /// "unattributed" — either the phase isn't a shielded failure, or the - /// failure wasn't a confidently-attributable broadcast rejection. On a + /// failure wasn't a confidently-attributable refusal before sending. On a /// `nil` shielded failure the progress view falls back to its /// elapsed-time heuristic (note-selection vs Halo 2 proof). Reset at the /// start of every `submit` so a retry doesn't inherit the previous @@ -192,7 +193,7 @@ final class IdentityRegistrationController: ObservableObject { /// - `.completed`: re-submitting after success would flip the /// UI from "Done" back to a spinner before failing on the /// consumed lock. - /// - `.unconfirmed`: the identity is probably already live on + /// - `.unconfirmed`: the identity may already be live on /// chain; re-submitting the same keys would fail the /// registered-key-hash stateful check and burn the funds. /// `.idle`, `.preparingKeys`, and `.failed` are allowed — the @@ -204,10 +205,11 @@ final class IdentityRegistrationController: ObservableObject { /// background priority and reports the identity id on success /// or rethrows on failure. The controller flips `phase` to /// `.completed` / `.unconfirmed` / `.failed` accordingly. On a shielded - /// `.failed` it records `failureStage = .broadcastRejected` ONLY for a - /// `PlatformWalletError.shieldedBroadcastFailed`; every other error leaves - /// `failureStage` nil (unattributed — the progress view uses its - /// elapsed-time heuristic) rather than guessing a stage by elimination. + /// `.failed` it records `failureStage = .broadcastNotSent` ONLY for a + /// `PlatformWalletError.shieldedBroadcastFailed` (refused before anything + /// was sent); every other error leaves `failureStage` nil (unattributed: + /// the progress view uses its elapsed-time heuristic) rather than + /// guessing a stage by elimination. func submit(body: @escaping () async throws -> Data) { switch phase { case .idle, .preparingKeys, .failed: @@ -229,9 +231,9 @@ final class IdentityRegistrationController: ObservableObject { self?.phase = .completed(identityId: identityId) } } catch let unconfirmed as ShieldedIdentityCreateUnconfirmedError { - // Broadcast landed but its result couldn't be confirmed and - // Rust's direct fetch came back empty. Hold the slot; the - // identity probably exists and will surface on the next sync. + // The transition may have reached a node; its result is not + // proved and Rust's direct fetch came back empty. Hold the slot; + // the identity may exist and would surface on a later sync. await MainActor.run { self?.terminalAt = Date() self?.phase = .unconfirmed( @@ -240,15 +242,15 @@ final class IdentityRegistrationController: ObservableObject { ) } } catch { - // Only a `shieldedBroadcastFailed` is a confidently-attributable - // broadcast rejection → mark the broadcast step. Everything else - // (Rust build / Halo 2 proof errors, which surface as a generic + // Only a `shieldedBroadcastFailed` (refused before anything was + // sent) is confidently attributable: mark the broadcast step. + // Everything else (Rust build / Halo 2 proof errors, which surface as a generic // `.walletOperation`, plus invalid-handle / marshalling failures) // is indistinguishable at this layer, so leave `failureStage` nil // and let the progress view's elapsed-time heuristic place it. let stage: FailureStage? if case PlatformWalletError.shieldedBroadcastFailed = error { - stage = .broadcastRejected + stage = .broadcastNotSent } else { stage = nil } diff --git a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/CreateIdentityView.swift b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/CreateIdentityView.swift index d47274cd161..5c5d8974477 100644 --- a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/CreateIdentityView.swift +++ b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/CreateIdentityView.swift @@ -480,7 +480,7 @@ struct CreateIdentityView: View { Section { VStack(alignment: .leading, spacing: 8) { Label( - "Broadcast succeeded — confirmation pending", + "Result not confirmed", systemImage: "exclamationmark.triangle.fill" ) .foregroundColor(.orange) @@ -494,10 +494,10 @@ struct CreateIdentityView: View { .foregroundColor(.primary) .textSelection(.enabled) Text( - "The transition was broadcast and accepted, but its " - + "execution-result proof couldn't be confirmed. The " - + "identity will appear in the Identities tab after the " - + "next sync. Do NOT re-register these keys — the slot " + "The transition may have reached the network, but its " + + "result couldn't be confirmed. If it went through, the " + + "identity will appear in the Identities tab after a " + + "later sync. Do NOT re-register these keys: the slot " + "is held to prevent burning funds." ) .font(.caption) @@ -1541,8 +1541,8 @@ struct CreateIdentityView: View { // the inline failure state. return case .unconfirmed: - // Broadcast landed but its result couldn't be confirmed; - // the identity is probably already live on chain. Mark the + // The transition may have reached a node; its result is not + // proved, and the identity may already be live on chain. Mark the // slot used (same as `.completed`) — `usedIdentityIndices` // unions the persisted `isUsed` reservation with the // `PersistentIdentity` rows, so this is the reservation @@ -2134,8 +2134,8 @@ struct CreateIdentityView: View { /// identity-registration account. /// /// The union matters for `.unconfirmed` Type-20 registrations: the - /// broadcast landed but no `PersistentIdentity` row exists until the - /// next sync confirms the identity, so `markIdentitySlotUsed`'s + /// transition may have reached a node, yet no `PersistentIdentity` row + /// exists until the next sync confirms it, so `markIdentitySlotUsed`'s /// persisted `isUsed` flag is the ONLY artifact holding the slot once /// the in-memory controller is gone. Without it the same index would /// be offered again and a duplicate submission would burn funds diff --git a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/RegistrationProgressView.swift b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/RegistrationProgressView.swift index ca36b281edb..6a9d6e05e6c 100644 --- a/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/RegistrationProgressView.swift +++ b/packages/swift-sdk/SwiftExampleApp/SwiftExampleApp/Views/RegistrationProgressView.swift @@ -39,7 +39,7 @@ import SwiftDashSDK /// Step 4 ("Waiting for platform confirmation") exists so a /// post-broadcast confirmation failure is attributed there — NOT to the /// Halo 2 proof step — and so the `.unconfirmed` terminal state (the -/// broadcast landed but its result couldn't be confirmed) has a step to +/// transition may have reached a node but its result is not proved) has a step to /// render an orange warning on while steps 1–3 stay done and step 5 /// stays pending. /// @@ -253,7 +253,7 @@ struct RegistrationProgressSection: View { /// On `.completed` return 6 (one past the last step) so all rows /// render `.done`. On `.unconfirmed` return 4 ("Waiting for platform /// confirmation") so that step carries the warning. On `.failed` - /// attribute the step: a `.broadcastRejected` failure marks step 3 + /// attribute the step: a `.broadcastNotSent` failure marks step 3 /// ("Broadcasting transition"); an UNATTRIBUTED failure /// (`failureStage == nil` — build / Halo 2 proof errors, or any other /// error we can't confidently place) keeps the note-selection vs Halo 2 @@ -269,21 +269,21 @@ struct RegistrationProgressSection: View { case .completed: return 6 case .unconfirmed: - // Broadcast landed; only the result confirmation failed. + // The transition may have reached a node; its result is not proved. // Attribute to the "Waiting for platform confirmation" step. return 4 case .inFlight: return shieldedStep(elapsedTo: now) case .failed: - // A definitive broadcast rejection (`failureStage == - // .broadcastRejected`) is attributed to the broadcast step (3). + // A refusal before anything was sent (`failureStage == + // .broadcastNotSent`) is attributed to the broadcast step (3). // For an unattributed failure (`failureStage == nil` — build / // Halo 2 proof errors, or any other error we can't confidently // place), keep the elapsed-time heuristic (note-selection vs // proof) — frozen at the failure instant; fall back to `now` only // if the terminal timestamp is missing (pre-submit failure shapes // never set it). - if controller.failureStage == .broadcastRejected { + if controller.failureStage == .broadcastNotSent { return 3 } return shieldedStep(elapsedTo: controller.terminalAt ?? now) @@ -386,10 +386,10 @@ struct RegistrationProgressSection: View { /// fallback — visually distinguishable so users don't think /// the step "didn't happen yet" once we've moved past it. /// `.warning` (orange triangle) marks the "Waiting for platform - /// confirmation" step when the broadcast landed but its result - /// couldn't be confirmed (the shielded `.unconfirmed` terminal + /// confirmation" step when the transition may have reached a node but + /// its result is not proved (the shielded `.unconfirmed` terminal /// state) — distinct from `.failed` because nothing is actually - /// wrong; the identity is probably live on chain. + /// wrong; the identity may be live on chain. enum StepState { case done, active, pending, skipped, failed, warning } private func stepState( @@ -483,7 +483,7 @@ struct RegistrationProgressSection: View { .foregroundColor(.red) .font(.title3) case .warning: - // Broadcast landed but its result couldn't be confirmed — + // The transition may have reached a node; its result is not proved: // not an error, so an orange triangle, not the red octagon. Image(systemName: "exclamationmark.triangle.fill") .foregroundColor(.orange) @@ -607,14 +607,14 @@ struct RegistrationProgressView: View { Section { VStack(alignment: .leading, spacing: 8) { Label( - "Broadcast succeeded — confirmation pending", + "Result not confirmed", systemImage: "exclamationmark.triangle.fill" ) .foregroundColor(.orange) .font(.headline) // Same base58 styling as the completed case — the id is // the derived identity id Rust handed back; the identity - // is probably already live on chain. + // may already be live on chain. Text(identityId.toBase58String()) .font(.system(.caption, design: .monospaced)) .foregroundColor(.secondary) @@ -624,12 +624,11 @@ struct RegistrationProgressView: View { .foregroundColor(.primary) .textSelection(.enabled) Text( - "The transition was broadcast and accepted, but its " - + "execution-result proof couldn't be confirmed. The " - + "identity above will appear in the Identities tab " - + "after the next sync. Do NOT re-submit — the slot is " - + "held to prevent burning funds against a duplicate " - + "registration." + "The transition may have reached the network, but its " + + "result couldn't be confirmed. If it went through, the " + + "identity above will appear in the Identities tab after " + + "a later sync. Do NOT re-submit: the slot is held to " + + "prevent burning funds against a duplicate registration." ) .font(.caption) .foregroundColor(.secondary) diff --git a/packages/swift-sdk/SwiftExampleApp/SwiftExampleAppTests/CreateIdentityResumableTests.swift b/packages/swift-sdk/SwiftExampleApp/SwiftExampleAppTests/CreateIdentityResumableTests.swift index 5514b577eb6..3dc6674d50a 100644 --- a/packages/swift-sdk/SwiftExampleApp/SwiftExampleAppTests/CreateIdentityResumableTests.swift +++ b/packages/swift-sdk/SwiftExampleApp/SwiftExampleAppTests/CreateIdentityResumableTests.swift @@ -419,7 +419,7 @@ final class CreateIdentityResumableTests: XCTestCase { identityIndex: 1, fundingKind: .shieldedPool ) { - throw PlatformWalletError.shieldedBroadcastFailed("rejected on merits") + throw PlatformWalletError.shieldedBroadcastFailed("no node address to send to") } for _ in 0..<200 { if case .failed = failing.phase { break }