• Stars
    star
    178
  • Rank 214,989 (Top 5 %)
  • Language
    TeX
  • License
    Creative Commons ...
  • Created over 5 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The Polkadot Protocol Specification

Polkadot Protocol Specification

Intorduction

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 our GitHub Releases page.

Process

Everyone, but specifically implementers and members of the Technical Fellowship, are welcome to open PRs to this repo and contribute to the specification. A PR is merged as soon as two members of the Spec Committee accept the PR.

Spec Committee

The Spec Committee consists of Researchers, Researcher Engineers, and Implementers of the Polkadot Protocol that actively contribute (= opening/contributing to PRs or issues regarding the spec) to the specification. For now and compared to the Technical Fellowship, the Spec Committee's responsibility is clearly defined as maintaining the specification of the protocol. In case of inactivity for three months, members will be removed again.

Web3 Foundation

Quadrivium

Smoldot

Parity

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 polkadot-spec
git submodule update --remote
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 making any changes:

git pull
git submodule update --remote

Because of the "complex" build, 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 the 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.

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.

Formatting

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.

Resources

Docusaurus docs: https://docusaurus.io/docs/category/guides

Kaitai docs: https://doc.kaitai.io/user_guide.html

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.

More Repositories

1

Grants-Program

Web3 Foundation Grants Program
JavaScript
1,018
star
2

General-Grants-Program

Web3 Foundation General Grants Program
590
star
3

polkadot-wiki

The source of truth for Polkadot.
JavaScript
370
star
4

schnorrkel

Schnorr VRFs and signatures on the Ristretto group
Rust
309
star
5

polkadot-validator-setup

Polkadot Validator Secure Setup
JavaScript
215
star
6

messaging

Messaging for Web3
TeX
167
star
7

PSPs

Polkadot Smart Contract Proposals
152
star
8

unbounded

Open source, freely available and on-chain funded font.
152
star
9

Grant-Milestone-Delivery

Repository to submit finished milestones
104
star
10

polkadot-deployer

Tool for deploying polkadot networks
JavaScript
101
star
11

research

Overview of W3F research initatives
JavaScript
95
star
12

consensus

Consensus for Web3
TeX
88
star
13

staking-rewards-collector

JavaScript
78
star
14

bls

Aggregatable BLS sigantures
Rust
65
star
15

1k-validators-be

Thousand Validators Program backend.
TypeScript
63
star
16

polkadot-wiki-old

The Polkadot wiki.
HTML
55
star
17

apk-proofs

Rust
50
star
18

polkadot-legacy-spec

A more technical description of Polkadot protocol
47
star
19

ring-vrf

TeX
36
star
20

jamtestvectors

The latest test vectors for JAM.
Python
31
star
21

substrate-telemetry-exporter

JavaScript
30
star
22

polkadot

Rust
30
star
23

hd-ed25519

Hierarchical derivations on Ed25519
Rust
25
star
24

polkadot-charts

Helm charts for deploying Polkadot networks.
Smarty
22
star
25

CardsAgainstBlockchain

Cards Against Blockchain
TeX
22
star
26

mooc-exercises

Exercises for Web3 MOOC
Rust
21
star
27

fflonk

Rust
21
star
28

validator-security

A collaborative document for good practice with validator security
20
star
29

1KC

Thousand Contributors Programme
20
star
30

polkadot-payouts

TypeScript
19
star
31

polkadot-watcher-validator

TypeScript
18
star
32

offences-monitor

Monitors slashable offences registered on a Substrate based chain.
JavaScript
18
star
33

w3f-education

Technical Education at Web3 Foundation
JavaScript
17
star
34

polkadot-registrar-challenger

Polkadot Registrar Service (beta)
Rust
15
star
35

ring-proof

ring-vrf ring proof v2.5
Rust
14
star
36

educhain

Parachain developed and maintained by Tech Ed team
Rust
14
star
37

polkadot-registrar-watcher

TypeScript
13
star
38

polkadot-light-paper

Light Polkadot info
12
star
39

ipfs-cluster-chart

Helm Chart for: https://cluster.ipfs.io/documentation/guides/k8s/
Shell
11
star
40

polkadot-tests

Polkadot Protocol Conformance Tests
Rust
11
star
41

polkadot-lab

Testing framework for Polkadot networks
TypeScript
11
star
42

polkadot-watcher-csv-exporter

polkadot-watcher-csv-exporter
TypeScript
11
star
43

chainspec-generator

CLI for generating the Polkadot and Kusama chain specification from Ethereum state.
TypeScript
11
star
44

faucet-bot

A DOTs-giving bot frontend to the faucet.
JavaScript
10
star
45

parachain-implementers-guide

9
star
46

ark-scale

Arkworks serialization wrapped in Parity SCALE codec
Rust
8
star
47

helm-charts

8
star
48

substrate-legacy

Rust
8
star
49

xcmp_prototype_playground

Prototyping several xcmp approaches
Rust
8
star
50

matrixbot

ChatBot for infrastructure interactions
Python
8
star
51

substrate-telemetry-chart

Smarty
7
star
52

polkadot-api-client-ts

TypeScript
7
star
53

polkadot-watcher-transaction

TypeScript
7
star
54

polkadot-dashboard

6
star
55

matrix-server-charts

Shell
6
star
56

injection-tool

Tools, scripts and utilities for making injections.
TypeScript
6
star
57

substrate-benchmarks-role

Ansible role for substrate runtime module benchmarking
Python
6
star
58

algorithmacs

Algorithmic style for Texmacs
TypeScript
6
star
59

ethereum-tracker

JavaScript
6
star
60

polkadot-docs

Polkadot Developer Documentation
6
star
61

validator-selection-tool

TypeScript
6
star
62

polkadot-claims

Claim a DOT allocation to a Polkadot public key.
Solidity
6
star
63

KTFPs

Kusama Treasury Funding Proposals
6
star
64

terraform-digitalocean-polkadot-deployer

Go
5
star
65

polkadot-react-icons

TypeScript
5
star
66

PPPs

Polkadot Protocol Proposals
TypeScript
5
star
67

terraform-ts

TypeScript
4
star
68

test-utils-ts

TypeScript
4
star
69

matrix-recorder-chart

HTML
4
star
70

helm-ts

TypeScript
4
star
71

substrate-alertrules-chart

Shell
4
star
72

polkadot-account-monitoring

Rust
4
star
73

kusama-guide-staging

staging server for kusama guide
HTML
4
star
74

components-ts

TypeScript
4
star
75

kusama-guide-hosting

Repository to deploy the Kusama Guide for hosting on GitHub Pages.
HTML
4
star
76

ethberlin4

Solidity
4
star
77

terraform-google-polkadot-lab

Creates the infrastructure for running polkadot network tests
HCL
3
star
78

polkadot-wiki-staging

polkadot wiki dev server build branch (github pages deployment)
JavaScript
3
star
79

edgeware-deployment

Dockerfile
3
star
80

cloudflare-ts

TypeScript
3
star
81

web3

3
star
82

terratest-polkadot-deployer

Go
3
star
83

polkadot-checker

JavaScript
3
star
84

terraform-google-polkadot-deployer

Go
3
star
85

teleport-role

HTML
3
star
86

terraform-azure-polkadot-deployer

HCL
3
star
87

node-docker

Dockerfile
3
star
88

NPoS-Economics

Jupyter Notebook
3
star
89

node-exporter-dashboard

3
star
90

polkadot-validator-ansible

Python
3
star
91

harvester-chart

Smarty
3
star
92

uptime-probe

Rust
3
star
93

1k-validators-candidate-verification

Rust
3
star
94

ghost-staging

Shell
3
star
95

disc2020-scalability-and-interoperability-workshop

HTML
3
star
96

algebraic-torus

A library to facilitate comptutation with algebraic torus
Sage
3
star
97

hs-p4p

p2p networking library in Haskell
Haskell
3
star
98

terraform-aws-polkadot-deployer

HCL
3
star
99

1k-watcher-claimed-payouts

A tool for generating reports about reward claims of all the 1k Validator Programme candidates.
Rust
3
star
100

crypto-ts

TypeScript
3
star