Reset the cached coin database and re-sync from chain (control method + dign verb)

[MichaelTaylor3d]

Task

Give the node a way to drop the cached coin database and re-sync it from chain, exposed as a
control method and a dign verb. The DIG App button (dig-app#TBD) drives this; it must not reach into
the database itself.

User directive, 2026-08-27 (verbatim): "we will need to reset the database when this is fixed.
There should be a button in dig-app to reset the coin datbase and resync"

Parent epic: https://github.com/DIG-Network/dig_ecosystem/issues/3170
Related: #382 (the CAT attribution defect that prompted it)

Why this is worth building even though #382's fix backfills

reconstruct_all walks every coin in the DB and attributes any that is unspent, unattributed and
a candidate — so once #382 wires the attributor, existing asset_id = NULL rows are repaired on the
next update tick without a reset. A reset is not the remedy for #382.

The case that genuinely needs it is narrower and permanent:

let Some(parent) = lineage.parent_spend(&c.parent_coin_info, created as u32).await? else {
    continue;
};

A coin whose parent spend could not be fetched — source unreachable, a transient failure, a pruned
response — is skipped, silently, and never retried. Nothing re-queues it. That coin stays
unattributed for the life of the database, so its asset never resolves and its value never appears in
an asset-scoped balance. There is currently no way for a user to recover from that except deleting
the file by hand.

That is the honest justification: not "the DB is stale" but "a one-off fetch failure is permanent
and otherwise unrecoverable."

The hazard this MUST get right — the repo already documents it

Between emptying the table and finishing the re-sync, the database is empty. The routing gate
(WalletDb::is_synced → routing::route) is what makes the local replica authoritative. So an
emptied-but-still-synced database answers balance 0, synced true on a funded wallet.

sync.rs already states this for the reorg-rollback path, in almost these words:

"The routing gate … is what makes an emptied DB authoritative, so a destructive push must clear it:
the wallet then reads from the fallback tier until a genuine catch-up re-establishes the flag.
Without this, one hostile frame makes a funded wallet answer balance 0, synced true."

The reset must clear is_synced in the same transaction that empties the coins, so a crash
between the two cannot leave an empty authoritative replica. Reads then fall back until a real
catch-up re-establishes the flag. This is the money-lie class (§2.6's narrow stop) and it is the whole
risk of the feature.

Other constraints

• Never touch key material. Coins are chain-derived and safe to discard; a seed is not. Scope the
  reset to chain-cached tables and say explicitly which ones.
• Refuse while a spend is in flight. coin_reservations, client_coin_reservations and
  pending_transactions reference coins by id. Wiping the coins beneath a reserved, unconfirmed spend
  loses the record of what is committed and invites a double-spend attempt. Refuse with a clear
  machine-branchable error rather than resetting anyway.
• Re-entrant. Pressing it twice, or while a resync is running, must not corrupt or start two
  catch-ups.
• Report progress. A resync from genesis is slow. The caller needs to distinguish "running" from
  "stalled" — dign wallet sync-status already reports phase and replica height; make the reset
  observable through the same read rather than inventing a second status surface.

Deliverables

• A control method (declare it in dig-node-control-interface, release-first per §4.1)
• A dign wallet verb, --json supported (§6.2)
• SPEC.md updated (§4.2); the Mirror creates need an advertised URL this node can be fetched at #426 CLI/RPC parity test kept green

Acceptance

On a real funded wallet: reset, watch the balance become unknown (never a confident zero), watch the
resync complete, and see the same balance and coins as before. §2.6 — evidence is that sequence on a
real machine.

[MichaelTaylor3d]

This is the blocker at the bottom of a live money-lie chain — measured today

dig-app shows zero $DIG on a funded wallet
(DIG-Network/dig-app#291). A zero is a confident claim, so a user who sent
$DIG concludes the transfer failed. Measured from the machine today, that symptom traces here:

• dig-app's own read path is honest — read_balances returns Unknown/Pending, never a Known
  empty holding, and carries no unwrap_or(0).
• The node's replica genuinely holds no CAT coins: wallet.sqlite has 948 coins, one distinct
  puzzle_hash, an empty cats table, and only asset_id = NULL unspent. CAT coins live at
  cat_puzzle_hash(owner_p2, asset_id) — a different hash — so they were never fetched.
• The installed node is dign 0.169.0, already past the 0.165.0 floor where the CAT-attribution
  fixes (fix(wallet): run CAT attribution in production so a funded wallet can name its $DIG #391 / feat(wallet): stage derived-hash CAT arrivals, promote only lineage-proven coins #393) landed, and reports phase: synced at peak 9222059.

That last point is why this ticket is the fix and an upgrade is not. The corrected path attributes
coins it fetches, and this replica is synced past the heights those coins arrived at. A node
that is synced never revisits the gap. Only a reset-and-resync can recover it, and there is no verb
for that: dign exposes none, and dig-node-control-interface 0.27.0 — the latest published —
declares no wallet-reset method.

Chain, both directions

• Blocks Button to reset the coin database and re-sync from chain dig-app#295 (the reset button, which drives this
  method) → which blocks dig-app shows zero $DIG CAT balance on a funded wallet dig-app#291.
• Epic: https://github.com/DIG-Network/dig_ecosystem/issues/3166

Release-first ordering: this method → a control-interface release → #295 → #291. Scoping #295 as
"just a button" will fail, because the capability it drives does not exist yet.

Labelled mvp + kind:business — it was unlabelled, while sitting under a shipped surface that
lies about money.

[MichaelTaylor3d]

Lane owns this in the wallet batch: branch loop/batch-wallet, draft PR #454. Progress and evidence land on the PR; this ticket closes on its merge.

[MichaelTaylor3d]

Built — PR #454 (2026-08-31)

control.wallet.resetCoinDb plus the dign wallet reset-coin-db --confirm verb.

The hazard this ticket names is closed structurally, not by ordering

initial_sync_complete and the recorded coverage are cleared in the same transaction that
empties the coins (WalletDb::reset_chain_cache). A crash between two separate writes cannot leave
an empty replica that is still authoritative — the balance 0, synced true state on a funded
wallet. Reads fall back to the chain tier until a genuine catch-up re-establishes the flag.

The coverage record is cleared alongside the flag deliberately: a coverage record describing a set
the replica no longer holds is the same falsehood one field along.

One thing the ticket did not specify, found while building it

The ticket says refuse while a spend is in flight. Implemented as a row count, that is wrong in
a way that costs the whole feature: reservation pruning is periodic, so a single lapsed, unpruned
hold would deny the reset for ever — a permanent denial of the only recovery this ticket
provides. Liveness is therefore judged by expiry against the node's own clock
(pending_transactions.expires_at, client_coin_reservations.expires_at_ms), and the instant is
not caller-supplied, because a far-future value would make every live hold read as expired — a lapse
oracle over exactly the guard being asked to stand down.

The count is taken inside the transaction, so a reservation taken between a pre-check and the
delete cannot slip the gap.

Other constraints

• A refusal is an ERROR, never a success carrying a flag. A caller ignoring a refused: true
  field would read "your cache was reset" and act on it. ResetRefusal is a type, not a string.
• Never touches key material. The cleared list is explicit and chain-derived only; derivations,
  network_settings, user_themes, peers and offers are deliberately absent.
• confirm: true travels on the WIRE, not asserted in the CLI. A destructive method guarded only
  by the CLI has no guard for any other client.
• Not a remote-reachable method. Absent from is_open_control_read, so it is token-gated, and
  the node binds loopback-only. It landed on the master-token tier because
  requires_master_token fails CLOSED for a name the contract has not published — which is the
  right tier for it regardless.

Tests, and what each catches

• a_reset_clears_the_authoritative_flag_along_with_the_coins — the money property. Asserts the
  synced pre-state first, so it cannot pass against a database that was never authoritative.
  Revert-proved: removing only the flag-clear statement makes it fail.
• a_reset_refuses_while_a_spend_is_in_flight_and_writes_nothing — asserts the coins AND the flag
  survive the refusal, so a refusal that had already deleted half the tables fails.
• a_reset_succeeds_once_the_reservation_has_expired — the control proving the refusal is keyed on
  the reservation rather than the method always refusing, and asked at the later instant without
  pruning first, which is the lapsed-row case above. Fixture time is pinned explicitly (0,
  10_000), never the wall clock.
• a_reset_does_not_discard_configuration_it_cannot_re_derive — a user theme survives while the
  coins do not; the standing guard on the table list.

Required cross-repo sibling

dig-node-control-interface must publish control.wallet.resetCoinDb as master-tier.
Publishing it as paired-reachable silently downgrades it in this node. Tracked in the PR body; needs
an orchestrator-dispatched lane, since it is a different repo.