Skip to content
This repository has been archived by the owner on Nov 15, 2023. It is now read-only.

ReadMe followup for #2313 #2317

Merged
merged 2 commits into from
Mar 15, 2023
Merged

ReadMe followup for #2313 #2317

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1c1d29
Readme again
skunert Mar 14, 2023
19efc39
relaychain -> relay chain
skunert Mar 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 49 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,53 +37,71 @@ and treat as best.
A Polkadot [collator](https://wiki.polkadot.network/docs/en/learn-collator) for the parachain is
implemented by the `polkadot-parachain` binary (previously called `polkadot-collator`).

### Relaychain Interaction
To operate a parachain node a connection to the corresponding relaychain is necessary. This can be achieved in one of two ways:
1. Run a full relaychain node within the parachain node (default)
2. Connect to an external relaychain node via websocket RPC
### Relay Chain Interaction
To operate a parachain node, a connection to the corresponding relay chain is necessary. This can be
achieved in one of two ways:
1. Run a full relay chain node within the parachain node (default)
2. Connect to an external relay chain node via WebSocket RPC

#### In-process Relaychain Node
If an external relaychain node is not specified (default behavior) then a full relaychain node will be spawned within the same process.
#### In-process Relay Chain Node
If an external relay chain node is not specified (default behavior), then a full relay chain node is
spawned within the same process.

This node has all of the typical components of a normal Polkadot node, and will have to fully sync with the relaychain to work.
This node has all of the typical components of a regular Polkadot node and will have to fully sync
with the relay chain to work.

##### Example command
```shell=
# In-process node with this chainspec is spawned
# |
# |-----------------------|
polkadot-parachain --chain parachain-chainspec.json --tmp -- --chain relaychain-chainspec.json
polkadot-parachain \
--chain parachain-chainspec.json \
--tmp \
-- \
--chain relaychain-chainspec.json
```

#### External Relaychain Node
An external relaychain node can be connected via websocket RPC by using the `--relay-chain-rpc-urls` command line argument. This option accepts one or more space-separated websocket URLs to a full relay chain node. By default only the first URL will be used, with the rest acting as a backup in case the connection to the first node will be lost.
#### External Relay Chain Node
An external relay chain node is connected via WebsSocket RPC by using the `--relay-chain-rpc-urls`
command line argument. This option accepts one or more space-separated WebSocket URLs to a full relay
chain node. By default, only the first URL will be used, with the rest as a backup in case the
connection to the first node is lost.

Parachain nodes using this feature won't have to fully sync with the relay chain to work, so in general they will use significantly less system resources.
Parachain nodes using this feature won't have to fully sync with the relay chain to work, so in general
they will use fewer system resources.

**Note:** At this time any parachain nodes using this feature will still spawn a very cut down relaychain node in-process, hence even though they lack the majority of normal Polkadot subsystems they will still need to be able to directly connect to the relay chain network.
**Note:** At this time, any parachain nodes using this feature will still spawn a significantly cut-down
relay chain node in-process. Even though they lack the majority of normal Polkadot subsystems, they
will still need to connect directly to the relay chain network.
##### Example command
```shell=
# Perform runtime calls and fetch Still required since we connect
# data via RPC from here. Backup node to the relaychain network
# | | |
# |---------------------------------| |----------------------------------------| |-----------------------|
polkadot-parachain --chain parachain-chainspec.json --tmp --relay-chain-rpc-urls "ws://relaychain-rpc-endpoint:9944" "ws://relaychain-rpc-endpoint-backup:9944" -- --chain relaychain-chainspec.json
polkadot-parachain \
--chain parachain-chainspec.json \
--tmp \
--relay-chain-rpc-urls \
"ws://relaychain-rpc-endpoint:9944" \
"ws://relaychain-rpc-endpoint-backup:9944" \
-- \
--chain relaychain-chainspec.json
```

## Installation and Setup
Before building Cumulus SDK based nodes / runtimes prepare your environment by following Substrate [installation instructions](https://docs.substrate.io/main-docs/install/).
Before building Cumulus SDK based nodes / runtimes prepare your environment by following Substrate
[installation instructions](https://docs.substrate.io/main-docs/install/).

To launch a local network, you can use [zombienet](https://github.com/paritytech/zombienet) for quick setup and experimentation or follow the [manual setup](#manual-setup).
To launch a local network, you can use [zombienet](https://github.com/paritytech/zombienet) for
quick setup and experimentation or follow the [manual setup](#manual-setup).

### Zombienet
We use Zombienet to spin up networks for integration tests and local networks. Follow [these installation steps](https://github.com/paritytech/zombienet#requirements-by-provider) to set it up on your machine.
A simple network specification with two relay chain nodes and one collator is located at [zombienet/examples/small_network.toml](zombienet/examples/small_network.toml).
We use Zombienet to spin up networks for integration tests and local networks.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
We use Zombienet to spin up networks for integration tests and local networks.
Zombienet is used to spin up networks for integration tests and local networks.

Follow [these installation steps](https://github.com/paritytech/zombienet#requirements-by-provider)
to set it up on your machine. A simple network specification with two relay chain nodes and one collator is
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
to set it up on your machine. A simple network specification with two relay chain nodes and one collator is
to set it up on local machine. A simple network specification with two relay chain nodes and one collator is

located at [zombienet/examples/small_network.toml](zombienet/examples/small_network.toml).


#### Which provider should I use?
Zombienet offers multiple providers to run networks. Choose the one that best fits your needs:
- **Podman:** Choose this if you want to spin up a network quick and easy.
- **Native:** Choose this if you want to develop and deploy your changes. Requires compilation of the binaries.
- **Native:** Choose this if you want to develop and deploy your changes. Requires compilation
of the binaries.
- **Kubernetes:** Choose this for advanced use-cases or running on cloud-infrastructure.

#### How to run
Expand Down Expand Up @@ -183,7 +201,12 @@ See [the `bridge-hubs` readme](parachains/runtimes/bridge-hubs/README.md) for de

## Rococo 👑

[Rococo](https://polkadot.js.org/apps/?rpc=wss://rococo-rpc.polkadot.io) is becoming a [Community Parachain Testbed](https://polkadot.network/blog/rococo-revamp-becoming-a-community-parachain-testbed/) for parachain teams in the Polkadot ecosystem. It supports multiple parachains with the differentiation of long-term connections and recurring short-term connections, to see which parachains are currently connected and how long they will be connected for [see here](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frococo-rpc.polkadot.io#/parachains).
[Rococo](https://polkadot.js.org/apps/?rpc=wss://rococo-rpc.polkadot.io) is becoming a
[Community Parachain Testbed](https://polkadot.network/blog/rococo-revamp-becoming-a-community-parachain-testbed/)
for parachain teams in the Polkadot ecosystem. It supports multiple parachains with the
differentiation of long-term connections and recurring short-term connections, to see which
parachains are currently connected and how long they will be connected for
[see here](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frococo-rpc.polkadot.io#/parachains).

Rococo is an elaborate style of design and the name describes the painstaking effort that has gone
into this project.
Expand Down