# son-rewards-lld ## 1. Purpose The purpose of this document is to provide low-level design for making payments to SONs for their contribution to the Peerplays network. ## 2. Scope The design requirement listed in this document will be limited to the payments to SON Nodes. The document will also outline the way we pay witnesses currently in our network. The document will also outline the new chain parameters required to configure the payments to SONs dynamically. The document will also outline the new data structures required to identify the transactions that a SON participated in. All the terminology used in the document is generic and will not be specific to any particular cryptocurrency like BTC or ETH. ## 3. Background The Bitcoin Sidechain functionality has been implemented in the Peerplays blockchain but it doesn't take into account, the change of witnesses. As per the current implementation of Sidechain, a multi-sig bitcoin address will be created on the bitcoin blockchain to hold the bitcoins that have been deposited into the pBTC accounts of the Peerplays users. Every Peerplays witnesses will have a bitcoin transaction signing key for this multi-sig bitcoin address and will be required to sign any withdrawal transaction. When a witness changes, the transaction signing key of the outgoing witness needs to be removed from the multi-sig bitcoin address and the key of the incoming witness needs to be added. The suggested proposal is to make the Sidechain code available as a plugin and assign the responsibility for running the sidechain code to separate nodes called the Sidechain Operating Nodes (SONs). The SON functionality will be independent of the witness functionality and SONs don't need to be changed much often. ## 4. Types of transactions ### 4.1 Transfer cryptocurrency(i.e. like BTC, ETH) from Deposit Address to PW Address In this case, SONs have to sign the transaction to be successful. So a reward should be made to SONs in this case. Miner fee for the external chain is also required but it is out of the scope of this document. ### 4.2 Transfer cryptocurrency from Old PW Address to New PW Address In this case, SONs have to sign the transaction to be successful. So a reward should be made to SONs in this case. Miner fee for the external chain is also required but it is out of the scope of this document. ### 4.3 Transfer UIA (User Issued Asset Eg. pBTC) from one account to another In this case, there is no need for a SON to sign for the transaction to be successful. This is a normal on-chain transaction. This has been supported in all the graphene-based chains for long. So no reward is required in this case. But a witness fee is applicable as in the case of core asset transfer. ## 5. How it all works currently ### 5.1 How are witnesses paid Currently whenever a new block is generated by a particular witness, we immediately deposit the amount into the vesting balance of the witness account. The amount comes from the **witness\_budget** allocated globally during the previous maintenance interval. This is stored in **dynamic\_global\_property\_object** of the blockchain for faster access. ### 5.2 How fee is collected For every operation, there is a rate specified that goes as the fee to the network. For core asset transaction, the fee is directly deducted from payer's account. For the UIA asset transaction, the fee is converted to the core using the base exchange rate of the UIA. Between two maintenance intervals, the core fee is accumulated in the core asset's **asset\_dynamic\_data\_object.** ### 5.3 How is budget calculated currently At the end of each maintenance, we calculate the budget for the coming cycle. Some of the parameters we take into consideration are **witness\_budget**, **worker\_budget, core\_accumulated\_fee, leftover\_witness\_budget etc.** A simple equation to arrive at the final budget (current\_supply) is, **current\_supply** = **current\_supply** + (**required\_witness\_budget** + **required\_worker\_budget** - **leftover\_worker\_funds** - **core\_accumulated\_fee** - **leftover\_witness\_budget**) **reserve\_supply** = **max\_supply** - **current\_supply** At the end of every maintenance, the above parameters are updated in the databases. ## 6. Proposed Design Change for SONs One of the requirements for the SONs is to pay the SON accounts proportional to the number of transactions they participate in. So there is a need to know the number of transactions a particular SON object has participated in from the last payout period till now. There is also a requirement to pay **SONS\_DAILY\_MAX\_REWARD** to set of SONs operating in the network. And this should be configurable so that in future if we have to add more SONs to handle transactions from other cryptocurrencies, we need more daily rewards or vice-versa. As can be seen in the previous section as to how the budget is calculated, how the core amount is pooled in from the reserve, we can follow a similar approach for SONs as well. With SONs budget factored into the budget calculations, our new equation would be, **current\_supply = current\_supply + (required\_witness\_budget + required\_worker\_budget + required\_son\_budget - leftover\_worker\_funds - core\_accumulated\_fee - leftover\_witness\_budget - leftover\_son\_budget)** **reserve\_supply = max\_supply - current\_supply** **required\_witness\_budget** ==> required witness budget till next maintenance interval **required\_worker\_budget** ==> required worker budget till next maintenance interval **required\_son\_budget ==> reserved SON budget to be paid out in the next maintenance interval = (chain\_parameters.son\_pay\_max)** **leftover\_worker\_funds** ==> Remaining funds from previous worker payout **core\_accumulated\_fee** ==> Accumulated fee (after all the cuts removed from it), since the last maintenance interval. **leftover\_witness\_budget** ==> Leftover funds from previous witness budget ( happens if any block is missed in between ) **leftover\_son\_budget ==> Leftover funds from previous son budget ( happens if there are no SON transactions on the network )** For us to efficiently find the number of transactions a SON has signed, we need a new **implementation\_id** object that complements our proposed **son\_object**. We store the transaction linked list that the SON has participated in and the number of transactions since the last payout. This way during maintenance we can calculate payouts faster for each SON. A new chain parameter to change the max daily rewards is also required. ### 6.1 parameter\_extension.**son\_pay\_daily\_max** This parameter is used to specify the current son max payout. It can be re-configured by **committee\_member\_update\_global\_parameters\_operation.** ### 6.2 dynamic\_global\_property\_object.**son\_budget** This parameter is used to denote the son\_budget till next payout interval. This is set every payout interval. ### 6.3 **son\_statistics\_object** This new class is an implementation type object. It stores the data which is changed frequently and better to separate it from the SON object. It has data about the transactions and number of pending since last payout. ### 6.4 **pay\_sons** This function should be introduced and called from perform\_chain\_maintenance. After this new budget should be recorded and saved.