diff --git a/README.md b/README.md index 1a3e165f56..2cc253c4ef 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,77 @@ -# Cumulus +# Cumulus :cloud: -A set of tools for writing [Polkadot](https://github.com/paritytech/polkadot) parachains that are based on [Substrate](https://github.com/paritytech/substrate). +A set of tools for writing [Substrate](https://substrate.dev/)-based +[Polkadot](https://wiki.polkadot.network/en/) +[parachains](https://wiki.polkadot.network/docs/en/learn-parachains). Refer to the included +[overview](docs/overview.md) for more details. -It's easy to write blockchains using Substrate, and the overhead of writing parachains' distribution, p2p, database, and synchronization layers is generally high and should be reusable. This project aims to make it easy to write parachains for Polkadot by leveraging the power of Substrate. +It's easy to write blockchains using Substrate, and the overhead of writing parachains' +distribution, p2p, database, and synchronization layers should be just as low. This project aims to +make it easy to write parachains for Polkadot by leveraging the power of Substrate. -Cumulus clouds are shaped sort of like dots and are up in the air, like this project (as it is an initial prototype -- expect a rename when it gets cooler.) +Cumulus clouds are shaped sort of like dots; together they form a system that is intricate, +beautiful and functional. -## cumulus-consensus +## Consensus -For now, this is only project contained in this repo. *cumulus-consensus* is a consensus engine for Substrate which follows a Polkadot relay chain. This will run a Polkadot node internally, and dictate to the client and synchronization algorithms which chain to follow, finalize, and treat as best. +[`cumulus-consensus`](consensus) is a +[consensus engine](https://substrate.dev/docs/en/knowledgebase/advanced/consensus) for Substrate +that follows a Polkadot +[relay chain](https://wiki.polkadot.network/docs/en/learn-architecture#relay-chain). This will run a +Polkadot node internally, and dictate to the client and synchronization algorithms which chain to +follow, +[finalize](https://wiki.polkadot.network/docs/en/learn-consensus#probabilistic-vs-provable-finality), +and treat as best. -## cumulus-runtime +## Runtime -A planned wrapper around substrate runtimes to turn them into parachain validation code and to provide proof-generation routines. +The [`cumulus-runtime`](runtime) is wrapper around Substrate runtimes that provides parachain +validation capabilities and proof-generation routines. -## cumulus-collator +## Collator -A planned Polkadot collator for the parachain. +A Polkadot [collator](https://wiki.polkadot.network/docs/en/maintain-collator) for the parachain is +implemented by [`cumulus-collator`](collator). -## Rococo +# Rococo :crown: -Rococo is the testnet for parachains. It currently runs the parachains `Tick`, `Trick` and `Track`. +[Rococo](https://polkadot.js.org/apps/?rpc=wss://rococo-rpc.polkadot.io) is the testnet for +parachains. It currently runs the parachains +[Tick](https://polkadot.js.org/apps/?rpc=wss://tick-rpc.polkadot.io), +[Trick](https://polkadot.js.org/apps/?rpc=wss://trick-rpc.polkadot.io) and +[Track](https://polkadot.js.org/apps/?rpc=wss://track-rpc.polkadot.io). -### Running a collator +Rococo is an elaborate style of design and the name describes the painstaking effort that has gone +into this project. Tick, Trick and Track are the German names for the cartoon ducks known to English +speakers as Huey, Dewey and Louie. -Collators are similar to validators in the relay chain. These nodes build the blocks that will eventually be included by the relay chain for a parachain. +## Build & Launch Rococo Collators -To run a collator on this test network you will need to compile the following binary: +Collators are similar to validators in the relay chain. These nodes build the blocks that will +eventually be included by the relay chain for a parachain. + +To run a Rococo collator you will need to compile the following binary: ``` cargo build --release -p rococo-collator ``` -After the build is finished you can use the binary to run a collator for all three parachains: +Once the executable is built, launch collators for each parachain (repeat once each for chain +`tick`, `trick`, `track`): ``` -./target/release/rococo-collator --chain tick --validator +./target/release/rococo-collator --chain $CHAIN --validator ``` -This will run the collator for the `Tick` parachain. To run a collator for one of the other nodes, the chain argument needs to be changed. +## Parachains -### Running a full node +The parachains of Rococo all use the same runtime code. The only difference between them is the +parachain ID used for registration with the relay chain: -To run a full node that should sync one of the parachains, you need to compile the following binary: +- Tick: 100 +- Trick: 110 +- Track: 120 -``` -cargo build --release -p rococo-collator -``` - -After the build is finished you can use the binary to run a collator for all three parachains: - -``` -./target/release/rococo-collator --chain tick -``` - -### Tick, Trick and Track - -These are the parachains of Rococo, essentially all run the exact same runtime code. The only difference is the parachain ID they are registered -with on the relay chain. `Tick` is using `100`, `Trick` `110` and `Track` `120`. The parachains demonstrate message -passing between themselves and the relay chain. The message passing is currently implemented as a -HRMP (Horizontal Message Passing). This means that every message is send to the relay chain and from the relay -chain to its destination parachain. +The network uses horizontal message passing (HRMP) to enable communication between parachains and +the relay chain and, in turn, between parachains. This means that every message is sent to the relay +chain, and from the relay chain to its destination parachain. diff --git a/docs/overview.md b/docs/overview.md index 47bf9ab807..3312cec126 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -57,7 +57,7 @@ Parachain blocks to the Parachain validators. Secondly, the Collator participate of the relay chain to be informed of new relay-chain blocks. This information will be used for the consensus and the block production logic. -## Block building +## Block Building Polkadot requires that a Parachain block is transmitted in a fixed format. These blocks sent by a Parachain to the Parachain validators are called proof-of-validity blocks (PovBlock). Such a