Polkadot Protocol Specification

Polkadot is a replicated sharded state machine designed to resolve the scalability and interoperability among blockchains. This repository contains the official specification for the Polkadot Protocol.

The latest releases of the Polkadot Protocol Specification can be found on our GitHub Releases page.

The Polkadot specification is written in AsciiDoc and currently compiled with Asciidoctor.

Contributing

Contributions are always welcome. For a quick primer on the AsciiDoc format, we recommend the AsciiDoc Writers Guide.

Dependencies

A handful of dependencies are required to successfully convert the spec into a publishable document. We provide a Gemfile that provides all dependecies.

You will have to install bundler to use the Gemfile. On a Debian based system, it can be installed with:

sudo apt-get install ruby-dev
# On some systems this might be required
gem install bundler

Once bundler is available, you can install any missing dependencies for a html build via bundle install:

bundle install

To also install the dependencies needed for a pdf build, add the --with pdf flag:

bundle install --with pdf

The pdf build requires various native dependencies to convert math to images with asciidoctor-mathematical, please check the official documentation for further details. Furthermore, the PDF is cleanup and compressed with ghostscript, so this will need to be installed as well.

Build

To build the html version of the spec, just run bundle exec make html. This create will create a polkadot-spec.html in the same folder.

To build the pdf version of the spec, just run bundle exec make pdf, which will create a polkadot-spec.pdf in the same folder.

We also provide full nix flake integration, e.g. you can run nix build github:w3f/polkadot-spec to build the latest html release.