CAT discovery: stage derived-hash arrivals, promote only lineage-proven coins into `coins`

[MichaelTaylor3d]

Task

PR-B of the #383 split. Discover CAT coins by derived puzzle hash, stage them, and write into coins only what a lineage proof establishes.

Decision: #383 (comment) (normative — read it first).
Sibling: PR-A carries the attributor wiring and closes #382. This ticket closes #380.

The shape

Derived-hash arrivals land in a new cat_admission_pending table. Only lineage-proven coins are ever written to coins, fully attributed. coins keeps exactly origin/main's semantics.

Why a staging table and not a flag on coins

git grep "FROM coins" finds 18 production sites in db.rs alone, plus 4 in rpc.rs and arrivals.rs — 22 readers. A lineage_proven column makes safety depend on every one of them remembering to filter.

This PR already proved that enumerations here are incomplete. SPEC §18.11a named the puzzle-hash sets; the implementing lane found seven; the gate found an eighth at sync.rs:957 — and that eighth is exactly where a false "you were paid" notification came from.

A staging table makes a fabricated coin unreachable by absence from the table those readers read, not by a guard they must remember to apply.

The obvious alternative does NOT work — checked, do not retry it

Admitting to coins and letting the existing out-of-band pass promote it cannot work: unexamined_attribution_candidates (crates/dig-wallet/src/sage/db.rs:2652) filters on AND asset_id IS NULL, so a derived-hash row admitted with asset_id = DIG is never a candidate and attribution_examined can never be set on it.

Making it reachable requires asset_id = NULL — which means XCH (db.rs:1021) and feeds the spend-input selector (rpc.rs:2933, :3319). That is the round-5 rejection reason, and it survives intact.

What this must defend against — all five rounds' defects

1. Fixes dig-node drops every CAT coin at ingestion, so $DIG balance reads a confident zero on a funded wallet #380 — the ingestion drop; CAT coins reach the wallet.
2. No unbounded or amplified chain read. Zero on the frame path; roughly one out-of-band read per coin, terminal (a coin is resolved once), and capped.
3. No denial. A promotion error must never reach a.attribute(db).await? — that is what turned a read failure into a session kill in rounds 3 and 4.
4. Failure mode is incompleteness, never a wrong figure. A coin not yet promoted is absent, not zero, and not XCH.
5. A fabricated coin never enters coins — so the balance, the spend selector and the arrivals notification are structurally clean rather than guarded.

The attack this exists to stop: anyone may CREATE_COIN at any puzzle hash, so a coin at the derived CAT hash costs 1 mojo per displayed base unit and needs only the victim's public address — no malicious peer. Round 5 admitted those directly, producing a fabricated balance, a permanent $DIG send kill-switch (selection is largest-first, the coin is unspendable, it never leaves the set), and a false payment notification.

Notes

• admit_hinted stays deleted. Its job — distinguishing a real CAT from mojos paid to its address — moves to promotion, off the frame path. That is the whole point: it was the only such defence, and round 4 deleted it for a DoS that promotion does not have.
• The eight puzzle-hash sets are the hazard map; re-derive them rather than trusting the list, since it grew twice already.
• §2.6 governs: the thinnest path to a real wallet showing a real $DIG balance from discovered coins.

[MichaelTaylor3d]

Sequencing changed: this is now the blocking half, not the follow-up.

PR-A (#391) was measured against the real wallet and the result is decisive: the attributor wiring alone does not restore the balance, because it never receives input.

[BEFORE]     coins=959  at_dig_cat_hash=0  attributed=0  dig_balance=0
[AFTER-PASS] coins=959  at_dig_cat_hash=0  attributed=0  dig_balance=0

[CALIB-BEFORE] coins=967  at_dig_cat_hash=8  attributed=0  dig_balance=0
[CALIB-AFTER]  coins=967  at_dig_cat_hash=8  attributed=8  dig_balance=3856455

Same code, same chain, one variable: seed the 8 real coins and the wiring attributes every one and lands on 3,856,455 exactly, through the binding check and the placeholder repair. The wiring is correct and complete; it is starved.

The measured cause is this ticket. The live replica holds 959 rows across exactly 3 distinct puzzle hashes — the p2 set — and zero at the $DIG CAT hash. On chain, 136 coins are hinted to that p2 across 51 distinct puzzle hashes. apply_coin_states filters on subscribed.contains(&s.coin.puzzle_hash), so 50 of 51 hashes are dropped at ingest.

One correction to the decision's cost estimate, which matters for how this is designed. §6 says PR-A costs "one out-of-band pass of delay". On PR-A alone the delay for a newly arriving CAT coin is unbounded, not one pass — it is dropped at the frame and never becomes a candidate. The honest statement: a CAT row already in the replica is attributed within one pass after catch-up; a CAT coin arriving from a peer is never attributed, because it is never admitted.

That does not contradict the decision — §6 assigns ingestion here — but it does mean the split leaves #382's user-visible symptom unfixed until this lands. §2.6's end-to-end-first bar says the deliverable is a person seeing it work, so this should be sequenced immediately rather than queued.

Everything in the staging design still binds unchanged, and the reason is sharper now that the numbers are known: 50 dropped hashes is exactly the surface an attacker also writes to, at 1 mojo per displayed base unit, needing only the victim's public address.

[MichaelTaylor3d]

Lane opened. Owning #390 end-to-end.

• Branch: loop/390-cat-staging, from origin/main @ e094078 (not from PR-A).
• Draft PR: feat(wallet): stage derived-hash CAT arrivals, promote only lineage-proven coins #393
• Head: 94f5510
• Worktree: C:\tmp\worktrees\dn390

Following the round-6 shape verbatim: staging table cat_admission_pending,
routing (not typing) in apply_coin_states, promotion in the out-of-band pass,
hard bound with eviction, promotion errors never propagated.

Next action: derive the puzzle-hash sets from source rather than trusting the
eight-item list, then write the staging schema.

[MichaelTaylor3d]

Design locked, measured against origin/main (not PR383's tree).

Blast radius checked (git grep + read, gitnexus index not built for this worktree — falling
back per §2.0 bound 2 and saying so):

• apply_coin_states — 2 production callers (sync.rs:826 in handle_coin_state_update,
  sync.rs:990 in initial_sync_with_authority), plus test callers. Gains a derived arg.
• SessionState — gains a derived borrow; constructed at sync_supervisor.rs:1414 and in tests.
• PuzzleHashSource::puzzle_hashes() — unchanged. The derived hashes are added at the
  supervisor's subscription point only, so followed_puzzle_hashes (the router's coverage
  question) and set_watched (a user-visible count) keep meaning addresses, not outer CAT hashes.
• CoveredSet::covers is containment, so widening the SUBSCRIBED set keeps
  covered ⊇ followed true. Verified at coverage.rs:76.
• record_arrivals already receives session.subscribed, which stays plain p2 only —
  so the sync.rs:957-class defect (CAT outer hashes reaching arrivals::classify) is
  unreachable by construction here rather than guarded. Test pins it.

Two things the round-6 decision assumed that are not on origin/main, so this PR does not
depend on them: attribution_examined and the supervisor-owned CatAttributor are PR-A's.
Promotion is therefore driven from the two sites that already hold a LineageSource:
CatAttributor::attribute (error swallowed, never returned) and
WalletBackend::refresh_tracked_coins.

Finding logged, not fixed here (§2.6, off-path): refresh_tracked_coins (rpc.rs:3105)
upserts coin_records_by_hints straight into coins with asset_id = NULL. A fabricated coin
hinted to the owner p2 therefore lands in coins as XCH and reaches the spend selector, on
main today, with no peer involved. Same attack, different tier. Will file separately.

Next: schema + cat_admission_pending DB layer.

[MichaelTaylor3d]

The acceptance bar is met: 3,856,455 on the real wallet

Head 2c1d327 on loop/390-cat-staging, PR #393.

Ran against a copy of the live replica (AppData\Local\DigNode\wallet.sqlite + its WAL),
with the coins and parent spends captured from api.coinset.org. I did not attempt a node
run under a LOCALAPPDATA/DIG_WALLET_PORT override — dig-node#392 — and took the
production-pass-over-the-real-replica route instead, as PR-A's lane did.

The starvation, measured:

[REPLICA] coins=948  distinct_puzzle_hashes=1  attributed=0
[REPLICA] rows already at a derived CAT hash = 0

One puzzle hash. Not three, not fifty-one — the replica holds the address and nothing else.

Where the money actually is. cat_puzzle_hash(<the wallet's p2>, DIG_ASSET_ID)
= 6ce1cdf86cb39059eb43e3c4c0e7c62fdf7d099fdb71033563cc4b9daeab376d.
get_coin_records_by_puzzle_hash on that hash returns 52 records, 8 of them unspent:

463 + 408 + 3 + 7 + 3096 + 3096 + 2382 + 3847000  =  3,856,455

Exactly the figure the ticket names, at a hash the replica had no row for.

The end-to-end pass:

[BEFORE]   dig_balance=0
[CHAIN]    coins captured at the derived hash = 8
[STAGE]    staged = 8
[PROMOTE]  PromoteStats { promoted: 8, refused: 0, deferred: 0 }
[AFTER]    dig_balance=3856455
[AFTER]    xch_balance=1599179999972

8 discovered, 8 proven against their real parent spends, 0 refused, and the XCH balance
unchanged — the staged coins never passed through the untyped state that would have made them
XCH.

Both proofs are load-bearing, verified by reverting only the fix (committed first, restored by
file copy, git status --porcelain clean afterwards):

• reverting staging to origin/main's drop →
  a_derived_cat_hash_coin_is_staged_while_a_p2_coin_is_admitted fails with left: 0, right: 1,
  which is the dig-node drops every CAT coin at ingestion, so $DIG balance reads a confident zero on a funded wallet #380 drop itself;
• mutating promote_one to believe the derivation when the parent spend proves nothing (the
  round-5 defect) → a_fabricated_coin_is_refused_while_a_real_one_is_promoted fails with
  promoted: 2, refused: 0 — the fabricated coin admitted.

Suite: 679 passed, 0 failed (cargo test -p dig-wallet --lib).

[MichaelTaylor3d]

Lane complete. PR #393 (DRAFT), head 44bacb6.

Acceptance bar met: 3,856,455 on the real replica. Five tests answered, both proofs shown
load-bearing by reverting only the fix. Full evidence in the PR body and in the measurement
comment above.

Sibling filed for the same attack on the coinset oracle tier, which #393 does not close:
#394

Not merged, not undrafted — the gate round has not run, and this PR family has already had a
release ship carrying defects its gate had found, so it stays unmergeable to everyone else until
the verdicts are in.

[MichaelTaylor3d]

Round 7 complete on #393 (head 46fa77b, DRAFT).

All four gating findings from the round-6 security verdict addressed, #394 folded in as a third tier of the same root cause, and all three non-gating findings fixed.

Round-7 summary: #393 (comment)

Two decisions recorded there for refutation: (1) finding 2 is closed by bounding the read RATE rather than by classifying never-existed vs unavailable, because the coinset facade cannot express the distinction and a terminal refusal on the answer it does give would erase real coins during an outage; (2) Closes #380 is dropped to Refs #380 — #391 remains the wiring half and closes it, and this PR merges first so #391 rebases onto merged main rather than a security fix rebasing onto an ungated draft.

Next action: the security leg re-runs IN FULL on 46fa77b (not scoped — findings 1-3 share a root that changes what enters the money table). PR stays DRAFT until it returns.

[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]

Verdict: ALREADY SHIPPED — verified against origin/main, not rebuilt (2026-08-31)

The already-shipped check (CLAUDE.md §2.0) run at the start of the wallet batch found this
ticket's design already implemented and wired. It was not rebuilt.

The merge: 4523894 — "feat(wallet): stage derived-hash CAT arrivals, promote only
lineage-proven coins (#393)", plus follow-ups 69a1c11 (claim the staged row before writing
the coin) and 154075d/e05da67 (#391, run attribution in production).

The shape this ticket specified, present verbatim:

• The staging table, not a flag on coins — cat_admission_pending,
  crates/dig-wallet/src/sage/db.rs:421-441, with both indexes including the
  fewest-attempts-first promotion queue.
• The module holding the discovered/believed distinction —
  crates/dig-wallet/src/sage/cat_discovery.rs, whose module doc carries the same two-row table
  this ticket's body specifies, the one-mojo-per-displayed-base-unit attack, and the
  largest-first permanent-send-kill-switch consequence.
• Wired on both paths, so it is not dormant: stage_from_states at
  crates/dig-wallet/src/sage/sync.rs:772 (the peer frame path — takes no LineageSource, so it
  structurally cannot perform a chain read, requirement 2), and promote_staged_cats at
  sync.rs:833 and rpc.rs:3281 (off the frame path).
• 18 tests in cat_discovery.rs.

The module doc also records the correction to its own earlier amplification claim — that a row
whose parent cannot be read stays staged by design and was therefore re-read every pass — which is
the failure an attacker would choose, so requirement 2's bound was measured rather than assumed.

Recommend: close as satisfied. No code in PR #454
touches this; that PR's Closes #390 is a bookkeeping close of work that landed in #393.