Pop CLI

An all-in-one tool for Polkadot development.

Install

You can install Pop CLI as follows:

cargo install --locked --git https://github.com/r0gue-io/pop-cli

ℹ️ A crates.io version will be available soon!

Getting Started

Parachains

Use pop to generate a new parachain from a template:

# Create a minimal parachain
pop new parachain my-app
# Get a pallet-contracts enabled parachain
pop new parachain my-app cpt
# Get a evm compatible parachain
pop new parachain my-app fpt

Use pop to build your parachain.

# Build your parachain
pop build parachain -p ./my-app

or

cd my-app
pop build parachain

You can also customize your parachain by providing config options for token symbol (as it appears in chain metadata), token decimals, and the initial endowment for developer accounts. Here's how:

# Create a minimal parachain with "DOT" as token symbol, 6 token decimals and 1 billion tokens per dev account
pop new parachain my-app --symbol DOT --decimals 6 --endowment 1_000_000_000

There's also the shorter version:

pop new parachain my-app -s DOT -d 6 -i 1_000_000_000

To create a new pallet, simply pop new pallet. And that's it. You will have a new pallet-template ready for hacking. To customize the new pallet you can follow these options:

# create a pallet with name `pallet-awesome` in the current working directory
pop new pallet pallet-awesome
# or with options
pop new pallet pallet-awesome --authors Me --description "This pallet oozes awesomeness" --path my_app/pallets

Finally, you would need to build and run it.

cd my-app
pop build parachain --release

For running any parachain, we recommend using zombienet. See below for more information about using pop up parachain to help you with this.

Contracts

Use pop to create a smart contract:

# Create a minimal smart contract
pop new contract my_contract

Test the smart contract:

# Test an existing smart contract
pop test contract -p ./my_contract

Build the smart contract:

# Build an existing smart contract
pop build contract -p ./my_contract

To deploy a contract you need your chain running. For testing purposes one option is to run substrate-contracts-node:

cargo install contracts-node
substrate-contracts-node

ℹ️ We plan to automate this in the future.

Deploy and instantiate the smart contract:

pop up contract -p ./my_contract --constructor new --args "false" --suri //Alice

Some of the options available are:

• Specify the contract constructor to use, which in this example is new().
• Specify the argument (args) to the constructor, which in this example is false.
• Specify the account uploading and instantiating the contract with --suri, which in this example is the default development account of //Alice. For other accounts, the actual secret key must be provided e.g. an 0x prefixed 64 bit hex string, or the seed phrase.

⚠️ Use only for development: Use a safer method of signing here before using this feature with production projects. We will be looking to provide alternative solutions in the future!

• You also can specify the url of your node with --url ws://your-endpoint, by default it is using ws://localhost:9944.

For more information about the options, check cargo-contract documentation

Interacting with the Smart Contract:

1. Read-only Operations: For operations that only require reading from the blockchain state. This approach does not require to submit an extrinsic (skip the flag x/--execute). Example using the get() message:

pop call contract -p ./my_contract --contract $INSTANTIATED_CONTRACT_ADDRESS --message get --suri //Alice

2. State-modifying Operations: For operations that change a storage value, thus altering the blockchain state. Include the x/--execute flag to submit an extrinsic on-chain.

Example executing the flip() message:

pop call contract -p ./my_contract --contract $INSTANTIATED_CONTRACT_ADDRESS --message flip --suri //Alice -x

E2E testing

For end-to-end testing you will need to have a Substrate node with pallet contracts. You do not need to run it in the background since the node is started for each test independently. To install the latest version:

cargo install contracts-node --git https://github.com/paritytech/substrate-contracts-node.git

If you want to run any other node with pallet-contracts you need to change CONTRACTS_NODE environment variable:

export CONTRACTS_NODE="YOUR_CONTRACTS_NODE_PATH"

Run e2e testing on the smart contract:

# Run e2e tests for an existing smart contract
 pop test contract  -p ./my_contract --features e2e-tests

Building Pop CLI locally

Build the tool locally with all the features:

cargo build --all-features

Build the tool only for parachain functionality:

cargo build --features parachain

Build the tool only for contracts functionality:

cargo build --features contract

Spawn Network using Zombienet

You can spawn a local network using zombienet as follows:

pop up parachain -f ./tests/zombienet.toml -p https://github.com/r0gue-io/pop-node

ℹ️ Pop CLI will automatically source the necessary polkadot binaries. Currently, these will be built if on a non-linux system.

Testing Pop CLI

To test the tool locally.

Run the unit tests:

cargo test

Due to the time it can take to build a test or a contract some tests has been separate to the normal testing flow.

To run the unit tests that involves building a contract:

cargo test --features unit_contract

To run the unit tests that involves building a parachain:

cargo test --features unit_parachain

Then we have some tests that check all the flow is correct:

Run the e2e tests for contracts functionality:

cargo test --features e2e_contract

Run the e2e tests for parachain functionality:

cargo test --features e2e_parachain

Run all tests:

cargo test --all-features

Acknowledgements

Pop CLI would not be possible without these awesome crates!

• Local network deployment powered by zombienet-sdk
• cargo contract a setup and deployment tool for developing Wasm based smart contracts via ink!