Paginate the unspent-coin read: control.wallet.coins and dign wallet coins

[MichaelTaylor3d]

Task

Paginate the unspent-coin read: control.wallet.coins and the dign wallet coins CLI that fronts it.

Parent epic: https://github.com/DIG-Network/dig_ecosystem/issues/3170

User directive, verbatim: "the dig-node cli also needs a command in its wallet to list available
coins, paginated"

What already exists — do NOT rebuild it

• control.wallet.coins — shipped, per-address, unspent-only (crates/dig-node-service/src/control.rs:148)
• dign wallet coins <ADDRESS> --asset xch|dig [--json] — shipped, unpaginated
• The persisted coins table with idx_coins_unspent … WHERE spent_height IS NULL, and
  WalletDb::unspent_coins(asset_id) (crates/dig-wallet/src/sage/db.rs)

The gap is only pagination. An address with thousands of coins currently returns everything in one
response.

The shape — reuse the repo's own Sage-parity idiom, do not invent one

crates/dig-wallet/src/sage/rpc.rs:358-366 already implements this correctly for coinsByParent.
Match it:

• ASCENDING by coin_id — a stable total order, so a page boundary is well-defined.
• Cursor, not offset. Return the last coin_id of the page; the caller resumes from it. An offset
  re-reads a shifting table and silently skips or repeats rows when a coin is spent between pages —
  and on a money surface a skipped coin reads as missing funds.
• has_more derived from rows remaining BEYOND the page, never from whether the page filled. The
  repo's own comment says why: the two differ exactly when the count is a multiple of the page size.
• An empty page is an answer, not an error (rpc.rs:1853).
• A short page is never marked complete to salvage a partial read (rpc.rs:1859).

Note the existing query's scope, and decide deliberately

unspent_coins(asset_id) filters by asset_id only — it does not filter by puzzle_hash. Check
what the RPC layer does with that before adding a page on top: if the address filter is applied above
the query, paginating the unfiltered query and then filtering would produce short pages and a wrong
has_more. Filter and paginate at the same level, in SQL, or the two disagree.

Also

• Keep --json machine output (§6.2) and make the cursor/has_more fields part of it — a scripted
  caller must be able to page without parsing prose.
• control.wallet.coins is a published contract in dig-node-control-interface; adding optional
  paging params is additive, but the catalog must be updated in the same family (§4.1 release-first).
  State the SemVer judgement.
• Update SPEC.md (§4.2) and the CLI parity test (Mirror creates need an advertised URL this node can be fetched at #426 guards drift between the RPC and the CLI).
• §2.4b: bring dig-*/chia-* deps to latest in the PR; index checks need a User-Agent header.

Acceptance

dign wallet coins <address> --asset dig pages through a real funded address, --json carries the
cursor, and the last page reports has_more: false without a spurious extra request. Evidence is a
real run (§2.6).

[MichaelTaylor3d]

Lane claimed (loop-implementer).

• dig-node branch: loop/381-paginate-coins, draft PR feat(wallet): paginate the unspent-coin read #413
• dig-node-control-interface branch: loop/381-paginate-coins (release-first, §4.1)

Measured first: the contract cannot express this today. WalletCoinsParams (0.24.0
src/params.rs:593) carries only {address, asset} and WalletCoinsResult (src/results.rs:784)
carries no complete/cursor. So the contract crate goes first and publishes 0.25.0 (MINOR —
additive optional params, additive omittable result fields), then dig-node adopts.

Shape adopted = the coinsByParent idiom, pinned to it rather than restated:
after_coin_id + limit, ascending coin_id, complete derived from a row fetched BEYOND the
page, limit REFUSED out of range rather than clamped. COINS_MAX_LIMIT/COINS_DEFAULT_LIMIT are
defined AS the sibling constants so the two cannot drift.

One decision worth flagging: complete is Option<bool>, not bool. This method shipped unpaged,
so a pre-0.25 node emits neither key; None means "did not disclose, and returned everything",
which is true of such a node. Reading an absent key as Some(false) would send a caller resuming
into a node that ignores after_coin_id — an infinite walk. Pinned by a KAT.

NEXT ACTION: contract crate cargo test --all-features green, then the dig-node side (rpc.rs
coins_for_address gains paging at BOTH tiers — the Db tier pages in SQL alongside the puzzle-hash
filter, the fallback tier sorts+pages in memory as coins_by_parent does).

[MichaelTaylor3d]

Progress — both halves are written and pushed.

Contract (release-first, goes first): dig-node-control-interface loop/381-paginate-coins,
draft PR DIG-Network/dig-node-control-interface#37, 0.24.0 -> 0.25.0.
Green: 176 lib tests + 9 doc-tests, clippy -D warnings clean, and all three new tests proven
load-bearing by mutation.

dig-node: loop/381-paginate-coins, draft PR #413, HEAD pushed. Changes:

• WalletDb::unspent_coins_page(asset_id, puzzle_hashes, after_coin_id, limit) — scope, asset,
  spent_height IS NULL, coin_id > cursor, ORDER BY coin_id ASC, LIMIT limit+1. All in ONE
  query, which is the point the ticket flagged: paginating a broader read and filtering afterwards
  cuts the page before the filter, so pages arrive short and complete is computed from a count
  that no longer describes what remains.
• coins_for_address paginates at BOTH tiers. The Db tier pages in SQL. The fallback tier sorts in
  memory then pages, exactly as coins_by_parent does and for the reason it records — the tier
  underneath merges peer and coinset answers and promises no order.
• page_fields() in control.rs now serves BOTH paged coin reads; coinsByParent's inline copy was
  folded into it, and page_suffix() does the same for the CLI summaries. Two copies of a page
  extraction can only drift, and a drift in a page boundary is a coin nobody sees.
• CLI: dign wallet coins <ADDRESS> [--asset …] [--after-coin-id <id>] [--limit <n>]. No new
  control method, so the Mirror creates need an advertised URL this node can be fetched at #426 parity set is unchanged.
• SPEC.md §23 row rewritten normatively (order, cursor-not-offset, complete from what remains,
  same-level filtering, refuse-not-clamp) plus the §8.6 CLI line.

§2.4b, measured not assumed: every dig-* dep of the two touched crates is already at the
latest published version (dig-chainsource-interface 0.3.2, dig-rpc-protocol 0.10.2, etc. — the
carets already resolve there). chia-* stays on the 0.36 line as a set; chia-sdk-driver/-types
top out at 0.36.0, so moving the others to a 0.48 would split the crate across two chia lines.

NEXT ACTION: cargo test -p dig-wallet -p dig-node-service --lib is running; then mutation-prove
the three dig-node paging tests, then cargo fmt/clippy, version bump, and REMOVE the temporary
[patch.crates-io] in the root Cargo.toml once the contract has published 0.25.0. That patch is
labelled in the file and MUST NOT merge.

[MichaelTaylor3d]

Both halves are complete, green, and pushed as DRAFT PRs. Handing back to the gate.

• contract (goes first): feat(wallet): paginate control.wallet.coins dig-node-control-interface#37 — 0.25.0
• dig-node: feat(wallet): paginate the unspent-coin read #413 — 0.169.0, HEAD 4e5e04e

Evidence: dig-wallet 526/0, dig-node-service 709/0 (1 ignored), contract 176/0 + 9
doc-tests, clippy clean on all three, cargo fmt applied. Every new test proven load-bearing by a
mutation run against a committed tree — the table is in PR #413's body.

Merge order is not optional and PR #413 cannot merge first. It carries a temporary
[patch.crates-io] pointing the contract at a local worktree, labelled in the file. #37 merges and
publishes 0.25.0, then the patch is deleted and the lock re-resolved against the published crate.

The exact shape for dig-app (DIG-Network/dig-app#294), so it needs no re-derivation:

Request — both page fields OPTIONAL; omitting both is byte-identical to today's request:

{"address":"xch1…","asset":"dig","after_coin_id":"<64-hex, optional>","limit":100}

Response — coins unchanged, two fields added:

{"coins":[{"coin_id":"…","asset":"dig","amount":123,"parent_coin_info":"…",
           "puzzle_hash":"…","created_height":5000000,"spent_height":null}],
 "complete":false,"cursor":"<last coin_id of this page>",
 "source":"db","synced":true,"peak_height":5000000}

Rules dig-app must honour:

• ascending coin_id; resume by passing cursor back as after_coin_id. Never page by offset —
  a coin spent between pages shifts an offset and skips a coin, which reads as missing funds.
• complete: true = whole set. complete: false = more remain, resume from cursor.
• complete: null = a node older than 0.25 that never paged, so its answer IS the whole set.
  Do NOT read it as false: such a node also ignores after_coin_id, so resuming re-serves page
  one forever.
• limit outside 1..=1000 is -32602 INVALID_PARAMS, never clamped. Omit it to get 100.
• An empty page is still an ANSWER; every way of failing to reach a chain is a distinct error.

CLI: dign wallet coins <ADDRESS> [--asset xch|dig] [--after-coin-id <id>] [--limit <n>] [--json].
--json carries complete and cursor verbatim; the human summary prints
N unspent coin(s) · MORE remain — resume after <cursor> or · complete.

Not done, and stated rather than implied: no run against a real funded mainnet address yet
(§2.6). The paging is proven against the DB tier with a real sqlite replica and against the
fallback tier's in-memory path, not against a live address with thousands of coins.