github.com/decred/politeia@v1.4.0/docs/politeia.md (about)

     1  ## Politeia (Pi) introduction
     2  
     3  Politeia, or Pi, is the Decred proposal system. It is intended to facilitate
     4  the submission, discussion and approval/rejection of governance proposals. 
     5  
     6  There are two broad types of proposal:
     7  1. Proposals that aim to establish stake-voter support for a course of action,
     8     e.g. direction of software development, adopting or changing some policy.
     9  2. Proposals that commit to spending project fund DCR, creating a budget that
    10     some entity can draw down against as they demonstrate progress towards the
    11     proposal's aim.
    12  
    13  There is a fee for submitting a proposal (0.1 DCR), to limit the potential for proposal spamming.
    14  
    15  When proposals are submitted, they are checked by Politeia administrators.
    16  Proposals that are deemed spam or invalid will be censored.
    17  
    18  When proposals are submitted, a censorship token is generated, which the
    19  proposal's owner can use, in the case that their proposal was censored, to
    20  demonstrate that it was submitted but censored.
    21  
    22  Valid proposals will be displayed on the Politeia platform, where they can be
    23  seen by all and discussed by Politeia members.
    24  
    25  There is a registration fee (0.1 DCR) for creating a Politeia account. Only
    26  members who have paid this fee are eligible to submit proposals and comments,
    27  and to make up/down votes on the Politeia web platform. 
    28  
    29  Up/down votes do not affect proposal funding decisions, they are used as soft
    30  signals and to determine display order. Up/down voting is not anonymous, the
    31  up/down voting history of Politeia accounts will be public information.
    32  
    33  When a proposal is submitted and passes screening, it will be displayed on
    34  Politeia but voting will not open immediately. The proposer has discretion to
    35  participate in discussion with Decred stakeholders and make edits to their
    36  proposal, then decide when to trigger the ticket-voting interval. When voting
    37  is triggered, edits to the proposal can no longer be made.
    38  
    39  Ticket-voting is used to determine whether proposals are approved by Decred's
    40  stake-governors. Ticket-voting is to be performed  from a Decred wallet with
    41  live tickets, it does not happen directly through the Politeia web platform.
    42  
    43  Politeia's aim is to serve as the decision-making force behind the Decred
    44  Decentralized Autonomous Entity (DAE). This is an ambitious aim, Politeia and
    45  its accompanying processes are in an experimental stage and thus subject to
    46  change.
    47  
    48  Initially at least, the disbursal of funds to successful proposals will be a
    49  manual process. Proposals that request funding should specify how much funding
    50  they require, denominated in a national currency like $USD. They should also
    51  specify a set of milestones or deliverables which will trigger the release of
    52  funds.
    53  
    54  When a proposal is approved by ticket-voters, this gives a green light to the
    55  proposing entity to begin work. When the first milestone is met, they can make
    56  a request for the release of the first tranche of funding. This will be
    57  reviewed and, where satisfactory, will be processed. It is expected that,
    58  initially at least, all proposals requesting funding are paid in arrears.
    59  
    60  An example is that stakeholders expect developers to write and show code before
    61  payment occurs. The existing contractors use this model. For example, Company 0
    62  carries the costs (and risk) for 4-6 weeks before payout occurs. This is a
    63  feature and not a bug.  Asking for a large sum of money without incurring costs
    64  shifts the risk to the DAE and that incentivizes malicious behavior.
    65  
    66  ## How to submit a Politeia (Pi) proposal
    67  
    68  When authoring a request using Pi one must answer the following 5 questions:
    69  1.  What
    70  2.  Why
    71  3.  How
    72  4.  Who
    73  5.  When
    74  
    75  In the following paragraphs we are going to explore some examples. We'll use a
    76  software feature as the example.
    77  
    78  ### What
    79  
    80  In the *What* section we try to answer what we are proposing. This should be a
    81  short description of the problem that will be addressed.
    82  
    83  ```
    84  Add monitoring RPC call that can be used for status reporting and as a
    85  heartbeat to ensure that politeiawww is functioning properly.
    86  ```
    87  
    88  ### Why
    89  
    90  In the *Why* section we try to answer why the proposal is needed and why it is
    91  a good idea.
    92  
    93  ```
    94  Currently there is no prescribed way to remotely determine if politeiawww is
    95  functioning correctly. We propose to add a single RPC that doubles as the
    96  heartbeat and a status monitor. The idea is that monitoring software can
    97  periodically issue the RPC and determine if an alert needs to be sent out to
    98  the admins.
    99  ```
   100  
   101  ### How
   102  
   103  ```
   104  1. Design and document RPC.
   105  2. Add a priviledged RPC called Status that replies with StatusReply.
   106  	* The Status RPC is an empty structure
   107  	* The StatusReply structure returns a tri-state status: OK, Warning,
   108  	  Critical. In addition to the status the RPC returns a server message
   109  	  that can be forwarded to the administrators in case of Warning or
   110  	  Failure.
   111  	* The StatusReply returns interesting statistics such as: number of
   112  	  proposals in memory, number of comments in memory etc.
   113  3. Add refclient unit tests that validate all 3 conditions.
   114  4. Add RPC to piwww so that the status calls can be scripted.
   115  ```
   116  
   117  ### Who
   118  
   119  In the *Who* section, describe the entity that is making the proposal, will
   120  complete the work, and will draw down on the proposal's budget. 
   121  
   122  ### When
   123  
   124  In the *When* section we try to answer what will be delivered when and when the
   125  stakeholders get to vote on the milestones.
   126  
   127  Create some sort of draw schedule that explains what milestones will be
   128  delivered when. In this example we do the design and documentation first and
   129  finish the work with the implementation of the code.
   130  
   131  We allow for some time between the deliverables in order to leave space for a
   132  vote by the stakeholders to see if the first step makes sense. Note that this
   133  is a small example and therefore the timelines are a bit longish. The milestone
   134  votes should be less than a week.
   135  
   136  ```
   137  1. 2 hours to design and add documentation on how to use the call with some
   138     examples.
   139  2. 8 hours to add the call, determine what status to set when and figure out
   140     what statistics to return.
   141  3. 4 hours to add refclient validation tests.
   142  4. 2 hours to add RPC to piwww
   143  
   144  In addition allow for 1 hour of overhead (going back and forth on slack/github
   145  etc). This will bring the grand total to 17 hours at a rate of $40/h. This
   146  proposal will therefore be capped at $680.
   147  
   148  The proposed schedule is to do this work over 2 weeks in order to allow back
   149  and forth on the details.
   150  
   151  Week 1 deliverables
   152  1. Design RPC 
   153  2. Write documentation that includes examples
   154  
   155  2 hours, to be completed on August 15 2018
   156  
   157  Week 2 deliverables
   158  1. Implement RPC
   159  2. Implement validation tests
   160  3. Implement piwww
   161  
   162  15 hours, to be completed on August 29 2018
   163  ```
   164  
   165  ## Marketing Example
   166  
   167  ###  What
   168  
   169  ```
   170  This proposal would fund a Decred presence at Real Blockchain Conference 2018,
   171  in Dublin, Ireland, November 11-13. It would cover costs for a booth, swag, and
   172  people to staff the booth.
   173  ```
   174  
   175  ### Why
   176  
   177  ```
   178  Real Blockchain Conference is a top cryptocurrency conference and totally not
   179  made up. Last year's conference had 5,000 attendees and they seemed cool, good
   180  solid Decred stakeholder material. With epic swag and a physical embodiment of
   181  Stakey in attendance, a presence at this conference would raise awareness of
   182  Decred.
   183  ```
   184  
   185  ### How (much)
   186  
   187  ```
   188  I will organize Decred's presence at this event, it will take about 20 hours of
   189  my time at 40$/hour: $800
   190  Conference registration/booth fees: $3,000
   191  Booth decorations: $1,000
   192  Decred swag to give away: $2,000
   193  3 booth staff for 3 (10 hour) days each at $30/hr: (3 x 3 x 10 x 30) $2,700
   194  Stakey costume: $500
   195  Stakey costume occupant: 3 (10 hour) days at $40/hr (that suit is hot!): $1,200
   196  Travel expenses for booth staff: Up to $2,000
   197  Accommodation for booth staff. We will stay at the conference hotel costing
   198  $200/night, it is unlikely that all booth staff need accommodation, but the
   199  maximum would be 200 x 3 nights x 4 staff: $2,400
   200  
   201  Maximum total budget: $15,600
   202  ```
   203  
   204  ### Who
   205  
   206  ```
   207  This proposal is submitted by @AllYourStake (on Slack, /u/StakeGovernor2000 on
   208  reddit). You may remember me as the organizer of Decred's presence at such
   209  blockchain events as Real Blockchain Conference 2017 and Buckets of Blockchain
   210  2018.
   211  
   212  I don't know exactly who the 3 booth staff and 1 Stakey suit wearer will be, I
   213  will be one of the staff and @Contributor1 is also interested.
   214  ```
   215  
   216  ### When
   217  
   218  ```
   219  Registration fees are due by September 30th, I will pay these up-front and
   220  request full reimbursement immediately.
   221  
   222  I will front the cost of the swag and Stakey suit, and claim this along with my
   223  travel/accommodation expenses and payment for my work, after the event.
   224  
   225  Booth staff who are already Decred contributors will bill for their hours and
   226  expenses directly, I will serve as intermediary for any staff costs not
   227  associated with established contributors.  ```