Skip to content

docs(rewards): reward-distributor pages for funders and mirroring peers - #87

Merged
MichaelTaylor3d merged 6 commits into
mainfrom
docs/3254-reward-distributor
Sep 11, 2026
Merged

MichaelTaylor3d merged 6 commits into
mainfrom
docs/3254-reward-distributor

Conversation

@MichaelTaylor3d

Copy link
Copy Markdown
Contributor

Summary

Adds two-audience documentation for the dig-rewards-coin managed reward distributor:

  • docs/audiences/reward-funders.md (NEW) — funder-facing: the funding model (AddIncentives vs CommitIncentives), clawback rule (not a computed figure — see #3303), and the SPEC §2.2 uptime warning with the required verbatim closing line and COMMITMENT_DEPTH_EPOCHS = 2 bound.
  • docs/run-a-node/earn-mirror-rewards.md (NEW) — peer/mirror-facing: claim cadence/jitter, payout floor vs fee ceiling, eviction (terminal for the entry, not the mirror), and what to check if unpaid (points to node status, does not reconstruct the never-admitted-vs-evicted distinction SPEC §12.5 clause 7 forbids).
  • sidebars.ts — new "Reward funders" category (funder page) + peer page added to "Node operators".
  • One-line cross-links from docs/run-a-node/index.md and docs/audiences/app-developers.md.

Both pages state their audience in the first three sentences and cross-link the other page by role. No figures were added to machine-spec surfaces (scripts/dig-spec.mjs, docs/rpc/**, static/*.json) — the three unserved reward RPC methods (dig-node v0.257.0 serves only dig.getRewardProverStatus) are named in prose only.

Blast radius: two new doc files + 3 existing files touched (sidebar + 2 cross-links); ripgrep-checked, no other doc references these new IDs yet.

Figure -> source trace

  • COMMITMENT_DEPTH_EPOCHS = 2 -> dig-rewards-coin SPEC.md §7.4 clause 1 (tag v0.4.0)
  • withdrawal_share_bps = 9000 (90/10 clawback split) -> SPEC.md §7.4/§7.5 (tag v0.4.0)
  • CLAIM_CADENCE_SECONDS = 86_400 / CLAIM_JITTER_SECONDS = 3_600 -> SPEC.md §8.6 (tag v0.4.0)
  • payout_threshold = 1_000 base units -> SPEC.md §8.3 (tag v0.4.0)
  • CHALLENGE_STRIKES_TO_EVICT = 3 -> SPEC.md §3.6 (tag v0.4.0)
  • dig-rpc-protocol four reward methods -> dig-rpc-protocol v0.11.0
  • dig-node serves only dig.getRewardProverStatus, others return -32601 -> measured against dig-node v0.257.0
  • no clawback affordance in app -> dig-app 15.6.0, consequence of the -32601 gap (dated, true cause named, no upgrade promise)
  • empty first-epoch is normal / accrued value carries forward -> SPEC §15 clause 9a, resolved by execution per ticket

Checks

  • npm run lint — pass
  • npm run typecheck — pass
  • npm run build (includes drift-gate prebuild) — pass; drift gate reported "drift gate passed" with unchanged RPC method counts (9 network / 10 node) — the three unserved reward methods were NOT added to machine-spec tables
  • npm run test:unit — pending, will report before marking ready

Refs #3254

🤖 Generated with Claude Code

MichaelTaylor3d and others added 2 commits September 10, 2026 20:10
Add two audience pages for the dig-rewards-coin managed reward
distributor: a funder page (fund/clawback/uptime risk) and a peer page
(claim cadence/eviction/troubleshooting), cross-linked by role. Wire
both into sidebars.ts and add one-line cross-links from the node
operator index and the app-developers landing page.

Refs #3254

Co-Authored-By: Claude Sonnet 5 <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.

Independent correctness review (loop-reviewer). Verdict: CHANGES-REQUIRED. head e5573dd.

Numeric/version claims cross-checked against artifacts (not against sibling docs):

  • dig-rewards-coin 0.4.0 (chain reader): tag --contains on the adding commit (581c679, 'feat: chain reader + SPEC 0.5 cohort-pin correction (0.4.0) (#6)') = v0.4.0 only. Matches.
  • COMMITMENT_DEPTH_EPOCHS = 2: dig-rewards-coin SPEC.md §7.4 clause 1 (also §2.2 clause 5, §14 table row C2).
  • dig-rpc-protocol v0.11.0: Cargo.toml on main (GitHub contents API) = 0.11.0. Matches.
  • dig-node v0.257.0: Cargo.toml on main = 0.257.0. Matches.
  • dig-app 15.6.0: Cargo.toml on main = 15.6.0 (ahead of the last cut tag v15.4.0, but that is the checked-out artifact, so it's the correct figure). Matches.
  • Only dig.getRewardProverStatus served: confirmed by reading dig-node crates/dig-node-core/src/seams/dig_rpc/dispatch.rs directly -- getRewardProverStatus is wired (line ~773); listRewardDistributors / getRewardDistributor / listRewardDistributorCommitments do not appear in dispatch at all (they exist only in crates/dig-node-core/src/rewards/port.rs and funded.rs -- port-side, not dispatched). Matches 'unserved -> -32601'.
  • CLAIM_CADENCE_SECONDS=86_400, CLAIM_JITTER_SECONDS=3_600: dig-rewards-coin SPEC.md §8.6 (lines ~1453-1454). Matches.
  • payout_threshold = 1_000 base units = 1.000 $DIG: SPEC.md §8.3 line 1404. Matches.
  • 200,000-mojo per-claim ceiling: dig-node crates/dig-node-service/src/rewards_claim/config.rs, CLAIM_FEE_CEILING_MOJOS_DEFAULT: u64 = 200_000. Matches.
  • Three-consecutive-strike eviction: dig-rewards-coin SPEC.md §3.6 heading 'Eviction is three consecutive strikes, not one failure'. Matches.

Drift-gate scope check (docs.dig.net CLAUDE.md): scripts/dig-spec.mjs, docs/rpc/**, docs/support/error-codes.md, static/*.json are all ABSENT from this diff, correctly -- three of the four reward RPC methods are unserved and must not enter the machine-spec tables.

i18n: no new files under i18n// in this diff. Confirmed by full gh pr diff --name-only.

Blocking findings below, both reproduced from the PR's own CI runs (not re-derived):

  1. Docusaurus build fails for the zh-CN locale: 'Docusaurus found broken links' on docs/audiences/reward-funders.md:116 and docs/run-a-node/earn-mirror-rewards.md:76 (run 34559377374). The English default-locale build compiles; the zh-CN locale build does not resolve the same relative links and the whole build step fails, which is why 'build + a11y/SEO tests' is red on this PR.
  2. 'Check version increment' is red: package.json base=0.17.3, head=0.17.3 -- this repo gates every PR (docs-only included) on a version bump, and this PR does not carry one.

check-merge-preconditions.sh --repo DIG-Network/docs.dig.net --pr 87 exit code: 1 (BLOCKED) -- draft=true, mergeStateStatus=BLOCKED, 'Check version increment' and 'build + a11y/SEO tests' both COMPLETED/FAILURE.

Not reviewed (out of my lane): the money/roles content on these pages -- that is the parallel adversarial leg's job.

Comment thread docs/audiences/reward-funders.md Outdated
Comment thread docs/run-a-node/earn-mirror-rewards.md Outdated
MichaelTaylor3d and others added 4 commits September 11, 2026 00:37
C1: earn-mirror-rewards.md:38-39 asserted a fee-floor guarantee nothing
on the node can compute (contradicted four lines later); replace with
the true mechanism and the actual reason 1 DIG was chosen.

C3: reward-funders.md:28 cited dig-rewards-coin 0.4.0; dig-rewards-coin
PR #9 cuts 0.4.1 -- update to match (merge #9 first, wait for
publish.yml, then this PR).

C4: earn-mirror-rewards.md:65-66 let "three consecutive strikes" read
as a diagnosis a peer can make; add that eviction and never-added are
indistinguishable on chain (RemoveEntry leaves no marker), per SPEC.md
section 12.5 clause 7.

Also bump package.json 0.17.3 -> 0.17.4 to satisfy this repo's
"Check version increment" gate for a docs-only PR; regenerated
static/openrpc*.json and static/knowledge-graph.json pick up the new
version via the repo's own gen scripts.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
… convention

The relative ./index.md and ../run-a-node/index.md links from these
two new pages resolve fine in the English build but break in the
zh-CN locale build (Docusaurus found broken links, zh-CN only) --
other run-a-node/* pages already sidestep this by linking to the
landing page with the absolute /docs/run-a-node form (see
docs/run-a-node/local-https.md); apply the same convention here.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…urce

This PR added a cross-link to the new earn-mirror-rewards.md page in
docs/run-a-node/index.md but left all 13 locale copies stale --
tests/unit/install-path-lint.test.mjs enforces byte-identical
untranslated copies for install pages, and a stale copy is also what
made the zh-CN build's broken-link check fail against the new page's
link (the copy it resolved against predated the earn-mirror-rewards.md
page). Copy the English source over every locale, per this repo's own
documented convention for these pages.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Same defect as the earlier link fix, one level up: docs/run-a-node/index.md
links to the new earn-mirror-rewards.md page relatively, which breaks the
zh-CN build the same way (no locale twin for the target). Use the
established /docs/run-a-node/<page> absolute form and re-sync the 13
locale copies.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@MichaelTaylor3d
MichaelTaylor3d marked this pull request as ready for review September 11, 2026 08:17
@MichaelTaylor3d
MichaelTaylor3d merged commit 269152e into main Sep 11, 2026
7 checks passed
@MichaelTaylor3d
MichaelTaylor3d deleted the docs/3254-reward-distributor branch September 11, 2026 08:19
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