diff --git a/docs/getting-started/beginner-guide.md b/docs/getting-started/beginner-guide.md index 7fbb22968..d8a2494c4 100644 --- a/docs/getting-started/beginner-guide.md +++ b/docs/getting-started/beginner-guide.md @@ -20,7 +20,7 @@ The following guides go into depth on key aspects of the Decred experience: * [Using the Block Explorer](using-the-block-explorer.md) * [Governance](../governance/introduction-to-decred-governance.md) * [Ticket buying guide](../mining/proof-of-stake.md) -* [Politeia](../governance/politeia.md) +* [Politeia](../governance/politeia/politeia.md) * [Voting on consensus rules changes](../governance/consensus-rules-voting.md) * [Using Testnet](../advanced/using-testnet.md) diff --git a/docs/governance/politeia.md b/docs/governance/politeia.md deleted file mode 100644 index aa609ba0c..000000000 --- a/docs/governance/politeia.md +++ /dev/null @@ -1,55 +0,0 @@ -# Politeia Proposals and Voting - ---- - -**What is Politeia?** - -Politeia, or Pi, is a platform which is being developed to support Decred’s governance. It facilitates the submission, tracking, and discussion of Decred governance proposals by the stakeholder community. - -The Politeia web platform (at [proposals.decred.org](https://proposals.decred.org/)) facilitates browsing, discussing and submitting proposals. - -**Politeia proposals** - -There are two broad types of proposal: - -1. Proposals that aim to establish Voter support for a course of action, e.g. direction of software development, adopting or changing some policy. -2. Proposals that commit to spending DCR from the Decred Treasury, creating a budget that some entity can draw down against as they demonstrate progress towards the proposal's aim. - -There is a fee for submitting a proposal (0.1 DCR), to limit the potential for proposal spamming. There is also a fee for registering a Politeia account (0.1 DCR), to limit comment spam and up/down voting sock-puppetry. Fees may be altered if a) they're not a sufficient spam-deterrent, or b) the price of DCR changes considerably. - -Reddit-style **up/down voting** is used for comment sorting only. Up/down votes are not anonymous. - -Ticket-voting on proposals doesn’t happen directly on Politeia, but within [Decrediton](../getting-started/user-guides/decrediton-setup.md) or [politeiavoter CLI](https://github.com/decred/politeia/tree/master/politeiavoter) with dcrwallet - -**Censorship** - -When proposals are submitted, they are checked by Politeia administrators. Proposals that are deemed spam or invalid will be censored. - -Politeia is built around the concept of _transparent censorship_, using [dcrtime](https://github.com/decred/dcrtime). Users cannot be silently censored, they can prove that censorship has occurred. When a proposal/comment is submitted, a censorship token is generated. Content creators can use these tokens to demonstrate that their specific proposal/comment was submitted, in a particular form, at a particular point in time. - -**Politeia users have cryptographic identities** (pub/priv key pairs) that can be used to demonstrate censorship of one's submissions. When you register for a Politeia account, a key-pair identity will be generated for you, this is stored in your browser by default. - -If you change browser/device you can import your Pi identity key or generate a new one, but for now it is important to *verify your account from the same browser you used to sign up*. The cryptographic Pi identity is only used for demonstrating that your submissions have been censored. - -**Submitting and approving proposals** - -Politeia's aim is to serve as the decision-making force behind the Decred Decentralized Autonomous Entity (DAE). This is an ambitious aim, Politeia and its accompanying processes are in an experimental stage and thus subject to change. - -For now, the process is something like this: - -1. Submit proposal. -2. Proposal reviewed by Politeia admins, spam is censored. -3. Valid proposals appear publicly on Politeia, open for discussion, but voting does not begin immediately. -4. Ticket-voting interval (~1 week) can be triggered by the proposal owner. Until ticket-voting is triggered, the proposal can be edited by its owner in response to community feedback. -5. Ticket-voting starts, ticket-holders vote through their wallet. Every ticket that was live 256 blocks before voting started is eligible to vote on the proposal. Votes by eligible tickets can be cast any time within the voting interval. Once votes are cast they cannot be changed. -6. When the ticket-voting period ends, the proposal is formally approved or rejected. There is a quorum requirement of 20% tickets voting Yes/No. For a proposal to pass it must achieve 60% Yes votes. -7. When a proposal with a budget and deliverables is approved, work can begin. The proposal owner can submit claims against that budget as deliverables are completed. -8. Payment claims will be handled manually by Decred Holdings Group until such times as this process can be adequately decentralized. - -Proposal voting works, initially, as a robust signalling mechanism from the Decred stakeholders to the people who control the Decred Treasury wallet. Over time, this will be iterated towards a DAE that decentralizes the functions currently performed by trusted humans. When the DAE is ready, it will control the Decred Treasury wallet directly. - -For proposals that request funding, an initial set of guidelines and examples has been prepared. It can be found at the bottom of [this page](https://github.com/decred/politeia/blob/master/politeia.md). Guidelines for good proposals and policies for censoring proposals will be iterated once Politeia is live. - -**Politeia Data** - -[This page](../advanced/navigating-politeia-data.md) offers a guide to navigating Politeia data in the repository where it is stored. \ No newline at end of file diff --git a/docs/governance/politeia/example-proposals.md b/docs/governance/politeia/example-proposals.md new file mode 100644 index 000000000..01e5c87e5 --- /dev/null +++ b/docs/governance/politeia/example-proposals.md @@ -0,0 +1,156 @@ +# Example Politeia Proposals + +--- + +Below are two example Politeia proposals that utilize the template provided in the +Politeia [Proposal Guidelines](proposal-guidelines.md). The first example proposes the +development of a new software feature. The second a marketing initiative. + +- [Software Feature Proposal](#software-feature-proposal) +- [Marketing Proposal](#marketing-proposal) + +## Software Feature Proposal + +### What + +In the *What* section, provide a short description of the problem that will +be addressed. + + Add monitoring RPC call that can be used for status reporting and as a + heartbeat to ensure that politeiawww is functioning properly. + +### Why + +In the *Why* section, answer why the proposal is needed and why it is +a good idea. + + Currently there is no prescribed way to remotely determine if politeiawww is + functioning correctly. We propose to add a single RPC that doubles as the + heartbeat and a status monitor. The idea is that monitoring software can + periodically issue the RPC and determine if an alert needs to be sent out to + the admins. + +### How + +In the *How* section, describe the steps you will perform to accomplish your +goals. + + 1. Design and document RPC. + 2. Add a priviledged RPC called Status that replies with StatusReply. + * The Status RPC is an empty structure + * The StatusReply structure returns a tri-state status: OK, Warning, + Critical. In addition to the status the RPC returns a server message + that can be forwarded to the administrators in case of Warning or + Failure. + * The StatusReply returns interesting statistics such as: number of + proposals in memory, number of comments in memory etc. + 3. Add refclient unit tests that validate all 3 conditions. + 4. Add RPC to politeiawwwcli so that the status calls can be scripted. + +### Who + +In the *Who* section, describe the entity making the proposal, who will +complete the work, and who will draw down on the proposal's budget. + + This proposal is submitted by @allstake (on Slack, /u/Satoshi2000 on reddit). You + may remember me from a discussion in #dcrdata, where I solicited feedback + on this idea (Matrix link). I have been active in the blockchain space for two + years, with a particular interest and passion for blockchain governance. See my + GitHub (github.com/satoshi200) for examples of my work, including an event-driven + lambo address creation module. + +### When + +In the *When* section, describe the project's milestones, expected +completion dates, and the draw schedule (how much DCR is paid for each milestone delivered). + + We proposing doing the design and documentation first and + finish the work with the implementation of the code. + We allow for some time between the deliverables in order to leave space for a + vote by the stakeholders to see if the first step makes sense. Note that this + is a small example and therefore the timelines are a bit longish. The milestone + votes should be less than a week. + + 1. 2 hours to design and add documentation on how to use the call with some + examples. + 2. 8 hours to add the call, determine what status to set when and figure out + what statistics to return. + 3. 4 hours to add refclient validation tests. + 4. 2 hours to add RPC to politeiawwwcli + In addition allow for 1 hour of overhead (going back and forth on slack/github + etc). This will bring the grand total to 17 hours at a rate of $40/hr. This + proposal will therefore be capped at $680. + The proposed schedule is to do this work over 2 weeks in order to allow back + and forth on the details. + Week 1 deliverables + 1. Design RPC + 2. Write documentation that includes examples + 2 hours, to be completed on August 15 2018 + Week 2 deliverables + 1. Implement RPC + 2. Implement validation tests + 3. Implement politeiawwwcli + 15 hours, to be completed on August 29 2018 + + +## Marketing Proposal + +### What + +In the *What* section, provide a short description of the problem that will +be addressed. + + This proposal would fund a Decred presence at Real Blockchain Conference, + in Dublin, Ireland, July 11-13. It would cover costs for a booth, swag, and + people to staff the booth. + +### Why + +In the *Why* section, answer why the proposal is needed and why it is +a good idea. + + Real Blockchain Conference is a top cryptocurrency conference and totally not made up. + Last year's conference had 5,000 attendees and they seemed cool, good solid Decred + stakeholder material. With epic swag and a physical embodiment of Stakey in attendance, + a presence at this conference would raise awareness of Decred. + +### How + +In the *How* section, describe the steps you will perform to accomplish your +goals. + + I will organize Decred's presence at this event, it will take about 20 hours of my time at 40$/hour. $800 + Conference registration/booth fees: $3,000 + Booth decorations: $1,000 + Decred swag to give away: $2,000 + 3 staff on the booth for 3 (10 hour) days each at $30/hr: (3 x 3 x 10 x 30) $2,700 + Stakey costume: $500 + Stakey costume occupant: 3 (10 hour) days at $40/hr (that suit is warm!): $1,200 + Travel expenses for booth staff: Up to $2,000 + Accommodation for booth staff. We will stay at the conference hotel costing $200/night, it is unlikely + that all booth staff need accommodation, but the maximum would be 200 x 3 nights x 4 staff = $2,400 + Maximum total budget: $15,600 + +### Who + +In the *Who* section, describe the entity making the proposal, who will +complete the work, and who will draw down on the proposal's budget. + + This proposal is submitted by @AllYourStake (on Slack, /u/StakeGovernor2000 on reddit). You may + remember me as the organizer of Decred's presence at such blockchain events as Real Blockchain + Conference 2017 and Buckets of Blockchain 2018. + I don't know exactly who the 3 booth staff and 1 Stakey suit wearer will be, I will be one of the + staff and @Contributor1 is also interested. + +### When + +In the *When* section, describe the project's milestones, expected +completion dates, and the draw schedule (how much DCR is paid for each milestone delivered). + + Registration fees are due by September 30th, I will pay these up-front and request full reimbursement + immediately. I will front the cost of the swag and Stakey suit, and claim this along with my + travel/accommodation expenses and payment for my work, after the event. + Booth staff who are already Decred contributors will bill for their hours and expenses directly, + I will serve as intermediary for any staff costs not associated with established contributors. + + diff --git a/docs/governance/politeia/politeia.md b/docs/governance/politeia/politeia.md new file mode 100644 index 000000000..1c53f11da --- /dev/null +++ b/docs/governance/politeia/politeia.md @@ -0,0 +1,56 @@ +# Politeia Proposals and Voting + +--- + +## What is Politeia? + +Politeia is a platform that supports Decred’s governance. It facilitates the submission, tracking, and discussion of Decred governance proposals by the stakeholder community. The Politeia [web platform](https://proposals.decred.org/) facilitates browsing, discussing and submitting proposals. + +Reddit-style **up/down voting** is used for comment sorting. Up/down votes are not anonymous. + +Voting on proposals does not happen directly on Politeia, as it requires signatures from your Decred wallet. Voting can be done from [Decrediton](../../getting-started/user-guides/decrediton-setup.md) or on the command line using the [politeiavoter CLI](https://github.com/decred/politeia/tree/master/politeiavoter) tool. + +There are two broad types of proposal: + +1. Proposals that aim to establish voter support for a course of action. For example, the direction of software development, or adopting or changing some policy. +2. Proposals that commit to spending DCR from the Decred Treasury. These proposals create a budget that some entity can draw down against as they demonstrate progress towards the proposal's aim. + +## How Politeia Works + +To vote, stakeholders must time-lock DCR to buy tickets. While tickets are live they can be used to cast a vote for or against each open Politeia proposal. For more information on tickets and their role in Decred's governance, see the [Introduction to Decred Governance](../../governance/introduction-to-decred-governance.md) page. + +There is a fee for submitting a proposal (0.1 DCR) to limit the potential for proposal spamming. There is also a fee for registering a Politeia account (0.1 DCR) to limit comment spam and up/down voting sock-puppetry. Fees may be altered if a) they aren't serving as a sufficient spam-deterrent, or b) the price of DCR changes considerably. + +### Transparent Censorship + +When proposals are submitted, they are checked by Politeia administrators. Proposals that are deemed spam or invalid will be censored. + +Politeia is built around the concept of **transparent censorship**, using [dcrtime](https://github.com/decred/dcrtime). Users cannot be silently censored; they can prove that censorship has occurred. When a user registers, a **cryptographic identity** (pub/priv key pair) is created. This cryptographic identity is then used to create a "censorship token" for each user submission (proposal, comment, comment upvote/downvote). If a user is censored, these tokens can be used to prove that a specific submission was submitted, the time it was submitted, and the exact form of the submission. This cryptographic identity is stored in the user's browser by default, but can be exported and re-imported at any time. + + +### Proposal Lifecycle + +Below is the basic process for submitting and evaluating proposals: + +1. A proposal is submitted. +2. The proposal is reviewed by Politeia admins. Spam is censored. +3. Valid proposals appear publicly on Politeia. They are open for discussion, but voting does not begin immediately, and the proposal can be edited by its owner in response to community feedback. +4. The proposal owner authorizes voting to start. An admin then triggers the start of voting. +5. The ticket-voting interval of 2016 blocks (~1 week) begins. A snapshot of the live ticket pool is taken at 256 blocks prior to the start of voting. Every ticket in the pool when this snapshot was taken can vote 'Yes' or 'No' on the proposal. Tickets bought after the snapshot cannot vote on the proposal. If a ticket is called to vote on-chain during the ticket-voting interval (to validate blocks or vote on consensus rule changes), it still has until the end of the ticket-voting interval to vote on the proposal. +6. When the ticket-voting period ends, the proposal is formally approved or rejected. There is a quorum requirement for a vote to be considered valid: 20% of the eligible tickets must vote 'Yes' or 'No'. The threshold for a proposal to be approved is 60% 'Yes' votes. +7. When a proposal with a budget and deliverables is approved, work can begin. The proposal owner can submit claims against the budget as deliverables are completed. +8. Payment claims will be handled manually by Decred Holdings Group (DHG) until such times as this process can be handled by the [Decred Decentralized Autonomous Entity (DAE)](#decentralized-autonomous-entity-dae). + +For guidance on creating a good proposal, see the [Proposal Guidelines](../../governance/politeia/proposal-guidelines.md) and [Example Proposals](../../governance/politeia/example-proposals.md) pages. + +### Decentralized Autonomous Entity (DAE) + +Politeia's aim is to serve as the decision-making force behind the Decred Decentralized Autonomous Entity (DAE). Because Politeia and its accompanying processes are still in an experimental stage, Politeia will serve initially as a robust signaling mechanism from Decred shareholders to the community members controlling the Decred Treasury wallet. Over time, this will be iterated towards a DAE that decentralizes the functions currently performed by trusted humans, and the DAE will control the project fund wallet directly. + +## Politeia Data + +All proposals, comments, and votes are anchored on the Decred blockchain using [dcrtime](https://github.com/decred/dcrtime) and stored in a public [git repository](https://github.com/decred-proposals/mainnet). See the [Navigating Politeia Data](../../advanced/navigating-politeia-data.md) page for instructions on accessing and interpreting Politeia data. + + + + diff --git a/docs/governance/politeia/proposal-guidelines.md b/docs/governance/politeia/proposal-guidelines.md new file mode 100644 index 000000000..385b9502c --- /dev/null +++ b/docs/governance/politeia/proposal-guidelines.md @@ -0,0 +1,76 @@ +# Proposal Guidelines + +--- + +The page provides a basic [proposal template](#proposal-template) and +[tips for creating a successful proposal](#tips-for-creating-a-successful-proposal). +See the [Example Proposals](../../governance/politeia/example-proposals.md) page for +example proposals that use this template. + + +## Proposal Template + +All proposals should answer the following questions: + +### What + +In the *What* section, provide a short description of the problem that will +be addressed. + +### Why + +In the *Why* section, answer why the proposal is needed and why it is +a good idea. + +### How + +In the *How* section, describe the steps you will perform to accomplish your +goals. + +### Who + +In the *Who* section, describe the entity that will +complete the work and draw down on the proposal's budget. + +### When + +In the *When* section, describe the project's milestones, expected +completion dates, and the draw schedule (how much DCR is paid for each milestone achieved). + +## Tips for Creating a Successful Proposal + +Following the below tips will greatly increase your proposal's chance of success. + +#### Engage the community + +Engaging with the [community](../../getting-started/beginner-guide.md#community) first, +before submitting a proposal, will allow you to gauge interest in your idea, gather +feedback, and better understand your proposal's chance of success before investing time +in a proposal. + +#### Demonstrate clearly how your proposal will benefit Decred + +Do not submit personal ventures, business ideas +or experimentation, unless it clearly benefits the project. +Explain how your proposal will directly further the project's aims, and provide +clear deliverables and milestones. + +#### Check the hype + +Many Decred stakeholders are highly technical veterans in the +blockchain space. Over-hyped, buzzword-filled proposals without substance will likely be +ignored. Be precise in your use of technical terms, realistic in your projections, +and bring your A game in the comments. + +#### Build Credibility + +The bigger the proposal, the more you will need to convince stakeholders you +are capable of doing what you propose. If you are unknown to the community, showcase past +contributions to other projects (bonus points for verifiable open-source contributions). +If your plan requires working with current Decred contractors, +be sure to communicate with them beforehand and secure their support. If you're looking to +build credibility within the community before submitting a proposal (a good strategy), +you will find the Decred project very welcoming to contributors of all levels. Start small, +deliver, and your chances of submitting a successful proposal will increase along with your +credibility. + diff --git a/docs/index.md b/docs/index.md index d53e3d6cc..da37cf5d3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,7 +22,7 @@ Subsidy | Party [Proof of Stake](mining/proof-of-stake.md) voting is central to Decred's governance. Decred holders can time-lock (or "stake") DCR to obtain voting tickets. Tickets are randomly called to vote on-chain; this involves both approving the work of PoW miners and voting Yes/No on any open [rule change proposals](governance/consensus-rules-voting.md). 30% of the block reward goes to the holders of the tickets that voted in that block. -The remaining 10% of the block reward goes into the [Decred Treasury](https://explorer.dcrdata.org/address/Dcur2mcGjmENx4DhNqDctW5wJCVyT3Qeqkx). Holders of live tickets decide how that treasury is used through [Politeia proposals and voting](governance/politeia.md). +The remaining 10% of the block reward goes into the [Decred Treasury](https://explorer.dcrdata.org/address/Dcur2mcGjmENx4DhNqDctW5wJCVyT3Qeqkx). Holders of live tickets decide how that treasury is used through [Politeia proposals and voting](governance/politeia/politeia.md). The [Decred Constitution](governance/decred-constitution.md) sets out some guiding principles for the project; the constitution is subject to amendment through Politeia proposals. diff --git a/docs/mining/proof-of-stake.md b/docs/mining/proof-of-stake.md index 6b675ca5f..7f2e98d93 100644 --- a/docs/mining/proof-of-stake.md +++ b/docs/mining/proof-of-stake.md @@ -13,7 +13,7 @@ PoS voting serves a number of purposes: 1. Providing a mechanism for stakeholders to influence Proof-of-Work (PoW) miners. Stakeholders can vote to withhold a miner's reward even if the block conforms to the consensus rules of the network. This allows stakeholders, in principle, to discourage problematic mining behavior such as mining empty blocks. 1. For a block to be valid, it has to be signed by at least 3 of the 5 tickets that are called to vote in that block. This makes the Decred blockchain more robust to certain kinds of attack, such as those which rely on secret mining. 1. The same principle makes the Decred blockchain resistant to contentious hard forks. PoW Miners are unable to build on a chain without the Votes of the tickets that are called. -1. Snap voting of live tickets is used to make decisions about the project treasury through [Politeia](../governance/politeia.md). +1. Snap voting of live tickets is used to make decisions about the project treasury through [Politeia](../governance/politeia/politeia.md). These roles are incentivized; ticket-holders (or "Proof-of-Stake (PoS) Voters") collectively receive 30% of the block reward when their tickets are called to vote. diff --git a/httpd.conf b/httpd.conf index 729f02fe1..e5d6058a7 100644 --- a/httpd.conf +++ b/httpd.conf @@ -565,5 +565,6 @@ Redirect /getting-started/using-testnet /advanced/using Redirect /advanced/contributing /contributing/source-code-contributions Redirect /advanced/using-github /contributing/using-github Redirect /advanced/contributor-compensation /contributing/contributor-compensation +Redirect /governance/politeia /governance/politeia/politeia ErrorDocument 404 /404.html diff --git a/mkdocs.yml b/mkdocs.yml index 0cc590943..1beb256d0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,10 +45,13 @@ nav: - 'Obtaining DCR': 'getting-started/obtaining-dcr.md' - 'Using the Block Explorer': 'getting-started/using-the-block-explorer.md' - Governance: + - Politeia: + - 'Politeia': 'governance/politeia/politeia.md' + - 'Proposal Guidelines': 'governance/politeia/proposal-guidelines.md' + - 'Example Proposals': 'governance/politeia/example-proposals.md' - 'Introduction to Decred governance': 'governance/introduction-to-decred-governance.md' - 'Consensus Rules Voting': 'governance/consensus-rules-voting.md' - 'How to Vote on Consensus Rule Changes': 'governance/how-to-vote.md' - - 'Politeia Proposals and Voting': 'governance/politeia.md' - 'Decred Constitution': 'governance/decred-constitution.md' - Wallets: - Decrediton (GUI):