Peerplays API Libraries
Tools and Integrations
Development Workflow Docs
Other Documentation
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.