Revenue Sharing Example Scenarios

--- tags: Spec-Revenue-Sharing --- # Revenue Sharing Example Scenarios All numbers were multiplied by 100, to get around minimum stake of 65. Tests passed just fine. TODO: update this document? ## Scenario 1 - Simple Join/Delegate ### Starting States There is one single **delegator** with funds of 10 DATA and no delegations. There is one broker and **BrokerPool** (broker agreement) with no delegations or funds. There is a maximum allocation policy of 5 DATA in this system. The policy for exchange rate of funds and tokens is based on Pool Value / Total Pool Tokens, or 1-to-1 if pool value is 0. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 0> Funds: 10 Brokers -------------------- <Broker 0> Funds: 0.0 Broker Pool: <Pool 0> Pools -------------------- <Pool 0> Broker Owner: <Broker 0> Revenue History: [] Amount staked: 0.0 Free Funds: 0.0 Pool Value: 0.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 0>] Internal Data Balances Pool Balances </details> ### Transition 1 1. The broker registers BrokerPool to the vault. 2. Mechanisms update the vault to now hold the BrokerPool address. ### Transition 2 1. The delegator seeks to delegate all 10 DATA to the broker agreement. 2. The delegator_join_check runs and returns true allowing the delegator to join 3. The pool_maximum_allocation function modifies the 10 DATA token request to be 5 DATA because it returns the maximum as 5 DATA. 4. Delegator invest policy occurs and translates the exchange rate to be 5 DATA for 5 Pool Tokens. 5. The mechanisms withdraw 5 DATA from the delegator funds and transfers it to the broker pool. 5 LP tokens for the broker pool are designated to the delegator in the vault. 6. The pool value increases from 0 to 5. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 0> Funds: 0 Brokers -------------------- <Broker 0> Funds: 0.0 Broker Pool: <Pool 0> Pools -------------------- <Pool 0> Broker Owner: <Broker 0> Revenue History: [] Amount staked: 0.0 Free Funds: 5.0 Pool Value: 5.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 0>] Internal Data Balances <Delegator 0>: 5 Pool Balances <Pool 0> <Delegator 0>:5 </details> ## Scenario 2 - Simple Staking ### Starting States The starting state is the ending state of scenario 1: * The BrokerPool has 5 DATA * The delegator has 5 LP tokens, and no other LP tokens exist. There is also a stream with which the broker wants to stake and become involved in. The **Bounty** (stream agreement) currently has no brokers or funds. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 1> Funds: 0 Brokers -------------------- <Broker 1> Funds: 0.0 Broker Pool: <Pool 1> Pools -------------------- <Pool 1> Broker Owner: <Broker 1> Revenue History: [] Amount staked: 0.0 Free Funds: 5.0 Pool Value: 5.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 1>] Internal Data Balances <Delegator 1>: 5 Pool Balances <Pool 1> <Delegator 1>:5 </details> ### Transition 1 1. The broker tells BrokerPool to stake 5 DATA to the Bounty. 2. 5 DATA is transferred from BrokerPool, leaving its "free funds" at 0 DATA. 3. 5 DATA is deposited as stake into the Bounty. Its funds are increased by 5 DATA. 4. The virtual account for stake on the broker pool keeps track of 5 DATA stake being allocated to the stream address. 5. The virtual account for stake on the stream agreement keeps track of 5 DATA stake being allocated from the broker pool address. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 1> Funds: 0 Brokers -------------------- <Broker 1> Funds: 0.0 Broker Pool: <Pool 1> Pools -------------------- <Pool 1> Broker Owner: <Broker 1> Revenue History: [] Amount staked: 5.0 Free Funds: 0.0 Pool Value: 5.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 1>] Internal Data Balances <Delegator 1>: 5 Pool Balances <Pool 1> <Delegator 1>:5 </details> ## Scenario 3 - Yield Allocated to Accounts ### Starting States The starting state is the ending state of scenario 2: * The BrokerPool has 0 DATA and a pool value of 5 DATA * 5 DATA has been staked in the stream agreement. In this scenario, BrokerPool has the following yield policy: * 20% broker share of revenue is disbursed to the broker as compensation * 80% is disbursed immediately to the internal balances of the delegators <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 4> Funds: 0 Brokers -------------------- <Broker 4> Funds: 0.0 Broker Pool: <Pool 4> Pools -------------------- <Pool 4> Broker Owner: <Broker 4> Revenue History: [] Amount staked: 5.0 Free Funds: 0.0 Pool Value: 5.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 4>] Internal Data Balances <Delegator 4>: 5 Pool Balances <Pool 4> <Delegator 4>:5 </details> ### Transition 1 1. 25 DATA is earned as revenue by the broker 2. The revenue is claimed triggering the yield policies and mechanisms. ### Transition 2 1. The owner share equals 20% of 25 = 5. The internal balance of DATA for the broker address (not broker pool) increases from 0 to 5. 2. The remainder is routed to the delegator's internal balance. Their internal balance goes from 5 to 25. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 4> Funds: 0 Brokers -------------------- <Broker 4> Funds: 5.0 Broker Pool: <Pool 4> Pools -------------------- <Pool 4> Broker Owner: <Broker 4> Revenue History: [25] Amount staked: 5.0 Free Funds: 0.0 Pool Value: 5.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 4>] Internal Data Balances <Delegator 4>: 25.0 Pool Balances <Pool 4> <Delegator 4>:5 </details> ## Scenario 4 - Yield Allocated to Pool Value ### Starting States The starting state is the ending state of scenario 2: * The BrokerPool has 0 DATA and a pool value of 5 DATA * 5 DATA has been staked in the stream agreement. In this scenario, BrokerPool has the following yield policy: * 20% broker share of revenue is disbursed to the broker as compensation * 80% is put into the pool value. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 6> Funds: 0 Brokers -------------------- <Broker 6> Funds: 0.0 Broker Pool: <Pool 6> Pools -------------------- <Pool 6> Broker Owner: <Broker 6> Revenue History: [] Amount staked: 5.0 Free Funds: 0.0 Pool Value: 5.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 6>] Internal Data Balances <Delegator 6>: 5 Pool Balances <Pool 6> <Delegator 6>:5 </details> ### Transition 1 1. Broker withdraws 25 DATA of revenue from Bounty 2. 25 DATA of revenue is added to BrokerPool, triggering the yield policies and mechanisms. ### Transition 2 1. The owner share equals 20% of 25 = 5. The internal balance of DATA for the broker address (not broker pool) increases from 0 to 5. 2. The remainder is routed to pool value. Pool value is increased by 20, making it equal to 25. 3. The funds of the broker pool goes from 0 to 20. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 6> Funds: 0 Brokers -------------------- <Broker 6> Funds: 5.0 Broker Pool: <Pool 6> Pools -------------------- <Pool 6> Broker Owner: <Broker 6> Revenue History: [25] Amount staked: 5.0 Free Funds: 20.0 Pool Value: 25.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 6>] Internal Data Balances <Delegator 6>: 5.0 Pool Balances <Pool 6> <Delegator 6>:5 </details> ## Scenario 5 - Withdraw The starting state is the ending state of scenario 4. The delegator divest policy is based upon an exchange rate for DATA/LP Tokens equal to Pool Value / Sum of All LP Tokens. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 8> Funds: 0 Brokers -------------------- <Broker 8> Funds: 5.0 Broker Pool: <Pool 8> Pools -------------------- <Pool 8> Broker Owner: <Broker 8> Revenue History: [25] Amount staked: 5.0 Free Funds: 20.0 Pool Value: 25.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 8>] Internal Data Balances <Delegator 8>: 5.0 Pool Balances <Pool 8> <Delegator 8>:5 </details> ### Transition 1 1. The delegator initiates withdrawing all funds by sending a message to cash out all pool tokens. 2. Delegator divest check is done which returns true allowing for the action to continue. 3. Delegator maximum withdraw returns 5 because there are no rules enforcing a lower maximum withdraw. 4. Because the pool value is equal to 25 and the number of pool tokens is equal to 5, the exchange rate is 25/5. This values each pool token as being worth 5 data 5. There is now 5 pool tokens for delegator 1 queued up and the two mechanisms below describe how they are handled ### Transition 1a - Immediate Withdraw Mechanism 1. Because there is 20 in terms of funds that is available currently, that is the amount of DATA which will be used in this mechanism. 2. 20 DATA / 5 Exchange Rate = 4 Pool Tokens to be paid off, so the pool tokens for delegator 1 goes from 5 to 1. 3. The pool value decreases from 25 to 5. 4. The funds of the broker pool decreases from 20 to 0. 5. The internal balance of the delegator increases from 0 to 20 in the vault. ### Transition 1b - Create Debit 1. Because there is 1 pool token which the broker pool can't pay out immediately a debit for 1 pool token payout is created. 2. The pool value is NOT changed by this because this payment is meant to be taken care of in the future, not at current time. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 8> Funds: 0 Brokers -------------------- <Broker 8> Funds: 5.0 Broker Pool: <Pool 8> Pools -------------------- <Pool 8> Broker Owner: <Broker 8> Revenue History: [25] Amount staked: 5.0 Free Funds: 0.0 Pool Value: 5.0 Debits: [(<Delegator 8>, 1.0)] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 8>] Internal Data Balances <Delegator 8>: 25.0 Pool Balances <Pool 8> <Delegator 8>:1.0 </details> ## Scenario 6 - Debit Close Out w/ Stake The starting state is the end of scenario 5. In this scenario, stake withdraw is automatically applied to debits outstanding. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 10> Funds: 0 Brokers -------------------- <Broker 10> Funds: 5.0 Broker Pool: <Pool 10> Pools -------------------- <Pool 10> Broker Owner: <Broker 10> Revenue History: [25] Amount staked: 5.0 Free Funds: 0.0 Pool Value: 5.0 Debits: [(<Delegator 10>, 1.0)] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 10>] Internal Data Balances <Delegator 10>: 25.0 Pool Balances <Pool 10> <Delegator 10>:1.0 </details> ### Transition 1 1. The broker withdraws all of the 5 DATA stake from the Bounty. 2. Because there is a debit of 1 pool token waiting to be paid out, the withdrawn stake is diverted to paying off the debt. The exchange rate is still 5 because pool value of 5 / 1 pool token = 5. 3. The pool value decreases from 5 to 0. 4. The funds of the pool remain at 0. 5. The pool tokens of delegator 1 goes from 1 to 0. 6. The debits are now paid off so there are no remaining debits. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 10> Funds: 0 Brokers -------------------- <Broker 10> Funds: 5.0 Broker Pool: <Pool 10> Pools -------------------- <Pool 10> Broker Owner: <Broker 10> Revenue History: [25] Amount staked: 0.0 Free Funds: 0.0 Pool Value: 0.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 10>] Internal Data Balances <Delegator 10>: 30.0 Pool Balances <Pool 10> </details> ## Scenario 7 - Debit Reduced Through Revenue The starting state is the end of scenario 5. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 10> Funds: 0 Brokers -------------------- <Broker 10> Funds: 5.0 Broker Pool: <Pool 10> Pools -------------------- <Pool 10> Broker Owner: <Broker 10> Revenue History: [25] Amount staked: 5.0 Free Funds: 0.0 Pool Value: 5.0 Debits: [(<Delegator 10>, 1.0)] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 10>] Internal Data Balances <Delegator 10>: 25.0 Pool Balances <Pool 10> <Delegator 10>:1.0 </details> ### Transition 1 1. Broker withdraws 25 DATA of revenue from Bounty 2. 25 DATA of revenue is added to BrokerPool, triggering the yield policies and mechanisms. ### Transition 2 1. The owner share equals 20% of 25 = 5. The internal balance of DATA for the broker address (not BrokerPool) increases from 5 to 10. 2. Pool value goes from 5 to 25, pool funds goes from 0 to 20 3. The exchange rate is now pool value of 25 / 1 pool token = 25. 4. The 20 DATA to be paid out is equivalent to .8 pool tokens so pool tokens for delegator 1 goes from 1 to .2 5. The funds of the broker pool decreases from 20 to 0. 6. The internal balance of the delegator increases from 25 to 45 in the vault. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 10> Funds: 0 Brokers -------------------- <Broker 10> Funds: 10.0 Broker Pool: <Pool 10> Pools -------------------- <Pool 10> Broker Owner: <Broker 10> Revenue History: [25, 25] Amount staked: 5.0 Free Funds: 0.0 Pool Value: 5.0 Debits: [(<Delegator 10>, 0.2)] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 10>] Internal Data Balances <Delegator 10>: 45.0 Pool Balances <Pool 10> <Delegator 10>:0.19999999999999996 </details> ## Scenario 8 - Getting slashed in a bounty > **NOTE: Scenarios 8 and 9 are still under discussion**: should we burn all tokens, or just make the "0 DATA left with non-zero pool tokens left" scenario impossible, e.g. by not allowing 100% slashing in the bounties... This scenario illustrates the risk of a losing all funds if a broker is slashed and has no more funds to do the work. It starts off at the ending state of scenario 2. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 12> Funds: 0 Brokers -------------------- <Broker 12> Funds: 0.0 Broker Pool: <Pool 12> Pools -------------------- <Pool 12> Broker Owner: <Broker 12> Revenue History: [] Amount staked: 5.0 Free Funds: 0.0 Pool Value: 5.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 12>] Internal Data Balances <Delegator 12>: 5 Pool Balances <Pool 12> <Delegator 12>:5 </details> ### Transition 1 1. The broker is slashed and loses all 5 stake. Stake goes from 5 to 0. 2. Pool value is decreased from 5 to 0. 3. There is now pool token balances, but 0 pool value, 0 stake, and 0 free funds in the pool. 4. *[Update 2023-01-31]* **All pool tokens get burned when pool value hits zero** (or under an implementation-specific epsilon value, to avoid numerical issues when pool restarts) <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 12> Funds: 0 Brokers -------------------- <Broker 12> Funds: 0.0 Broker Pool: <Pool 12> Pools -------------------- <Pool 12> Broker Owner: <Broker 12> Revenue History: [] Amount staked: 0.0 Free Funds: 0.0 Pool Value: 0.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 12>] Internal Data Balances <Delegator 12>: 5 Pool Balances </details> ## Scenario 9 - Pool Restarted This scenario takes the end of scenario 8 and shows what happens when a new delegator arrives after pool value went to nothing. Because pool value is 0, the exchange rate would default to 1-to-1. It starts at the end of scenario 8. Delegator2 initially has 5 DATA. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 14> Funds: 0 Brokers -------------------- <Broker 14> Funds: 0.0 Broker Pool: <Pool 14> Pools -------------------- <Pool 14> Broker Owner: <Broker 14> Revenue History: [] Amount staked: 0.0 Free Funds: 0.0 Pool Value: 0.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 14>] Internal Data Balances <Delegator 14>: 5 Pool Balances </details> ### Transition 1 1. Delegator2 puts in 5 DATA 2. Gets 5 pool tokens ### Transition 2 1. Delegator1 tries to exit infinity pool tokens 2. Fails because all pool tokens were burned when pool value went to zero ### Comment If the pool tokens weren't burned, and instead Delegator1 would be allowed to keep their 5 pool tokens, they could immediately withdraw them when Delegator2 arrives, to "steal" half of Delegator2's stake, halving the pool token value in DATA. <details> <summary>Detailed State</summary> Delegators -------------------- <Delegator 14> Funds: 0 <Delegator 15> Funds: 0 Brokers -------------------- <Broker 14> Funds: 0.0 Broker Pool: <Pool 14> Pools -------------------- <Pool 14> Broker Owner: <Broker 14> Revenue History: [] Amount staked: 0.0 Free Funds: 5.0 Pool Value: 5.0 Debits: [] Max Withdraw Mode: constant Max Withdraw Constant: 5 Max Allocation Policy: constant Max Allocation Constant: 5 Vault -------------------- Registered pools [<Pool 14>] Internal Data Balances <Delegator 14>: 5 <Delegator 15>: 0 Pool Balances <Pool 14> <Delegator 15>:5 </details> # Future Scenarios to Design ## Scenario XX - Early Adoption Failure This scenario represents how a failure could happen for early adopters with improper policies