docs(rewards): reward-distributor pages for funders and mirroring peers - #87
Conversation
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
left a comment
There was a problem hiding this comment.
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):
- 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.
- '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.
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>
Summary
Adds two-audience documentation for the
dig-rewards-coinmanaged reward distributor:docs/audiences/reward-funders.md(NEW) — funder-facing: the funding model (AddIncentivesvsCommitIncentives), clawback rule (not a computed figure — see #3303), and the SPEC §2.2 uptime warning with the required verbatim closing line andCOMMITMENT_DEPTH_EPOCHS = 2bound.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".docs/run-a-node/index.mdanddocs/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 onlydig.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-coinSPEC.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_000base units ->SPEC.md§8.3 (tag v0.4.0)CHALLENGE_STRIKES_TO_EVICT = 3->SPEC.md§3.6 (tag v0.4.0)dig-rpc-protocolv0.11.0dig.getRewardProverStatus, others return -32601 -> measured against dig-node v0.257.0Checks
npm run lint— passnpm run typecheck— passnpm 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 tablesnpm run test:unit— pending, will report before marking readyRefs #3254
🤖 Generated with Claude Code