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

docs/audiences/app-developers.md

@@ -112,6 +112,11 @@ Your store is reachable by its [URN](../concepts.md#urn) / [`chia://`](../browse
 
 ---
 
+## Want your store mirrored more widely?
+
+If you want other operators to help serve your store, you can fund a **reward distributor** that
+pays mirrors automatically. See [Fund a reward distributor](./reward-funders.md).
+
 ## Go deeper: the protocol
 
 The plain-language model above is all you need to ship. When you want the full design:

docs/audiences/reward-funders.md

@@ -0,0 +1,116 @@
+---
+sidebar_position: 1
+title: Fund a reward distributor
+description: "Fund a managed reward distributor that pays your mirrors automatically, with a bounded, recoverable commitment — and what a stopped prover does and does not do to that payment."
+keywords:
+  - reward distributor
+  - fund mirrors
+  - clawback
+  - CommitIncentives
+  - reward funders
+tags:
+  - dig-rewards-coin
+  - dig-rpc
+  - custody
+---
+
+# Fund a reward distributor
+
+> **This page is for the funder** — whoever pays a store's `dig-rewards-coin` reward distributor to
+> attract mirrors. If you are a peer *mirroring* someone else's store to earn from a distributor
+> someone else funded, this is not your page: see
+> [Earn rewards for mirroring](../run-a-node/earn-mirror-rewards.md) instead, and read the role
+> difference there before assuming a figure on that page is yours.
+
+## The mental model
+
+A reward distributor is an on-chain, `Managed`-type CHIP-0051 coin
+(`dig-rewards-coin` [0.4.1](https://crates.io/crates/dig-rewards-coin)) that a funder launches and
+commits $DIG to, so that peers who mirror the funder's store are paid automatically for passing
+periodic challenges. **The distributor pays itself** — payouts are permissionless spends any
+eligible peer can build once admitted — so the funder is not in the path of an individual payment.
+The funder's own node runs the **prover**, the process that admits and evicts peers from the paid
+list; it does not gate payment itself (see the uptime warning below).
+
+## Funding is per commitment, and only `CommitIncentives` is recoverable
+
+There are two ways to put $DIG into a distributor, and they are not interchangeable:
+
+- **`AddIncentives`** adds to the *current* epoch's rewards. It creates no commitment slot. It is an
+  **irrevocable donation** — there is nothing later to claw back.
+- **`CommitIncentives`** funds a *future* epoch and creates a commitment slot recording a
+  `clawback_puzzle_hash` entitled to reclaim it. This is the recoverable funding path, and it
+  defaults to **`COMMITMENT_DEPTH_EPOCHS = 2`** future epochs
+  (`dig-rewards-coin` `SPEC.md` §7.4 clause 1, tag `v0.4.0`) — deep enough for one full epoch of
+  slack at the default 7-day epoch length, shallow enough to bound exposure if the prover ever stops
+  admitting new peers (see the warning below).
+
+**Only `CommitIncentives` gives you anything to withdraw.** If your funding UI offers a clawback
+button next to money that went in through `AddIncentives`, that button does not correspond to
+anything on chain.
+
+## Clawback: who, and how much — the rule, not a number
+
+Only the holder of the key recorded as that commitment slot's `clawback_puzzle_hash` may claw it
+back (`SPEC.md` §7.4 clause 3, `v0.4.0`) — **not** the manager singleton, **not** the launcher
+coin, and **not** any operator role. A clawback returns **90%** of the committed slot; the
+remaining **10%** is forfeit to the reserve, where it is later paid out to whichever peers hold
+entries at that time — not to the mirrors whose costs the funder is retracting against (`SPEC.md`
+§7.4/§7.5, `v0.4.0`).
+
+We are not showing a computed recoverable amount on this page. A pre-existing defect in this
+crate's `withdraw_committed_incentives` (tracked as
+[dig-rewards-coin#3303](https://github.com/DIG-Network/dig-rewards-coin/issues/3303), present
+since 0.3.0) returns an uncorrected wrapped `u64` for a clawback figure, so any number the software
+shows you for "what you'd get back" is **not yet trustworthy** — the 90/10 *rule* above is normative
+and correct; a *displayed total* is not, until that fix lands. Do not rely on a shown recoverable
+figure to decide how much to commit.
+
+## Your uptime — what your prover does and does not control
+
+**This is the funder's own risk, not a peer's.** Your prover is the process that decides *who* is on
+the paid list; it is not the gate on *whether* anyone gets paid.
+
+1. **Payment does not pause when your prover stops.** Accrual and payouts are permissionless — a
+   peer who already holds an entry can claim without your node's participation, at any time.
+2. **Your funds are not lost when it stops.** They stay in the reserve, and anything you funded with
+   `CommitIncentives` remains clawback-eligible the whole time.
+3. **What actually breaks: the paid list freezes.** While your prover is stopped, peers who have
+   stopped mirroring your store keep earning, and peers who start mirroring cannot be added to the
+   list that gets paid.
+4. **Losing your manager singleton key freezes that list permanently** — unless you chose a
+   recovery-capable inner puzzle (a multisig or k-of-n) for the manager singleton **at launch**.
+   That choice is offered only on the creation screen, before the launch spend is signed, and is
+   fixed for the distributor's whole life once you sign.
+5. **How bad #3 can get, as a number:** it is bounded by how many future epochs you've already
+   committed — `COMMITMENT_DEPTH_EPOCHS = 2` by default. At the default epoch length that is at most
+   roughly two weeks of paying a list that stopped tracking who is really mirroring — a bounded risk,
+   not an open-ended one.
+
+**Downtime does not pause payment. It hands payment to a list that has stopped being true.**
+
+## What you can check on this node today
+
+`dig-rpc-protocol` v0.11.0 defines four reward-distributor RPC methods
+(`dig.getRewardProverStatus`, `dig.listRewardDistributors`, `dig.getRewardDistributor`,
+`dig.listRewardDistributorCommitments`). **As of `dig-node` v0.257.0, only
+`dig.getRewardProverStatus` is served** — the other three return `-32601` (method not found). The
+cause is that `dig-node` has not yet implemented them, not a version mismatch you can resolve by
+upgrading. **Consequence: as of `dig-app` 15.6.0, there is no clawback affordance in the app** — the
+UI to browse your commitments and initiate a withdrawal is not there yet, on any current version.
+This page will be updated when that surface ships; there is no workaround today beyond building
+against the RPC and driver directly.
+
+## The empty first epoch is normal, not a stranding risk
+
+Every distributor spends its first epoch with no admitted peers yet — the default launch delay and
+the minimum time before a first entry can be written mean an empty entry set at the start is the
+ordinary path, not a misconfiguration. Value that accrues during that window carries forward and is
+fully distributable once peers are admitted; you do not need to tune anything about your launch
+timing to avoid losing it.
+
+## Related
+
+- [Earn rewards for mirroring](../run-a-node/earn-mirror-rewards.md) — the peer's side of this same
+  distributor
+- [Run a DIG node](/docs/run-a-node)

docs/run-a-node/earn-mirror-rewards.md

@@ -0,0 +1,84 @@
+---
+sidebar_position: 12
+title: Earn rewards for mirroring
+description: "Get paid automatically for mirroring a store whose funder runs a reward distributor — the claim cadence, the payout floor, why a claim is skipped rather than failed, and what to do if you stop getting paid."
+keywords:
+  - reward distributor
+  - mirror rewards
+  - claim cadence
+  - payout threshold
+tags:
+  - dig-rewards-coin
+  - dig-node
+  - mirror
+---
+
+# Earn rewards for mirroring
+
+> **This page is for a mirroring peer** — a `dig-node` operator mirroring someone else's store and
+> being paid for it. If you are the one funding a reward distributor to attract mirrors, this is not
+> your page: see [Fund a reward distributor](../audiences/reward-funders.md) instead, and read the
+> role difference there before assuming a figure on that page is yours.
+
+## The mental model
+
+A store's funder can launch a `dig-rewards-coin` reward distributor and commit $DIG to it. If you
+mirror that store and pass the distributor's periodic challenges, your node accrues a share and can
+claim it. **These are your own earnings from that specific distributor** — not the funder's total
+commitment, and not any other peer's.
+
+## How your claim works
+
+Your node's claim loop runs on its own cadence, independent of the distributor: it claims every
+**24 hours** by default (`CLAIM_CADENCE_SECONDS = 86_400`), jittered by at least **1 hour**
+(`CLAIM_JITTER_SECONDS = 3_600`) so a fleet of peers sharing the default doesn't converge on the
+same minute and self-congest (`dig-rewards-coin` `SPEC.md` §8.6, tag `v0.4.0`).
+
+**If your accrued amount is below the payout floor, the claim is skipped, not failed.** The floor is
+**1,000 base units = 1.000 $DIG** (`SPEC.md` §8.3, `v0.4.0`). Nothing compares that to a fee: the
+threshold is in $DIG base units, an on-chain fee is in XCH mojos, and your node has no rate between
+the two — so "the fee is smaller than the claim" is not computed anywhere. 1 $DIG was chosen as above
+any *plausible* fee, and small enough that a mirror earning at the §6.5 funding floor clears it daily
+(`SPEC.md` §8.3 clauses 1-2, `v0.4.0`); a mirror earning below that funding floor clears it less often. A skipped
+claim is not an error and nothing is lost: your accrual keeps building toward the next attempt.
+
+There is no computable floor in $DIG terms that also accounts for the on-chain fee in mojos — those
+are two different assets with no exchange rate available on your node. The **$DIG payout threshold
+above is the real floor** on whether a claim goes out at all. Your node's own fee settings (a
+200,000-mojo ceiling per claim, plus a persisted per-window budget) are a **ceiling** on what your
+node is willing to spend claiming, not a floor on what you're owed — do not read them as the
+minimum payout.
+
+## Eviction — three consecutive missed challenges, and it is not permanent
+
+The distributor's prover challenges every mirror it has admitted. A cycle your node fails
+increments a strike counter for you; a cycle you pass resets it to zero. At **three consecutive
+strikes** you are removed from the paid list (`SPEC.md` §3.6, `v0.4.0`) — roughly three hours of
+continuous unavailability at the default challenge cadence, long enough to be a real outage rather
+than one dropped packet.
+
+Removal is terminal for that entry, not for you as a mirror: you can pass the challenge again and,
+after a cooldown, be re-admitted. Your own claim loop keeps watching a distributor it knows about
+even while you hold no entry in it — it costs your node nothing but an occasional chain read, and
+it's the only way to notice you've been re-admitted.
+
+## If you stop getting paid
+
+A missing payout can mean several benign things — you're below the payout floor this cycle, your
+entry hasn't landed yet, or you're between challenges. **It can also mean something is actually
+wrong** — a networking problem, a challenge you're failing without knowing it, or eviction. Holding no
+entry does not tell you which of these it is: an entry you were evicted from and an entry that was
+never added look identical on chain, because `RemoveEntry` spends the slot and leaves no marker
+behind, and nothing may present a guess between them as an accounting fact (`SPEC.md` §12.5 clause 7,
+`v0.4.0`). Your own past `InitiatePayout` spends are the only on-chain evidence of your own claim
+history. Your
+node's own status surface is where to check, because a list of ordinary reasons is not a substitute
+for knowing whether one of them is actually the failure: if your `dig-node` reports a real problem
+(a chain-source outage, a cycle deadline miss, a stopped claim loop), treat that report as the
+signal — don't assume "not paid yet" is always benign without checking.
+
+## Related
+
+- [Fund a reward distributor](../audiences/reward-funders.md) — the funder's side of this same
+  distributor
+- [Run a DIG node](/docs/run-a-node)

docs/run-a-node/index.md

@@ -98,6 +98,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digs serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
 - [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
+- [Earn rewards for mirroring](/docs/run-a-node/earn-mirror-rewards) — get paid automatically for mirroring a store whose funder runs a reward distributor
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `dig-store` on its own (publishing, not serving)
 

i18n/de/docusaurus-plugin-content-docs/current/run-a-node/index.md

@@ -98,6 +98,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digs serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
 - [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
+- [Earn rewards for mirroring](/docs/run-a-node/earn-mirror-rewards) — get paid automatically for mirroring a store whose funder runs a reward distributor
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `dig-store` on its own (publishing, not serving)
 

i18n/es/docusaurus-plugin-content-docs/current/run-a-node/index.md

@@ -98,6 +98,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digs serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
 - [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
+- [Earn rewards for mirroring](/docs/run-a-node/earn-mirror-rewards) — get paid automatically for mirroring a store whose funder runs a reward distributor
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `dig-store` on its own (publishing, not serving)
 

i18n/fr/docusaurus-plugin-content-docs/current/run-a-node/index.md

@@ -98,6 +98,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digs serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
 - [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
+- [Earn rewards for mirroring](/docs/run-a-node/earn-mirror-rewards) — get paid automatically for mirroring a store whose funder runs a reward distributor
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `dig-store` on its own (publishing, not serving)
 

i18n/hi/docusaurus-plugin-content-docs/current/run-a-node/index.md

@@ -98,6 +98,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digs serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
 - [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
+- [Earn rewards for mirroring](/docs/run-a-node/earn-mirror-rewards) — get paid automatically for mirroring a store whose funder runs a reward distributor
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `dig-store` on its own (publishing, not serving)
 

i18n/id/docusaurus-plugin-content-docs/current/run-a-node/index.md

@@ -98,6 +98,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digs serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
 - [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
+- [Earn rewards for mirroring](/docs/run-a-node/earn-mirror-rewards) — get paid automatically for mirroring a store whose funder runs a reward distributor
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `dig-store` on its own (publishing, not serving)
 

i18n/ja/docusaurus-plugin-content-docs/current/run-a-node/index.md

@@ -98,6 +98,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digs serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
 - [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
+- [Earn rewards for mirroring](/docs/run-a-node/earn-mirror-rewards) — get paid automatically for mirroring a store whose funder runs a reward distributor
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `dig-store` on its own (publishing, not serving)
 

i18n/ko/docusaurus-plugin-content-docs/current/run-a-node/index.md

@@ -98,6 +98,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digs serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
 - [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
+- [Earn rewards for mirroring](/docs/run-a-node/earn-mirror-rewards) — get paid automatically for mirroring a store whose funder runs a reward distributor
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `dig-store` on its own (publishing, not serving)
 

i18n/pt-BR/docusaurus-plugin-content-docs/current/run-a-node/index.md

@@ -98,6 +98,7 @@ You don't need a node. Get the **[DIG Browser ↗](https://github.com/DIG-Networ
 - [Self-host a remote origin](../rpc/dig-remote.md) — `digs serve` + dig:// clone/pull/push
 - [Manage your node](./manage.md) — the control.* admin RPCs + the My Node UI
 - [The dig-node Control Panel](./control-panel.md) — run your node from the DIG extension: live status, reserved cache space (LRU), and — once paired — upstream/hosted stores/sync/peers
+- [Earn rewards for mirroring](/docs/run-a-node/earn-mirror-rewards) — get paid automatically for mirroring a store whose funder runs a reward distributor
 - [Using the public network RPC](../rpc/public-network-rpc.md) — the dig RPC your node speaks, and operating a node on the network
 - [Installing the CLI](../digstore/cli/install.md) — `dig-store` on its own (publishing, not serving)