Overview

Governance Overview
In a nutshell, governance works like this: every block a portion of
block reward (10%) is being "reserved" for the project's own future
use. These coins then fund projects, proposed by community
members (for example, a salary for the development team). Once a
project is proposed, it is voted on by the network (more precisely, by
the owners of masternodes) to determine if it should be funded.

The payment itself happens approximately once a month (more

precisely, once every 43200 blocks). This payment occurs through a
special block, called a “superblock.” This superblock is essentially a
regular block with a coinbase transaction added which pays money
to the proposals selected for budgeting in the current voting cycle.

Governance Code Overview

The majority of governance-related code is in src/masternode-
budget.h and src/masternode-budget.cpp. The main object
that handles governance logic is CBudgetManager singelton called
budget. Some of the logic is in src/masternode-payments.cpp,
but it mostly redirects calls to budget object. Console RPC



commands are handled in src/rpcmasternode-budget.cpp, the
calls are also redirected to budget object.
User perspective
How to submit proposal?
Every node can submit a proposal. Proposal submission is a two-
step process:

1. First, you have to "prepare" the proposal with mnbudget

prepare. It creates a transaction burning 50 HLM and
containing the hash of the not-yet-created proposalExample:
mnbudget prepare cool-project http://bit.ly/1xWf863 3
1296000 y6R9oN12KnB9zydzTLc3LikD9cCjjQzYG7 400


2. This will prepare a proposal to be funded in 3 payments

totaling 3*400=1200 HLM starting from superblock 1296000.


3. Output:
464a0eb70ea91c94295214df48c47baa72b3876cfb658
744aaf863c7b5bf1ff0 - it's the collateral transaction hash,
needs to be copied for the next step


4. After the transaction has 6 confirmations, you can submit the

proposal with mnbudget submit. It will be broadcasted into
the network. (It doesn't have to be immidiately for the next
superblock, it can be for any of the superblocks in the
future)Example: mnbudget submit cool-project http://
bit.ly/1xWf863 3 1296000
y6R9oN12KnB9zydzTLc3LikD9cCjjQzYG7 400
464a0eb70ea91c94295214df48c47baa72b3876cfb658
744aaf863c7b5bf1ff0

How to vote for a proposal?
Only a masternode owner can vote for proposals. It can be done
from the wallet that controls their masternodes, a vote per
masternode. For each proposal votes on behalf of the same
masternode can be issued with at least 1 hour interval.

Example: mnbudget vote-many

464a0eb70ea91c94295214df48c47baa72b3876cfb658744a
af863c7b5bf1ff0 yes

This will vote with all masternodes controlled by the wallet.

How to see proposals for the next

period?
mnbudget show will display all proposals that the node knows of
and how many "yes", "no" and "abstain" votes they have.

mnbudget projection will display the proposals that are passing

and will be paid in the next superblock.

How to see what block height is the

next superblock?
mnbudget nextblock 

Development
perspective
How to enable governance?
1. Decide on following values and hardcode them in
CBudgetManager::GetTotalBudget():


◦ Block height to start from


◦ Budget size (right now it's 10% of block subsidy for 43200
blocks)


2. The mnbudget and mnfinalbudget commands will work

from the beginning.


3. Activate the payment of the budgeted funds with sporks ()


Sporks
I don't know how much you know about sporks, so I'll be brief.
Sporks are effectively a set of variables that all nodes on the
network share. These variables control how nodes behave and can
be used to dynamically change the protocol of the network. (There's
a video where Dash creator explains sporks for general public:
https://youtu.be/rp-ebgbgK-M).
Sporks are controlled with a spork key. It's an assymetric key pair -
private key is known to the dev team, public key is hardcoded into
all nodes.

• To be able to change spork values a node must be run with -

sporkkey=<privkey> command line argument (or with the
corresponding line in the config file).


• To change spork value you need to run RPC command spork

<spork_id> <value>


• To show spork values run spork show


There are 2 spork keys related to governance:

SPORK_13_ENABLE_SUPERBLOCKS - checked in
masternode-payments.cpp. If active

• Budget proposals are paid by miners (FillBlockPayee())


• Superblocks are allowed on block validation

(IsBlockValueValid())


• Superblocks are allowed on transaction validation

(IsBlockPayeeValid())


SPORK_9_MASTERNODE_BUDGET_ENFORCEMENT -
checked in masternode-payments.cpp

• Enforces budget payment blocks to have valid budget

payments (IsBlockPayeeValid())

How Governance Works?
Governance works in 43200-block cycles (approximately 1 month).
During such cycle proposals are submitted and voted for. Proposals
and votes are relayed through the network to all nodes.

2880 blocks before the superblock starts budget finalization period.

One node (or several) submits finalized budget into the network,
masternodes receive it and vote for it.

The first block of the following budget cycle is called superblock.

The superblock and several successive blocks are the blocks where
payments for budget proposals are made. Let's say we have 6
proposals for budget starting block 1296000. The first proposal will
be paid on block 1296000, the second one - on block 1296001, and
so on.

Proposal Preparation
All "mnbudget" commands are handled by function mnbudget()
in src/rpcmasternode-budget.cpp

Preparation is redirected to preparebudget() function. It validates

parameters and then executes following steps:

• Calculates hash of the proposal-to-be, calling

CBudgetProposalBroadcast::GetHash()


• Submits collateral transaction with

CWallet::GetBudgetSystemCollateralTX() and
CWallet::CommitTransaction(), writing the hash into
blockchain


Proposal Submission
Proposal submission is redirected to submitbudget(). After
validating the parameters it:

• Checks the collateral transaction with

IsBudgetCollateralValid() including existance of the
transaction and that it has 6 confirmations


Voting for Proposal

Voting is redirected to mnbudgetvote() . There are two options for
voting:

• vote-many <hash> <yes|no|abstain> is executed from

MN controller node ("many" mode). For each masternode:


◦ CMasternode object is located with

CMasternodeManager::Find() and masternode
collateral transaction identifier CMasternode::vin is
obtained (it serves as a unique masternode identifier)


◦ Vote object CBudgetVote is created and signed through

CBudgetVote::Sign()


◦ Vote is added to governance subsystem through

CBudgetManager::UpdateProposal()


• vote <hash> <yes|no|abstain> is executed from

masternode itself ("local" mode)


◦ Masternode collateral transaction identifier is obtained

from CActiveMasternode::vin

 ◦ Vote object CBudgetVote is created and signed through
CBudgetVote::Sign()


◦ Vote is added to governance subsystem through

CBudgetManager::UpdateProposal()


Propagating and Validating Votes

Votes (and proposals) are sent into the network via Bitcon
inventory messages. See RelayInv() calls in src/masternode-
budget.cpp.

Each node on the network keeps a container of all proposals

(including old proposals or proposals for future superblocks). From
this set of proposals a subset is selected , following this rules:

• All proposals are sorted by difference between "yes" and "no"

votes


• Only proposals for the next superblock are selected


• Amount of "yes" minus "no" votes must be greater than 10%

amount of masternodes currently online


• Proposal must be at least 24 hours old, i.e.

"established" (therefore, a proposal that is created less a day
before the superblock has zero chance of being included)


• From the sequence ordered and filtered as described above

top X proposals are picked where X is such that Σ amount(X)
<= GetTotalBudget(blockStart) = 43200 HLM

This subset is considered to be the node's view of the budget for
the next superblock. Is is composed in
CBudgetManager::GetBudget(). This budget continuously
evolves as new proposals and votes are being broadcast through
the network.

Viewing Proposals and Their Votes

mnbudget show is redirected to getbudgetinfo() function. It
then calls CBudgetManager::GetAllProposals()

mnbudget projection is redirected to getbudgetprojection(). It

displays proposals for the next period obtained from
CBudgetManager::GetBudget(). The rules for the proposals to
get into the projection are described in the section above.

Final Budget Submission

2880 blocks before the superblock starts budget finalization. This
process consists of one node submitting finalized budget and all the
masternodes voting for that budget. The node that will submit
finalized budgets must to be run with -
budgetvotemode=suggest command line argument (or with the
corresponding line in the config file). It is again a two-step process

1. Every time it receives a new block, will check if its current view
of the budget was submitted as finalized budget. If no, the
node will create a transaction burning 50 HLM and containing
the hash of the finalized budget to be created


2. After 7 confirmations of the collateral transaction the node

broadcasts finalized budget into the network. If before 7th
confirmation arrived the view of the budget is changed the
process starts again (because of this you might see 50 HLM
 being paid more times than the number of submitted budgets)


The node responsible for budget finalization needs to be online

during finalization process (2880 blocks) and to have enough funds
in order to be able to submit finalized budgets. There might be
several nodes submitting finalized budgets.

Finalized budget submission is performed by

CBudgetManager::SubmitFinalBudget() which is called by
CBudgetManager::NewBlock(). It's sent into the network via
Bitcon inventory messages.

The finalized budgets can be viewed with mnfinalbudget show

command on any node.

Automatic voting for final budget

When a masternode receives finalized budget broadcast it
compares it with it's own view of the budget. If both are identical
(i.e. have the same proposals in the same order), it will vote for it
and broadcast the vote into the network.

The check and voting are performed in

CFinalizedBudget::AutoCheck() which is called from
CBudgetManager::CheckAndRemove() which is called from
CBudgetManager::NewBlock().

Manual voting for final budget

It is possible for masternode operators to vote manually for a
finalized budget. The command is mnfinalbudget vote-many
<final-budget-hash> executed from MN controller node.

mnfinalbudget vote <final-budget-hash> can be executed

from the masternode.
Issuing the Superblock
During the budget finalization it is still possible to vote for the
proposals. When votes are broadcast, they reach the node that
submits finalized budget at some point. If it triggers a change in the
budget (either proposal set or the ordering in that set), a new
finalized budget is broadcast and voted for. Typically, it looks like
this: there is a new finalized budget, it receives votes, it stops
receiving votes, a there is a new finalized budget, repeat.

When the mining node starts creating the superblock it will get the
finalized budget with the highest amount of votes that it knows of
and will put the payment for the corresponding proposal into the
block. This logic is in CBudgetManager::FillBlockPayee().

The proposals are paid out one per block: if the superblock height is
N than the first proposal is paid in block N, the next one is paid in
block N+1, and so on. The miner will only pay out a finalized budget
that has more votes than 0.05 * M, where M is the number of
masternodes currently online.

Determining of whether there is a finalzied budget to be paid is

performed in CBudgetManager::IsBudgetPaymentBlock()

All nodes receiving that block validate it (with

CBudgetManager::IsTransactionValid()) and, as a part of this
process they check the budget payment transactions:

• The node considers a budget payment transaction invalid if it

has less than 0.05 * M votes, where M is the number of
masternodes currently online.


• The node accepts transactions for all finalized budgets that

have X votes, where X is such that it belongs to confidence
interval F-0.1M < X < F+0.1M, where F equals the highest
 amount of votes for all finalized budgets for this superblock.


Suggestions for next

stage:
In my opinion, a reasonable next action would be to set up the
governance for the testnet - modify GetTotalBudget() (if
necessary), - and deploy it into testnet. Then enable the 2 sporks
and start testing governance: submitting proposals, voting,
submitting finalized budget, seeing it receive votes and seeing the
budget being paid.