polkadot-launch

Simple CLI tool to launch a local Polkadot test network.

Install

npm i polkadot-launch -g

Use

polkadot-launch config.json

Configuration File

The required configuration file defines the properties of the network you want to set up.

The file has two section: relaychain and parachains. You can see an example here.

relaychain

• 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 (probably rococo-local).
• nodes: An array of nodes that will be validators on the relay chain.
  • name: Must be one of alice, bob, charlie, or dave.
  • wsPort: The websocket port for this node.
  • port: The TCP port for this node.

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> \

parachains

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.

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 \

How Does It Work?

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. This will include the authorities you specified. 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 200.log # Collator for Parachain ID 200

• polkadot-js api is used to connect to these spawned nodes over their WebSocket endpoint.
  • api.rpc.system.localPeerId() is used to retrieve the node's PeerId.
  • api.rpc.system.peers() is used to retrieve connected peers to a node.
  • api.tx.sudo.sudo(api.tx.registrar.registerPara(id, always, wasm, header)) is used to register a parachain.
    • wasm is generated using the <node> export-genesis-wasm subcommand.
    • header is retrieved by calling api.rpc.chain.getHeader(genesis_hash).

Development

To work on this project, you will need yarn.

Install all NodeJS dependencies with:

yarn

This project uses ES6 syntax, which means we need to transpile it to NodeJS compatible JavaScript with babel.

To do this, you just run:

yarn build

This will create a dist folder with JavaScript that you can run with node.

These steps can be done for you automatically by running:

yarn start

When you have finished your changes, make a pull request to this repo.

Get Help

Open an issue if you have problems or feature requests!