wallet-commands-for-son

1. Purpose

The purpose of this document is to provide the design for the commands to be added to the CLI Wallet for SONs.

2. Scope

The design requirement listed in this document will be limited to the commands to be added to the CLI Wallet. This will outline the commands required to be added and their implementation. Also outlined here will be the sequence in which the required steps will be performed including:

• any interactions with the user.

• validations to ensure complete and accurate information gathering.

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 multisig 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 multisig 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 multisig 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. Process Overview

Described here is the design for commands to be added to the CLI Wallet for adding/removing SON, voting for SON, etc.

5. Context

The following commands will have to be added in the CLI wallet and new APIs created for the same to allow the users to use the SON functionality:

a. create_son(string owner_account, string url, bool broadcast) This command creates a transaction to create a new SON. The parameters required are: owner_account: account name which has to be registered as an SON, url: published url where the SON has published his details and his marketing pitch and broadcast: whether to broadcast this transaction or not (default: false).

b. vote_for_son(string voting_account, string son_account, bool approve, bool broadcast) This command creates a transaction to vote for an SON. The parameters required are: voting_account: account name which is voting son_account: account name of the SON to whom the votes are being cast approve: whether the votes are being cast or withdrawn (default: false) broadcast: whether to broadcast this transaction or not (default: false)

c. get_son(string owner_account) Command to get the details of an SON. The parameters required are: owner_account: account name of the SON

d. update_son(string son_name, string url, string bitcoin_signing_key, bool broadcast) This command creates a transaction to update the SON. The parameters required are: son_name: The name of the SON to be updated url: published url where the SON has published his details and his marketing pitch to be updated bitcoin_signing_key: bitcoin transaction signing key of the SON to be updated broadcast: whether to broadcast this transaction or not (default: false)

e. update_son_votes(string voting_account, std::vector<std::string> sons_to_approve, std::vector<std::string> sons_to_reject, uint16_t desired_number_of_sons, bool broadcast) This command creates a transaction to update the votes for SONs. The parameters required are: voting_account: The account name which is voting sons_to_approve: The SONs to which the votes have to be casted sons_to_reject: The SONs from which the votes have to be removed desired_number_of_sons: The total number of SONs that the user wants to vote for broadcast: whether to broadcast this transaction or not (default: false)

f. list_sons(string& lowerbound, uint32 limit) Command to list the SONs starting from a lowerbound account id. lowerbound: The account id to start searching SONs from limit: The max number of SONs to be returned

g. claim_registered_son(const std::string& son_name) Command to save the private keys of the registered SON in the wallet permanently after the registration of SON is successful. The SON should have been created from the same CLI wallet. son_name: The name of the SON whose private keys are being saved in the wallet.

h. remove_son(string owner_account, bool broadcast) This command creates the transaction for remove_son_operation. The parameters required are: owner_account: The account name of the witness to be removed. broadcast: whether to broadcast this transaction or not (default: false)

i. list_active_sons(string& lowerbound, uint32 limit)

Command to list the SONs that are active currently.

We can use global_property_object::active_sons to retrieve the currently active SONs list.

lowerbound: The account id to start searching SONs from limit: The max number of SONs to be returned

The following commands will have to be updated in the CLI wallet and in the existing APIs to add the functionality related to SONs:

a. get_global_properties() This command returns the global properties of the blockchain such as head_block_num, head_block_id, next_maintenance_time, active_witnesses, active_committee_members, etc. This should be modified to provide the active_sons as well.

b. resync() method The resync method in the wallet.cpp file updates the wallet_data annotations e.g. wallet has been restarted and was not notified of the events while it was down.