Skip to content

README.md

Latest commit

 

History

History
200 lines (136 loc) · 12.2 KB

README.md

File metadata and controls

200 lines (136 loc) · 12.2 KB
Raw

icp-cli-network-launcher

Launches a local ICP test network powered by PocketIC. Designed as the network backend for icp-cli, but can also be used standalone.

# Start a local network with default settings (application + NNS subnets)
icp-cli-network-launcher --gateway-port=4943

# Start with Bitcoin integration (implicitly enables Internet Identity)
icp-cli-network-launcher --gateway-port=4943 --bitcoind-addr=127.0.0.1:18444

The CLI interface is stable across releases of PocketIC (see SPEC.md), and the primary way pocket-ic is installed for use with icp-cli is by installing icp-cli-network-launcher. The downloadable package contains both the launcher and the pocket-ic binary it supports.

One launcher version is tied to one PocketIC version — if the PocketIC version is a published release, the launcher version matches (e.g. 10.0.0); if it's a git hash, it's added as a tag (e.g. 10.0.0+97ad9167). The launcher expects the pocket-ic binary in the same directory.

CLI Reference

Flags

Flag Type Description
--gateway-port integer Port for the HTTP gateway (ICP API). Random if not set.
--config-port integer Port for the PocketIC admin interface. Random if not set.
--bind IP address Network interface to bind the HTTP gateway on.
--pocketic-config-bind IP address Network interface to bind the PocketIC config API (also called the admin API) on
--domain string Domain for the gateway to respond to
--custom-domains-file path Path to a file for custom domain to canister ID mappings (domain:principal, one per line)
--state-dir path Directory to persist PocketIC state across restarts. Ephemeral if not set.
--artificial-delay-ms integer Artificial delay for update call execution (ms).
--subnet enum Subnet to add. Can be specified multiple times. See Subnet Configuration.
--bitcoind-addr host:port Bitcoin P2P node address. Can be specified multiple times. See Bitcoin/Dogecoin.
--dogecoind-addr host:port Dogecoin P2P node address. Can be specified multiple times. See Bitcoin/Dogecoin.
--ii flag Enable Internet Identity. See Internet Identity.
--nns flag Enable NNS and SNS. See NNS.
--interface-version semver Expected CLI interface version. Also read from ICP_CLI_NETWORK_LAUNCHER_INTERFACE_VERSION env var. Used by automated setups.
--status-dir path Directory to write the status file to. Used by automated setups.
--verbose flag Enable verbose logging from PocketIC.

Subnet Configuration

Subnets fall into two independent categories:

Always-on base topology — created unconditionally, not affected by --subnet:

  • NNS — required for system operations.
  • fiduciary — mirrors the mainnet topology.
  • test-threshold-keys — provides test_key_1 and dfx_test_key for all threshold algorithms (ECDSA, Schnorr, and VetKd).

Workload subnets — selected with the --subnet flag. Available types: application, system, verified-application, bitcoin, sns.

Default behavior:

  • With no --subnet flags: one application subnet is created (in addition to the base topology).
  • With any --subnet flag: the default application subnet is not created; only the workload subnets you specify are added.

--subnet=nns and --subnet=fiduciary are still accepted for backward compatibility but have no effect, since those subnets are always created. --subnet=test-threshold-keys is not a valid value.

Examples:

# Default: NNS + fiduciary + TestThresholdKeys + application
icp-cli-network-launcher

# Two application subnets (NNS + fiduciary + TestThresholdKeys always included)
icp-cli-network-launcher --subnet=application --subnet=application

# System + application (NNS + fiduciary + TestThresholdKeys always included)
icp-cli-network-launcher --subnet=system --subnet=application

# Only system (no application subnet!) + NNS + fiduciary + TestThresholdKeys
icp-cli-network-launcher --subnet=system

Internet Identity

The --ii flag creates an II subnet and installs the Internet Identity canister.

The II subnet and canister are also implicitly enabled when any of the following are used:

  • --nns

NNS

The --nns flag installs the NNS (Network Nervous System) and SNS (Service Nervous System). It has the following effects:

  • Creates an SNS subnet
  • Creates an II subnet (implies --ii)
  • Enables NNS governance, NNS UI, SNS, and canister migration features

Bitcoin and Dogecoin Integration

The --bitcoind-addr and --dogecoind-addr flags connect the network to external Bitcoin or Dogecoin nodes for chain integration testing.

Implicit effects:

  • A bitcoin subnet is automatically created (shared by both Bitcoin and Dogecoin)
  • The respective chain feature (bitcoin or dogecoin) is enabled

Address format: host:port — this is the P2P address of the node, not the RPC address.

Examples:

# Connect to a local Bitcoin node
icp-cli-network-launcher --bitcoind-addr=127.0.0.1:18444

# Connect to both Bitcoin and Dogecoin nodes
icp-cli-network-launcher --bitcoind-addr=127.0.0.1:18444 --dogecoind-addr=127.0.0.1:22556

# Multiple Bitcoin nodes
icp-cli-network-launcher --bitcoind-addr=127.0.0.1:18444 --bitcoind-addr=192.168.1.5:18444

Interaction Summary

The following table summarizes the subnets created for common configurations. NNS, fiduciary, and TestThresholdKeys subnets are always present regardless of flags.

Configuration Subnets created
(no flags) NNS, fiduciary, TestThresholdKeys, application
--ii NNS, fiduciary, TestThresholdKeys, application, II
--nns NNS, fiduciary, TestThresholdKeys, application, II, SNS
--bitcoind-addr=... NNS, fiduciary, TestThresholdKeys, application, bitcoin
--dogecoind-addr=... NNS, fiduciary, TestThresholdKeys, application, bitcoin
--subnet=system NNS, fiduciary, TestThresholdKeys, system
--subnet=system --bitcoind-addr=... NNS, fiduciary, TestThresholdKeys, system, bitcoin
--nns --subnet=system NNS, fiduciary, TestThresholdKeys, system, II, SNS

Key points:

  • NNS, fiduciary, and TestThresholdKeys are always present — they cannot be omitted.
  • Specifying any --subnet flag replaces the default application subnet. Add --subnet=application explicitly if you still need it.
  • --bitcoind-addr and --dogecoind-addr always add a bitcoin subnet, regardless of --subnet flags.
  • --nns always adds an SNS subnet and an II subnet, regardless of --subnet flags.
  • Threshold signature keys (test_key_1, dfx_test_key) are always available via the TestThresholdKeys subnet — --ii is not required for threshold signing.

Status File

When --status-dir is provided, the launcher writes a JSON status file (status.json) to the specified directory once the network is ready. This is used by icp-cli and other automated setups to discover the running network.

Field Type Description
v string Status file format version. Currently "1".
gateway_port number Port where the HTTP gateway (ICP API) is listening.
root_key string Hex-encoded root key of the network.
config_port number Port of the PocketIC admin interface.
instance_id number PocketIC instance ID.
default_effective_canister_id string Default effective canister ID for provisional canister creation calls.

Shutdown

The launcher handles SIGINT (Ctrl+C) and SIGTERM for graceful shutdown. It stops the PocketIC server and waits for it to exit before terminating.

Once the network is gone, the launcher empties the status directory — the status file's absence is how automated setups learn the network stopped — and then removes the directory itself if it can. A bind-mounted status dir, as with the Docker image, cannot be removed and is left behind empty.

Experimental features

If the launcher is built with --feature cloud-engine, you can create subnets of type cloud-engine. The subnet admin is set to the anonymous principal. The :engine-beta Docker tag is an alternative to the standard image with this feature enabled.

Installing

icp-cli-network-launcher is typically installed automatically by icp-cli. It can be updated to the latest version with icp network update.

Binary downloads are also available on the releases page.

A Docker image is published under the name ghcr.io/dfinity/icp-cli-network-launcher. The container port 4943 should be published for gateway access, and if a status dir is needed, mount it at /app/status.

Development

Prerequisites

  • Rust v1.90 or later. If you have Rustup installed it will automatically use the right version.
  • Bash, jq, and curl for the package.sh script.

Building

./package.sh [directory]

This will build the code, download the appropriate version of pocket-ic, and place it in a destination folder. If you do not supply a folder it will use dist/icp-cli-network-launcher-<VERSION> and additionally create a tarball.

Testing

cargo test

The Docker image is checked separately, since container mode has failure modes no test on the host reaches — the launcher runs as PID 1 and its status dir is a bind mount:

docker build -t launcher:smoke .
./scripts/smoke-test-image.sh launcher:smoke

This starts the image with a bind-mounted status dir the way icp-cli does, shuts it down with SIGINT, and checks that the network came up and the shutdown was clean. CI runs the same script against every image variant on each pull request.

License

This project is licensed under the Apache-2.0 license.

Contribution

This project does not accept external contributions. Pull requests from individuals outside the organization will be automatically closed.