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.