Repository navigation
Description
Expected Behavior
platform_wallet_manager_shielded_fund_from_wallet_drain and its Swift wrapper PlatformWalletManager.shieldedFundFromWalletDrain accept an optional built-lock callback. It works the same way as the other fresh-lock funding calls since #5476 (shieldedFundFromAssetLock, shieldedFundFromCoinJoinDrain, fundFromCore): the callback receives the new lock's outpoint once the transaction is signed, before the lock's row is persisted or broadcast.
Current Behavior
The Rust core already reports a drain's lock. The AssetLockBuiltObserver contract covers DrainWalletBalance, and the observer runs before the drain's row is stored durably:
platform/packages/rs-platform-wallet/src/wallet/asset_lock/build.rs
Lines 36 to 73 in b0ccf7b
| /// Callback that receives the outpoint of an asset lock built for a | |
| /// [`AssetLockFunding::FromWalletBalance`](super::AssetLockFunding::FromWalletBalance), | |
| /// [`AssetLockFunding::DrainAccountBalance`](super::AssetLockFunding::DrainAccountBalance) or | |
| /// [`AssetLockFunding::DrainWalletBalance`](super::AssetLockFunding::DrainWalletBalance) request. It runs synchronously | |
| /// once the transaction is signed, before the lock's row is persisted or the | |
| /// lock is broadcast. A caller that watches persisted lock rows uses it to | |
| /// tell its own new lock apart from rows the wallet re-inserts during | |
| /// recovery; it must record the outpoint before returning, durably if that | |
| /// distinction has to survive a restart. The ordering covers persisted rows | |
| /// only, and only for calls that pass an observer: a fresh lock from a call | |
| /// that passes none (identity registration and top-up, a generic funded | |
| /// proof, a wallet drain over FFI) also appears as a row nobody reported. | |
| /// | |
| /// It runs while the wallet serializes asset-lock builds, so it must not | |
| /// block and must not call back into the wallet: another build would wait | |
| /// for it. It runs at most once per call and must not panic. | |
| /// | |
| /// - Without an operation context (`FromWalletBalance`, | |
| /// `DrainAccountBalance`) the lock is tracked in memory first, so | |
| /// in-memory listings can show it just before the callback runs, and its | |
| /// row is queued best-effort afterwards. The callback does not run when | |
| /// the wallet is gone at tracking. A lock whose broadcast then fails is | |
| /// removed again after a definite rejection; otherwise it stays tracked | |
| /// and can be resumed by its outpoint (a resume may then find it already | |
| /// consumed). Both hold in memory; on disk they hold only when the | |
| /// best-effort row store or removal succeeded, so after a restart a | |
| /// failed store can leave no row for a broadcast lock, or the row of a | |
| /// removed one. | |
| /// - For a wallet drain (`DrainWalletBalance`) the callback runs before the | |
| /// row is stored durably and before the lock is tracked. If that store | |
| /// fails, the lock is not tracked and is recovered by resuming the drain | |
| /// with the same operation UUID, not by its outpoint. | |
| /// | |
| /// It does not run for [`AssetLockFunding::FromExistingAssetLock`](super::AssetLockFunding::FromExistingAssetLock) (a resumed | |
| /// drain included), whose outpoint the caller already holds, nor when the | |
| /// build itself fails or is abandoned before the outpoint is handed out. | |
| pub type AssetLockBuiltObserver<'a> = dyn Fn(OutPoint) + Send + Sync + 'a; |
The FFI drops it. It passes None with the note that the caller persisted the operation UUID and that out_outcome reports the outpoint:
platform/packages/rs-platform-wallet-ffi/src/shielded_wallet_drain.rs
Lines 173 to 181 in b0ccf7b
| #[no_mangle] | |
| pub unsafe extern "C" fn platform_wallet_manager_shielded_fund_from_wallet_drain( | |
| handle: Handle, | |
| wallet_id_bytes: *const u8, | |
| operation_id_bytes: *const u8, | |
| account_index: u32, | |
| recipient_raw_43: *const u8, | |
| core_signer_handle: *mut MnemonicResolverHandle, | |
| out_outcome: *mut WalletDrainOutcomeFFI, |
platform/packages/rs-platform-wallet-ffi/src/shielded_wallet_drain.rs
Lines 240 to 248 in b0ccf7b
| None, | |
| 0, | |
| None, | |
| None, | |
| // No built-lock observer: the caller persisted the | |
| // operation UUID before this call, the lock's row | |
| // carries it, and `out_outcome` reports the outpoint. | |
| None, | |
| ) |
out_outcome arrives only when the call returns. Since #5460, that can be minutes after the lock was broadcast: an oversized InstantSend proof falls back to waiting for a ChainLock. For that whole time the lock's row looks exactly like a stuck lock, at status Broadcast or InstantSend-locked. A host that offers "finish this transfer" for stuck locks therefore offers it for a drain that is still running, and a tap starts a second resume of the same lock. The wallet's shield_guard queues that resume behind the drain, so nothing is spent twice. The resume then blocks for the rest of the wait and ends as "already consumed".
The Swift wrapper has no parameter to pass a callback even if the FFI took one:
Lines 133 to 142 in b0ccf7b
| /// Drain the permitted transparent accounts into a single Orchard recipient. | |
| /// Persist `operationId` before calling. A repeated UUID identifies the same | |
| /// operation and must never be replaced with a new UUID after an unknown result. | |
| /// The SDK determines the amount and durably associates the lock before dispatch. | |
| public func shieldedFundFromWalletDrain( | |
| walletId: Data, | |
| operationId: UUID, | |
| fundingAccountIndex: UInt32 = 0, | |
| recipientRaw43: Data | |
| ) async -> WalletDrainOutcome { |
Compare shieldedFundFromAssetLock:
Lines 135 to 142 in b0ccf7b
| public func shieldedFundFromAssetLock( | |
| walletId: Data, | |
| fundingAccountIndex: UInt32, | |
| amountDuffs: UInt64, | |
| recipients: [ShieldedFundFromAssetLockRecipient], | |
| surplusOutput: Data? = nil, | |
| onAssetLockBuilt: AssetLockBuiltHandler? = nil | |
| ) async throws { |
Possible Solution
- FFI. Add
on_asset_lock_built: AssetLockBuiltFnandon_asset_lock_built_context: *mut c_voidtoplatform_wallet_manager_shielded_fund_from_wallet_drain, asplatform_wallet_manager_shielded_fund_from_asset_lockdoes. Wrap them withobserver_refand pass the observer instead ofNone. Both may be null.- This changes the C ABI in place, as feat(platform-wallet)!: report a freshly built asset lock's outpoint to the caller #5476 did, so the generated header and the Swift call site change together.
- Swift. Add
onAssetLockBuilt: AssetLockBuiltHandler? = niltoshieldedFundFromWalletDrainand forward it like the other funding calls do. - Contract. The observer semantics stay as documented for
DrainWalletBalance:- it fires at most once;
- it fires before the durable row store;
- it does not fire when a repeated UUID resumes an existing lock (
FromExistingAssetLock), because the host already holds that outpoint from the earlier call or from the status read.
- Tests. Extend the wiring tests added in feat(platform-wallet)!: report a freshly built asset lock's outpoint to the caller #5476 to the drain entry point: the callback fires once with the outpoint
out_outcomelater reports; a null callback is accepted; a repeated UUID does not fire it.
No Kotlin/JNI change is needed: rs-unified-sdk-jni does not expose the wallet drain.
Alternatives Considered
-
Host-side claim by operation UUID. This is what dashwallet-ios does today (fix(wallet): show a completing shielded transfer as an ordinary internal transfer dashwallet-ios#1212). The host:
- claims the drain's operation id before the call;
- has every reader carry the row's
operation_idfrom its snapshot of the lock rows; - re-checks the authoritative row before a resume;
- holds the claim after a completed drain until the row leaves the pending statuses.
It works, but it is a second claim mechanism next to the outpoint one. Each reader has to thread the id through, and forgetting it fails open. With this callback the host claims the drain's lock by outpoint, like every other fresh lock, and all of that goes.
-
An SDK-side registry of the locks a running call is consuming (platform-wallet: expose which tracked asset locks a running funding call is consuming #5477). This would make both the outpoint claims and this callback unnecessary for that purpose. It is the larger change and is still open. This issue is the narrow step that brings the drain in line with the other funding calls in the meantime.
-
A unified, operation-keyed host notification model (platform-wallet: one notification model for hosts — asset-lock lifecycle events keyed by operation id through the event bus #5539). This would also cover it, but it is a broader redesign.
Additional Context
- Related: feat(platform-wallet)!: report a freshly built asset lock's outpoint to the caller #5476 (built-lock callback for the other funding calls), fix(platform-wallet): retry an oversized InstantSend asset-lock transition with a ChainLock proof #5460 (ChainLock fallback that makes the wait long), platform-wallet: expose which tracked asset locks a running funding call is consuming #5477, platform-wallet: one notification model for hosts — asset-lock lifecycle events keyed by operation id through the event bus #5539.
- App side: fix(wallet): show a completing shielded transfer as an ordinary internal transfer dashwallet-ios#1212.
Activity
chore: merge develop into fix/shielded-transfer-in-flight-row