Unify UTXO crates under one state model

[gosunuts]

Problem

The current architecture is fragmented by borrowed implementation concepts rather than by a single domain model.

• crates/utxo owns the authoritative live UTXO set.
• crates/index owns electrs-shaped funding/spending rows.
• crates/wallet owns descriptors, PSBT helpers, and partial watched-state concepts.
• crates/utreexo owns proof/accumulator logic but is not meaningfully wired into block apply.
• crates/filters owns compact block filters for discovery/rescan.
• crates/pruning owns block/undo deletion policy.
• NodeState wires these together through optional handles and side effects.

This makes "coin state at a chain tip" implicit and scattered. Wallet funding, address/script lookup, UTXO proof attachment, indexing, and pruning should all consume one coherent UTXO/block delta model instead of each subsystem interpreting blocks independently.

Desired Direction

Make crates/utxo the center of the state model.

Conceptually:

crates/utxo
  CoinState
    ├─ live_utxo              // authoritative OutPoint -> Coin state
    ├─ watched_index?         // optional descriptor/script -> live coin projection
    ├─ funding_api?           // optional automated PSBT funding source
    └─ proof_provider?        // optional utreexo/full-node proof backend

wallet should not own coin state directly. Instead, it should observe wallet-relevant coins through the utxo state model and expose them as a simple deposit/withdrawal experience.

crates/wallet
  ├─ descriptor parsing/validation
  ├─ PSBT construction/finalization helpers
  └─ external signer trait only

[metaphorics]

Done.

[gosunuts]

Related architecture issue: #77 defines the durable chain-event and independent-consumer boundary that this UTXO state-model unification needs. #77 treats this issue as its parent-level state-model dependency.

[rabbitson87]

Status check against this ticket's own Desired Direction, prompted by #77 naming this its parent-level state-model dependency. The 2026-07-30 "Done." does not appear to hold, so recording what is actually in the tree rather than leaving #77 blocked on an ambiguous parent.

Verified on main:

Desired direction	State	Evidence
crates/wallet = descriptor parsing, PSBT construction/finalization, external signer trait only	largely yes	descriptor.rs (89), psbt.rs (131), finalize.rs (243), fee_bump.rs (131), signer_iface.rs (21)
wallet must not own coin state directly	no	crates/wallet/src/watcher.rs:10 — Watcher { descriptors, addr_to_utxos: HashMap<Address, Vec<OutPoint>> }
wallet observes coins through the utxo state model	no	crates/wallet has no dependency on bitcoin-rs-utxo at all; watcher.rs imports bitcoin_rs_index::{ScriptHash, ScriptHashRow} and interprets index rows itself
crates/utxo exposes CoinState with live_utxo / watched_index? / funding_api? / proof_provider?	not implemented	none of CoinState, watched_index, funding_api, proof_provider occur anywhere in crates/

coin_selection.rs is fine on this axis — it takes Candidates as parameters rather than holding a set.

The violation is latent rather than active, and that is the useful part. Watcher is referenced nowhere outside its own re-export in crates/wallet/src/lib.rs:34. crates/node declares bitcoin-rs-wallet only for feature passthrough (rocksdb/fjall/redb) and uses no symbol from it; crates/rpc uses exactly one function, bump_psbt_with_rate_sat_per_kvb, in handlers/wallet.rs:569.

So nothing interprets index rows on the wallet's behalf at runtime today — because wallet watching is not wired in at all. The decision this ticket exists to make is still ahead of us, not behind us. Whoever wires the deposit/withdrawal experience in will either extend Watcher's address→outpoint index-scanning shape, or route it through a CoinState in crates/utxo. This ticket says which, and #77 defines the event boundary that projection would be fed from.

Reading of the "Done.": the wallet-side shape matches the ticket (it is descriptors + PSBT + signer, and it does not own an authoritative coin set). What was never built is the centre — the CoinState aggregate in crates/utxo with the optional watched/funding/proof projections — and the wallet→utxo direction that replaces Watcher's direct index reads. If the "Done." was scoped to the wallet-side split, that reading is consistent with the code; the ticket as written is not complete.

One incidental note from the UTXO-memory work in #83, since it touches the centre this ticket wants to build: UtxoRecord's payload layout changed (v5 — directories in front of the payloads, Core-style amount compression). It is an internal encoding behind the existing find_output / OneUtxoOut / OutputParts accessors, and hash_serialized_3 plus the MuHash trailer are computed over decoded consensus values, so a CoinState built on those accessors is unaffected by it. Worth knowing before designing against crates/utxo's internals rather than its API.

[rabbitson87]

Follow-up to the status check above, and a proposed way out of the deadlock with #77.

This ticket names #77 as what its unification needs; #77 names this ticket as its "parent-level state-model dependency". Each waiting on the other is why this has sat since June. I have posted a boundary proposal on #77 (#77) arguing the loop comes from one unresolved question, and that answering it frees both.

Short version. Two of CoinState's four members are derived state — they need backfill, readiness, reorg rollback and their own retention — which is precisely what #77 says must be an independently-reconciling consumer off the apply path. The other two are not.

CoinState member	Proposed owner
live_utxo	this ticket — authoritative, and UtxoSet already is it
funding_api?	this ticket — a read-side query over authoritative coins; holds no rows, owns no cursor, cannot go stale
watched_index?	#77 consumer — putting it in CoinState means updating it inside commit_block, which contradicts #77's "Default IBD has no optional-index work on its critical path"
proof_provider?	#77 consumer, protocol in #76 — #77 already says Utreexo consumes the transition contract behind its experimental mode

If that split is accepted, this ticket becomes independently buildable. Its scope reduces to authoritative coin set plus a read-side query/funding surface, which has no dependency on #77 at all — the two members that were blocking it are exactly the two that move. The wallet-facing outcome this ticket wants is then reached from two directions: the watched projection lands as a #77 consumer (the same shape #75 needs), and wallet coin selection / PSBT funding reads through crates/utxo's query surface instead of Watcher's direct bitcoin_rs_index reads.

One constraint that falls out and is worth recording here rather than discovering later: funding_api must take a coin source as a parameter rather than reaching for one. The only non-scanning source is the watched index, which by this split sits on the far side of the boundary and may be Building or Stale; having crates/utxo reach for it would make authoritative-state queries depend on consumer readiness. Caller supplies candidates, crates/utxo validates and selects against authoritative state. (UtxoSetView::scan_script_pubkeys walks all 256 shards, so it is not that source — it is scantxoutset's path, which is a full scan in Bitcoin Core too.)

Proposal, not a conclusion — it rides on the reconciliation-vs-journal decision being taken in #77.