Skip to content

docs: document wallet chain-read control methods - #71

Merged
MichaelTaylor3d merged 1 commit into
mainfrom
docs/2392-wallet-chain-reads
Aug 9, 2026
Merged

docs: document wallet chain-read control methods#71
MichaelTaylor3d merged 1 commit into
mainfrom
docs/2392-wallet-chain-reads

Conversation

@MichaelTaylor3d

@MichaelTaylor3d MichaelTaylor3d commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

What changed

Closes the documentation gap in #2392: dig-node's control plane now serves five control.wallet.* methods, but only control.wallet.balance was documented.

  • docs/run-a-node/manage.md — restructured the single control.wallet.balance section into a control.wallet.* overview (open-read vs token-gated split, the "never signs" invariant) followed by five subsections: balance (unchanged content), coins, peak, coinById, broadcast. Each documents its request/result shape, field table, and the load-bearing semantics from the spec (coins: [] vs an unreachable-chain error, peak_height: null as unknown-not-zero, coinById's ability to see a spent coin, broadcast's accepted-vs-confirmed distinction).
  • docs/support/error-codes.md — generalized the -32040..-32043 row descriptions and links from "wallet-balance read codes" to cover all control.wallet.* methods; no codes added or removed.
  • scripts/dig-spec.mjs — generalized the matching meaning strings feeding static/error-codes.json so the machine-readable catalog and the prose stay in sync.
  • static/error-codes.json — regenerated (npm run machine-specs); the drift gate passed (65 codes, 4 surfaces — same counts as before, wording only).
  • package.json — version bump 0.15.00.16.0 (minor: new documented capability).

Saturation search

Searched the whole docs tree for control.wallet / wallet.balance / control.* summaries. No other page lists or summarizes individual control methods — docs/rpc/methods.md's dig.methods example is the network-profile method list and doesn't include control.* (admin-plane, not network profile), so it did not need updating. docs/run-a-node/manage.md's own control.* bullet summary (status/cache/peers) now has a fourth bullet for wallet.

Verified

  • node scripts/gen-machine-specs.mjs — drift gate passed, no code-set changes.
  • npm run build — full Docusaurus build (all 15 locales) completed with exit 0, no broken-link errors introduced.

Blast radius

Docs-only change, one repo (docs.dig.net), no code/API touched. The only "existing claim" I checked for mismatch against the given method shapes: the prior control.wallet.balance doc's error table and source/synced/peak_height semantics — carried forward unchanged, no discrepancy found.

Co-Authored-By: Claude noreply@anthropic.com

Extends the existing control.wallet.balance page into a full
control.wallet.* reference covering the four open chain reads
(balance, coins, peak, coinById) and the one token-gated write
(broadcast) that dig-node's control plane now serves. Generalizes
the -32040..-32043 error-code descriptions in error-codes.md and
their source in scripts/dig-spec.mjs, which previously named only
control.wallet.balance, to cover every control.wallet.* method.

Co-Authored-By: Claude <noreply@anthropic.com>
@MichaelTaylor3d
MichaelTaylor3d force-pushed the docs/2392-wallet-chain-reads branch from e8444e9 to 552b838 Compare August 9, 2026 02:29
@MichaelTaylor3d
MichaelTaylor3d marked this pull request as ready for review August 9, 2026 02:29
@MichaelTaylor3d

Copy link
Copy Markdown
Contributor Author

HOLD — do not merge until control.wallet.coinById is actually served

This PR documents five control.wallet.* methods. Four are live today. control.wallet.coinById is
not
— it is still in flight (dig-node-control-interface#7 → 0.7.0, and dig-node#201 to serve it).

docs.dig.net deploys on merge, so merging now would publish documentation for a capability that does not
exist. Documentation is a claim about the system; a documented method that returns -32601 is the same
class of defect as a UI control that looks live and does nothing.

Release order for this change: dig-node-control-interface 0.7.0 publishes → dig-node serves it and
releases → then this merges. The other four methods' docs (balance, coins, peak, broadcast)
are correct today and are only waiting on the fifth for this reason — they shipped in dig-node#200 with
no docs at all, which is the gap this PR also closes.

Held by the #2392 lane orchestrator, which will merge it once the serving release is green and live.
Refs DIG-Network/dig_ecosystem#2392.

@MichaelTaylor3d
MichaelTaylor3d marked this pull request as draft August 9, 2026 03:31
@MichaelTaylor3d

Copy link
Copy Markdown
Contributor Author

Converted to draft deliberately — this is a HOLD, not a problem with the PR.

The content is clean and the checks are green. It is blocked on a sequencing fact, not a defect: it documents control.wallet.coinById, which dig-node does not serve yet. Publishing user-facing docs for an unserved method would make docs.dig.net assert something false about the running system.

Merge order:

  1. dig-node-control-interface Auto-redirect first-time visitors to their browser locale #7 -> 0.7.0 on crates.io (declares the method) — in flight now.
  2. dig-node#201 adopts 0.7.0 and actually serves it.
  3. This PR, once a real node answers the method it describes.

It was sitting CLEAN and non-draft, so the hold was purely a note somebody had to read and honour — the same conventional-not-structural shape the review gate flagged on #7 itself. Draft makes it unmergeable until step 2 lands. Mark ready then; no rebase or content change is expected.

@MichaelTaylor3d

Copy link
Copy Markdown
Contributor Author

Merge-order constraint — this PR must land AFTER dig-node serves control.wallet.coinById, never before.

This PR documents control.wallet.coinById (10 references in the diff). The method does not exist on any released dig-node: it is implemented on DIG-Network/dig-node PR #201 (branch feat/2392-coin-read-by-id, dig_ecosystem#2392) and the contract half is dig-node-control-interface PR #7 → 0.7.0, neither merged yet.

Merging this first would publish user-facing documentation for a method that answers -32601 METHOD_NOT_FOUND on every node in the field. Per §4.3, docs are authoritative for users — a documented method that does not exist is worse than an undocumented one that does.

Order: contract 0.7.0 publishes → dig-node #201 merges and releases → this PR merges.

The PR is CLEAN and green; nothing here needs changing. It is purely a sequencing hold. Posted from the dig-node lane so the constraint survives outside a session's context.

@MichaelTaylor3d
MichaelTaylor3d marked this pull request as ready for review August 9, 2026 15:19
@MichaelTaylor3d
MichaelTaylor3d merged commit d79649a into main Aug 9, 2026
8 checks passed
@MichaelTaylor3d
MichaelTaylor3d deleted the docs/2392-wallet-chain-reads branch August 9, 2026 15:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant