wallet rpc: utxo state filtering and per-utxo state in account_utxos

[nullPointerEnjoyer]

Summary

Part 3 of the series: #2126 (mempool local-origin orphans) → #2127 (wallet chain-aware repush) → this PR.

Adds optional utxo_states and with_locked parameters to the account_utxos RPC (defaulting to all states / unlocked, i.e. the previous behavior), and includes the state of the creating transaction (Confirmed / InMempool / Inactive / Conflicted / Abandoned) in every returned UtxoInfo.

With this, callers can obtain a trustworthy spendable view — account_utxos with utxo_states=["Confirmed"] whose coin sum equals account_balance called with the same values — instead of having to diff the full listing against the balance to spot outputs of dropped transactions. This pairs with #2127's reconcile pass, which now deterministically marks dropped transactions Abandoned in the wallet state.

Changes

• output_cache: utxos_with_states (the existing utxos now delegates to it), attaching the creating transaction's state to each result;
• account/wallet/runtime_wallet/read: get_utxos_with_states and get_multisig_utxos_with_states threading the state through;
• wallet-rpc-lib: account_utxos gains the optional utxo_types, utxo_states, with_locked parameters; UtxoInfo carries the state; standalone_multisig_utxos responses carry it too;
• wallet-rpc-daemon: RPC.md regenerated;
• e2e tests in wallet-rpc-lib/tests/basic.rs.

Compatibility note

The new state field is required on the wire: a client deserializing responses from a daemon that predates it needs to update first. Wallet client and daemon are versioned and released together, and existing callers that omit the new parameters see no behavior change.

Tests

• e2e (wallet-rpc-lib/tests/basic.rs): state filtering, per-UTXO state reporting, spendable-view/balance equivalence;
• full wallet, wallet-controller, node-comm, wallet-rpc-lib suites green; fmt and clippy clean (--all-features --all-targets).

[github-actions]

🔍 OpenCodeReview found 2 issue(s) in this PR.

• ✅ Successfully posted inline: 0 comment(s)
• 📋 Routed to summary by policy: 2 comment(s)

---

📄 wallet/src/account/mod.rs (L2158-L2161)

⚠️ GitHub could not post this as an inline comment: Routed to summary (severity low · category performance)

The backward-compatible wrapper eagerly builds the full Vec of triples (with cloned UtxoState per entry) just to map it back down to pairs, adding an extra allocation per call on every existing caller. Since the underlying scan already builds the Vec, an in-place truncate-style rewrite (e.g., map a mutable Vec of tuples and drain the state field, or a parallel iterator adapter) could avoid the second allocation. Low priority, but applies identically in get_utxos and the OutputCache::utxos wrapper.

💡 Suggested Change

Before:

self.get_multisig_utxos_with_states(utxo_types, median_time, utxo_states, with_locked)
    .into_iter()
    .map(|(outpoint, output, _state)| (outpoint, output))
    .collect()

After:

let mut result: Vec<_> = self.get_multisig_utxos_with_states(
    utxo_types,
    median_time,
    utxo_states,
    with_locked,
)
.into_iter()
.map(|(outpoint, output, _)| (outpoint, output))
.collect();
result

---

📄 wallet/wallet-rpc-lib/src/rpc/server_impl.rs (L528-L531)

⚠️ GitHub could not post this as an inline comment: Routed to summary (severity low · category maintainability)

utxo_types is collected into an owned Vec and then re-iterated via &...iter().map(...).collect::<Vec<_>>() just to call try_into on the reference — a double allocation. Per the TryFrom<&Vec<UtxoType>> impl (types/src/utxo_types.rs), only the empty case fails, so building the intermediate Vec<UtxoType> and referencing it is unnecessary; convert the collected vec directly. Also consider handling the error the same explicit way utxo_states does below for consistency.

💡 Suggested Change

Before:

        let utxo_types =
            (&utxo_types.unwrap_or_default().iter().map(UtxoType::from).collect::<Vec<_>>())
                .try_into()
                .unwrap_or(UtxoTypes::ALL);

After:

        let utxo_type_filter: Vec<UtxoType> =
            utxo_types.unwrap_or_default().iter().map(UtxoType::from).collect();
        let utxo_types = match (&utxo_type_filter).try_into() {
            Ok(types) => types,
            Err(BitFlagError::Empty) => UtxoTypes::ALL,
        };

[nullPointerEnjoyer]

OpenCodeReview cycle summary

Cycle	Head	Findings	Resolution
1	76bf68dc5	1 (bug-med: handles-client empty-utxo_states default changed silently)	2e8fadefd — unified the fallbacks with the server-side defaults and documented the pre-PR Confirmed default
2	2e8fadefd	0	—
3	412a76640	1 (test-med: balance invariant untested for LockThenTransfer)	549811a70 — see below
4	549811a70	0	—

On the cycle-3 finding: PoS block rewards are tracked by the wallet as block data (the RewardAdded event), not as utxos, so account_utxos never lists a LockThenTransfer utxo and the end-to-end invariant test can only exercise Transfer outputs. The design boundary is now pinned by an assertion (account_utxos with utxo_types=[LockThenTransfer] must return an empty set) so that a future wallet change which starts listing them forces the invariant test to be extended.