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

:information_source: For detailed instructions on how to install Pop CLI, please refer to our documentation: https://learn.onpop.io/v/contracts/welcome/installing-pop-cli

A crates.io version will be available soon!

Telemetry

Pop CLI collects anonymous usage metrics to help us understand how the tool is being used and how we can improve it. We do not collect any personal information. If you wish to disable telemetry or read more about our telemetry practices please see our telemetry documentation.

Getting Started

Parachains

Use pop to create a new Parachain project. To be guided through the entire parachain creation process, simply execute

pop new parachain

If no guidance is needed, proceed with:

# Create a minimal parachain
pop new parachain my-app

pop-cli supports diverse project templates, to use a specific one use the flag --template:

# Create an assets parachain
pop new parachain my-app pop -t assets
# Create a contracts parachain
pop new parachain my-app pop -t contracts
# Create a evm parachain
pop new parachain my-app pop -t evm

We also integrate other provider templates in the tool, check them running:

pop new parachain --help

Some examples are:

# Get Parity's pallet-contracts enabled parachain template
pop new parachain my-app parity -t cpt
# Get Parity's evm compatible parachain template
pop new parachain my-app parity -t fpt

For Pop templates 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

Use pop to build your Parachain:

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

or

cd my-app
pop build parachain

Finally, to build your Parachain:

cd my-app
pop build parachain --release

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

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

Run a command after the network has been spun up

The following will spin up the network locally according the the zombienet file and once the network is up, it will run the command specified in --cmd:

pop up parachain -f ./tests/zombienet.toml -p https://github.com/r0gue-io/pop-node --cmd ./path/to/my/script

Contracts

Use pop to create a new Smart Contract project:

# 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

By default the contract is compiled with debug functionality included.

This enables the contract to output debug messages, but increases the contract size and the amount of gas used.

For production builds, use the --release flag: --release:

pop build contract -p ./my_contract --release

Deploy and instantiate the Smart Contract:

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

:information_source: If you don't specify a live chain, pop will automatically spawn a local node for testing purposes.

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.

:warning: 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. 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

Pallets

To create a new Pallet, simply run pop new pallet. You will have a new pallet 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

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 Smart Contracts functionality:

cargo build --features contract

Testing Pop CLI

To test the tool locally. Due to the time it can take to build a Parachain or a Smart Contract, some tests have been separated from the normal testing flow into integration tests.

Run the unit tests only:

cargo test --lib

To run the integration tests relating to Smart Contracts:

cargo test --test contract

To run the integration tests relating to Parachains:

cargo test --test parachain

Run all tests (unit + integration):

cargo test

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!

License

The entire code within this repository is licensed under the GPLv3.

Please contact us if you have questions about the licensing of our products.