From f68e124a96bb06c1c4cac1b0741ee662ea010af7 Mon Sep 17 00:00:00 2001 From: Sebastian Kunert Date: Tue, 8 Nov 2022 19:26:20 +0100 Subject: [PATCH] Add example zombienet network file and instructions (#1839) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add simple example on how to spin up network. * Update readme * Remove unnecessary prefix * Improve folder structure * Add link to file * Fix paths in readme * Update README.md Co-authored-by: Bastian Köcher Co-authored-by: Bastian Köcher --- README.md | 135 ++++++++++-------- scripts/ci/gitlab/pipeline/zombienet.yml | 2 +- zombienet/examples/small_network.toml | 25 ++++ ...rom_tip_without_connected_collator.feature | 0 ...s_from_tip_without_connected_collator.toml | 0 .../tests}/0002-pov_recovery.feature | 0 .../tests}/0002-pov_recovery.toml | 0 .../tests}/0003-full_node_catching_up.feature | 0 .../tests}/0003-full_node_catching_up.toml | 0 .../tests}/0004-runtime_upgrade.feature | 0 .../tests}/0004-runtime_upgrade.toml | 0 .../tests}/0005-migrate_solo_to_para.feature | 0 .../tests}/0005-migrate_solo_to_para.toml | 0 .../0006-rpc_collator_builds_blocks.feature | 0 .../0006-rpc_collator_builds_blocks.toml | 0 .../tests}/migrate_solo_to_para.js | 0 .../tests}/register-para.js | 0 .../tests}/runtime_upgrade.js | 0 18 files changed, 104 insertions(+), 58 deletions(-) create mode 100644 zombienet/examples/small_network.toml rename {zombienet_tests => zombienet/tests}/0001-sync_blocks_from_tip_without_connected_collator.feature (100%) rename {zombienet_tests => zombienet/tests}/0001-sync_blocks_from_tip_without_connected_collator.toml (100%) rename {zombienet_tests => zombienet/tests}/0002-pov_recovery.feature (100%) rename {zombienet_tests => zombienet/tests}/0002-pov_recovery.toml (100%) rename {zombienet_tests => zombienet/tests}/0003-full_node_catching_up.feature (100%) rename {zombienet_tests => zombienet/tests}/0003-full_node_catching_up.toml (100%) rename {zombienet_tests => zombienet/tests}/0004-runtime_upgrade.feature (100%) rename {zombienet_tests => zombienet/tests}/0004-runtime_upgrade.toml (100%) rename {zombienet_tests => zombienet/tests}/0005-migrate_solo_to_para.feature (100%) rename {zombienet_tests => zombienet/tests}/0005-migrate_solo_to_para.toml (100%) rename {zombienet_tests => zombienet/tests}/0006-rpc_collator_builds_blocks.feature (100%) rename {zombienet_tests => zombienet/tests}/0006-rpc_collator_builds_blocks.toml (100%) rename {zombienet_tests => zombienet/tests}/migrate_solo_to_para.js (100%) rename {zombienet_tests => zombienet/tests}/register-para.js (100%) rename {zombienet_tests => zombienet/tests}/runtime_upgrade.js (100%) diff --git a/README.md b/README.md index 3d6a47fbba6..e4e1e86ec42 100644 --- a/README.md +++ b/README.md @@ -37,10 +37,85 @@ 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`). -## Installation - +## 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/). +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). + + +#### 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. +- **Kubernetes:** Choose this for advanced use-cases or running on cloud-infrastructure. + +#### How to run +To run the example network, use the following commands: + +```bash +# Podman provider +zombienet --provider podman spawn ./zombienet/examples/small_network.toml + +# Native provider, assumes polkadot and polkadot-parachains binary in $PATH +zombienet --provider native spawn ./zombienet/examples/small_network.toml +``` + +### Manual Setup +#### Launch the Relay Chain + +```bash +# Clone +git clone https://github.com/paritytech/polkadot +cd polkadot + +# Compile Polkadot with the real overseer feature +cargo build --release --bin polkadot + +# Generate a raw chain spec +./target/release/polkadot build-spec --chain rococo-local --disable-default-bootnode --raw > rococo-local-cfde.json + +# Alice +./target/release/polkadot --chain rococo-local-cfde.json --alice --tmp + +# Bob (In a separate terminal) +./target/release/polkadot --chain rococo-local-cfde.json --bob --tmp --port 30334 +``` + +#### Launch the Parachain + +```bash +# Clone +git clone https://github.com/paritytech/cumulus +cd cumulus + +# Compile +cargo build --release --bin polkadot-parachain + +# Export genesis state +./target/release/polkadot-parachain export-genesis-state > genesis-state + +# Export genesis wasm +./target/release/polkadot-parachain export-genesis-wasm > genesis-wasm + +# Collator1 +./target/release/polkadot-parachain --collator --alice --force-authoring --tmp --port 40335 --ws-port 9946 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30335 + +# Collator2 +./target/release/polkadot-parachain --collator --bob --force-authoring --tmp --port 40336 --ws-port 9947 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30336 + +# Parachain Full Node 1 +./target/release/polkadot-parachain --tmp --port 40337 --ws-port 9948 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30337 +``` + +#### Register the parachain + +![image](https://user-images.githubusercontent.com/2915325/99548884-1be13580-2987-11eb-9a8b-20be658d34f9.png) + + ## Statemint 🪙 This repository also contains the Statemint runtime (as well as the canary runtime Statemine and the @@ -63,7 +138,7 @@ CHAIN=westmint # or statemine ./target/release/polkadot-parachain --chain $CHAIN ``` -Refer to the [setup instructions below](#local-setup) to run a local network for development. +Refer to the [setup instructions](#local-setup) to run a local network for development. ## Contracts 📝 @@ -117,60 +192,6 @@ The network uses horizontal message passing (HRMP) to enable communication betwe 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. -### Local Setup - -Launch a local setup including a Relay Chain and a Parachain. - -#### Launch the Relay Chain - -```bash -# Clone -git clone https://github.com/paritytech/polkadot -cd polkadot - -# Compile Polkadot with the real overseer feature -cargo build --release - -# Generate a raw chain spec -./target/release/polkadot build-spec --chain rococo-local --disable-default-bootnode --raw > rococo-local-cfde.json - -# Alice -./target/release/polkadot --chain rococo-local-cfde.json --alice --tmp - -# Bob (In a separate terminal) -./target/release/polkadot --chain rococo-local-cfde.json --bob --tmp --port 30334 -``` - -#### Launch the Parachain - -```bash -# Clone -git clone https://github.com/paritytech/cumulus -cd cumulus - -# Compile -cargo build --release - -# Export genesis state -./target/release/polkadot-parachain export-genesis-state > genesis-state - -# Export genesis wasm -./target/release/polkadot-parachain export-genesis-wasm > genesis-wasm - -# Collator1 -./target/release/polkadot-parachain --collator --alice --force-authoring --tmp --port 40335 --ws-port 9946 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30335 - -# Collator2 -./target/release/polkadot-parachain --collator --bob --force-authoring --tmp --port 40336 --ws-port 9947 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30336 - -# Parachain Full Node 1 -./target/release/polkadot-parachain --tmp --port 40337 --ws-port 9948 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30337 -``` - -#### Register the parachain - -![image](https://user-images.githubusercontent.com/2915325/99548884-1be13580-2987-11eb-9a8b-20be658d34f9.png) - ### Containerize After building `polkadot-parachain` with cargo or with Parity CI image as documented in [this chapter](#build--launch-rococo-collators), diff --git a/scripts/ci/gitlab/pipeline/zombienet.yml b/scripts/ci/gitlab/pipeline/zombienet.yml index 4682af16ee4..2238d6117fd 100644 --- a/scripts/ci/gitlab/pipeline/zombienet.yml +++ b/scripts/ci/gitlab/pipeline/zombienet.yml @@ -21,7 +21,7 @@ artifacts: true variables: POLKADOT_IMAGE: "docker.io/paritypr/polkadot-debug:master" - GH_DIR: "https://github.com/paritytech/cumulus/tree/${CI_COMMIT_SHORT_SHA}/zombienet_tests" + GH_DIR: "https://github.com/paritytech/cumulus/tree/${CI_COMMIT_SHORT_SHA}/zombienet/tests" COL_IMAGE: "docker.io/paritypr/test-parachain:${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHORT_SHA}" allow_failure: true retry: 2 diff --git a/zombienet/examples/small_network.toml b/zombienet/examples/small_network.toml new file mode 100644 index 00000000000..ac5ee11e5bb --- /dev/null +++ b/zombienet/examples/small_network.toml @@ -0,0 +1,25 @@ +[relaychain] +default_image = "parity/polkadot:latest" +default_command = "polkadot" +chain = "rococo-local" + + [[relaychain.nodes]] + name = "alice" + validator = true + + [[relaychain.nodes]] + name = "bob" + validator = true + +[[parachains]] +id = 2000 +cumulus_based = true +chain = "statemine-local" + + # run charlie as parachain collator + [[parachains.collators]] + name = "charlie" + validator = true + image = "parity/polkadot-parachain:latest" + command = "polkadot-parachain" + args = ["--force-authoring"] diff --git a/zombienet_tests/0001-sync_blocks_from_tip_without_connected_collator.feature b/zombienet/tests/0001-sync_blocks_from_tip_without_connected_collator.feature similarity index 100% rename from zombienet_tests/0001-sync_blocks_from_tip_without_connected_collator.feature rename to zombienet/tests/0001-sync_blocks_from_tip_without_connected_collator.feature diff --git a/zombienet_tests/0001-sync_blocks_from_tip_without_connected_collator.toml b/zombienet/tests/0001-sync_blocks_from_tip_without_connected_collator.toml similarity index 100% rename from zombienet_tests/0001-sync_blocks_from_tip_without_connected_collator.toml rename to zombienet/tests/0001-sync_blocks_from_tip_without_connected_collator.toml diff --git a/zombienet_tests/0002-pov_recovery.feature b/zombienet/tests/0002-pov_recovery.feature similarity index 100% rename from zombienet_tests/0002-pov_recovery.feature rename to zombienet/tests/0002-pov_recovery.feature diff --git a/zombienet_tests/0002-pov_recovery.toml b/zombienet/tests/0002-pov_recovery.toml similarity index 100% rename from zombienet_tests/0002-pov_recovery.toml rename to zombienet/tests/0002-pov_recovery.toml diff --git a/zombienet_tests/0003-full_node_catching_up.feature b/zombienet/tests/0003-full_node_catching_up.feature similarity index 100% rename from zombienet_tests/0003-full_node_catching_up.feature rename to zombienet/tests/0003-full_node_catching_up.feature diff --git a/zombienet_tests/0003-full_node_catching_up.toml b/zombienet/tests/0003-full_node_catching_up.toml similarity index 100% rename from zombienet_tests/0003-full_node_catching_up.toml rename to zombienet/tests/0003-full_node_catching_up.toml diff --git a/zombienet_tests/0004-runtime_upgrade.feature b/zombienet/tests/0004-runtime_upgrade.feature similarity index 100% rename from zombienet_tests/0004-runtime_upgrade.feature rename to zombienet/tests/0004-runtime_upgrade.feature diff --git a/zombienet_tests/0004-runtime_upgrade.toml b/zombienet/tests/0004-runtime_upgrade.toml similarity index 100% rename from zombienet_tests/0004-runtime_upgrade.toml rename to zombienet/tests/0004-runtime_upgrade.toml diff --git a/zombienet_tests/0005-migrate_solo_to_para.feature b/zombienet/tests/0005-migrate_solo_to_para.feature similarity index 100% rename from zombienet_tests/0005-migrate_solo_to_para.feature rename to zombienet/tests/0005-migrate_solo_to_para.feature diff --git a/zombienet_tests/0005-migrate_solo_to_para.toml b/zombienet/tests/0005-migrate_solo_to_para.toml similarity index 100% rename from zombienet_tests/0005-migrate_solo_to_para.toml rename to zombienet/tests/0005-migrate_solo_to_para.toml diff --git a/zombienet_tests/0006-rpc_collator_builds_blocks.feature b/zombienet/tests/0006-rpc_collator_builds_blocks.feature similarity index 100% rename from zombienet_tests/0006-rpc_collator_builds_blocks.feature rename to zombienet/tests/0006-rpc_collator_builds_blocks.feature diff --git a/zombienet_tests/0006-rpc_collator_builds_blocks.toml b/zombienet/tests/0006-rpc_collator_builds_blocks.toml similarity index 100% rename from zombienet_tests/0006-rpc_collator_builds_blocks.toml rename to zombienet/tests/0006-rpc_collator_builds_blocks.toml diff --git a/zombienet_tests/migrate_solo_to_para.js b/zombienet/tests/migrate_solo_to_para.js similarity index 100% rename from zombienet_tests/migrate_solo_to_para.js rename to zombienet/tests/migrate_solo_to_para.js diff --git a/zombienet_tests/register-para.js b/zombienet/tests/register-para.js similarity index 100% rename from zombienet_tests/register-para.js rename to zombienet/tests/register-para.js diff --git a/zombienet_tests/runtime_upgrade.js b/zombienet/tests/runtime_upgrade.js similarity index 100% rename from zombienet_tests/runtime_upgrade.js rename to zombienet/tests/runtime_upgrade.js