Skip to content

Asset-lock ChainLock finality wait has no per-record promotion and no cancellation — stuck locks unrecoverable, app shutdown hangs #4238

Open

Description

@Claudius-Maginificent

TL;DR: The asset-lock finality wait (wait_for_chain_lock/wait_for_proof in rs-platform-wallet) can get permanently stuck waiting for a ChainLock promotion that never happens, and — because it has no cancellation signal — that same stuck wait also blocks the host application from shutting down cleanly.

User story

As a developer integrating platform-wallet (e.g. a wallet app funding an identity or shielding funds from an asset lock), I want the finality wait to (a) actually promote a tracked lock once its transaction is ChainLocked, and (b) be cancellable on shutdown, so that a missed InstantSend lock never permanently strands funds and never prevents the host app from closing.

Scenario

Base flow

A host app broadcasts a Type-8 asset-lock transaction and calls into platform-wallet to wait for finality proof: an InstantSend lock first, falling back to a ChainLock-based proof if the IS-lock doesn't arrive within the timeout.

Actual behavior

  • If the IS-lock wait times out, the fallback enters wait_for_chain_lock's indefinite wait. That function only promotes a per-record proof when TransactionContext::InChainLockedBlock is applied through account application — but ChainLockProcessed events can fire with accounts=0, finalized_txids=0, in which case no record is ever promoted, even though the wallet-level last_applied_chain_lock metadata is healthy and the transaction is demonstrably ChainLocked on-chain. The wait then never resolves.
  • Retrying via resume_asset_lock's defensive re-broadcast re-triggers SPV mempool detection and overwrites the persisted TransactionContext back to Mempool, erasing whatever height the record had — so even wait_for_proof's catch-up fallback (which needs a known local height) is self-defeated on retry.
  • Separately, wait_for_chain_lock's unbounded arm (None => { notified.as_mut().await; continue; }) awaits only its own internal notify. No cancellation primitive exists anywhere in AssetLockManager (manager.rs, sync/proof.rs, sync/recovery.rs — grepped directly, zero hits), so nothing can wake this wait early. A host application's graceful-shutdown path that cancels/joins its own tasks has no way to interrupt it; if shutdown proceeds to tear down the async runtime anyway, a task still polling this wait panics against the shut-down runtime.
  • A third, independent defect compounds recovery from either of the above: a wallet re-import/rescan that finds the same asset-lock transaction on chain (it lands in the ordinary transaction/UTXO scan just fine) never creates a corresponding TrackedAssetLock row for it. track_asset_lock() — the only function in the crate that inserts into the tracked-lock table — has exactly one call site repo-wide, inside build_asset_lock_transaction() (wallet/asset_lock/build.rs), i.e. it only fires when the wallet itself is actively creating a new lock. There is no code path anywhere that inspects a scanned transaction's special-transaction payload and backfills a tracked-lock entry for one the wallet already owns. So "the wallet recognizes this transaction is mine" (ordinary tx/UTXO scanning) and "this transaction has a tracked-lock row" (only written by the build path) are two disconnected mechanisms — a fresh import can rescan and find the transaction yet its tracked-lock table stays permanently empty.

Expected behavior

  • A wallet-level-verified ChainLock should promote every tracked record whose transaction is included at or below that height, independent of whether that ChainLock's own apply pass touched zero accounts.
  • Persisted TransactionContext writes should be monotonic — a re-detection (e.g. from a defensive re-broadcast) must never downgrade a record that already has InChainLockedBlock/InBlock context back to Mempool.
  • wait_for_chain_lock/wait_for_proof should accept and select! on a cancellation signal, so a host application can interrupt the wait during shutdown instead of the wait outliving the shutdown budget.
  • A wallet that already recognizes an on-chain asset-lock transaction as its own (via ordinary scan) should end up with a tracked-lock row for it — whether via reconstruction during rescan, or some other means internal to this crate.

Detailed discussion

Root-caused while investigating dashpay/dash-evo-tool#930 and dashpay/dash-evo-tool#933 — both describe the same underlying shape (an unbounded, uncancellable finality wait) from the consuming application's side: #930 is a permanently stuck asset lock with no recovery path; #933 is an app-shutdown hang/panic caused by the same pending wait outliving the graceful-shutdown budget.

Confirmed directly against rs-platform-wallet source at the commit dash-evo-tool currently pins (288a6cae4f9653d6085d2b3d6c7410210a0c95ba):

Affects rs-platform-wallet from #4006 (e8b9da21, 2026-07-05) onward; confirmed still present at the commit above.

Why the third defect (no reconstruction on rescan/re-import) cannot be worked around downstream, and belongs here rather than in a consuming application: checked the full public surface a host application has available (this crate's pub API, plus rs-platform-wallet-ffi) and there is no angle available to a consumer:

  • track_asset_lock() is pub(crate) — invisible outside this crate, so no downstream application can register a reconstructed entry even if it detected one itself.
  • The FFI persistence layer (asset_lock_persistence.rs) only re-loads rows this crate already wrote; it has no "import a lock I found by other means" entry point.
  • The one public read accessor that could theoretically support a consumer detecting a candidate transaction itself, account_transactions_blocking(), is documented as an in-memory debug surface populated only when keep-finalized-transactions is enabled — off by default — so it isn't a reliable detection path either.
  • The only way to fully route around this today is for a consumer to bypass AssetLockManager entirely: derive the claiming key from the wallet seed itself, hand-construct a ChainAssetLockProof (a plain public rs-dpp struct, not gated by this crate), and submit the matching state transition directly via dash-sdk — for a single, user-supplied, already-known outpoint. That is a one-off manual recovery, not a fix, and it duplicates this crate's trust-sensitive key/proof logic outside its own reviewed path. The actual fix has to live in this crate, either as reconstruction during rescan or via some other internal mechanism — a downstream consumer has no supported way to close this gap itself.

Prior work

Attribution

🤖 Co-authored by Claudius the Magnificent AI Agent

Activity

  1. romchornyi commented on Sep 14, 2026

    @romchornyi
    Contributor

    Another field shape of the "per-record promotion never happens" case, from a Dash Wallet iOS support report (ticket 32167), with a fix in #4738.

    Shape. A shielded fund-from-asset-lock resume on a lock that was 12 days old. Platform rejected the InstantSend proof (10513, quorum rotated out), the IS→ChainLock fallback ran, and the funding record was TransactionContext::InstantSend(_) — an InstantLock, no BlockInfo. record.height() is None, apply_chain_lock skips such records by design, so wait_for_chain_lock could never reach InChainLockedBlock. With the user-facing None timeout from #4006 the resume parked forever; every retry and relaunch did the same. The transaction itself was mined and chain-locked long before.

    Fix direction taken. A ChainLock proof only needs the outpoint and a chain-locked height at or above the tx's block, so the wait now looks the height up instead of waiting for the record: DAPI getTransaction reports the block, the answer is accepted only if the SPV header store holds the same hash at that height and the wallet's applied ChainLock covers it. The wait stays unbounded (as #4006 intends) but re-checks on lock events and on a 60 s tick; an InBlock record covered by the wallet's ChainLock also resolves now. Verified end to end on testnet against a wedged lock: one resume, proof built from the looked-up height, shield succeeded.

    Still open here (not covered by that PR): cancellation of the wait, the re-broadcast Mempool downgrade, and the rescan tracked-row backfill. One way a mined record ends up InstantSend is tracked in dashpay/rust-dashcore#1020.

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

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions