Simple CLI tool to launch a local Polkadot test network.
yarn global add polkadot-launch
Or, if you use npm
:
npm i polkadot-launch -g
To use polkadot-launch, you need to have binary files for a polkadot
relay chain and a
polkadot-collator
.
You can generate these files by cloning the rococo-v1
branch of these projects and building them
with the specific flags below:
git clone https://github.com/paritytech/polkadot
cd polkadot
cargo build --release
and
git clone https://github.com/paritytech/cumulus
cd cumulus
cargo build --release -p polkadot-collator
polkadot-launch config.json
The required configuration file defines the properties of the network you want to set up.
You can see an example here.
bin
: The path of the Polkadot relay chain binary used to setup your test network. For example<path/to/polkadot>/target/release/polkadot
.chain
: The chain you want to use to generate your spec (probablyrococo-local
).nodes
: An array of nodes that will be validators on the relay chain.name
: Must be one ofalice
,bob
,charlie
, ordave
.wsPort
: The websocket port for this node.port
: The TCP port for this node.basePath
: The directory used for the blockchain db and other outputs. When unspecified, we use--tmp
.flags
: Any additional command line flags you want to add when starting your node.
genesis
: A JSON object of the properties you want to modify from the genesis configuration. Non-specified properties will be unchanged from the original genesis configuration.
These variable are fed directly into the Polkadot binary and used to spawn a node:
<bin> \
--chain=<chain>-raw.json \
--tmp \
--ws-port=<wsPort> \
--port=<port> \
--<name> \
An example of genesis
is:
"genesis": {
"runtime": {
"runtime_genesis_config": {
"parachainsConfiguration": {
"config": {
"validation_upgrade_frequency": 1,
"validation_upgrade_delay": 1
}
},
"palletCollective": {
"members": ["5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", "5DbKjhNLpqX3zqZdNBc9BGb4fHU1cRBaDhJUskrvkwfraDi6"]
}
},
"session_length_in_blocks": 10
}
}
All genesis
properties can be found in the chainspec output:
./polkadot build-spec --chain=rococo-local --disable-default-bootnode
parachains
is an array of objects that consists of:
bin
: The path of the collator node binary used to create blocks for your parachain. For example<path/to/substrate-parachain-template>/target/release/polkadot-collator
.id
: The id to assign to this parachain. Must be unique.wsPort
: The websocket port for this node.port
: The TCP port for this node.balance
: (Optional) Configure a starting amount of balance on the relay chain for this chain's account ID.chain
: (Optional) Configure an alternative chain specification to be used for launching the parachain.basePath
: The directory used for the blockchain db and other outputs. When unspecified, we use--tmp
.flags
: Any additional command line flags you want to add when starting your node.
These variables are fed directly into the collator binary and used to spawn a node:
<bin> \
--tmp \
--ws-port=<wsPort> \
--port=<port> \
--parachain-id=<id> \
--validator \
--chain=<chain>
-- \
--chain=<relaychain.chain>-raw.json \
This is similar to parachains
but for "simple" collators like the adder-collator, a very simple
collator that lives in the polkadot repo and is meant just for simple testing. It supports a subset
of configuration values:
bin
: The path to the collator binary.id
: The id to assign to this parachain. Must be unique.port
: The TCP port for this node.balance
: (Optional) Configure a starting amount of balance on the relay chain for this chain's account ID.
Open HRMP channels between the specified parachains so that it's possible to send messages between those. Keep in mind that an HRMP channel is unidirectional and in case you need to communicate both ways you need to open channels in both directions.
"hrmpChannels": [
{
"sender": "200",
"recipient": "300",
"maxCapacity": 8,
"maxMessageSize": 512
}
]
These are the Polkadot JS types you might need to include so that Polkadot JS will be able to interface properly with your runtime.
"types": {
"HrmpChannelId": {
"sender": "u32",
"receiver": "u32"
}
}
Or you can specify a path to the type definition json file instead:
"types": "./typedefs.json"
A simple boolean flag for whether you want to make sure all of the transactions submitted in polkadot-launch wait for finalization.
This tool just automates the steps needed to spin up multiple relay chain nodes and parachain nodes in order to create a local test network.
child_process
is used to execute commands on your node:- We build a fresh chain spec using the
chain
parameter specified in your config.- Includes the authorities you specified.
- Includes changes to the
parachainsConfiguration
. - Includes parachains you have added.
wasm
is generated using the<node> export-genesis-wasm
subcommand.header
is retrieved by callingapi.rpc.chain.getHeader(genesis_hash)
.
- The final file is named
<chain>-raw.json
.
- We spawn new node instances using the information provided in your config. Each node produces a
<name>.log
file in your working directory that you can use to track the output. For example:tail -f alice.log # Alice validator on the relay chain # or tail -f 9988.log # Collator for Parachain ID 200 on wsPort 9988
- We build a fresh chain spec using the
polkadot-js api
is used to connect to these spawned nodes over their WebSocket endpoint.
To work on this project, you will need yarn
.
Install all NodeJS dependencies with:
yarn
Start the application with:
yarn start config.json
When you have finished your changes, make a pull request to this repo.
Open an issue if you have problems or feature requests!