Skip to content

feat(platform-wallet): report the wallet drain's built asset lock to the caller, as the other funding calls do #5737

Open

Description

@romchornyi

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:

/// 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:

#[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,

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:

/// 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:

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: AssetLockBuiltFn and on_asset_lock_built_context: *mut c_void to platform_wallet_manager_shielded_fund_from_wallet_drain, as platform_wallet_manager_shielded_fund_from_asset_lock does. Wrap them with observer_ref and pass the observer instead of None. Both may be null.
  • Swift. Add onAssetLockBuilt: AssetLockBuiltHandler? = nil to shieldedFundFromWalletDrain and 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_outcome later 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

Additional Context

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions