Politeia is the Decred proposal system. Politeia is a system for storing off-chain data that is both versioned and timestamped, essentially “git, a popular revision control system, plus timestamping”. Instead of attempting to store all the data related to Decred’s governance on-chain, we have opted to create an off-chain store of data that is anchored into Decred’s blockchain, minimizing its on-chain footprint.
The politeia stack is as follows:
~~~~~~~~ Internet ~~~~~~~~~
|
+-------------------------+
| politeia www |
+-------------------------+
|
+-------------------------+
| politeiad |
+-------------------------+
| git backend |
+-------------------------+
|
~~~~~~~~ Internet ~~~~~~~~~
|
+-------------------------+
| dcrtimed |
+-------------------------+
- politeia - Reference client application.
- politeiad - Reference server daemon.
- politeia_verify - Reference verification tool.
- politeiawww - Web backend server.
- politeiawww_refclient - Web reference client application.
- politeiawww_dbutil - Politeiawww database tool for debugging and creating admin users.
Note that politeiawww does not provide HTML output. It strictly handles the JSON REST RPC commands only. The GUI for politeiawww can be found at: https://github.com/decred/politeiagui
-
politeiadandpoliteiawwwboth have configuration files that you should set up to make execution easier. -
You should create the configuration files under the following path:
- macOS
/Users/<username>/Library/Application Support/Politeiad/politeiad.conf - Windows
C:\Users\<username>\AppData\Local\Politeiad/politeiad.conf - Ubuntu
~/.politeiad/politeiad.conf
- macOS
-
Copy and change the
sample-politeiawww.confandsample-politeiad.conffiles. -
You may use the following default configurations:
politeiad.conf:
rpcuser=user
rpcpass=pass
testnet=true
politeiawww.conf:
rpchost=127.0.0.1
rpcuser=user
rpcpass=pass
rpccert="/Users/<username>/Library/Application Support/Politeiad/https.cert"
proxy=true
testnet=true
note 1: The rpccert path is referenced on macOS path. See above for more OS paths.
note 2: politeiawww uses an email server to send verification codes for
things like new user registration, and those settings are also configured within
politeiawww.conf. See below for more
information.
cd $GOPATH/src/github.com/decred/politeia
dep ensure && go install -v ./...
politeiad
politeia -v -testnet -rpchost 127.0.0.1 identity
Accept politeiad's identity by pressing enter.
Result should look something like this:
FQDN : localhost
Nick : politeiad
Key : dfd6caacf0bbe5725efc67e703e912c37931b4edbf17122947a1e0fcd9755f6d
Identity : 99e748e13d7ecf70ef6b5afa376d692cd7cb4dbb3d26fa83f417d29e44c6bb6c
Fingerprint: medI4T1+z3Dva1r6N21pLNfLTbs9JvqD9BfSnkTGu2w=
Save to /Users/<username>/Library/Application Support/Politeia/identity.json or ctrl-c to abort
Identity saved to: /Users/<username>/Library/Application Support/Politeia/identity.json
politeiawww
Awesome! From this point you have your politeia server up running!
- With politeiad and politeiawww running type on your terminal:
politeiawww_refclient
Result should look something like this:
=== Start ===
Request: GET /
Version: 1
Route : /v1
CSRF :
Request: GET /v1/policy
Request: POST /v1/user/new
Request: GET /v1/user/verify/?email=2e645574ba5dcf42@example.com&verificationtoken=41b27466ea295a9fd9e521d2aa2e8fc7837d48441fb6af8106abc4ecd929c94d&signature=546509014b4257b47186944f3ba47ed6e7077e3862cf635b0f4b9350ab3cf6c24ff8d341f65ecabc51b8dbeb8098deaa2c26d3faf4edbd6a6aa2aec47cd92b0a
Request: POST /v1/proposals/new
[...]
refclient run successful
=== End ===
- The generated email is what gives you access to the PoliteiaGUI application where your password will be the email's username. Example:
email: 2e645574ba5dcf42@example.com
password: 2e645574ba5dcf42
Note: Make sure you do not have an email server set up for politeiawww, because politeiawww_refclient will not execute correctly. So before you execute politeiawww_refclient, make sure to comment out or remove the following config options and restart politeiawww: mailhost, mailuser, mailpass, webserveraddress."
- This tool allows you to elevate a user in politeiawww to have admin permissions. You will have to shut down politeiawww, and then execute in your terminal:
politeiawww_dbutil -testnet -setadmin <email> <true/false>
-
This feature prevents users from submitting new proposals and comments until the paywall amount has been paid.
-
By default, it needs a transaction with 2 confirmations to accept the payment.
-
If running on testnet, it's possible to change the minimum blocks required for accept the payment by setting
minconfirmationsflag for politeiawww:politeiawww --minconfirmations=1
- When using politeiawww_refclient, the
-use-paywallflag is true by default. When running the refclient without the paywall, set-use-paywall=false, but note that it will not be possible to test new proposals and comments or theadminflag. - To test the admin flow:
- Run the refclient once with paywall enabled and make the payment.
- Stop politeiawww.
- Set the user created in the first refclient execution as admin with politeiawww_dbutil.
- Run refclient again with the
emailandpasswordflags set to the user created in the first refclient execution.
- https://faucet.decred.org - instance of testnetfaucet which is used by politeiawww_refclient to satisfy paywall requests in an automated fashion.
- https://test-proposals.decred.org/ - testing/development instance of politeiagui.
- git - the git command line tool must be installed on the machine that runs politeiad and be in the PATH. The version that was used to validate the daemon is 2.11.0.
- politeiad/api/v1 - JSON REST API for politeia clients.
- politeiad/cmd/politeia - Client reference implementation
- politeiawww/api/v1 - JSON API for WWW.
- politeiawww/cmd/politeiawww_refclient - Reference implementation for WWW API.
- util - common used miscellaneous utility functions.
The paywall functionality of politeia requires a master public key for an account to derive payment addresses. You may either use one of the pre-generated test keys (grep the source for tpub) or you may acquire one by creating accounts and retrieving the public keys for those accounts:
Put the result of the following command as paywallxpub=tpub... in politeiawww.conf.
dcrctl --wallet --testnet createnewaccount politeiapayments
dcrctl --wallet --testnet getmasterpubkey politeiapayments
- Send proposal:
politeia -v -testnet -rpchost 127.0.0.1 new "My awesome proposal" proposal.txt spec.txt
Result will look something like:
00: 331ea9090db0c9f6f597bd9840fd5b171830f6e0b3ba1cb24dfa91f0c95aedc1 proposal.txt text/plain; charset=utf-8
01: be0997732fa648fd083baa85e782d9e4768602dbe8a0a431ba17a01000ba93db spec.txt text/plain; charset=utf-8
Submitted proposal name: My awesome proposal
Censorship record:
Merkle : 8e125a9c791634f6f68672c7bc3b71dc50f986a0525e3e7361ad180cadbf6347
Token : 6284c5f8fba5665373b8e6651ebc8747b289fed242d2f880f64a284496bb4ca8
Signature: 82d69b4ec83d2a732fe92028dbf78853d0814aeb4fcf0ff597c110c8843720951f7b9fae4305b0f1d9346c39bc960a364590236f9e0871f6f79860fc57d4c70a
- Publishing a proposal (requires credentials):
politeia -testnet -rpchost 127.0.0.1 -rpcuser user -rpcpass pass setunvettedstatus publish 6284c5f8fba5665373b8e6651ebc8747b289fed242d2f880f64a284496bb4ca8
Set proposal status:
Status : public
- Censoring a proposal (requires credentials):
politeia -testnet -rpchost 127.0.0.1 -rpcuser user -rpcpass pass setunvettedstatus censor 527cb21b78a56d597f5ab4c199195343ecfcd56cf0d76910b2a63c97635a6532
Set proposal status:
Status : censored
To independently verify that Politeia has received your proposal, you can use
the politeia_verify tool and provide politeiad's public key, the proposal's
censorship token and signature, and the proposal files:
politeia_verify -v -k dfd6caacf0bbe5725efc67e703e912c37931b4edbf17122947a1e0fcd9755f6d -t 6284c5f8fba5665373b8e6651ebc8747b289fed242d2f880f64a284496bb4ca8 -s 82d69b4ec83d2a732fe92028dbf78853d0814aeb4fcf0ff597c110c8843720951f7b9fae4305b0f1d9346c39bc960a364590236f9e0871f6f79860fc57d4c70 proposal.md
Proposal successfully verified.
If the proposal fails to verify, it will return an error:
politeia_verify -v -k xfd6caacf0bbe5725efc67e703e912c37931b4edbf17122947a1e0fcd9755f6d -t 6284c5f8fba5665373b8e6651ebc8747b289fed242d2f880f64a284496bb4ca8 -s 82d69b4ec83d2a732fe92028dbf78853d0814aeb4fcf0ff597c110c8843720951f7b9fae4305b0f1d9346c39bc960a364590236f9e0871f6f79860fc57d4c70 proposal.md
Proposal failed verification. Please ensure the public key and merkle are correct.
Merkle: 0dd10219cd79342198085cbe6f737bd54efe119b24c84cbc053023ed6b7da4c8
Note: All politeia commands can dump the JSON output of every RPC command by adding the -json command line flag.
# politeiawww
location /api/ {
# disable caching
expires off;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_bypass_cache $http_upgrade;
proxy_http_version 1.1;
proxy_ssl_trusted_certificated /path/to/politeiawww.crt;
proxy_ssl_verify on;
proxy_pass https://test-politeia.domain.com:4443/;
}
# politeiagui
location / {
# redirect not found
error_page 404 =200 /;
proxy_intercept_errors on;
# disable caching
expires off;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_http_version 1.1;
# backend
proxy_pass http://127.0.0.1:8000;
}
The current code should work with most SSL-based SMTP servers (but not TLS) using username and password as authentication.