-
Notifications
You must be signed in to change notification settings - Fork 18
Proposal Mechanism
Peerplays uses the same proposal mechanism as Graphene, with a few modifications. These modifications include:
- Gamified Proof of Stake (PIP, longer explanation) changes how voters are rewarded for their participation.
- The selection of operations that can be proposed is expanded. The new operations include operations related to sports, tournaments, and betting.
There is some documentation about proposals on the BitShares documentation page, such as this, but it is limited to proposed transactions and not proposals in general.
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. The full list of supported operations is in operations.hpp:55.
In addition to a list of operations, a proposal also has a defined review period and expiration time.
A proposal is created by a proposal_create_operation. This operation defines the review period and expiration time, as well as the list of operations proposed.
The proposal is then approved by a number of proposal_update_operation. These can add or remove active approvals, owner approvals, or key approvals.
Alternatively, it can be deleted (which is effectively a veto on the proposal) by a proposal_delete_operation. This can be done only by accounts who are required authorities on this proposal, so the same effect would be achieved by simply not adding one's approval to the proposal.
A proposal is 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 is checked on the proposal_update_operation, and on successful verification, the proposed operations are applied.
The list of authorities required for accepting a proposal depends entirely on the list of proposed operations. The proposal itself carries no extra authorities or requirements.
Specifically, the proposal-related operations require the following authorities:
- the
proposal_create_operationrequires only the authority of the submitter - the
proposal_update_operationwhich adds an approval requires the authority of the approver - the
proposal_delete_operationrequires 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.
There are three kinds of approvals being tracked for each operation: owner approvals, active approvals, and key approvals. Each operation can specify its required approvals of each kind separately.
Fees are associated with operations, not proposals. However, the operations to create or update a proposal carry their own fees, for which the payer can be chosen when creating the operation. Each of these carry a 20 unit fee plus a price per kilobyte.
The fees for the operations inside the proposal depend on the operation. For Peerplays-related ones, like creating a sport, the fee is fixed to 1 unit (equal to GRAPHENE_BLOCKCHAIN_PRECISION) and is paid by the witness account.
Peerplays adds many new operations related to sports and betting. Let's start by proposing one such operation. We will choose creating a new sport, because that one requires only the user, the sport name, and no other parameters.
In the code, this is represented by a proposal_create_operation that wraps a single sport_create_operation. In cli_wallet, this can be done as
propose_create_sport <account_name> 2019-12-31T23:59 {"en":"football"} true
Creating a proposal in cli_wallet both creates the proposal (with a proposal_create_operation) and automatically adds an approval of the creating user (with a proposal_update_operation). So proposals that require only the proposer's authority are immediately accepted without having to enter further commands.
The common parameters to proposal function are the name of the proposer (who also pays the fees associated with this proposal) and an expiration time. The last parameter is broadcast; if it's set to true, the operation will be broadcast to the network. You usually want to do this only after you added all the local approvals. The propose_create_sport and similar methods already add your approval, so we set it to true.
There are also parameters that are specific to the kind of proposal, in this case the name of the new sport.
Proposals that requires other people's approval are created without broadcasting
Approvals are added to proposals using the approve_proposal command, such as
approve_proposal <committee_member> "1.10.1" {"active_approvals_to_add" : ["<MY-COMMITTEE-MEMBER>"]} true
where "1.10.1" is the proposal ID. Once again, there is nothing to be done for accepting the proposal. The proposal becomes accepted once there are sufficient approvals for its operation(s). Each node can verify the approvals by itself, there doesn't have to be any distributed broadcast of a proposal being accepted. Once a node verifies this, it applies the operation in its database.