Politeia: Proposals in a Timestamped Filesystem

Rather than settling for governance infrastructure that is just good enough to get the job done, we opted to create what we consider to be the ideal infrastructure for self-governance of a cryptocurrency.

Politeia: Proposals in a Timestamped Filesystem



Rather than settling for governance infrastructure that is just good enough to get the job done, we opted to create what we consider to be the ideal infrastructure for self-governance of a cryptocurrency. We call our system for storing governance data Politeia, which is based on the ancient Greek term, meaning “a system of government”. 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. While we will use it first as the basis for our proposal system, it has been developed as a generic tool that allows its users to create and maintain arbitrary data in a version-controlled and timestamped environment. Politeia can be used without holding any decred, although it does depend on using a dcrtime server for creating timestamps. In addition to making the initial release of Politeia, we are excited to announce a competition for projects based on Politeia, with winners announced at an event in Austin, Texas on December 1st, 2017. The prizes for 1st, 2nd and 3rd place will be the equivalent of USD 10,000, USD 5,000 and USD 2,000, respectively, paid in decred.


As part of Decred’s work to create a sustainable and fair system of governance, we asked the question “how should we store data related to Decred’s governance?”. Since Decred is a cryptocurrency, a natural option would be to store this data directly on Decred’s blockchain. However, as many cryptocurrency users are aware, this is an incredibly inefficient way to store this data. Further, a governance system will necessarily generate contentious content over time, so the question of “do we want all this data stored directly in our blockchain?” has a rather obvious answer of “no”. In lieu of storing this data on the blockchain, the next best thing we can do is to store this data in a version-controlled repository with timestamps anchored in the blockchain.

The larger goal with Politeia is to create a resilient public record that mimics the function of typical nation state websites for their governance bodies, e.g. senate.gov or house.gov. Having cryptographically verifiable public records will give users of Politeia the assurance that their governance is being executed in a transparent fashion, with all records independently verifiable and stored in a format that is difficult to forge. By making Decred’s governance data time-ordered in a verifiable fashion, we ensure that attempts to manipulate Decred’s governance, either from outside or within, will be much more difficult than when using a conventional website or similar.

Technical Summary

The rough idea is “git plus timestamping”, and rather than reinvent the wheel, Politeia makes direct use of git for revision control. Git is an excellent tool for revision control, but it gives only limited assurances as to when a particular change was made, e.g. you can recreate a git repository with fake timestamps without much effort. As you can imagine, this ability to arbitrarily recreate a git repository makes it a less-than-ideal candidate for creating an indisputable format for recording data. However, by adding cryptographic timestamping to git, we obtain a means of recording data that cannot be arbitrarily rewritten. Episodically “anchoring” a repository’s commit hash into the Decred chain using dcrtime and then committing the anchor data to the same repository creates a time-ordering that is computationally infeasible to recreate.

Anchors stored in the git repository include a transaction hash and a merkle path, where the merkle path hashes down to the merkle root contained in the transaction corresponding to the transaction hash. This transaction hash, merkle path and Decred’s blockchain are the minimal set of data required to independently verify an anchor is valid, indicating that a particular git commit hash existed before the timestamp on the next anchor in its repository. This time-ordering, combined with git’s standard process of hashing commit data to generate a commit hash, is a means of demonstrating the provenance, i.e. origin or source, of that data.

In the context of proposals in Decred, we will be restricting proposals to text with markdown and PNG images. This is being done to limit potential security issues that come with other more complex data formats, e.g. ZIP or PDF. While markdown and PNGs are not exactly glamorous formats, they are simple and sufficient to express any reasonable proposal.

Since Politeia will require manual review of submitted proposals, we created 2 statuses for new proposals: unvetted and vetted. This classification is useful because data submitted for inclusion may have formatting errors, contain inappropriate content, or need to satisfy other constraints before it is included into Politeia. Each proposal submission has a corresponding censorship token issued which allows a proposal submitter to publicly demonstrate that their proposal was censored, in the case that one of the administrators censors it. This censorship token allows for Politeia to avoid one of the more insidious and common practices of modern social media sites, where data is silently censored. By using censorship tokens, Politeia creates a transparent censorship process, so administrators can be held publicly accountable for their censorship actions, when found to be acting inappropriately.

Use cases

For Decred, Politeia will provide an unalterable public record of proposals, comments on proposals, and stakeholder votes. Although Decred will be using Politeia in a public capacity, it can provide similar utility as a private unalterable store of data. This generic concept of versioned and timestamped data can be applied in numerous public and private use cases, e.g. document and record storage, reputation and identity systems, and supply chains.

Using Politeia

The Politeia backend can currently be used to store flat text, markdown and PNG images. While this list of acceptable file types is quite short, it can easily be expanded to include other types of files, as needed. Currently, Politeia supports creating new user accounts, users submitting proposals, administrators reviewing those proposals, and administrators either approving or censoring them.

Decred users are expected to use the Politeia web interface for making comments and submitting proposals. Developers who are interested in exploring alternative applications of Politeia can use the command line interface to interact directly with the backend, per the example on GitHub.

Politeia Frontend

The backend portion of Politeia is mostly complete, but the frontend is rather minimal and a work-in-progress. The frontend of Politeia is a web interface, written using React and Redux, along with a user management system. Currently, this interface is in a very raw state and will be getting a steady stream of updates over the next few weeks. The Politeia frontend has been designed with an eye to embedding it directly into Decrediton, our GUI wallet.

Comments on proposals, editing proposals and voting on proposals will be added (in that order) over the next few weeks. During this time, we will be maintaining and updating a public test server for Politeia at test-proposals.decred.org, so users can participate via the frontend while features are being added. After running this public test server for a while and adding the missing features, we will reset the system and formally initiate our permanent public proposal system. In the meantime, users are encouraged to give feedback after using our public test server.

Contest Announcement

Since Politeia has many potential uses and we can only reasonably explore a few of them ourselves due to time constraints, we are announcing a competition for alternate uses of Politeia. The competition will run between now and December 1st, 2017, and we will invite the most promising competitors to give presentations at a 1-day conference in Austin, TX. In terms of requirements, submissions must be based on the Politeia source code and be prepared for a short public demonstration. Competitors are encouraged to work in small groups and registration is open to everyone, whether local or remote. The winners will be announced at the conference in Austin, and prizes will be for USD 10,000 (1st place), USD 5,000 (2nd place), and USD 2,000 (3rd place), payable directly in decred. Due to having roughly 5 weeks to prepare a submission between now and this event in Austin, applicants are expected to demo software at the proof-of-concept level. This means that we expect submissions to be necessarily sparse on features, but they must demonstrate that the idea works and has utility beyond our proposal system. To prevent too many submissions of the same type, we suggest competitors contact the user ingsoc on Slack to check whether a particular application is already being worked on by another competitor.


Politeia is a continuation of Decred’s commitment to delivering governance infrastructure that is novel and high-utility. Creating a permanent public record of the history of Decred’s governance is an important step towards a more transparent and effective method of governance. Any proposal submitted to Politeia that is censored can be publicly demonstrated as having been censored, creating accountability for the administrators of the proposal system. There are myriad potential uses for Politeia, and we are excited to see what competitors come up with for the event on December 1st. If you’re interested in getting in touch and discussing Politeia, please contact us on GitHub, Slack, Reddit or our Forum.