From 8171edb8bf08b3df563b484f29f69c307b5a52df Mon Sep 17 00:00:00 2001 From: Yak Date: Tue, 22 Jul 2025 17:39:16 -0400 Subject: [PATCH 1/6] add CHIPs --- CHIPs/chip-0050.md | 58 +++++++++++++++++++++++++++++++++++++++ CHIPs/chip-0051.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+) create mode 100644 CHIPs/chip-0050.md create mode 100644 CHIPs/chip-0051.md diff --git a/CHIPs/chip-0050.md b/CHIPs/chip-0050.md new file mode 100644 index 00000000..13e644a6 --- /dev/null +++ b/CHIPs/chip-0050.md @@ -0,0 +1,58 @@ +CHIP Number | < Creator must leave this blank. Editor will assign a number.> +:-------------|:---- +Title | Action Layer and Slots +Description | A singleton inner layer that handles the core needs of complex dApps: efficient multi-action calls in a single spend and persistent state. +Author | [yakuhito](https://github.com/Yakuhito) +Editor | < Creator must leave this blank. Editor will be assigned.> +Comments-URI | < Creator must leave this blank. Editor will assign a URI.> +Status | < Creator must leave this blank. Editor will assign a status.> +Category | Informational +Sub-Category | Chialisp +Created | 2025-07-22 +Requires | - +Replaces | - +Superseded-By | - + +## Abstract +This CHIP proposes a singleton inner layer that handles the common needs of Chia decentralized applications. The combination of puzzles allows singletons to efficiently support more than one ‘action’ (i.e., functionality), much like Solidity contracts have multiple methods that can be called. Moreover, multiple actions can be efficiently called within the same spend, drastically reducing total spend bundle cost. Each action call has access to spend-specific context via the ephemeral state (e.g., am I the first action to run?), as well as long-term context via the persistent/normal dApp state (e.g., what’s the current registration price for an item?). Finalizers are customizable components that can be defined to control the logic the singleton runs at the end of every spend. The default finalizer simply recreates the singleton with a new state, while the reserve finalizer also manages a CAT or XCH reserve owned by the dApp. This proposal also includes slots, another form of persistent storage that leverages the coinset model. + +## Motivation +A set of core properties (behavior) can be observed when analyzing most blockchain-powered decentralized applications. Namely: + * **Multiple capabilities**: A dApp may have multiple distinct functionalities. Users interacting with it may run one or more of these functionalities. For example, a user may add/remove liquidity from a TibetSwap pair or swap one asset for the other. + * **Multiple interactions from many parties**: As a shared resource, the dApp is expected to support multiple interactions from different parties, sometimes in the same block. A dApp should do this efficiently (i.e., in a way that minimizes transaction cost as much as practically possible), and, ideally, in a way that works well with the mempool’s current Replace-by-Fee rules. + * **State**: Most dApps have state variables, which are persistent across spends. These variables may be simple values (integers, strings, etc.), lists of values, or even mappings. + * **Reserves**: Some dApps may also manage user funds. For example, a TibetSwap pair manages the funds of liquidity providers, which it uses to allow traders to swap one asset for the other. + +The action layer and slots were designed as a ‘framework’ that takes care of these needs with minimal code changes across apps. This way, Chialisp developers can focus on designing and optimizing an app’s defining logic without having to worry about the aspects described above. + + +## Backwards Compatibility +This proposal includes a new set of puzzles intended as a dApp framework. The main goal is to greatly simplify dApp development, but their use is completely optional. Both already-deployed and future apps may opt not to use the puzzles described in this CHIP without them being considered as going against the CHIP. + +## Rationale +To support multiple actions, a pattern similar to the p2_1_of_n puzzle was employed. Namely, all puzzles allowed to run are put into a Merkle tree whose corresponding root is kept in the action layer. When an action is run, its puzzle, along with the corresponding Merkle proof, are revealed. For subsequent action runs in the same spends, the previous puzzle reveal is referenced, eliminating the need to store and hash the same puzzle reveal multiple times. + +Each action is given two states as truths, as well as a user-provided solution. The ephemeral state starts out as `()` for each new singleton spend, giving actions a way to access spend-specific context (e.g., whether the action is the first to be run in the spend, which is relevant if the action uses relative conditions). The second state is persistent - it is preserved across spends and always constitutes the output of the previous action (except for the state given to the first action in the eve singleton spend). Actions return new states to be passed to the next action (or discarded - like the ephemeral state is for the last action run in a spend), as well as a list of output conditions which will be processed and (by default) passed to the singleton layer. + +The action layer’s customizable component is called a finalizer, which includes any logic that needs to run at the end of a spend. The default finalizer is a minimal puzzle that only re-creates the singleton coin with a new state. The reserve finalizer also allows the singleton to manage one reserve whose amount is kept in the persistent state (usually as the first value). Actions in singletons leveraging the reserve finalizer can make the reserve output a given condition by prepending a special value (-42) to it. + +In some cases, storing values in the persistent state is not appropriate. For example, lists or mappings may grow to have a large number of entries, each of which is only rarely accessed. Storing such data structures in the state would be unoptimal, as the state is passed through all actions that run and hashed every spend. Slots were created to address this problem by offering a more expensive way of storing data that is not needed during most spends. A singleton may create slots - 0-amount coins holding some data - at any time. The special puzzle allows only the owner singleton to later spend the coin to retrieve the data. Slots can also be used to enforce uniqueness of keys across a list of key-value pairs, as described [here](https://blog.fireacademy.io/p/uniqueness-on-chain) and [here](https://blog.fireacademy.io/p/solving-the-problem-of-uniqueness). + +## Specification +The action layer can be found [here](https://github.com/Yakuhito/slot-machine/blob/master/puzzles/singleton/action.clsp). The default finalizer can be found [here](https://github.com/Yakuhito/slot-machine/blob/master/puzzles/singleton/finalizer.clsp), and the reserve finalizer can be found [here](https://github.com/Yakuhito/slot-machine/blob/master/puzzles/singleton/reserve_finalizer.clsp). The slot puzzle can be found [here](https://github.com/Yakuhito/slot-machine/blob/master/puzzles/singleton/slot.clsp). More documentation about the action layer and slots can be found [here](https://docs.catalog.cat/technical-manual/action-layer) and [here](https://docs.catalog.cat/technical-manual/slots). + + +## Test Cases +A series of tests verifying on-chain apps powered by the action layer can be found in chia-wallet-sdk. + +## Reference Implementation +The reference implementation can be found [here](https://github.com/Yakuhito/slot-machine). It includes puzzles for three apps that use the action layer: CATalog, XCHandles, and the Reward Distributor. Apps are in varying states of completion and will have their own subsequent CHIPs. A CLI tool for viewing and interacting with the apps through Coinset.org and the Sage RPC is also included in the repository. + +Drivers for the action layer and associated apps, as well as tests, have been integrated into chia-wallet-sdk. + + +## Security +Puzzle security risk is the main concern when it comes to this standard. Multiple members of the Chia community have reviewed the standardized components of the action layer (‘action.clsp’, the default and reserve finalizers, and the slot puzzle). Chialisp developers implementing actions or custom finalizers should perform full audits on new apps, as the action layer is not intended to act as a security sandbox. + +## Copyright +Copyright and rights to this CHIP waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/CHIPs/chip-0051.md b/CHIPs/chip-0051.md new file mode 100644 index 00000000..f2149f8e --- /dev/null +++ b/CHIPs/chip-0051.md @@ -0,0 +1,68 @@ +CHIP Number | < Creator must leave this blank. Editor will assign a number.> +:-------------|:---- +Title | Reward Distributor +Description | Puzzles that enable continuous on-chain reward distribution to a changing set of recipients. +Author | [yakuhito](https://github.com/Yakuhito), [Michael Taylor](https://github.com/MichaelTaylor3D) +Editor | < Creator must leave this blank. Editor will be assigned.> +Comments-URI | < Creator must leave this blank. Editor will assign a URI.> +Status | < Creator must leave this blank. Editor will assign a status.> +Category | Informational +Sub-Category | Chialisp +Created | 2025-07-22 +Requires | CHIP-0050 (Action Layer and Slots) +Replaces | - +Superseded-By | - + +## Abstract +The reward distributor is an on-chain application responsible for continuously distributing incentives to a dynamic list of recipients. It is inspired by the [mechanism](https://uploads-ssl.webflow.com/5ad71ffeb79acc67c8bcdaba/5ad8d1193a40977462982470_scalable-reward-distribution-paper.pdf) frequently used on other chains for liquidity farms. The singleton uses a list of active recipients and their weights to distribute rewards each second. Anyone can commit additional funds to be distributed in the current or future epochs. Commitments for the latter can be partially clawed back (i.e., they’re subject to withdrawal penalties) before the start of the epoch designated during deposit. Control over the list of reward recipients depends on which mode the distributor operates in. In the manager mode, an external party can directly add and remove entries from the list. In the NFT mode, the list is built as users stake and unstake NFTs minted by a particular DID, with each NFT having the same weight. **We are making this CHIP to explain the reward distributor’s capabilities with the hope that other projects with similar requirements will be able to use our implementation.** + +## Motivation +The reward distributor was first envisioned as a direct result of DIG Network’s need for an on-chain solution that minimizes trust. The DIG reward distribution scheme has three main shareholders: + * **Reward sponsors** provide the funds used to incentivize stores. They want to see that previous funds have been distributed correctly in the past, and ideally get part of their commitments back if the system doesn’t work as expected. + * **Managers (validators)** are responsible for checking which stores are eligible for rewards at a given time, as well as maintaining a publicly accessible list of the stores currently being rewarded. They earn a small portion of the total funds in exchange for allowing the system to distribute the rest correctly. + * **Mirror operators** expect rewards for meeting the eligibility criteria (hosting data and serving it) and a way to ensure those rewards are adequately paid. + +The system described above has a centralized component. Namely, a manager is a trusted oracle that publishes off-chain data (a list of entries - mirrors - eligible for rewards) and keeps it up-to-date. This CHIP proposes an on-chain solution to minimize the trust required between the three principal shareholders. It also proposes an alternative mode of operation for the reward distributor, where the manager is replaced by code that adds entries to the payout list when users deposit NFTs minted by a DID and removes them when users wish to unstake their NFTs. + +## Backwards Compatibility +This proposal does not introduce any breaking changes. + +## Rationale +As mentioned in [DIP-0002](https://github.com/DIG-Network/DIPS/blob/main/DIPs/dip-0002.md), the following requirements were identified after a series of public and private discussions: + * **XCH and CAT payouts**: Each reward distributor pays incentives in either XCH, the native currency of the Chia blockchain, or in a specific Chia Asset Token (CAT). + * **Continuous rewards/incentives**: An entry’s payout should accurately reflect its presence (and weight) in the reward list in a given epoch. While a transaction is not made every second, reward recipients should have confidence that a deterministic amount of rewards is set aside for them every second. The accrued amount can only be paid out to them, even if the manager starts misbehaving in the future. + * **Anyone can commit incentives for future epochs**: Anyone should be able to sponsor future epochs by committing funds. Commitments can be clawed back to account for the possibility that a manager might go rogue or offline. This clawback incurs a penalty, making manager misconduct costly to all parties: the manager loses reputation and future rewards, while the sponsor loses a part of their commitment. + * **Manager controls the list of active entries**: The manager is the only entity that can add or remove entries from the active entries list. Active entries continuously earn a part of the epoch's total payout. The distribution is weighted according to each entry’s share, which is set by the manager. Alternatively, if the reward distributor operates in the NFT mode, anyone can stake any NFT minted by a predefined DID to add an entry to the list. The user is able to get back their NFT at any time by unstaking it, which also removes their entry from the rewards list. + * **Fee proportional to total payout amount**: The manager provides an essential service and has to cover network fees for transactions that update the reward recipient list. As such, it makes sense to incentivize the manager by reserving a fixed percentage of each epoch’s total rewards. More generally, reward distributors can be set up to send a fee proportional to distributed incentives to a payout puzzle hash specified at launch. + * **Payouts can be manually triggered**: Reward recipients are automatically paid out when they are removed from the active entries list. Payouts can also be manually triggered after the accrued rewards exceed a predefined threshold (minimum amount). + +## Specification +The reward distributor is a singleton that uses the action layer and slots, as presented in CHIP-0050. It contains the following actions: + * **sync**: Distributes rewards for the elapsed time since the last sync operation, which occurred in the same epoch. + * **new_epoch**: Transitions to a new epoch at the end of the current one, also transferring the (manager’s) fee. + * **commit_incentives** & **withdraw_incentives** : Used to commit incentives for a future epoch (i.e., sponsor it) and to withdraw a previous commitment. The latter operation carries an associated penalty. + * **add_rewards**: Adds incentives to the current epoch. The amount cannot be clawed back. + * **add_entry** & **remove_entry**: Used by the manager to modify the active entry list if the distributor is in the ‘manager’ mode + * **stake** & **unstake**: Used by users to lock and unlock NFTs minted by a DID to add or remove an entry in the active rewards list if the distributor is in the ‘NFT’ mode + * **inititate_payout**: Initiates a payout of accrued rewards. The payout amount needs to exceed a minimum threshold defined at distributor launch. + +The reward distributor’s type is static and set at launch. An NFT reward distributor will not contain the add_entry/remove_entry actions, while a managed reward distributor will not contain the stake/unstake actions. More detailed documentation for the DIG reward distributor can be found [here](https://docs.xchandles.com/techincal-manual/dig-reward-distributor). + + +## Test Cases +A series of tests covering one or more cases for all actions of the reward distributor are available in chia-wallet-sdk. + +## Reference Implementation +The reference implementation can be found [here](https://github.com/Yakuhito/slot-machine/). It includes puzzles and a CLI for deploying and interacting with reward distributors through Coinset.org the Sage RPC. Reward distributor actions are defined [here](https://github.com/Yakuhito/slot-machine/tree/master/puzzles/actions/reward_distributor). + +Note that reward distributor drivers and tests have been integrated into chia-wallet-sdk. + +## Security +Because the reward distributor controls committed funds until they’re paid out, puzzle risk is a significant concern, especially in the context of an on-chain app with high complexity. Multiple members of the Chia community have reviewed the puzzles included in this CHIP. + +## Copyright +Copyright and rights to this CHIP waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + + + + From 822146272b41db9b8160a97f96286d9041071bd4 Mon Sep 17 00:00:00 2001 From: Yak Date: Wed, 23 Jul 2025 12:28:19 -0400 Subject: [PATCH 2/6] update puzzle location --- CHIPs/chip-0051.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CHIPs/chip-0051.md b/CHIPs/chip-0051.md index f2149f8e..f42ad50e 100644 --- a/CHIPs/chip-0051.md +++ b/CHIPs/chip-0051.md @@ -53,9 +53,7 @@ The reward distributor’s type is static and set at launch. An NFT reward distr A series of tests covering one or more cases for all actions of the reward distributor are available in chia-wallet-sdk. ## Reference Implementation -The reference implementation can be found [here](https://github.com/Yakuhito/slot-machine/). It includes puzzles and a CLI for deploying and interacting with reward distributors through Coinset.org the Sage RPC. Reward distributor actions are defined [here](https://github.com/Yakuhito/slot-machine/tree/master/puzzles/actions/reward_distributor). - -Note that reward distributor drivers and tests have been integrated into chia-wallet-sdk. +The puzzles for the reward distributor can be found [here](https://github.com/DIG-Network/reward-distributor-clsp/tree/main/puzzles/actions/reward_distributor). Drivers and tests for both kinds of reward distributors have been integrated into chia-wallet-sdk. A CLI for deploying and interacting with reward distributors through Coinset.org the Sage RPC is available [here](https://github.com/Yakuhito/slot-machine). ## Security Because the reward distributor controls committed funds until they’re paid out, puzzle risk is a significant concern, especially in the context of an on-chain app with high complexity. Multiple members of the Chia community have reviewed the puzzles included in this CHIP. From f2054cf44b504d2c741719d269c8504c59f137a7 Mon Sep 17 00:00:00 2001 From: danieljperry Date: Thu, 24 Jul 2025 08:51:49 +0200 Subject: [PATCH 3/6] Add CHIPs 50 and 51 as drafts --- CHIPs/chip-0050.md | 10 +++++----- CHIPs/chip-0051.md | 8 ++++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/CHIPs/chip-0050.md b/CHIPs/chip-0050.md index 13e644a6..6f716eaa 100644 --- a/CHIPs/chip-0050.md +++ b/CHIPs/chip-0050.md @@ -1,11 +1,11 @@ -CHIP Number | < Creator must leave this blank. Editor will assign a number.> +CHIP Number | 0050 :-------------|:---- Title | Action Layer and Slots -Description | A singleton inner layer that handles the core needs of complex dApps: efficient multi-action calls in a single spend and persistent state. +Description | A singleton inner layer that handles the core needs of complex dApps: efficient multi-action calls in a single spend and persistent state. Author | [yakuhito](https://github.com/Yakuhito) -Editor | < Creator must leave this blank. Editor will be assigned.> -Comments-URI | < Creator must leave this blank. Editor will assign a URI.> -Status | < Creator must leave this blank. Editor will assign a status.> +Editor | [Dan Perry](https://github.com/danieljperry) +Comments-URI | [CHIPs repo, PR #165](https://github.com/Chia-Network/chips/pull/165) +Status | Draft Category | Informational Sub-Category | Chialisp Created | 2025-07-22 diff --git a/CHIPs/chip-0051.md b/CHIPs/chip-0051.md index f42ad50e..ed722054 100644 --- a/CHIPs/chip-0051.md +++ b/CHIPs/chip-0051.md @@ -1,11 +1,11 @@ -CHIP Number | < Creator must leave this blank. Editor will assign a number.> +CHIP Number | 0051 :-------------|:---- Title | Reward Distributor Description | Puzzles that enable continuous on-chain reward distribution to a changing set of recipients. Author | [yakuhito](https://github.com/Yakuhito), [Michael Taylor](https://github.com/MichaelTaylor3D) -Editor | < Creator must leave this blank. Editor will be assigned.> -Comments-URI | < Creator must leave this blank. Editor will assign a URI.> -Status | < Creator must leave this blank. Editor will assign a status.> +Editor | [Dan Perry](https://github.com/danieljperry) +Comments-URI | [CHIPs repo, PR #165](https://github.com/Chia-Network/chips/pull/165) +Status | Draft Category | Informational Sub-Category | Chialisp Created | 2025-07-22 From 1d2728615f5f423fc7d511a63dc110406ec3c074 Mon Sep 17 00:00:00 2001 From: Yak Date: Thu, 14 Aug 2025 19:14:28 +0300 Subject: [PATCH 4/6] security: griefing attacks --- CHIPs/chip-0051.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHIPs/chip-0051.md b/CHIPs/chip-0051.md index ed722054..8c781a99 100644 --- a/CHIPs/chip-0051.md +++ b/CHIPs/chip-0051.md @@ -58,6 +58,8 @@ The puzzles for the reward distributor can be found [here](https://github.com/DI ## Security Because the reward distributor controls committed funds until they’re paid out, puzzle risk is a significant concern, especially in the context of an on-chain app with high complexity. Multiple members of the Chia community have reviewed the puzzles included in this CHIP. +It should also be noted that, in the manager operating mode, managers are responsible for keeping the active entry list of a reward distributor accurate. Since every modification requires an on-chain transaction, the software managers run should have protections against 'griefing' attacks. Entries may continuously switch their status (e.g., mirrors could go online, then offline, then repeat the process many times) in an attempt to make the manager pay significant network fees over many update transactions. + ## Copyright Copyright and rights to this CHIP waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 8e339bf659e27acfbf9d855f5c4109d03dbe2de2 Mon Sep 17 00:00:00 2001 From: danieljperry Date: Thu, 21 Aug 2025 21:37:19 +0800 Subject: [PATCH 5/6] Move CHIPs 50 and 51 to Review status --- CHIPs/chip-0050.md | 2 +- CHIPs/chip-0051.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHIPs/chip-0050.md b/CHIPs/chip-0050.md index 6f716eaa..3aa9b66f 100644 --- a/CHIPs/chip-0050.md +++ b/CHIPs/chip-0050.md @@ -5,7 +5,7 @@ Description | A singleton inner layer that handles the core needs of complex d Author | [yakuhito](https://github.com/Yakuhito) Editor | [Dan Perry](https://github.com/danieljperry) Comments-URI | [CHIPs repo, PR #165](https://github.com/Chia-Network/chips/pull/165) -Status | Draft +Status | Review Category | Informational Sub-Category | Chialisp Created | 2025-07-22 diff --git a/CHIPs/chip-0051.md b/CHIPs/chip-0051.md index 8c781a99..c538032a 100644 --- a/CHIPs/chip-0051.md +++ b/CHIPs/chip-0051.md @@ -5,7 +5,7 @@ Description | Puzzles that enable continuous on-chain reward distribution to a Author | [yakuhito](https://github.com/Yakuhito), [Michael Taylor](https://github.com/MichaelTaylor3D) Editor | [Dan Perry](https://github.com/danieljperry) Comments-URI | [CHIPs repo, PR #165](https://github.com/Chia-Network/chips/pull/165) -Status | Draft +Status | Review Category | Informational Sub-Category | Chialisp Created | 2025-07-22 From e1858fc36a933ee829d258c5f0ef3caab0b84594 Mon Sep 17 00:00:00 2001 From: Yak Date: Tue, 3 Feb 2026 18:16:10 +0900 Subject: [PATCH 6/6] update CHIP-0051 --- CHIPs/chip-0051.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/CHIPs/chip-0051.md b/CHIPs/chip-0051.md index c538032a..e1b632ce 100644 --- a/CHIPs/chip-0051.md +++ b/CHIPs/chip-0051.md @@ -9,12 +9,12 @@ Status | Review Category | Informational Sub-Category | Chialisp Created | 2025-07-22 -Requires | CHIP-0050 (Action Layer and Slots) +Requires | CHIP-0050 (Action Layer and Slots), CHIP-0035 (DataLayer Delegation Capabilities) Replaces | - Superseded-By | - ## Abstract -The reward distributor is an on-chain application responsible for continuously distributing incentives to a dynamic list of recipients. It is inspired by the [mechanism](https://uploads-ssl.webflow.com/5ad71ffeb79acc67c8bcdaba/5ad8d1193a40977462982470_scalable-reward-distribution-paper.pdf) frequently used on other chains for liquidity farms. The singleton uses a list of active recipients and their weights to distribute rewards each second. Anyone can commit additional funds to be distributed in the current or future epochs. Commitments for the latter can be partially clawed back (i.e., they’re subject to withdrawal penalties) before the start of the epoch designated during deposit. Control over the list of reward recipients depends on which mode the distributor operates in. In the manager mode, an external party can directly add and remove entries from the list. In the NFT mode, the list is built as users stake and unstake NFTs minted by a particular DID, with each NFT having the same weight. **We are making this CHIP to explain the reward distributor’s capabilities with the hope that other projects with similar requirements will be able to use our implementation.** +The reward distributor is an on-chain application responsible for continuously distributing incentives to a dynamic list of recipients. It is inspired by the [mechanism](https://uploads-ssl.webflow.com/5ad71ffeb79acc67c8bcdaba/5ad8d1193a40977462982470_scalable-reward-distribution-paper.pdf) frequently used on other chains for liquidity farms. The singleton uses a list of active recipients and their weights to distribute rewards each second. Anyone can commit additional funds to be distributed in the current or future epochs. Commitments for the latter can be partially clawed back (i.e., they’re subject to withdrawal penalties) before the start of the epoch designated during deposit. Control over the list of reward recipients depends on which mode the distributor operates in. In the managed mode, an external party can directly add and remove entries from the list. In the collection NFT mode, the list is built as users stake and unstake NFTs minted by a particular DID, with each NFT having the same weight. In the curated NFT mode, a list of NFTs and their respective weights is tracked via a [CHIP-0035](https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0035.md) DataLayer store. In the CAT mode, CATs with a particular asset id can be staked to earn a share of the rewards proportional to the staked CAT's amount. **We are making this CHIP to explain the reward distributor’s capabilities with the hope that other projects with similar requirements will be able to use our implementation.** ## Motivation The reward distributor was first envisioned as a direct result of DIG Network’s need for an on-chain solution that minimizes trust. The DIG reward distribution scheme has three main shareholders: @@ -22,7 +22,7 @@ The reward distributor was first envisioned as a direct result of DIG Network’ * **Managers (validators)** are responsible for checking which stores are eligible for rewards at a given time, as well as maintaining a publicly accessible list of the stores currently being rewarded. They earn a small portion of the total funds in exchange for allowing the system to distribute the rest correctly. * **Mirror operators** expect rewards for meeting the eligibility criteria (hosting data and serving it) and a way to ensure those rewards are adequately paid. -The system described above has a centralized component. Namely, a manager is a trusted oracle that publishes off-chain data (a list of entries - mirrors - eligible for rewards) and keeps it up-to-date. This CHIP proposes an on-chain solution to minimize the trust required between the three principal shareholders. It also proposes an alternative mode of operation for the reward distributor, where the manager is replaced by code that adds entries to the payout list when users deposit NFTs minted by a DID and removes them when users wish to unstake their NFTs. +The system described above has a centralized component. Namely, a manager is a trusted oracle that publishes off-chain data (a list of entries - mirrors - eligible for rewards) and keeps it up-to-date. This CHIP proposes an on-chain solution to minimize the trust required between the three principal shareholders. It also proposes alternative modes of operation for the reward distributor, where the manager is replaced by code that adds entries to the payout list when users deposit NFTs or CATs and removes them when users wish to unstake their assets. ## Backwards Compatibility This proposal does not introduce any breaking changes. @@ -42,23 +42,25 @@ The reward distributor is a singleton that uses the action layer and slots, as p * **new_epoch**: Transitions to a new epoch at the end of the current one, also transferring the (manager’s) fee. * **commit_incentives** & **withdraw_incentives** : Used to commit incentives for a future epoch (i.e., sponsor it) and to withdraw a previous commitment. The latter operation carries an associated penalty. * **add_rewards**: Adds incentives to the current epoch. The amount cannot be clawed back. - * **add_entry** & **remove_entry**: Used by the manager to modify the active entry list if the distributor is in the ‘manager’ mode - * **stake** & **unstake**: Used by users to lock and unlock NFTs minted by a DID to add or remove an entry in the active rewards list if the distributor is in the ‘NFT’ mode - * **inititate_payout**: Initiates a payout of accrued rewards. The payout amount needs to exceed a minimum threshold defined at distributor launch. + * **add_entry** & **remove_entry**: Used by the manager to modify the active entry list if the distributor is in the ‘managed’ mode + * **stake** & **unstake**: Used by users to lock and unlock assets to add or remove an entry in the active rewards list if the distributor is in a non-manager mode. The logic verifying assets should be staked/unstaked is defined in locking/unlocking puzzles, detailed below. + * **inititate_payout**: Initiates a payout of accrued rewards. The payout amount needs to exceed a minimum threshold defined at distributor launch. Based on configuration set at launch, an approval in the form of a message from the recipient puzzle hash may or may not be required for every payout. + * **refresh**: In the curated NFT mode, this action can be called by anyone to update an NFT's weight to the current one set in the DataLayer store (if there is a mismatch). This action allows projects (curators) to have a dynamic list of weights. This action is optional for the curated NFT mode - distributors containing it are referred to as 'refreshable.' Non-refreshable distributors do not allow the update of an NFT's staked weight unless the owner voluntarily unstakes and stakes it again. -The reward distributor’s type is static and set at launch. An NFT reward distributor will not contain the add_entry/remove_entry actions, while a managed reward distributor will not contain the stake/unstake actions. More detailed documentation for the DIG reward distributor can be found [here](https://docs.xchandles.com/techincal-manual/dig-reward-distributor). +The reward distributor’s type is static and set at launch. A managed NFT/curated NFT/CAT reward distributor will not contain the add_entry/remove_entry actions, while a managed reward distributor will not contain the stake/unstake actions. Only curated NFT reward distributors may contain the 'refresh' action. More detailed documentation for the DIG reward distributor can be found [here](https://docs.xchandles.com/techincal-manual/dig-reward-distributor). +In non-managed modes of the reward distributor, the stake and unstake puzzles manage common functionality (such as slot assertion and optional consolidation for the same puzzle hash, as well as payouts) while delegating the calculation of additional/removed shares and specific locking conditions to locking and unlocking puzzles. For example, a collection NFT reward distributor and a CAT reward distributor will have the same stake/unstake base puzzles. The former's locking puzzle will be set to the 'nfts_from_dl' variation of the locking puzzle and the NFT unlocking puzzle, while the latter will use the CAT locking and unlocking puzzles. ## Test Cases A series of tests covering one or more cases for all actions of the reward distributor are available in chia-wallet-sdk. ## Reference Implementation -The puzzles for the reward distributor can be found [here](https://github.com/DIG-Network/reward-distributor-clsp/tree/main/puzzles/actions/reward_distributor). Drivers and tests for both kinds of reward distributors have been integrated into chia-wallet-sdk. A CLI for deploying and interacting with reward distributors through Coinset.org the Sage RPC is available [here](https://github.com/Yakuhito/slot-machine). +The puzzles for the reward distributor can be found [here](https://github.com/DIG-Network/reward-distributor-clsp/tree/main/rue-puzzles/actions/reward-distributor) ([Chialisp](https://github.com/DIG-Network/reward-distributor-clsp/tree/main/puzzles/actions/reward_distributor)). Drivers and tests for both kinds of reward distributors have been integrated into chia-wallet-sdk. A CLI for deploying and interacting with reward distributors through Coinset.org the Sage RPC is available [here](https://github.com/Yakuhito/slot-machine). ## Security Because the reward distributor controls committed funds until they’re paid out, puzzle risk is a significant concern, especially in the context of an on-chain app with high complexity. Multiple members of the Chia community have reviewed the puzzles included in this CHIP. -It should also be noted that, in the manager operating mode, managers are responsible for keeping the active entry list of a reward distributor accurate. Since every modification requires an on-chain transaction, the software managers run should have protections against 'griefing' attacks. Entries may continuously switch their status (e.g., mirrors could go online, then offline, then repeat the process many times) in an attempt to make the manager pay significant network fees over many update transactions. +It should also be noted that, in the managed operating mode, managers are responsible for keeping the active entry list of a reward distributor accurate. Since every modification requires an on-chain transaction, the software managers run should have protections against 'griefing' attacks. Entries may continuously switch their status (e.g., mirrors could go online, then offline, then repeat the process many times) in an attempt to make the manager pay significant network fees over many update transactions. ## Copyright Copyright and rights to this CHIP waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).