son-objects-and-operators
1. Purpose
The purpose of this document is to provide low-level design for creating new SON objects, updating the objects, listing them once created and voting for them.
2. Scope
The design requirement listed in this document will be limited to the creation of the new SON objects, updating the objects, listing the objects on CLI and voting for the objects.
The document will also outline the new data structures required to create and update the objects/accounts on the blockchain through UML diagrams.
The document will also outline the related function flow between modules through Sequence diagrams.
The document will also outline the roles of the accounts/users operating the SONs.
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. Disambiguation of types of users
This section tries to disambiguate the types of users registered on the current system and their roles.
4.1 Witness
Witnesses are the workhorses of the network.
The main task of the nodes is to gather the transactions, put them into a block, sign the block and broadcast it to network.
For each block produced by a witness, there is payment in core asset which is configured on the chain.
4.2 Workers
Workers are the group of users who maintain the network and introduce new features into the network.
4.3 Committee Members
Committee members are the unpaid volunteers that organize the community and propose changes to the network.
4.4 PPY Holders
PPY Holders are regular users who hold PPY in their accounts.
They can cast a vote and influence the decisions of the network.
4.5 SON Operators (new)
SON operators are the users that start a SON node on the network.
They can ask for votes from other users to be selected as top N SON operators. (N is currently proposed to be 15)
4.5.1 Roles and Requirements
These are the possible states for the new user role of SON,
Active SON - an account that is one of the top 15 voted SONs and is actively performing the operations of Sidechain.
Inactive SON - an account that is ready to perform the work required for Sidechain operation, but does not have the votes to be one of the top 15 votes SONs. An inactive SON can become active during a maintenance interval if it receives enough votes to become one of the top 15 voted SONs.
Maintenance_Requested SON - An SON account has requested for Maintenance and waiting for the maintenance interval for its account to be updated to In_Maintenance. SON-214 Done
In_Maintenance SON - An SON is in maintenance.
De-Registered SON - If an SON de-registers by itself through remove_son command or goes down abruptly and stays down for 12 hours or in maintenance for 12 hours, it is de-registered. (de-registered user will have to create the son node again using create_son )
Prospective SON operator's accounts should have a minimum amount of core asset (PPY) that needs to be vested in order to join the SONs. (50 PPY proposed currently)
SON Operator cannot reclaim the vested assets till after 2 days of deregistration of the node.
5. Design Changes Suggested
This section outlines the changes needed to realize the functionality of creation, update, and deletion of SON Nodes.
And it also outlines some of the Sequence diagrams of the use cases list_sons, vote_for_son.
Following is a brief overview of new data structures introduced,
5.1 son_object
This class holds all the information about SON and is stored in the DB.
son_create_operation creates the son object.
son_update_operation updates the son object.
son_delete_operation deletes the son object from DB.
5.2 son_create_operation
This class is used to create a son object in DB.
Whenever the SON creation is triggered this operation is pushed into a transaction.
It holds information like son_account, public block signing key.
5.3 son_update_operation
This class is used to update an already created son object in DB.
5.4 son_delete_operation
This class is used to delete an already created son object in DB.
5.5 son_create_evaluator
This class contains do_evaluate and do_apply functions which evaluate and apply the create operation respectively.
do_apply creates son_object in DB.
5.6 son_update_evaluator
This class contains do_evaluate and do_apply functions which evaluate and apply the update operation respectively.
do_evaluate checks for the son_object existence in DB.
do_apply updates the son_object with parameters supplied in son_update_operation.
5.7 son_delete_evaluator
This class contains do_evaluate and do_apply functions which evaluate and apply the update operation respectively.
do_evaluate checks for the son_object existence in DB.
do_apply deletes the son_object with parameters supplied in son_delete_operation.
5.7 vote_id_type (Enum)
A new vote type son is introduced which is needed in vote_for_son flow.
5.8 chain_parameters
A new extension parameter in chain_parameters maximum_son_count needs to be introduced with default value as 15 initially (proposed currently).
Later if the count has to be changed it can be done through committee_member_update_global_parameters_operation.
6. UML and Sequence Diagrams
7. CLI Wallet Commands
Following are the CLI Wallet commands to realize the functionality shown above,
7.1 Node Startup with SON Enabled
./programs/witness_node/witness_node --resync --replay --son_enable | The command enables the SON functionality in the node |
7.2 Register as SON Node (wallet)
create_son <account_name> <proposal_url> true | The command registers the node on-chain and creates an ID |
7.3 list_sons (wallet)
list_sons | The command lists all the account names that own SONs, active or inactive |
7.4 vote_for_son (wallet)
vote_for_son <voting_account> <son_account> <approve> <broadcast> | The command allows voting in or out for a given SON account |
7.5 update_son (wallet)
update_son <son_account> <proposal_url> <signing_key> <broadcast> | The command updates the created SON Object related to the SON account given |
7.6 remove_son (wallet)
remove_son <son_account> <broadcast> | The command marks the SON Node as delete on-chain |