Skip to content

docs(run-a-node): document which source answered a wallet balance read - #68

Merged
MichaelTaylor3d merged 1 commit into
mainfrom
docs/2233-tier-source
Aug 6, 2026
Merged

docs(run-a-node): document which source answered a wallet balance read#68
MichaelTaylor3d merged 1 commit into
mainfrom
docs/2233-tier-source

Conversation

@MichaelTaylor3d

Copy link
Copy Markdown
Contributor

Docs half of dig_ecosystem#2233 (S1 of the #2232 sync plan). Node half: DIG-Network/dig-node#189. Contract half: DIG-Network/dig-node-control-interface#5.

control.wallet.balance now returns a source field, and its synced / peak_height fields changed meaning: they describe the source that answered, not the node in general. docs/run-a-node/manage.md described the old behaviour, which is a bug per §4.3.

Updated: the result JSON sample, the field table, and a new short "Where the answer came from" subsection written for audience 1 (node operators) — plain language, no protocol jargon, leading with the consequence that matters to a person: a "fallback" answer means their address was sent to a public service.

This also makes an existing claim in point-a-consumer.md — that reading from your own node is more private because "your addresses aren't disclosed to a public operator" — checkable by the reader rather than something they have to take on trust.

No i18n changes needed: peak_height appears only in the English tree (grep -rl peak_height i18n/ is empty), so no locale copy is being left stale.

0.13.0 → 0.14.0 (minor: new documented capability).

git diff --shortstat and --ignore-cr-at-eol agree (17/4), so no CRLF flip.

Refs dig_ecosystem#2233

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

@MichaelTaylor3d MichaelTaylor3d left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT: PASS — reviewed at 84ec5461fc861848b1765ec6d87855771b0dcc23.

Verified:

  • Describes shipped behaviour, not intent. The sample, the field table and the new subsection match dig-node#189's actual arms: "fallback"synced:false and peak_height:null, "db" ⇒ the replica's peak. The source row correctly documents null as "a node too old to say", which matches the contract crate's Option tri-state rather than inventing a default.
  • §4.3 clean. No reference to SYSTEM.md / SPEC.md / CLAUDE.md / internal tickets; no drift commentary; audience-1 voice throughout. The consequence a person actually cares about — the address you asked about was sent to that service — leads, which is the right ordering for this audience.
  • No stale locale copy. I re-derived the claim independently: peak_height appears in exactly one file tree-wide (docs/run-a-node/manage.md), and the 13 localised manage.md files are the shorter, pre-balance-section version (46 lines vs 130) with no balance content at all — so nothing localized goes stale. Their incompleteness is a pre-existing gap, not this PR's.
  • The claim in point-a-consumer.md:46 ("your addresses aren't disclosed to a public operator") does become checkable by the reader for the first time, as the body says.
  • --shortstat matches --ignore-cr-at-eol (17/4). 0.13.0 → 0.14.0 is right for new documented capability.

No findings. Nothing open from me on this PR.

One cross-PR heads-up, not a change request here: I have raised a gating item on dig-node#189 about the tier tracing event being debug! under an info default filter. It does not affect any sentence on this page — nothing here promises the tier appears in the log.

@MichaelTaylor3d
MichaelTaylor3d merged commit d5eaf5a into main Aug 6, 2026
7 checks passed
@MichaelTaylor3d
MichaelTaylor3d deleted the docs/2233-tier-source branch August 6, 2026 07:03
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