1. Purpose

The purpose of this document is to outline the steps required by a Peerplays node operator to enable/disable Sidechain plugin in the Peerplays blockchain.

2. Scope

The functional requirement listed in this document will be limited to the configuration portion of the SON. This will outline the required steps that will be performed by the Peerplays node operator to enable/disable Sidechain plugin in the Peerplays blockchain from the command line. 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 SONs. As per the current implementation of Sidechain, a multisig bitcoin wallet 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 wallet and will be required to sign any withdrawal transaction. When a SONs changes, the transaction signing key of the outgoing witness needs to be removed from the multisig bitcoin wallet 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 SONs will be independent of the witnesses and don't need to be changed much often.

4. Process Overview

Described here is the process to configure the SON plugin in the Peerplays blockchain.

5. Context

The Peerplays blockchain will allow the node operators to enable/disable the Sidechain functionality on their node. They will have to stake PPY 50 to be able to register as an SON. As soon as the Sidechain functionality is enabled/disabled and the user vests 50 PPY, the Peerplays blockchain will add the node to its list of Sidechain enabled nodes and make the node operator available for SON voting. An SON enabled node will be able to operate as an SON only when it receives the votes required to become one of the top 15 SONs.

6. Flow Diagram

7. SON Commands

Any Peerplays node can become a SON irrespective of it is a witness or not. It can connect to a local or remote Bitcoin node and verify the transactions.

7.1 Enable SON

./programs/witness_node/witness_node --resync --replay --son-enable

This command will enable the SON functionality in the Peerplays node. The node will be registered in the peerplays blockchain as an SON enabled node. Peerplays users will be able to vote for this user to be an active SON. The node will be able to listen to the changes on the Bitcoin blockchain. An active SON can perform all the functionality of the sidechain once it has been voted into the top 15 SONs.

7.1.1. Pre-Conditions & Errors

The error messages are to be displayed in GUI wallet or cli_wallet or other programmatic means.

1. The SON node should not be enabled and active for the same Peerplays account

2. Trying to enable an already in enabled SON node will give the error message "SON is already enabled for the account_name."

3. The account trying to enable SON should have a minimum balance of 50 PPY which has to be VESTED to become SON

4. If the account is not having the minimum required balance, an error message "Minimum VESTING Balance for SON node activation is not available. Make sure that the account is funded with MINIMUM_VESTING_BALANCE"

5. If a previous VESTED balance is available, it will not be considered to be the minimum VESTING BALANCE. This is to avoid accounts spamming the blockchain with SON-activate commands.

7.2. Disable SON

This section talks about permanently disabling SON.

./programs/witness_node/witness_node --resync --replay --son-disable

This command will disable the SON functionality in the Peerplays node and deregister the node in the peerplays blockchain as an SON enabled node. Any votes casted to the user to be an active SON will be reverted. The user will be able to claim their vested PPY after 2 days of deregistering their node.

7.1.2. Pre-Conditions & Errors

The error messages are to be displayed in GUI wallet or cli_wallet or other programmatic means.

1. Only a SON node which is in "enabled state" can be disabled

2. Trying to de-activate/disable a Peerplays node with SON not enabled will give the error message "SON is not enabled for account_name"

3. If a SON is disabled and trying to move the VESTED funds before 2 days duration via any means should be prevented

API Requirements

All the v1 Sidechain APIs should work as it is. Except for those, an API to provide the list of SON enabled users will be required. The API should return the list in the following format:

[
    {
        serial_num: 1,
        id: 1.20.1,
        user: memphis123,
        rank: 1,
        about_url: www.memphis-node.com,
        sidechain_url: http://www.memphis-node.com/sidechain,
        is_active: true,
        votes: 23223245
    },
    {
        ....
    },
    ....
]

CLI Wallet Command Requirements

These are new options to be added.

1. list_sons: We need a command in the CLI Wallet similar to list_witnesses to get the list of SONs.

2. list_active_sons: This command should provide a list of active SONs on the Peerplays blockchain.

1. Purpose

The purpose of this document is to outline the steps required to pay the SONs for their contribution to the Peerplays network.

2. Scope

The functional requirement listed in this document will be limited to the payment portion of the SON. This will outline the required steps to pay the SONs for the functions performed by them on the Peerplays blockchain. 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 SONs. As per the current implementation of Sidechain, a multisig bitcoin wallet 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 wallet and will be required to sign any withdrawal transaction. When a SONs changes, the transaction signing key of the outgoing witness needs to be removed from the multisig bitcoin wallet 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 SONs will be independent of the witnesses and don't need to be changed much often.

4. Process Overview

Described here is the process to pay the SONs on the Peerplays Blockchain.

5. Flow Diagram

N/A

6. Context

The SON operators will be paid in PPY from the payment pool set up specifically for payments to SONs. This pool will be replenished by depositing a percentage of all the transaction on the Peerplays network. This percentage should be a chain parameter so that it can be changed. The fee will be distributed at the Maintenance intervals based on transactions signed and weight of voting (therefore voting power affects payout) for each SON. Currently set maximum SON payment is 200 PPY daily and is specified in `SONS_DAILY_MAX_REWARD`.

7. Requirements

7.1 Supported Operation Types

All operations performed by SONs must be tallied and paid according to budget and defined payout procedure (as described in sections below).

System must include a library (global parameters) of configurable fee amounts fee amounts associated with each operation. Library must track each operation, its type, fee amount and currency in which fee is charged (PPY by default). Fees are set and amendable by committee members in accordance with committee member procedures to update global parameters.

Operations commonly performed by SONs are as follows:

• asset_issue_operation

• asset_reserve_operation

• proposal_create_operation

• proposal_update_operation

• proposal_delete_operation

• son_create_operation

• son_update_operation

• son_delete_operation

• son_heartbeat_operation

• son_report_down_operation

• son_maintenance_operation

• son_wallet_recreate_operation

• son_wallet_update_operation

• son_wallet_deposit_create_operation

• son_wallet_deposit_process_operation

• son_wallet_withdraw_create_operation

• son_wallet_withdraw_process_operation

See Risks section for considerations regarding fee amounts and their implications on financial viability of SON.

7.2 Paying Witnesses

Whenever a witness generates a new block, reward amount must be immediately deposited into witness account's vesting balance.

The amount must be withdrawn from witness_budget

7.3 Collecting Fees

All operations require a fee to be collected and paid to the network.

Fee collection is determined by operation type (as described in section Supported Operation Types):

1. Core asset transaction fees are deducted from payer's account

2. UIA (pBTC) transaction fees are converted to core asset using base exchange rate (note: bBTC to BTC is 1:1)fee mus

In a scenario where user has 0 PPY, fee must be collected from fee_pool.

7.4 Calculating budget

The equation for calculating SON budget is as follows:

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 )

other required variables:

• total_transactions_per_day - tracks number of transactions SON participated in

• SONs_REWARD_POOL - stores SON reward amounts

• SONS_DAILY_MAX_REWARD - configurable variable which sets maximum size of reward

• son_pay_max - dictates how much SONs are to be paid out it next payment interval

7.5 Determining payout

Payout must be determined by the number of transactions verified by a node. Higher availability nodes participate in more transactions and therefore receive higher payout.

SONs are paid based on % ratio between total_transactions_per_day and SONS_DAILY_MAX_REWARD, where SON's % share of daily transactions determines what % of SONS_DAILY_MAX_REWARD is paid. Payout happens only during SON maintenance interval, therefore payout is configurable based on the payment interval and can be configured to happen once every x maintenance intervals.

7.6 Payment Pool

Payments to SONs are stored inside son_budget which functions similarly to witness_budget. Specifically, son_budget accumulates transaction fees collected by peerplays network. As described above, payout happens during the maintenance interval .

SONS_DAILY_MAX_REWARD must initially be set to 200 PPY. We may to have to change this as per market realities etc. Currently BTC is the only supported cryptocurrency.

Note: SONS_DAILY_MAX_REWARD must be reviewed in production to determine whether this limit is too low or restrictive. Depending on the fees associated with each transaction (as described in Transaction Type section above), highly active SONs may perform a number of operations and reach daily max limit quickly thus creation a disproportion between operations performed vs max daily reward.

8 Risks

SON concept has proven to be technically feasible, however, there are financial viability implications that must be taken into account.

SON operations must be priced in ways that offset electricity cost of node operators by a margin that makes it worthwhile to operate a node, however also low enough to make the blockchain cost effective to its users.

Inability to find a fee model attractive to node operators will impede availability of SONs (for which there is a minimum threshold), while high fees are likely to impede user interest due to high cost.

Note that because fees may be amended by committee members, fees they set may create risks mentioned above. It is recommended that committee member operations in relation to fees are closely monitored.

Sample test:

1. configure witness_pay_per_block chain parameter = 1

2. configure son_pay_daily_max chain extension parameter = 10000 ( As we don’t have enough fee collected on our chain, keeping it low is essential to test properly)

3. configure son_pay_time chain extension parameter = maintenance_interval or multiples of maintenance_interval. (Eg. x, 2x, 3x, 4x etc x = maintenance_interval). As budget is calculated during maintenance period son_pay_time should be multiples of maintenance_interval.

4. Temporarily, txs_signed of son_statistics_object is incremented through son heartbeats to enable testing of SON Rewards. ( txs_signed can be obtained by get_object 2.24.0 command). txs_signed are reset and added to total_txs_signed if SONs are paid out successfully.

5. Check that the get_dynamic_global_properties has son_budget and last_son_payout_time updated correctly like below,

   get_dynamic_global_properties { "id": "2.1.0", "random": "0f0b35fba1f53d22384e642356c25510e63f18b7", "head_block_number": 4708, "head_block_id": "00001264be90f462d553e2edee2e7fee698215c1", "time": "2020-03-19T10:25:42", "current_witness": "1.6.2", "next_maintenance_time": "2020-03-19T10:30:00", "last_budget_time": "2020-03-19T10:24:00", "witness_budget": 93, "last_son_payout_time": "2020-03-19T10:24:00", "son_budget": 10000, "accounts_registered_this_interval": 0, "recently_missed_count": 7, "current_aslot": 8917831, "recent_slots_filled": "1298074214633706907132624082304903", "dynamic_flags": 0, "last_irreversible_block_num": 4700 }

6. list_account_balances <sonaccount01> to check that the pay is added to the SON account’s balance.

7. If there are 13 active SONs, and each SON sent 3 heartbeats before next payout time, You can find below snippet in the log during the chain maintenance, pay 769 to 2.24.0 for 3 transactions signed total txs = 13 x 3 = 39. so pay for each SON -> (3/39)x10000 = 769

Purpose

The purpose of this document is to outline the steps required by a user to vote for an SON in the Peerplays blockchain and the consensus mechanism for SONs.

Scope

The functional requirement listed in this document will be limited to the voting and consensus portion of the SON. This will outline the required steps that will be performed by a user to vote for an SON in the Peerplays blockchain and their selection as active SONs. 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.

Background

The Bitcoin Sidechain functionality has been implemented in the Peerplays blockchain but it doesn't take into account, the change of SONs. As per the current implementation of Sidechain, a multisig bitcoin wallet 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 wallet and will be required to sign any withdrawal transaction. When a SONs changes, the transaction signing key of the outgoing witness needs to be removed from the multisig bitcoin wallet 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 SONs will be independent of the witnesses and don't need to be changed much often.

Process Overview

Described here is the process to vote for SONs in the Peerplays Blockchain.

Context

The Peerplays blockchain will allow the users to vote for the SON enabled node operators. The Peerplays blockchain should have a minimum of 15 active SON nodes. The user should be able to see a list of the SON enabled nodes and vote for up to 15 nodes. An SON enabled node will be able to operate as an active SON only when it receives the votes required to become one of the top 15 SONs. The number of active SON Nodes can be increased by the witnesses/advisor by making a change to the chain parameters. The active SONs will have corresponding bitcoin transaction signing keys in order to sign transactions for the Peerplays bitcoin multisig address on the bitcoin blockchain. When the active SONs change on the Peerplays blockchain, their corresponding bitcoin transaction signing keys are changed in the Peerplays bitcoin multisig address on the bitcoin blockchain.

Each SON when processing inter blockchain communications (IBC) will carry a percentage of weight in the signing based on the votes they have received. Every IBC request will require signed consensus by at least ⅔ of the Active Cast Weighted (ACW) Votes for the SONs. Active Cast Weighted votes means the votes casted to active SONs by users who have staked some PPY weighted by their staked PPY.

If an SON enabled node's downtime exceeds 12 continuous hours, it should be automatically deregistered in the Peerplays blockchain as an SON enabled node and all the votes cast for me should be reverted.

If an SON decides to stop operating the node by disabling the SON plugin, any votes cast to him will be removed and another SON will take his place.

Flow Diagram

SON Voting Command

The below command from the CLI wallet will be used to vote for SONs: vote_for_son <voting_account> <son> <approve> <broadcast>

• voting_account_id: the name or id of the account who is voting with their shares

• son: the name or id of the son's owner account

• approve: true if you wish to vote in favor of that son, false to remove your vote in favor of that son

• broadcast: true if you wish to broadcast the transaction

1. Purpose

The purpose of this document is to outline various scenarios in which SONs will be switched from the top 2/3rd and also among the top 15 minimum ACTIVE SONs.

2. Scope

The functional requirement listed in this document will be limited to the multi-sig key change scenarios only.

3. Background

The Bitcoin Sidechain functionality has been implemented in the Peerplays blockchain but it doesn't take into account, the change of SONs. As per the current implementation of Sidechain, a multisig bitcoin wallet 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 wallet and will be required to sign any withdrawal transaction. When a SONs changes, the transaction signing key of the outgoing witness needs to be removed from the multisig bitcoin wallet 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 SONs will be independent of the witnesses and don't need to be changed much often.

4. Process Overview

Various scenarios are outlined in the Scenarios section

5. Context

The SONs has a ranking & grouping. The ranking is depending on the total effective stake of the votes received. We can have infinitely many SONs and rankings. The top 15 nodes aka ACTIVE nodes are the ones which are mandated by the SON implementation. ie at any point of time, there has to be 15 nodes for the SON feature to be operational. Apart from the ACTIVE group of top 15, we also have a 2/3rd top ranked SONs in terms of votes which signs the transactions.

Any time there is a change to active SON list, a change to primary wallet scripts will be triggered. Therefore any change to active SONs list must result in creation of new primary wallet using public keys of SONs that remain active after the change. The reason for this is that primary wallet is created based on public keys of all active sons, when the composition of active SON list changes, it affects what keys are associated with the primary wallet.

At each maintenance intervals, list of candidates for active SONs is compared to list of current active SONs, if lists are different, list of current active SONs is understood to change and thus a new primary wallet must be generated.

6. Scenarios

Scenarios below are examples of changes that may impact active SONs list and thus trigger re-creation of primary wallet using public keys of SONs on active SONs list.

6.1 Ranking change within the top 2/3rd SONs

In this scenario the SONs will change their ranking and order but the top 2/3rd SONs will remain the same. This means, if there are 15 SONs and the 2/3rd is 10 SONs, the rank of the 10 SONs will be changed. But it will not have any impact on the multi-sig wallet. On using the list_sons will provide the new order.

During design, if possible its recommended to have invoke the immediate ranking change only in the case of a change involving the multi-signature key change. ie, this particular scenario can be ignored until the first deposit transaction happens. This will induce a slight delay in the display of ranking of the SONs for the reporting purposes.

6.2 Ranking Change due new votes resulting in the change of multi-wallet key

This scenario addresses the normal case where one or more of the top 2/3rd SONs loses votes and they moves out of the top 2/3rd.

An example scenario is with 15 ACTIVE SONs where the top 10 are forming the 2/3rd quorum. When one of them loses votes, an ACTIVE node or a node outside of TOP 15 ACTIVE nodes replaces its position.

This scenario would trigger:

• creation of a new Bitcoin address

• move the Bitcoin (BTC) balances to the new address which is controlled by the new set of top SONs

• The deposit and transfer APIs of the SON should return new multi-signature wallet address

6.3 Ranking change - ACTIVE SON change

If an ACTIVE SON receives or loses votes, its effective stake can change. This can trigger the ranking change. The change will be executed at the next son_maintenance_interval` , ie 24 hours or during the next deposit/withdraw operation whichever comes first.

Ranking changes in the list of SONs must result in creation of new multi-signature wallet using public keys of new SONs. Balances are then transferred to the new address.

Note that any changes to list of SONs must result in new wallet being generated and balances transferred to new wallet address.

6.4 Ranking Change - Disabling an ACTIVE SON

If an ACTIVE SON disables its node, another node has to replace it.

This can trigger the ranking change. The change will be executed at the next son_maintenance_interval` , ie 24 hours or during the next deposit/withdraw operation whichever comes first.

Ranking changes in the list of SONs must result in creation of new multi-signature wallet using public keys of new SONs. Balances are then transferred to the new address.

6.5 Ranking change - an ACTIVE SON goes offline

In this scenario, an ACTIVE SON but not in the top 2/3rd in terms of cumulative votes received goes down.

• SON goes down/offline

• The SON network records this

• Upon completion of 12 hours after the SON going down/offline event is recorded, the ranking change is triggered

• The Ranking change will be executed on the first deposit transaction or once in 24 hours whichever comes first.

• This approach is done at the cost of status change at the front-end, but to avoid unnecessary operations in the chain

Ranking changes in the list of SONs must result in creation of new multi-signature wallet using public keys of new SONs. Balances are then transferred to the new address.

6.6. A top 2/3rd SON goes offline

A high stake SON or a group of SONs goes offline without notice. This scenario or slowness is often observed during large scale internet routing attacks involving BGP poisoning or a data center maintenance where a group of servers becomes unreachable. (This often happens when certain German data center performs an upgrade or maintenance).

• If we have ACTIVE SONs, and if need to perform a key change before the on the maintenance interval or before the next deposit transaction is requested, we can proceed with the change of keys

• Upon such a change the funds has to be transferred to the new wallet created

• The fund transfer will be possible if the remaining SONs who originally signed the transaction has enough authority (weight) to perform the withdraw operation on the old wallet

• If the remaining SONs doesn't have enough control / weight to operate the multi-signature wallet, the funds will locked in the previous wallet until the necessary SONs becomes active. There seems to no way to address this. But, new deposits to the address will not be entrained as the deposit API will return new Bitcoin address.

If change of keys occurs for any SONs, this event must must result in creation of new multi-signature wallet using new SON keys. Balances are then transferred to the new address.

6.7 A top SON goes into maintenance - with key change

If a SON part of the multi-signature wallet creation with a large stake enough to trigger change in the keys, the maintenance mode should trigger a change in the ranking of the SONs & also a change in the keys.

To avoid frequent key changes, the key change can be handled upon the first deposit or withdrawal. The deposit and withdrawal operations to the SON should be made via calling respective APIs to make this possible.

IMPORTANT: The time taken for the wallet change operation should be captured and we need to take this account for fine tuning the strategy for key changes. This is something that we can't easily predict right now, but needs to test and verify.

This scenario must trigger creation of new wallet using SON public keys, and transfer of balance to new wallet address due to change in SON composition and public keys.

1. Purpose

The purpose of this document is to outline requirements for status monitoring of Sidechain Operation Nodes for purpose of determining whether SONs are active and able to participate in blockchain transactions.

2. Scope

The functional requirement listed in this document will be limited to the configuration portion of the SON. This will outline the required steps that will be performed by the Peerplays node operator to enable/disable Sidechain plugin in the Peerplays blockchain from the command line. Also outlined here will be the sequence in which the required steps will be performed including:

• SON heartbeats

• SON maintenance mode actions

• SON de-registration

3. Background

The Bitcoin Sidechain functionality has been implemented in the Peerplays blockchain but it doesn't take into account, the change of SONs. As per the current implementation of Sidechain, a multisig bitcoin wallet 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 wallet and will be required to sign any withdrawal transaction. When a SONs changes, the transaction signing key of the outgoing witness needs to be removed from the multisig bitcoin wallet 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 SONs will be independent of the witnesses and don't need to be changed much often.

4. Process Overview

Described here is the process of SON status reporting (heartbeat) and maintenance mode activities.

1. System sends heartbeat to registered SONs based on specified frequency

2. Process responses:

   1. Active and Request Maintenance SONs will respond to heartbeat

      1. Update statistics with last active timestamp and transactions signed updates

   2. In maintenance and inactive SONs will not respond to heartbeat

      1. inactive flow

      2. in maintenance flow

5. Context

The Peerplays blockchain will allow the node operators to enable/disable the Sidechain functionality on their node. They will have to stake PPY 50 to be able to register as an SON. As soon as the Sidechain functionality is enabled/disabled and the user vests 50 PPY, the Peerplays blockchain will add the node to its list of Sidechain enabled nodes and make the node operator available for SON voting. An SON enabled node will be able to operate as an SON only when it receives the votes required to become one of the top 15 SONs.

6. Flow Diagram

[TBD]

7. Requirements

SON monitoring is required because only active SONs can participate in blockchain transactions.

7.1. SON Status monitoring and statistics (Heartbeat)

System must include an automated heartbeat check that monitors status of registered SONs per each 180 second interval (heartbeat interval). This interval must be configurable via chain_parameters in extensions.son_heartbeat_frequency, and set to 180 seconds by default. (Other configuration may be possible via genesis.json). Note that this interval may be different in production, but for testing purposes it should be within 3 minutes.

Heartbeats must be sent by SONs who are in active, or request_maintenance status. All sent heartbeat activity must be logged. SONs in inactive status must not send heartbeat.

The following statistics must be tracked and logged as part of heartbeat monitoring:

• number of transactions signed - number of transactions signed by SON. This value must be updated each time a transaction is signed. This counter is reset during SON rewards.

• total downtime - compounded time that SON was down represented in HH:MM:SS format. This value must be updated to compounds all current interval downtime values.

• current interval downtime - Time since last transition to in_maintenance. This counter is reset during maintenance

• last down timestamp - timestamp of last transition to in_maintenance status

• last active timestamp - timestamp of last transition to active status, or last heartbeat where status is active or request_maintenance.

SONs in active or request_maintenance must be treated as active for the purpose of transaction signing.

SONs in in_maintenance or inactive status must not participate in transaction signing.

Statistics for active SONs must be updated after every heartbeat where SON is active, request maintenance.

7.2. Requesting maintenance

System must include a wallet command which requests SON to be placed in maintenance mode. Requesting SON maintenance must be available to SONs in active status. Once request SON maintenance is initiated, target SON must be set to in_maintenance at the upcoming chain maintenance interval.

[TBD/INACCURATE. TO CONFIRM WITH SATYA SONs in maintenance modes can be changed to active or inactive mode via voting process described in SON Voting and Consensus requirements. Voting and change of status must be initiated by sending a heartbeat.]

System must allow cancelling of maintenance request via cancel_request_son_maintenance command. System must restrict this command to SONs in request_maintenance status.

After successful execution of cancel maintenance request, SON must be placed into active status.7.3

7.3. Reporting unavailable SONs

7.4 SON De-registration Operation

System must de-register SONs that have been in maintenance state for longer than allowed. Allowed maintenance threshold must be a configurable parameter extensions.son_deregister_time, with 12 hours being the default value. Alternatively, deregister threshold may be specified in genesis.json

Once system identifies an SON that has been in maintenance state for longer than specified threshold, system must create a proposal with son delete operation raised by one of schedules SONs.

Declaring inactive

SON monitoring process must track SONs which miss a heartbeat and declare an SON inactive if an SON misses two consecutive heartbeats. Tracking missed heartbeats must reset for each SON where a heartbeat is received after a missed heartbeat.

1. Purpose

The purpose of this document is to outline how SONs create and manage proposals that are created with various transactions

2. Scope

The functional requirements listed in this document cover the following proposals:

• son_report_down

• son_report_down_operation

• son_wallet_update_operation

• son_wallet_deposit_create_operation

• son_wallet_deposit_process_operation

• son_wallet_withdraw_create_operation

• son_wallet_withdraw_process_operation

• sidechain_transaction_create_operation

3. Background

When certain types of transactions are performed by SONs, proposals are created to seek approval for these transactions. Proposals are created using create operation, and must be approved or rejected following proposal creation. Approved proposals fulfill their associated transaction (for example deposit), rejected proposals cancel the transaction.

4. Process Overview

N/A

5. Context

Each proposal contains a list of operations. These operations are the way to change anything in the blockchain, including performing transfers, modifying chain parameters, creating and modifying accounts, assets, and also proposals.

In addition to a list of operations, a proposal also has a defined review period and expiration time.

6. Flow Diagram

N/A

7. Proposals

7.1 Proposal Lifetime

A proposal must when proposal_create_operation operation is executed. This operation defines the review period and expiration time, as well as the list of operations proposed.

The proposal then must require approval via proposal_update_operation. This operation must include functions to add or remove active approvals, owner approvals, or key approvals.

Ability to delete (which is effectively a veto on the proposal) a proposal must exist via proposal_delete_operation. Execution of this operation must be restricted to accounts who are required authorities on this proposal, alternatively, the same effect would be achieved by simply not adding one's approval to the proposal.

7.2 Approving Proposals

A proposal must be accepted when it reaches the required approvals through the proposal_update_operation. There is no specific step or operation to accept a proposal, instead authority must be checked on the proposal_update_operation, and upon successful verification, the proposed operations must be applied.

The list of authorities required for accepting a proposal must depend on the list of proposed operations. The proposal itself must not carry any extra authorities or requirements.

Specifically, the proposal-related operations must require the following authorities:

• the proposal_create_operation requires only the authority of the submitter

• the proposal_update_operation which adds an approval requires the authority of the approver

• the proposal_delete_operation requires the authority of the veto-giver, which must be a required authority on at least one operation of the affected proposal.

Other operations have different authority requirements.

7.2 Types of Approvals

There are three kinds of approvals that must be tracked for each operation: owner approvals, active approvals, and key approvals. Each operation must specify its required approvals of each kind separately.

7.3 Fees

Fees must be associated with operations, not proposals. However, the operations to create or update a proposal must carry their own fees, for which the payer must be chosen when creating the operation. Each of these transactions must carry a 20 unit fee plus a price per kilobyte.

The fees for the operations inside the proposal must be determined by operation. For Peerplays-related ones, like creating a sport, the fee is fixed to 1 unit (equal to GRAPHENE_BLOCKCHAIN_PRECISION) and must be paid by the witness account.

7.4 Operations requiring proposals

List of operations and their associated proposals:

• SON report down (son_report_down) must be checked for timestamps stored in SON statistics object to confirm that SON is down (missed two heartbeats)

• SON De-register (son_delete_operation) must be checked for total downtime stored in SON statistics objects to confirm that SON has been in maintenance for too long and must be de-registered/deleted

• SON wallet update (son_wallet_update_operation) must be checked against active SONs to find matching transaction data. 2/3rds of active sons must confirm a match for a successful check

• Deposit (son_wallet_deposit_create_operation) must not required proposal for object creation, but must be checked to verify that parameters are correct (same as in existing object), an active SON is creating the object, and only the expected son is confirming the transaction.

• Process Deposit (son_wallet_deposit_process_operation) +asset_issue_operation - check critical values from son_wallet_deposit_object are identical to critical values from sidechain transaction. Minimum mandatory checks are: check sender and amount. Depending on sidechain, checks of other values may be warranted (Bitcoin - vout and number of transaction confirmations, Peerplays - exchange rate)

• Transfer (transfer_operation) - TBD

• Withdrawal (son_wallet_withdraw_create_operation) must not require a proposal for object creation, however, must be checked to verify that parameters are correct (same as in existing object), an active SON is creating the object, and only the expected son is confirming the transaction

• Process Withdrawal (son_wallet_withdraw_process_operation) + asset_reserve_operation - check critical values from son_wallet_withdraw_object are identical to critical values from sidechain transaction. Minimum mandatory checks are: check sender and amount. Depending on sidechain, checks of other values may be warranted (Bitcoin - vout and number of transaction confirmations, Peerplays - exchange rate)

• Sidechain transaction creation (sidechain_transaction_create_operation) must be checked to verify that given object id is already created

8 Reference

List of Graphene operations

https://github.com/peerplays-network/peerplays/blob/master/libraries/chain/include/graphene/chain/protocol/operations.hpp#L55

Purpose

The purpose of this document is to outline the steps required to use smart contracts for Inter-blockchain communication with blockchains that support smart contracts such as Ethereum, EOS and the likes.

Scope

The functional requirement listed in this document will be limited to the use of smart contracts to enable inter-blockchain communication between Peerplays and other blockchains that support smart contracts. This will outline the required steps to create smart contracts on other blockchains which can then be called by the Peerplays blockchain to perform various operations such as withdrawal of the cryptocurrency back to the user. 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.

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 wallet 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 wallet 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 wallet 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 SONs will be independent of the witnesses and don't need to be changed much often.

Process Overview

Described here is the process to use smart contracts on enable inter-blockchain communication between Peerplays and other blockchains that support smart contracts. For ease of understanding, we will use EOS as an example for the parent chain.

Context

To facilitate the transfer of tokens from other blockchains to Peerplays, smart contracts have to be deployed on both Peerplays and the EOS blockchain. We would also need to check the smart contract tables every 5-10 seconds, scanning for transactions to relay across the network. This can be done by polling functions relay_eos and relay_ppy running on the SONs. relay_eos will check the smart contract tables on the EOS and relay_ppy will check the smart contract tables on PPY. These functions may be called IBC Relays.

This cannot be implemented until we have Smart Contracts implemented in Peerplays.

Smart Contracts Flow

1. The user will initiate an inter-blockchain transaction orig_trx on the EOS mainnet using peerplays.io contract. The transaction information will be recorded in the origtrx table of the peerplays.io contract on the EOS mainnet side;

2. relay_eos will get the transaction and transaction-related information (block information and Merkle path), then pass it to the relay of Peerplays side (relay_ppy);

3. relay_ppy constructs 'cash' transaction and calls the cash action of the eos.io contract on the Peerplays side. If the call succeeds in the cash function, the corresponding token will be issued to the target user after deducting the fees;

4. relay_ppy will get cash_trx and related information (block information and Merkle path) and pass them to relay_eos. relay_eos will construct the cashconfirm transaction and call the cashconfirm action of the peerplays.io contract on the EOS mainnet side, which will delete the original transaction record in peerplays.io contract. This will complete the inter-blockchain transaction.

5. At step 3, if the call fails, relay_ppy will get an exception in the cash_trx and pass them to relay_eos. relay_eos will construct a cashrefund transaction and call the cashrefund action of the peerplays.io contract on the EOS mainnet side, which will refund the amount to the sender after deducting the fees.

References

https://github.com/boscore/Documentation/blob/master/IBC/EOSIO_IBC_Priciple_and_Design.md