Skip to content

Navigating Politeia Data


Data from the proposals.decred.org site is stored in the decred-proposals/mainnet repo. This page provides a guide on how to navigate this repo and interpret the contents of its files.

For the purpose of this guide we’ll be using this previous proposal as an example. To see data associated with this proposal, click the on the See on GitHub link on the proposal’s page. You can also look up a proposal directly in the decred-proposals/mainnet repo using the proposal’s unique hash number. For our example proposal, the hash is: c68bb790ba0843980bb9695de4628995e75e0d1f36c992951db49eca7b3b4bcd

Below is a screenshot of the root directory of the decred-proposals/mainnet repo.

The root of the mainnet repository. * = proposal folders, A = anchoring data

Folders marked with * contain proposal data. Folders and files marked with A contain anchoring data. Anchoring data relates to the anchoring of Politeia data to the Decred blockchain through dcrtime, which facilitates Politeia’s transparent censorship functionality. This guide will not describe those files in detail, as they are not likely to be of interest for analysis.

Within each proposal folder there are sequentially numbered sub-folders, one for each version of the proposal. The first folder (‘/1’) corresponds to the initial version of the proposal submitted to Politeia. If a proposal author updates their proposal (typically in response to community feedback), the updated version and it’s associated data are put into folder (‘/2’), and so on.

Below shows the contents of our example proposal’s folder. As we can see, there are two versions of the proposal.

Versions of the example proposal

If we click on the latest version (‘/2’), we can see all the relevant data for this version.

Folder for version 2 of the example proposal

Below is a table with descriptions of the files and folders found in each proposal version folder.

Proposal data

Folder/File Description
/payload Folder containing an index.md file, which has the full text of the proposal and any images associated with the proposal.
/plugins/decred Folder containing the comments.journal file, which contains comments and up/down vote data for comments. If a proposal has begun voting (or finished voting), this folder will also contain a ballot.journal file containing the ticket holder voting data.
00.metadata.txt Data about the proposal submission:
  • timestamp
  • pubkey of submitter
  • title
  • signature
02.metadata.txt Data about admin approval for display:
  • timestamp
  • pubkey of admin
13.metadata.txt: Data about proposal owner authorizing the start of voting. Where proposal owner has authorized and then rescinded authorization this will appear in multiple commits:
  • timestamp
  • owner pubkey
  • transaction hash
14.metadata.txt Data about admin authorizing the start of voting. Includes specification of the vote: duration (2016 blocks):
  • quorum requirement (20%) (subject to change)
  • approval threshold (60%) (subject to change)
  • id and descriptions for voting options
15.metadata.txt Data about voting period:
  • starting block height and hash
  • ending block height
  • a list of every ticket eligible to vote on the proposal
recordmetadata.json Metadata about the record.

Voting and comment data

A git commit is made every hour for each active proposal to update the comments.journal file. If voting has started on a proposal, the same commit will also be used to update its ballot.journal file. The hourly commits are stopped once the voting has been completed and all votes have been recorded in git. Commits are made every hour because making a git commit is expensive performance-wise and making a commit for every vote and comment would not be practical. Additionally, grouping votes in hourly commits helps protect the privacy of ticketholders.

Vote data

Data on votes cast by ticket holders on a given proposal is stored in the ballot.journal file in the /plugins/decred folder. The commit history for this file can be consulted to see which hour votes were cast in. The table below describes the parameters recorded for each vote.

ballot.journal

Parameter Description
token The proposal being voted on
ticket The ticket which is voting
votebit Whether the vote was Yes (2) or No (1)
signature
receipt

Comment data

Data on comments is stored in the comments.journal file in the /plugins/decred folder. The table below describes the parameters recorded for each comment.

comments.journal

Parameter Description
action The action taken by the commenter. If a comment is added, action = add. If a comment is voted on, action = addlike. If action = addlike, the comment action is additionally assigned ‘1’ for upvote or ‘-1’ for downvote.
token The proposal being commented on.
parentid The id of the parent comment, or ‘0’ if a top-level comment.
commentid The identifier (id) for the comment
timestamp A unix timestamp specifying time comment was submitted
publickey The public key of the Politeia user who made the comment
censored The censorship status. If the comment has been censored, censored = true, and the comment will not be shown on proposals.decred.org.
receipt
totalvotes
resultvotes

User data

In the datasets presented here, users are identified by their public keys. On proposals.decred.org, users are identified by their username (chosen when they created their public/private key pair).

Currently, to associate a public key with a username, you need to go through proposals.decred.org. To look up the public key for a user, click on their username anywhere on the site. This will take you to the user’s profile, which has a URL like this: https://proposals.decred.org/user/350a4b6c-5cdd-4d87-822a-4900dc3a930c

The final part of this URL is the Universally Unique ID (UUID) for the account. This can be input into a public API exposed by the Politeia website, which will takes the UUID as an input and outputs user profile data, including the public key. For example, if you paste the above example UUID into a browser, https://proposals.decred.org/api/v1/user/350a4b6c-5cdd-4d87-822a-4900dc3a930c, it will return all publicly-available data for that user, including their public key: "publickey":"cd6e57b93f95dd0386d670c7ce42cb0ccd1cd5b997e87a716e9359e20251994e"