gnapoli23/polkadot-spec

The Polkadot Protocol Specification

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 spec.polkadot.network or 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 most 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 -y curl make cmake gcc g++ ruby-dev python3-pydot graphviz
# Install Bundler
gem install bundler
# Install Kaitai
curl -LO https://github.com/kaitai-io/kaitai_struct_compiler/releases/download/0.10/kaitai-struct-compiler_0.10_all.deb
sudo apt-get install -y ./kaitai-struct-compiler_0.10_all.deb

Furthermore you will also need to have graphviz and the kaitai-struct-compiler installed.

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.

To export the Kaitai Struct definitions contained in the spec, just run bundle exec make kaitai, which will create the .ksy file(s) 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.

Test

To test some of the machine readable definition in the spec, just run bundle exec make test.

The test requires curl, jq and xxd to download required data via JSON RPC.

License

Any code in this repository is licensed under the GPL 3.0 and any documentation or specification is licensed under the CC BY-SA 2.0.