From 4c3aa1333e054d3dc17285e811b0ec7584646eba Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Tue, 14 Mar 2023 11:23:40 +0100 Subject: [PATCH 1/5] Update readme --- README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/README.md b/README.md index b78d7fdd2b6..ad3cafc6a7e 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,34 @@ 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, we need a connection to the corresponding relaychain. Currently, there are two available options: +#### In-process Relaychain Node +This is the default. If a relaychain chain spec is passed to the node via command line arguments, the collator node spawns an in-process full node. This full node has all the typical components, including all polkadot subsystems, its own substrate networking stack, and the relaychain runtime. + +##### Example command +```shell= +# In-process node with this chainspec is spawned +# | +# |-----------------------| +polkadot-parachain --chain parachain-chainspec.json --tmp -- --chain relaychain-chainspec.json +``` + +#### External Relaychain Node +You can connect to an external relaychain node via websocket RPC by using the `--relay-chain-rpc-urls ws://:` command line argument. The specified remote node will be used to perform runtime calls and fetch information about new/best/finalized blocks from the relaychain. + +Parachain nodes using this feature are generally more light-weight since it does not need to sync the relaychain. You can specify multiple websocket addresses to provide backup nodes. In case of connection loss, the parachain node will switch to the next node in the list. + +**Note:** At this time parachain nodes will still spawn a minimal relaychain node in-process. The minimal relaychain node contains only a subset of the polkadot subsystems and a separate substrate networking stack. +##### 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 +``` + ## 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/). From fb28a764058801a07cdc18aec37200b3bba55f83 Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Tue, 14 Mar 2023 11:33:46 +0100 Subject: [PATCH 2/5] Improve --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ad3cafc6a7e..3a63ff2d1b2 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,11 @@ A Polkadot [collator](https://wiki.polkadot.network/docs/en/learn-collator) for implemented by the `polkadot-parachain` binary (previously called `polkadot-collator`). ### Relaychain Interaction -To operate a parachain, we need a connection to the corresponding relaychain. Currently, there are two available options: +To operate a parachain, we need a connection to the corresponding relaychain. +Currently, there are two options available: +1. Use an in-process relaychain full-node +2. Connect to an external relaychain node via websocket RPC + #### In-process Relaychain Node This is the default. If a relaychain chain spec is passed to the node via command line arguments, the collator node spawns an in-process full node. This full node has all the typical components, including all polkadot subsystems, its own substrate networking stack, and the relaychain runtime. From 1158ab9275819f63728c6de9d8619356da2550b9 Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Tue, 14 Mar 2023 14:58:26 +0100 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Koute --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3a63ff2d1b2..f7ded04c92a 100644 --- a/README.md +++ b/README.md @@ -38,13 +38,14 @@ A Polkadot [collator](https://wiki.polkadot.network/docs/en/learn-collator) for implemented by the `polkadot-parachain` binary (previously called `polkadot-collator`). ### Relaychain Interaction -To operate a parachain, we need a connection to the corresponding relaychain. -Currently, there are two options available: -1. Use an in-process relaychain full-node +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 #### In-process Relaychain Node -This is the default. If a relaychain chain spec is passed to the node via command line arguments, the collator node spawns an in-process full node. This full node has all the typical components, including all polkadot subsystems, its own substrate networking stack, and the relaychain runtime. +By default if an external relaychain node is not specified then a full relaychain node will be 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. ##### Example command ```shell= @@ -55,11 +56,11 @@ polkadot-parachain --chain parachain-chainspec.json --tmp -- --chain relaychain- ``` #### External Relaychain Node -You can connect to an external relaychain node via websocket RPC by using the `--relay-chain-rpc-urls ws://:` command line argument. The specified remote node will be used to perform runtime calls and fetch information about new/best/finalized blocks from the relaychain. +You can connect to an external relaychain node 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. -Parachain nodes using this feature are generally more light-weight since it does not need to sync the relaychain. You can specify multiple websocket addresses to provide backup nodes. In case of connection loss, the parachain node will switch to the next node in the list. +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. -**Note:** At this time parachain nodes will still spawn a minimal relaychain node in-process. The minimal relaychain node contains only a subset of the polkadot subsystems and a separate substrate networking stack. +**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. ##### Example command ```shell= # Perform runtime calls and fetch Still required since we connect From c89fc443ea992498193c7c5ec9aa53db7e5159fe Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Tue, 14 Mar 2023 15:04:24 +0100 Subject: [PATCH 4/5] Quote urls --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f7ded04c92a..6ee2fc4e12c 100644 --- a/README.md +++ b/README.md @@ -63,11 +63,11 @@ Parachain nodes using this feature won't have to fully sync with the relay chain **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. ##### 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 +# 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 ``` ## Installation and Setup From ea22a25083bf3e824ad4928679206902d258d546 Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Tue, 14 Mar 2023 15:17:08 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Michal Kucharczyk <1728078+michalkucharczyk@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6ee2fc4e12c..df95e3d9273 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ To operate a parachain node a connection to the corresponding relaychain is nece 2. Connect to an external relaychain node via websocket RPC #### In-process Relaychain Node -By default if an external relaychain node is not specified then a full relaychain node will be spawned within the same process. +If an external relaychain node is not specified (default behavior) then a full relaychain node will be 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. @@ -56,7 +56,7 @@ polkadot-parachain --chain parachain-chainspec.json --tmp -- --chain relaychain- ``` #### External Relaychain Node -You can connect to an external relaychain node 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. +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. 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.