diff --git a/docs/user/governance/img/core-qt/governance-tab.png b/docs/user/governance/img/core-qt/governance-tab.png index a6cb7f5ef..cb4bcb065 100644 Binary files a/docs/user/governance/img/core-qt/governance-tab.png and b/docs/user/governance/img/core-qt/governance-tab.png differ diff --git a/docs/user/governance/img/core-qt/proposal-create-conf.png b/docs/user/governance/img/core-qt/proposal-create-conf.png new file mode 100644 index 000000000..5fc236a5f Binary files /dev/null and b/docs/user/governance/img/core-qt/proposal-create-conf.png differ diff --git a/docs/user/governance/img/core-qt/proposal-create.png b/docs/user/governance/img/core-qt/proposal-create.png index aeae4e147..a15884aa7 100644 Binary files a/docs/user/governance/img/core-qt/proposal-create.png and b/docs/user/governance/img/core-qt/proposal-create.png differ diff --git a/docs/user/governance/img/core-qt/proposal-created.png b/docs/user/governance/img/core-qt/proposal-created.png new file mode 100644 index 000000000..cc261e354 Binary files /dev/null and b/docs/user/governance/img/core-qt/proposal-created.png differ diff --git a/docs/user/governance/img/core-qt/proposal-submitted-conf.png b/docs/user/governance/img/core-qt/proposal-submitted-conf.png index 43ce8efec..be4b89bca 100644 Binary files a/docs/user/governance/img/core-qt/proposal-submitted-conf.png and b/docs/user/governance/img/core-qt/proposal-submitted-conf.png differ diff --git a/docs/user/governance/img/core-qt/proposal-validate.png b/docs/user/governance/img/core-qt/proposal-validate.png deleted file mode 100644 index 004d3519e..000000000 Binary files a/docs/user/governance/img/core-qt/proposal-validate.png and /dev/null differ diff --git a/docs/user/governance/img/core-qt/resume-proposal-broadcast.png b/docs/user/governance/img/core-qt/resume-proposal-broadcast.png new file mode 100644 index 000000000..6b0f1f1c5 Binary files /dev/null and b/docs/user/governance/img/core-qt/resume-proposal-broadcast.png differ diff --git a/docs/user/governance/understanding.rst b/docs/user/governance/understanding.rst index e0e3e1bd5..a4700e7c0 100644 --- a/docs/user/governance/understanding.rst +++ b/docs/user/governance/understanding.rst @@ -163,10 +163,10 @@ reasonable chance of passing their proposal, it is created as a governance object on the blockchain. A fee of 1 DASH is associated with this action to prevent spam and ensure only serious proposals make it to this stage. Several tools exist to allow masternode operators to -comfortably review and vote on proposals. The net total of yes votes must -exceed 10% of the total masternode count at the time votes are tallied -in order to pass. If there are more passing proposals than the available -block subsidy can provide for, the proposals with the most yes votes will +comfortably review and vote on proposals. The weighted net total of yes votes +minus no votes must meet or exceed the threshold described under Budget +allocation in order to pass. If there are more passing proposals than the available +block subsidy can provide for, the proposals with the most weighted yes votes minus no votes will pass first, creating a cut-off point for less popular proposals. The same process is then repeated every month, and the total amount of Dash available for proposals decreases by approximately 7.14% per year, @@ -207,7 +207,7 @@ proposal owner. Discussion on Dash Central occurs below this information, and masternode owners have the option to verify their ownership of a masternode and ability to cast a vote by signing a message from the masternode collateral address. Masternodes can vote at -any time, and also change their vote at any time until the cutoff block +any time, and also change their vote once per hour until the cutoff block is mined and voting stops. This occurs 1662 blocks prior to the superblock. After voting stops, the blockchain executes a decentralized tally and validates all votes. Once consensus is reached, the results @@ -266,9 +266,11 @@ The total budget of the network can be calculated by taking 20% of the block subsidy over the period of time between two superblocks, which occur every 16616 blocks or approximately 30.29 days. A voting cutoff occurs 1662 blocks before the superblock, and the final votes are tallied at -this point. A proposal must satisfy the condition ``(YES votes - NO -votes) > (Total Number of Masternodes / 10)`` in order to be considered -passing. Then, in the superblock, the winning proposals are awarded in +this point. A proposal passes when yes votes minus no votes reach at least +10% of the total eligible votes, with a minimum of 10 votes +on mainnet. Only enabled masternodes count toward these totals. A regular +masternode's vote counts as one vote; an evonode's vote counts as four. +Then, in the superblock, the winning proposals are awarded in the order of the margin by which they are passing until either the entire budget is allocated or no more passing proposals exist. This allows for completely trustless and decentralized allocation of the diff --git a/docs/user/governance/using.rst b/docs/user/governance/using.rst index 0c3e9d393..5fa45c763 100644 --- a/docs/user/governance/using.rst +++ b/docs/user/governance/using.rst @@ -37,21 +37,24 @@ Votes - Votes are cast using the registered voting address - The voting address can be delegated to a third party -- Votes can be changed at any time +- Votes can be changed once per hour +- A regular masternode's vote counts as one vote; an evonode's vote counts + as four - Votes are counted every 16616 blocks (approx. 30.29 days) Budgets ------- - Budgets are proposals which receive a net total of yes votes equal to - or greater than 10% of the total possible votes (for example over 448 - out of 4480) -- Budgets can be nullified at any time if vote totals (cast or re-cast) - fall below the approval threshold + or greater than 10% of the total eligible votes, rounded down, with a + minimum of 10 votes on mainnet (for example, 448 out of 4480) +- Budgets can lose approval if vote totals (cast or re-cast) fall below + the approval threshold - Budgets are processed (paid) in order of yes minus no votes. More - popular budgets get payment priority. -- Approximately 7919 dash (in 2024) are available for each budget cycle, - decreasing by 7.14% every 210240 blocks (approx. 383.25 days). + popular budgets get payment priority. +- The budget available for each cycle can be checked using the commands + in :ref:`budget-cycles`, and decreases by approximately 7.14% every + 210240 blocks (approx. 383.25 days). Object structure ---------------- @@ -69,18 +72,16 @@ The following information is required to create a proposal: Persistence ----------- -- Proposals become active one day after submission -- Proposals will remain visible on the network until they are either - disapproved or the proposal's last payment-cycle is reached -- Approval occurs when yes votes minus no votes equals 10% or more of - the total available votes. -- Disapproval occurs when no votes minus yes votes equals 10% or more of - the total available votes. -- The total available votes is the count of online and responding - masternodes and can be seen by running the command - ``masternode count`` in the Dash Core wallet debug window. A graph of - the total masternode count can be found `here - `__ +- Proposals become fully accepted after the proposal fee transaction has + six confirmations +- Proposals remain on the network until their payment period ends or + masternodes vote to remove them +- Approval occurs when yes votes minus no votes meets the threshold + described under Budgets +- Falling below the approval threshold does not remove a proposal +- The total eligible votes comes from registered masternodes that are + not banned for failing to provide service. Regular masternodes count + as one vote each, and evonodes count as four. Templates --------- @@ -100,40 +101,21 @@ Budget cycles When preparing a proposal, be aware of when the next cycle will occur and plan accordingly. It is recommended to choose your proposal payment start block at least one cycle in the future to allow time for -discussion and gathering support and votes. Note that votes will no -longer be tallied 1662 blocks (approximately 3 days) prior to the -superblock. - -+--------------+------------------------------+ -| Block height | Approximate date | -+==============+==============================+ -| 1212968 | Thu Jan 30 02:38:52 UTC 2020 | -+--------------+------------------------------+ -| 1229584 | Sat Feb 29 09:43:54 UTC 2020 | -+--------------+------------------------------+ -| 1246200 | Mon Mar 30 16:48:56 UTC 2020 | -+--------------+------------------------------+ -| 1262816 | Wed Apr 29 23:53:58 UTC 2020 | -+--------------+------------------------------+ -| 1279432 | Sat May 30 06:59:00 UTC 2020 | -+--------------+------------------------------+ -| 1296048 | Mon Jun 29 14:04:02 UTC 2020 | -+--------------+------------------------------+ -| 1312664 | Wed Jul 29 21:09:04 UTC 2020 | -+--------------+------------------------------+ -| 1329280 | Sat Aug 29 04:14:06 UTC 2020 | -+--------------+------------------------------+ -| 1345896 | Mon Sep 28 11:19:08 UTC 2020 | -+--------------+------------------------------+ -| 1362512 | Wed Oct 28 18:24:10 UTC 2020 | -+--------------+------------------------------+ -| 1379128 | Sat Nov 28 01:29:12 UTC 2020 | -+--------------+------------------------------+ -| 1395744 | Mon Dec 28 08:34:14 UTC 2020 | -+--------------+------------------------------+ - -You can view the source code for this calculation at this -`GitHub gist `_ +discussion and gathering support and votes. Vote at least 1662 blocks +(approximately 3 days) before the superblock. After this point, masternodes +begin choosing which proposals to pay, so later votes may not affect +the upcoming payment. + +To find the next superblock height, run the following command in the +Dash Core wallet console:: + + getgovernanceinfo + +The ``nextsuperblock`` field gives the next superblock height. Subsequent +mainnet superblocks occur every 16616 blocks. To check the maximum budget +for a superblock, use that height in the following command:: + + getsuperblockbudget .. _creating-proposals: @@ -141,8 +123,8 @@ Creating proposals ================== Once you have prepared the text of your proposal and set up a website or forum post, it is time to -submit your proposal to the blockchain for voting. While all tasks involved with creating a budget -proposal can be executed from the Dash Core wallet (:ref:`GUI ` or +submit your proposal to the network for voting. You can create a budget +proposal using the Dash Core wallet (:ref:`GUI ` or :ref:`console `) or the :ref:`Dash Budget Proposal Generator `. @@ -157,10 +139,10 @@ manual console commands. To use this feature, your wallet must be unlocked and c balance to cover the 1 DASH proposal fee plus a small transaction fee. Accessing the Governance tab -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Open your Dash Core Wallet and click on the **Governance** tab. This displays a list of existing -proposals and provides a **Create Proposal** button in the upper right corner. +proposals and provides **Create Proposal** and **Resume Proposal** buttons. .. figure:: img/core-qt/governance-tab.png :width: 500px @@ -173,108 +155,63 @@ Creating a new proposal Click the **Create Proposal** button to open the proposal creation dialog. Enter your proposal details: -- **Proposal name**: A unique identifier -- **URL**: Link to detailed proposal information (use a URL shortener if needed) +- **Proposal name**: A label of 40 characters or less +- **Description URL**: Link to detailed proposal information - **Payment address**: The Dash address that will receive payments - **Payment amount**: Amount requested per payment cycle -- **First payment date**: Select the superblock date for the first payment -- **# of payments**: Number of payment cycles requested - -The dialog displays the total amount requested and notes the 1 DASH proposal fee that will be -burned. Click **Next** when all fields are complete. +- **Payment date**: Select the first payment +- **Payments**: Number of payment cycles requested .. figure:: img/core-qt/proposal-create.png - :width: 350px + :width: 500px Entering proposal details in the creation dialog -Validating the proposal -^^^^^^^^^^^^^^^^^^^^^^^ - -The wallet will generate and display your proposal data in JSON format along with the proposal hash. -Review the information carefully to ensure accuracy. -Click **Validate** to check the format of the proposal data. If the data is valid, click **Next** to -proceed to the next step. Otherwise, click **Back** to adjust your proposal data. +The dialog displays the total amount requested. Check your proposal details carefully before +proceeding. **View JSON** and **View Payload** let you inspect the data that will be submitted to +the network. -.. figure:: img/core-qt/proposal-validate.png - :width: 400px - - Validating the proposal JSON and hash - -Preparing the proposal fee -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Then, click **Create Proposal**, unlock the wallet if prompted, and review the proposal confirmation +screen. .. warning:: - The following step will create a transaction burning 1 DASH as the proposal submission fee. This - transaction is irreversible once broadcast. Verify all proposal details are correct before - proceeding. - -After validation, you will see a screen prompting you to prepare and burn the 1 DASH proposal fee. -This fee is required to prevent spam and is permanently removed from circulation. Click **Prepare -proposal** to create the fee transaction. - -.. figure:: img/core-qt/proposal-prepare-burn.png - :width: 350px - - Proposal fee burn preparation screen - -Click **Yes** on the confirmation dialog to broadcast the fee transaction. + Creating the proposal permanently spends the 1 DASH proposal fee, plus a transaction fee. The + proposal fee cannot be refunded. Verify all proposal details before proceeding. -.. figure:: img/core-qt/proposal-burn-fee-notice.png +.. figure:: img/core-qt/proposal-create-conf.png :width: 300px - Confirmation dialog for burning the proposal fee - -The transaction ID will be generated and displayed in the TxID field. - -.. figure:: img/core-qt/proposal-prepare-burned.png - :width: 350px - - Transaction ID generated for the proposal fee - -Waiting for confirmations -^^^^^^^^^^^^^^^^^^^^^^^^^ + Proposal create confirmation screen -The wallet will display the confirmation progress for your fee transaction. One confirmation -is required before you can submit the proposal to the network. After the first confirmation, click -the **Next** button to move to the proposal submission screen. +Click **Send** on the confirmation dialog to broadcast the fee transaction. -.. figure:: img/core-qt/proposal-prepare-burned-conf-wait.png - :width: 350px - - Waiting for confirmations (1 of 6) - -Submitting the proposal -^^^^^^^^^^^^^^^^^^^^^^^ - -Click **Submit Proposal** to broadcast your governance object to the network. - -.. figure:: img/core-qt/proposal-submit-awaiting.png - :width: 350px - - Submitting proposal with 5 of 6 confirmations +.. figure:: img/core-qt/proposal-created.png + :width: 400px -If successful, a message will be displayed with your proposal ID. Click **OK** to close the message. + Proposal created -.. figure:: img/core-qt/proposal-submitted-conf.png - :width: 300px +After successful creation, the wallet opens a dialog to monitor and broadcast the proposal. You can +return to pending proposals later using **Resume Proposal** from the Governance tab. - Proposal successfully submitted to the network +Broadcasting the proposal +^^^^^^^^^^^^^^^^^^^^^^^^^ -The proposal ID will also be shown on the submission screen. The proposal ID can be used to track -voting on the proposal. +The proposal initially shows a **Pending** collateral status. After the fee transaction has one +confirmation, the status changes to **Ready** and the **Broadcast** button becomes available. Click +**Broadcast** to submit the proposal. A successful submission displays your proposal ID, which you +can use to track voting on the proposal. -.. figure:: img/core-qt/proposal-submitted.png - :width: 350px +.. figure:: img/core-qt/resume-proposal-broadcast.png + :width: 500px - Proposal submitted with proposal ID shown +The proposal becomes fully accepted by the network after the fee payment has six confirmations. .. note:: - You can submit your proposal ID to DashCentral to claim ownership and enable simplified voting - for masternodes using DashCentral voting services. + You can use the proposal ID to identify your proposal on DashCentral. Consult the service's + current instructions for claiming it. .. _dash-budget-proposal-generator: @@ -312,7 +249,7 @@ governance object. Running this command will cost you 1 DASH, which will be "burnt" or permanently removed from circulation. This one-time fee protects the governance system from becoming overwhelmed by spam, poorly thought out proposals or users not acting in good faith. A small -transaction fee is charged as well, so make sure slightly more than 5 +transaction fee is charged as well, so make sure slightly more than 1 DASH is available in your wallet. Many budget proposals request reimbursement of the 1 DASH fee. @@ -434,7 +371,9 @@ Submit the proposal ^^^^^^^^^^^^^^^^^^^ Once the transaction has six confirmations, use the ``gobject submit`` command -to submit the prepared governance object to the network for voting. See the +to submit the prepared governance object to the network for voting. Submission +after one confirmation is also possible, but the proposal remains postponed +until the fee transaction has six confirmations. See the :ref:`Core developer documentation ` for additional details. @@ -452,7 +391,7 @@ Example command:: gobject submit 0 1 1636000000 7b226e616d65223a22546573742d70726f706f73616c5f31222c227061796d656e745f61646472657373223a227964354b4d52457333474c4d65366d544a597233597248316a75774e777246436642222c227061796d656e745f616d6f756e74223a31302c2274797065223a312c2275726c223a22687474703a2f2f746573742e636f6d222c2273746172745f65706f6368223a313633353735303030302c22656e645f65706f6368223a313633363735303030307d 9192fb57953baba168f685e32378aa6471061301a097598c68ef1a4c136c9ea3 -The command will execute and respond with a transaction ID for the proposal +The command will respond with the governance object hash, which can be used to track voting on the proposal:: 3108b76c8735132a0b6de856b434a40d75924ba0a535c4a61be4dba0bf83263f @@ -460,20 +399,20 @@ which can be used to track voting on the proposal:: Voting on proposals =================== -**You must vote at least three days before the superblock is created or -your vote will not be counted. The exact deadline is 1662 blocks before -the superblock.** +**Vote at least 1662 blocks (approximately three days) before the +superblock. Masternodes begin choosing which proposals to pay at this +point, so later votes may not affect the upcoming payment.** Voting on DAO proposals is an important part of operating a masternode. Since masternodes are heavily invested in Dash, they are expected to critically appraise proposals each month and vote in a manner they perceive to be consistent with the best interests of the network. Each -masternode may vote once on each proposal, and the vote can be changed -at any time before the voting deadline. The following sites and tools +masternode can vote yes, no or abstain on each proposal. You can normally +change your vote on a proposal once per hour. A regular masternode's vote +counts as one vote, while an evonode's vote counts as four. The following sites and tools are available to view and manage proposals and voting: - `DashCentral `__ -- `Dash Ninja - Governance `__ - `Dash Masternode Tool - Proposals `__ For information on how to create a proposal, see :ref:`here @@ -482,17 +421,9 @@ For information on how to create a proposal, see :ref:`here DashCentral ----------- -Many masternode operators store their password-protected masternode -private key on `DashCentral `__ to enable -simple voting with a user-friendly interface. The popularity of this -site has made it a common place for discussion of the proposals after -they are submitted to the governance system. To vote from the -DashCentral web interface, first add your masternode private key to your -account according to the instructions here. Note that the masternode -private key is not the same as the private key controlling the 1000 DASH -collateral, so there is no risk of losing your collateral. A separate -password is required to unlock the masternode private key for voting, so -the risk of the site operator voting in your name is minimal. +`DashCentral `__ provides proposal discussion and voting services. +Follow the service's current instructions to configure voting. Use your masternode's voting key when +setting up voting services. Anyone with access to this key can vote on your behalf. When you are ready to vote, go to the `budget proposals page `_. Simply click to view the @@ -525,50 +456,37 @@ tab to **Vote Yes**, **Vote No** or **Vote Abstain** directly from DMT. Dash Core wallet or masternode ------------------------------ -If you started your masternode using the Dash Core Wallet (not -recommended), you can vote manually from **Window > Console**, or -directly from your masternode via SSH using ``dash-cli``. First click on -the proposal you want to vote on at either `DashCentral -`__ or `Dash Ninja -`__. You will see a command -for manual voting below the proposal description. Copy and paste the -command and modify it as necessary. As an example, take this proposal -from `Dash Ninja -`__ (or -`DashCentral -`__). -The voting code for Dash Core Wallet is as follows:: - - gobject vote-many 6ed7418455e07f4b30b99f0d4a24a2b83282e12b26fe3415673ecbea04ff6c9d funding yes - gobject vote-many 6ed7418455e07f4b30b99f0d4a24a2b83282e12b26fe3415673ecbea04ff6c9d funding no - gobject vote-many 6ed7418455e07f4b30b99f0d4a24a2b83282e12b26fe3415673ecbea04ff6c9d funding abstain - -Note that to vote from your masternode directly, you need to prefix the -command with ``dash-cli``, which is usually found in the ``.dashcore`` -folder. The command should be similar to the following:: - - ~/.dashcore/dash-cli gobject vote-many 6ed7418455e07f4b30b99f0d4a24a2b83282e12b26fe3415673ecbea04ff6c9d funding yes - ~/.dashcore/dash-cli gobject vote-many 6ed7418455e07f4b30b99f0d4a24a2b83282e12b26fe3415673ecbea04ff6c9d funding no - ~/.dashcore/dash-cli gobject vote-many 6ed7418455e07f4b30b99f0d4a24a2b83282e12b26fe3415673ecbea04ff6c9d funding abstain - -Note this command will trigger a vote from all masternodes configured in -``dash.conf``. If you have multiple masternodes each with its own .conf -file, or if you want to vote with only some of your masternodes, you -must change the command from ``vote-many`` to ``vote``. If your vote was -successful, you should see a confirmation message reading **Voted -successfully**. - -.. figure:: img/vote-dashcore.png - :width: 300px - - Voting from the debug console in Dash Core Wallet +To vote from the Dash Core wallet console or through ``dash-cli``, the wallet +must contain the private key for your masternode's registered voting address. +Unlock an encrypted wallet before voting. -You can also view a list of proposals in JSON format from the console to -copy and paste the proposal hash for voting as follows:: +Use ``gobject list`` to find proposals and their IDs (shown as hashes):: gobject list +To vote with every valid masternode whose voting key is present in the wallet, +use one of these commands, replacing ```` with the proposal's +actual proposal ID:: + + gobject vote-many funding yes + gobject vote-many funding no + gobject vote-many funding abstain + +To vote with one masternode, use ``vote-alias`` and supply its ProTx hash:: + + gobject vote-alias funding yes + +Replace ``yes`` with ``no`` or ``abstain`` as appropriate. The ProTx hash +identifies the masternode registration; it is not the proposal hash. + +For command-line use, prefix the command with ``dash-cli`` and run it against +the node with the wallet containing the voting key:: + + dash-cli gobject vote-alias funding yes + +Check the response to confirm that your votes succeeded and review any +error messages. + .. _delegating-votes: Delegating votes