diff --git a/templates/minimal/README.md b/templates/minimal/README.md index a4ccef2b03cd..10db7ee08885 100644 --- a/templates/minimal/README.md +++ b/templates/minimal/README.md @@ -146,11 +146,12 @@ docker run --rm polkadot-sdk-minimal-template ### Zombienet with Omni Node -We set up a network specification in `zombienet-omni-node.toml`. To use it we need -[zombienet](https://www.npmjs.com/package/@zombienet/cli). The installation guide for -`zombienet` can be found [here](https://paritytech.github.io/zombienet/install.html#installation). +#### Install `zombienet` -#### Updating the network spec with a chain spec +We can install `zombienet` as described [here](https://paritytech.github.io/zombienet/install.html#installation), +and `zombienet-omni-node.toml` contains the network specification we want to start. + +#### Update `zombienet-omni-node` with a valid chain spec path Before starting the network with zombienet we must update the network specification dawith a valid chain spec path. If we need to generate one, we can look up at the previous diff --git a/templates/parachain/README.md b/templates/parachain/README.md index c92726ae75cd..58685e7fdfd0 100644 --- a/templates/parachain/README.md +++ b/templates/parachain/README.md @@ -11,32 +11,56 @@ -* ⏫ This template provides a starting point to build a [parachain](https://wiki.polkadot.network/docs/learn-parachains). +## Table of Contents -* ☁️ It is based on the +- [Intro](#intro) + +- [Template Structure](#template-structure) + +- [Getting Started](#getting-started) + +- [Starting a Development Chain](#starting-a-development-chain) + + - [Omni Node](#omni-node) + - [Zombienet setup with Omni Node](#zombienet-setup-with-omni-node) + - [Parachain Template Node](#parachain-template-node) + - [Connect with the Polkadot-JS Apps Front-End](#connect-with-the-polkadot-js-apps-front-end) + - [Takeways](#takeways) + +- [Next Steps](#next-steps) +- [Contributing](#contributing) +- [Getting Help](#getting-help) + +## Intro + +- ⏫ This template provides a starting point to build a [parachain](https://wiki.polkadot.network/docs/learn-parachains). + +- ☁️ It is based on the [Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) framework. -* 🔧 Its runtime is configured with a single custom pallet as a starting point, and a handful of ready-made pallets +- 🔧 Its runtime is configured with a single custom pallet as a starting point, and a handful of ready-made pallets such as a [Balances pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/index.html). -* 👉 Learn more about parachains [here](https://wiki.polkadot.network/docs/learn-parachains) +- 👉 Learn more about parachains [here](https://wiki.polkadot.network/docs/learn-parachains) ## Template Structure A Polkadot SDK based project such as this one consists of: -* 💿 a [Node](./node/README.md) - the binary application. -* 🧮 the [Runtime](./runtime/README.md) - the core logic of the parachain. -* 🎨 the [Pallets](./pallets/README.md) - from which the runtime is constructed. +- 💿 a [Node](./node/README.md) - the binary application, not part of the project default-members list and not compiled unless +building the project with `--workspace` flag, which builds all workspace members, and is an alternative to +[Omni Node](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/omni_node/index.html). +- 🧮 the [Runtime](./runtime/README.md) - the core logic of the parachain. +- 🎨 the [Pallets](./pallets/README.md) - from which the runtime is constructed. ## Getting Started -* 🦀 The template is using the Rust language. +- 🦀 The template is using the Rust language. -* 👉 Check the +- 👉 Check the [Rust installation instructions](https://www.rust-lang.org/tools/install) for your system. -* 🛠️ Depending on your operating system and Rust version, there might be additional +- 🛠️ Depending on your operating system and Rust version, there might be additional packages required to compile this template - please take note of the Rust compiler output. Fetch parachain template code: @@ -47,131 +71,141 @@ git clone https://github.com/paritytech/polkadot-sdk-parachain-template.git para cd parachain-template ``` -### Build +## Starting a Development Chain -🔨 Use the following command to build just the `runtime`. There is also -a `node` crate that when started can load the runtime accordingly, but the -recommended way of running the template is with `Omni Node`. +### Omni Node +[Omni Node](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/omni_node/index.html) can +be used to run the parachain template's runtime. `polkadot-omni-node` binary crate usage is described at a high-level +[on crates.io](https://crates.io/crates/polkadot-omni-node). + +#### Install `polkadot-omni-node` ```sh -cargo build --release +cargo install polkadot-omni-node ``` -### Local Development Chain with Omni Node +#### Build `parachain-template-runtime` -⬇️ Omni Node can run by using the `polkadot-omni-node` binary, which can be downloaded -from [Polkadot SDK releases](https://github.com/paritytech/polkadot-sdk/releases/latest). +```sh +cargo build -p parachain-template-runtime --release +``` -🔗 Once downloaded, add it to the `PATH` environment variable like so: +#### Install `staging-chain-spec-builder` ```sh -export PATH=":$PATH" +cargo install staging-chain-spec-builder ``` -↩️ If not already built, we should build the `runtime` and generate a development chain spec. -The chain spec will be passed to the Omni Node binary when starting it. +#### Use chain-spec-builder to generate the chain_spec.json file ```sh -# Build the parachain runtime. -cargo build --release -# Install chain-spec-builder if not installed already. -cargo install staging-chain-spec-builder -# Use chain-spec-builder to generate the chain_spec.json file based on the development preset. chain-spec-builder create --relay-chain "rococo-local" --para-id 1000 --runtime \ - named-preset development + named-preset development ``` -⚙️ The `relay-chain` and `para-id` flags in the chain spec generation above are extra bits of -information required to configure the node in relation to its parachain id (which must be set -to `1000` for the parachain template, to be the same as the `ParachainInfo` pallet [genesis config](https://github.com/paritytech/polkadot-sdk/blob/master/templates/parachain/runtime/src/genesis_config_presets.rs)). -The `relay-chain` must correspond to the relay chain id where the parachain connects to. +**Note**: the `relay-chain` and `para-id` flags are mandatory information required by +Omni Node, and for parachain template case the value for `para-id` must be set to `1000`, since this +is also the value injected through [ParachainInfo](https://docs.rs/staging-parachain-info/0.17.0/staging_parachain_info/) +pallet into the `parachain-template-runtime`'s storage. -We'll start Omni Node with zombienet, but before doing that we must update the path to the -`chain_spec.json` file in the `parachains` section of the `zombienet-omni-node.toml` file, -which holds the zombienet network specification: +#### Run Omni Node -```toml -# ... -[[parachains]] -id = 1000 -# insert the correct path on your file system -chain_spec_path = "" -# ... +Start Omni Node with the generated chain spec. + +```sh +polkadot-omni-node --chain ``` -🚀 Start the parachain runtime with Omni Node like below. This will -start two relay chain nodes and one collator node: +**Note**: this starts only the parachain's node, but this is not enough for proggressing with block production and finalization. +We need to create an active relay chain too, and a good follow up after this is to configure zombienet to run the relay chain +alongside the parachain. + +### Zombienet setup with Omni Node + +Assuming we continue from the last step of the previous section, we have a chain spec and we need to setup a relay chain. +We can install `zombienet` as described [here](https://paritytech.github.io/zombienet/install.html#installation), and +`zombienet-omni-node.toml` contains the network specification we want to start. + +#### Relay chain prerequisites + +Download the `polkadot` (and the accompanying `polkadot-prepare-worker` and `polkadot-execute-worker`) binaries from +[Polkadot SDK releases](https://github.com/paritytech/polkadot-sdk/releases). Then expose them on `PATH` like so: ```sh -zombienet --provider native spawn ./zombienet-omni-node.toml +export PATH="$PATH:" ``` -### Local Development Chain +#### Update `zombienet-omni-node.toml` with a valid chain spec path -🧟 This project uses [Zombienet](https://github.com/paritytech/zombienet) to orchestrate the relaychain and parachain nodes. -You can grab a [released binary](https://github.com/paritytech/zombienet/releases/latest) or use an [npm version](https://www.npmjs.com/package/@zombienet/cli). +```toml +# ... +[[parachains]] +id = 1000 +chain_spec_path = "" +# ... +``` -This template produces a parachain node. You can install it in your environment by running: +#### Start the network ```sh -cargo install --path node +zombienet --provider native spawn zombienet-omni-node.toml ``` -You still need a relaychain node - you can download the `polkadot` -(and the accompanying `polkadot-prepare-worker` and `polkadot-execute-worker`) -binaries from [Polkadot SDK releases](https://github.com/paritytech/polkadot-sdk/releases/latest). +### Parachain Template Node -In addition to the installed parachain node, make sure to bring -`zombienet`, `polkadot`, `polkadot-prepare-worker`, and `polkadot-execute-worker` -into `PATH`. +As mentioned in the `Template Structure` section, the `node` crate is optionally compiled and it is an alternative +to `Omni Node`. Similarly, it requires setting up a relay chain, and we'll use `zombienet` once more. -This way, we can conveniently use them in the following steps. - -👥 The following command starts a local development chain, with a single relay chain node and a single parachain collator: +#### Install the `parachain-template-node` ```sh -zombienet --provider native spawn ./zombienet.toml - -# Alternatively, the npm version: -npx --yes @zombienet/cli --provider native spawn ./zombienet.toml +cargo install --path node ``` -Development chains: +#### Setup and run -* 🧹 Do not persist the state. -* 💰 Are preconfigured with a genesis state that includes several prefunded development accounts. -* 🧑‍⚖️ Development accounts are used as validators, collators, and `sudo` accounts. +Please refer to the same section related to `Omni Node` [here](#zombienet-with-omni-node), except that instead of +using `zombienet-omni-node.toml` we'll use `zombienet.toml`. ### Connect with the Polkadot-JS Apps Front-End -* 🌐 You can interact with your local node using the +- 🌐 You can interact with your local node using the hosted version of the Polkadot/Substrate Portal: [relay chain](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) and [parachain](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9988). -* 🪐 A hosted version is also +- 🪐 A hosted version is also available on [IPFS](https://dotapps.io/). -* 🧑‍🔧 You can also find the source code and instructions for hosting your own instance in the +- 🧑‍🔧 You can also find the source code and instructions for hosting your own instance in the [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository. +### Takewayas + +Development parachains: + +- 🔗 Connect to relay chains, and we showcased how to connect to a local one. +- 🧹 Do not persist the state. +- 💰 Are preconfigured with a genesis state that includes several prefunded development accounts. +- 🧑‍⚖️ Development accounts are used as validators, collators, and `sudo` accounts. + ## Contributing -* 🔄 This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk). +- 🔄 This template is automatically updated after releases in the main [Polkadot SDK monorepo](https://github.com/paritytech/polkadot-sdk). -* ➡️ Any pull requests should be directed to this [source](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain). +- ➡️ Any pull requests should be directed to this [source](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain). -* 😇 Please refer to the monorepo's +- 😇 Please refer to the monorepo's [contribution guidelines](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md) and [Code of Conduct](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CODE_OF_CONDUCT.md). ## Getting Help -* 🧑‍🏫 To learn about Polkadot in general, [Polkadot.network](https://polkadot.network/) website is a good starting point. +- 🧑‍🏫 To learn about Polkadot in general, [Polkadot.network](https://polkadot.network/) website is a good starting point. -* 🧑‍🔧 For technical introduction, [here](https://github.com/paritytech/polkadot-sdk#-documentation) are +- 🧑‍🔧 For technical introduction, [here](https://github.com/paritytech/polkadot-sdk#-documentation) are the Polkadot SDK documentation resources. -* 👥 Additionally, there are [GitHub issues](https://github.com/paritytech/polkadot-sdk/issues) and +- 👥 Additionally, there are [GitHub issues](https://github.com/paritytech/polkadot-sdk/issues) and [Substrate StackExchange](https://substrate.stackexchange.com/).