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.

This website is built using Docusaurus 2, a modern static website generator.

Local Development

To clone, build and serve the website locally, run the following commands:

git clone --recurse-submodules https://github.com/w3f/polkadot-spec
cd website
npm i
npm run build # or build_with_kaitai to also rebuild kaitai SVG files
npm run serve

If you already have the repo cloned, remember to update it and the submodule before doing any changes:

git pull
git submodule update --remote

Because of the "complex" build, unfortunately you can't see the changes in real time, if you directly edit the docs folder. There are two workarounds:

• use a Markdown plugin or editor (e.g. the extension Markdown All in One for VSCode) to see the changes in real time. You won't be able to see the placeholders rendered and other elements, but you'll be able to render the markdown and latex;

• build the website a first time, then run npm run start instead of npm run serve, and edit the files inside the website/docs folder. This will allow you to see the changes in real time, but you have to remember to bring the changes inside the docs folder before committing. Also, in this way, you can't put the placeholders and other elements inside the markdown files of website/docs as they wouldn't be rendered.

Contributing

You can find the markdown files inside the docs folder.

When building, the scripts inside preBuild will generate a docs folder, from which Docusaurus will render the website. Then, the rendered content will be modified by the plugins in the browser.

LaTeX

You can use LaTeX inside the markdown files using the following syntax:

$ LaTeX here $

or

$$
LaTeX here 
$$

Numeration System

Inside preBuild, you can find the script numerationSystem. This will assign to several entities a number and substitute the placeholders inside the markdown files. This is done to avoid having to manually update the numbers when adding new entities.

This is the structure of the spec:

- Macro Chapter X
    1. Chapter A
        - Section 1.1
            ... subsections
        - Section 1.2
    2. Chapter B
        - Section 2.1
            ... subsections
        - Section 2.2
- Macro Chapter Y
    etc.

Example:

- Polkadot Host
    1. Overview
        1.1 Light Client
        ...
    2. State and Transitions
        ...

The entities involved are:

• Chapters
• Sections
• Definitions
• Algorithms
• Tables
• Images

Those defined as "Macro Chapters" will not be numbered.

Chapters

To write a new chapter, use the following syntax:

---
title: -chap-num- Chapter Title
---
<!-- Chapter content here -->

The placeholder -chap-num- will be replaced by the number assigned by numerationSystem.

If you add a chapter (or "Macro Chapter"), you must also add it to the sidebars.js file and adjust the numbers of the other chapters.

Sections

To write a new section, use the following syntax:

## -sec-num- Section name {#id-section-name}

• Use a markdown header from H2 to H5 included, so the maximum depth is a.b.c.d.e (H2 is a.b).
• Put the placeholder -sec-num- in the header, which will be replaced;
• Add an id to the header, which will be used to reference the section.

Definitions

To write a definition:

###### Definition -def-num- Runtime Pointer {#defn-runtime-pointer}

• Use a markdown H6 header (######);
• Put the placeholder -def-num- in the header;
• Add an id to the header.

Then, you should include the definition content inside the custom admonition :::definition (you can find all the custom admonitions inside src/theme/Admonition/Types.js).

So the final result will be the following:

###### Definition -def-num- Runtime Pointer {#defn-runtime-pointer}
:::definition <!-- Open admonition -->

Definition content here

::: <!-- Close admonition -->

Algorithms

To define an algorithm, use the same syntax as for definitions but with the placeholder -algo-num-:

###### Algorithm -algo-num- Aggregate-Key {#algo-aggregate-key}

At the top of the page, you must include the Pseudocode component and the LaTeX algorithm you want to render:

---
title: -chap-num- States and Transitions
---
import Pseudocode from '@site/src/components/Pseudocode';
import aggregateKey from '!!raw-loader!@site/src/algorithms/aggregateKey.tex';

After this, you can build the algorithm using the admonition :::algorithm, and using the Pseudocode component (refer to the file to know more about its props). This will be the final result:

---
title: -chap-num- States and Transitions
---
import Pseudocode from '@site/src/components/Pseudocode';
import aggregateKey from '!!raw-loader!@site/src/algorithms/aggregateKey.tex';

<!-- Page content here -->

###### Algorithm -algo-num- Aggregate-Key {#algo-aggregate-key}
:::algorithm
<Pseudocode
    content={aggregateKey}
    algID="aggregateKey"
    options={{ "lineNumber": true }}
/>

<!-- Algorithm description here -->
:::

Tables and Images

To define a table or an image, use the same syntax as for definitions and algorithms (always using an H6 header) but with the placeholder -tab-num- or -img-num-:

###### Table -tab-num- Name {#tab-name}

or

###### Image -img-num- Name {#img-name}

For these two entities you won't need to use any component or admonition.

References

To reference any of the entities from anywhere in the website, you have to use the following syntax:

[Entity -xxx-num-ref-](entity-page#entity-id)

• Use a markdown link;
• Put the placeholder -xxx-num-ref- in the text link, which will be replaced (xxx depends on the entity, for example -def-num-ref- for definitions);
• The link should point to the header id of the definition, with the page name as a prefix (if entity-page.md is a page, ".md" must be omitted).

Bibliography

The cited works are defined inside bibliography.bib. To cite a work, use the following syntax:

[@work-id]

Automatically, the bibliography will be generated at the end of the page.

Broken Links

During the preBuild, the external links in the markdown files will be checked.
After the build, the internal links will be checked.
If any link is broken, the console will show a warning.

Refer to checkBrokenInternalLinks/index.ts and checkBrokenExternalLinks/index.ts.

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.