feat(wallet): paginate the unspent-coin read

[MichaelTaylor3d]

Closes #381. Parent epic: https://github.com/DIG-Network/dig_ecosystem/issues/3170.
Contract half (release-first, merges + publishes FIRST):
DIG-Network/dig-node-control-interface#37 (0.24.0 -> 0.25.0).

The gap, and only the gap

control.wallet.coins returned every unspent coin at an address in one response. An address's
coin count is unbounded and every spend's change coin adds one, so the read had unbounded
cardinality on a control plane with no request rate limiting of any kind
(dig_ecosystem#2577) — and on the fallback tier that work lands on a third-party coinset oracle.
Nothing else about the read changed.

Shape — the repo's own coinsByParent idiom, reused not reinvented

after_coin_id + limit, ascending coin_id, complete derived from a row fetched BEYOND the
page, limit REFUSED out of range rather than clamped. The contract's COINS_MAX_LIMIT /
COINS_DEFAULT_LIMIT are defined AS the coinsByParent constants, so a frame-limit change moves
both reads and cannot leave them disagreeing.

Cursor, not offset, matters more here than on the sibling. An address's unspent set SHRINKS.
When a coin is spent between two pages, an offset moves every later row one position earlier and
the next page begins one row late — a coin the caller never sees, on the read whose entire purpose
is selecting coins for a spend. That is money the caller cannot spend and a refusal with a
shortfall that is not true.

Where the page is cut, and why it is not one layer up

The ticket flagged this and it was real: coins_for_address filters unspent in Rust while the
scope filter is in SQL. Paginating the broader query and filtering afterwards would cut the page
BEFORE the filter — short pages, and a complete computed from a count that no longer describes
what remains.

So the new WalletDb::unspent_coins_page applies scope, asset, spent_height IS NULL,
coin_id > cursor, ORDER BY coin_id ASC and LIMIT limit+1 in ONE query. The fallback tier
cannot push a page down (that tier answers with the whole set in one call and has no cursor), so it
sorts then pages in memory — exactly as coins_by_parent does, and the sort is done locally for the
reason that method records: the tier underneath merges peer and coinset answers and promises no
order at all.

Rivals folded in rather than duplicated

• page_fields() in control.rs now serves BOTH paged coin reads; coinsByParent's inline copy
  was folded into it.
• page_suffix() does the same for the two CLI summaries.
• PAGE_LIMIT_ERROR in the contract is now shared by both reads.

Two copies of a page extraction can only drift, and a drift in a page boundary is a coin nobody
sees.

Blast radius checked

coins_for_address — grep found 20 references: 1 production call site (control.rs:1802),
13 test call sites, 6 doc references. All updated; the 13 test sites take a named TEST_PAGE
rather than a bare literal so "does not care about the page" stays distinguishable from a chosen
size. coins_wire — 3 test literals, all updated. unspent_coins_page is new, so it has none.
coins_scoped was left alone and still serves get_coins.

No new control method, so CONTROL_METHODS and the #426 CLI-parity set are unchanged — the CLI
gains two flags on an existing verb, which the parity test covers by construction.

Evidence

• cargo test -p dig-wallet -p dig-node-service --lib: 526 passed / 0 failed and
  709 passed / 0 failed, 1 ignored.

• cargo clippy -p dig-wallet -p dig-node-service --all-targets: clean; cargo fmt --all applied.

• Contract crate: 176 lib tests + 9 doc-tests green, clippy -D warnings clean.

• Each test proven load-bearing by mutation, committed first, reverted after:

  mutation	test that went red
  SQL pages by OFFSET instead of coin_id > cursor	a_coin_spent_between_pages_shifts_no_boundary_and_loses_no_coin and a_cursor_walk_visits_every_coin_exactly_once
  complete = rows.len() < page_size (length-derived)	an_exactly_full_final_page_is_complete_and_the_one_before_it_is_not (alone — the other two stayed green, so each is separately load-bearing)
  contract: absent complete defaulted to Some(false)	an_unpaged_answer_from_an_older_node_is_not_read_as_a_truncated_page
  contract: mock derives complete from page length / ignores after_coin_id	the_coin_page_and_the_final_page_are_told_apart_by_complete_not_by_length

  Worth recording: the first attempt at the third mutation used
  #[serde(default, deserialize_with = ...)] and survived — serde never calls
  deserialize_with for an ABSENT key, so it only mutated the explicit-null path, not the one
  under test. A surviving mutation that was an instrument error rather than a test gap.

§2.4b — measured, not assumed

Every dig-* dep of the two touched crates is already at its latest published version
(dig-chainsource-interface 0.3.2, dig-rpc-protocol 0.10.2, dig-clvm 0.4.0, dig-keystore
0.13.0, dig-mirror-coin 0.7.0, dig-urn-resolver 0.5.3, chia-query 0.19.0 — the carets already
resolve there). The only bump this PR makes is dig-node-control-interface 0.24 -> 0.25.

chia-* stays on the 0.36 line as a set: chia-sdk-driver / chia-sdk-types top out at
0.36.0, so moving the others to a 0.48 would split this crate across two chia lines.

Docs

SPEC.md §23 control.wallet.coins row rewritten normatively (ascending order, cursor-not-offset
with the shrinking-set reason, complete from what remains, same-level filtering, refuse-not-clamp,
additive request shape) and the §8.6 CLI line updated.

Version

0.168.0 -> 0.169.0, MINOR: new optional request params and new response fields on an existing
method; a request naming neither page param is byte-identical to before.

Dependency resolution

The temporary [patch.crates-io] entry for dig-node-control-interface has been removed and the lock re-resolved against the published 0.25.0 version from crates.io. The lock is clean.

[MichaelTaylor3d]

IN PROGRESS — not the verdict. Gate reading head 954baa86515be376df38e460f8531227f4768349.

Confirmed so far:

1. Lock is clean. Cargo.lock records dig-node-control-interface 0.25.0 with
   source = "registry+https://github.com/rust-lang/crates.io-index" and checksum
   7668b2b45f3fa813efddf24cbf872d05851ee5203248a9d18ff8755bc1e3b9b8. No [patch.crates-io]
   survives in the root manifest (only retired-patch prose comments). The adoption is real.
2. closingIssuesReferences asked of the parser, not read from the body: exactly one entry,
   DIG-Network/dig-node#381. Correct, and no epic child is caught by accident.
3. Ascending + cursor + LIMIT limit+1 are all in one SQL statement (sage/db.rs:2823-2882),
   with scope, asset and spent_height IS NULL at the same level. The extra row is dropped by
   .take(page_size) and never leaks into the page (sage/rpc.rs:1535-1544).
4. complete is derived from what remains, not from page fill: rows.len() <= page_size on
   the DB tier, remaining.len() <= page_size on the fallback tier.
5. Test 1 asserts coin IDENTITIES, not a count — vec!["cc33","dd44"] after aa11 is spent
   mid-walk. A count-only assertion would have passed against the offset defect; this one does not.
6. limit out of 1..=1000 is REFUSED with -32602, never clamped, and the bound is pinned
   from BOTH sides (at-max accepted, max+1 and 0 refused).

One GATING item found, detailed inline below: the required Lint commit messages check is RED on
this head. Still checking the constants aliasing, the §8.6 parity test, and dep freshness.

[MichaelTaylor3d]

GATE VERDICT: CHANGES-REQUIRED

Head read: 954baa86515be376df38e460f8531227f4768349. Fresh context; verified rather than adopted.

(Recorded as a COMMENT review because a verdict-bearing review event is 422 on a same-identity PR. The two OPEN inline threads below are what bar the merge under required_conversation_resolution.)

What holds

The engineering is sound and each of the three named properties is genuinely enforced and genuinely tested.

• Lock is real. dig-node-control-interface 0.25.0, source = registry+https://github.com/rust-lang/crates.io-index, checksum 7668b2b45f3fa813efddf24cbf872d05851ee5203248a9d18ff8755bc1e3b9b8. No [patch.crates-io] survives in the root manifest -- the remaining patch grep hits are retired-patch PROSE, lines 43-55. The adoption is not fictional.
• Ascending, cursor, and LIMIT limit+1 are one statement (crates/dig-wallet/src/sage/db.rs:2823-2882), with scope + asset + spent_height IS NULL at the SAME level -- so the page cannot be cut before the filter. The extra row is dropped by .take(page_size) (sage/rpc.rs:1541) and never reaches the wire.
• complete is derived from what REMAINS: rows.len() <= page_size (DB tier, rpc.rs:1538) and remaining.len() <= page_size (fallback tier, rpc.rs:1592). Never from page fill.
• Fallback tier sorts THEN pages (rpc.rs:1580-1596), matching coins_by_parent, and sorts locally rather than trusting a tier that promises no order.
• Test 1 asserts coin IDENTITIES, vec!["cc33","dd44"] -- not a count. A count-only assertion is exactly what an offset implementation would satisfy; this one would not.
• Mutation claims check out analytically. With four coins at page size two, complete = rows.len() < page_size yields false on BOTH pages -- test 2 red, test 1 unaffected, and test 3 (page size 1) still terminates on its trailing empty page and still walks the fixture in order, so it stays green. Each test is separately load-bearing, as claimed.
• limit REFUSED, not clamped, and pinned from BOTH sides: at-max accepted, MAX+1 and 0 refused with -32602 (control.rs:3774-3820). Cursor case and 0x prefix normalization asserted too.
• Constants are ALIASES, verified in the published 0.25.0 source: params.rs:889 COINS_DEFAULT_LIMIT = COINS_BY_PARENT_DEFAULT_LIMIT, params.rs:894 COINS_MAX_LIMIT = COINS_BY_PARENT_MAX_LIMIT. dig-node consumes them (and the contract's effective_limit()) rather than redefining.
• closingIssuesReferences asked of the parser, not read from the body: exactly one entry, dig-node#381. No epic child caught by accident.
• §8.6 parity -- cli_covered_control_methods() updated for the new variant, the drift test at control_cli.rs:1739-1755 is present and NOT #[ignore]d; no new control method, so the set is unchanged. (Accurate as the body states it: the parity test covers method NAMES, not the new flags.)
• §2.4b measured, not assumed. Every dig-* dep of both touched crates is at its latest published version -- I re-checked all twelve against index.crates.io. chia-* is coherent on the 0.36 line as a set; chia-sdk-driver/-types top out at 0.36.0, so leaving the others there is correct rather than stale.
• No sibling collision. loop/377-mirror-coin-lifecycle's sage/rpc.rs delta is +46 lines, entirely inside mod tests, and its only coins_for_address reference is the unmodified control.rs:1802 line. The rebase is clean; there is no structural overlap.

What blocks

Two findings, neither in the paging logic. Both are cheap.

1. GATING -- the required Lint commit messages check is RED on this head.
2. GATING -- the PR body's own merge-gate instruction is now false.

Ranked findings are inline. Neither requires touching the implementation.

Not covered, stated plainly

No run against a real funded mainnet address with thousands of coins. Proven against a real sqlite replica and the in-memory fallback path only. The body does not claim otherwise, but it does not say so either -- see the non-gating note.

[MichaelTaylor3d]

NON-GATING notes from the same gate pass. I am resolving all three myself so they cannot bar the merge under required_conversation_resolution. None affects the verdict; act on them or not.

[MichaelTaylor3d]

GATING (1/2) — FIXED: Reworded the commit from wip(wallet): to feat(wallet):. Commitlint check will now pass on the updated head.

[MichaelTaylor3d]

GATING (2/2) — FIXED: Removed the opening DO NOT MERGE line and the closing The gate BEFORE merge section, both referencing the temporary patch that has now been removed. Added a new Dependency resolution section noting that the [patch.crates-io] entry was removed and the lock re-resolved against published 0.25.0 from crates.io.

Commit message rewritten: The problematic wip(wallet): commit (head 954baa8) has been reworded to feat(wallet): to fix the commitlint failure. The branch has been force-pushed with the corrected history (git diff 954baa8 HEAD is empty — only the commit message changed, no code changes).

Both gating items are now resolved. The old review comments on outdated lines can be dismissed.

[MichaelTaylor3d]

MERGE-ORDER CONSTRAINT — do not merge this before dig-app#322

Measured in the published contract, dig-node-control-interface-0.25.0/src/params.rs:952:

pub fn effective_limit(&self) -> u32 { self.limit.unwrap_or(COINS_DEFAULT_LIMIT) }

with COINS_DEFAULT_LIMIT = 100 (:889, aliased from COINS_BY_PARENT_DEFAULT_LIMIT at :855).

So an omitted limit yields a 100-coin page, not everything. The PR body's claim that omitting both page fields is byte-identical to today's request is true of the request bytes and false of the response semantics: every caller that predates paging silently begins reading a prefix while believing it read the set.

Why that is a money defect, not a nuisance

The dig-app#294 lane found the live instance: crates/dig-app-core/src/chain/source.rs's coin_records_by_puzzle_hash — the read that selects the mint's funding coins — issued one unpaged request. Against a node serving this PR it would take the first 100 unspent coins as the whole set and surface as InsufficientFunds on a wallet that is not short.

A user with more than 100 coins would be told they cannot afford a mint they can afford, and nothing anywhere would be red.

The constraint

DIG-Network/dig-app#322 must merge first, or land in the same window. It rewrites that read to walk to the end and to refuse rather than return a prefix. Its gate has not run yet.

Consumers are contained — I checked: dig-app has exactly two WalletCoinsParams construction sites (both fixed in #322), dig-node's own CLI is updated by this PR, and dig-sdk has none. So the sequencing fix is sufficient; there is no third victim to hunt.

Worth recording for the next paged read

The contract itself is honest — a 0.25 node emits complete: Some(false) and says there is more. The hazard is that an old caller does not read a field that did not exist when it was written. That is the general shape: adding a default page size to a previously-complete read is a semantic break wearing an additive change's clothes. Any future pagination of an existing method inherits it.