Skip to content

Commit

Permalink
updated minimal & parachain README
Browse files Browse the repository at this point in the history 
Signed-off-by: Iulian Barbu <[email protected]>
  • Loading branch information
@iulianbarbu
iulianbarbu committed Oct 25, 2024
1 parent 145e622 commit d3b16ab
Show file tree
Hide file tree
Showing 2 changed files with 115 additions and 80 deletions.
9 changes: 5 additions & 4 deletions templates/minimal/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
186 changes: 110 additions & 76 deletions templates/parachain/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,32 +11,56 @@
</div>

* ⏫ 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:
Expand All @@ -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-to-binary>:$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 \
<target/release/wbuild/path/to/parachain-template-runtime.wasm> named-preset development
<target/release/wbuild/path/to/minimal-template-runtime.wasm> 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 = "<path/to/chain_spec.json>"
# ...
Start Omni Node with the generated chain spec.

```sh
polkadot-omni-node --chain <path/to/chain_spec.json>
```

🚀 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:<path/to/binaries>"
```

### 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 = "<TO BE UPDATED WITH A VALID 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/).

0 comments on commit d3b16ab

Please sign in to comment.