Devnet Quickstart

This page describes a quickstart method for running pd+cometbft to test changes during development.

To start, you’ll need to install a specific version of CometBFT.

Generating configs

To generate a clean set of configs, run

cargo run --release --bin pd -- testnet generate

This will write configs to ~/.penumbra/testnet_data/.

Running pd

You’ll probably want to set RUST_LOG. Here’s one suggestion that’s quite verbose:

# Optional. Expect about 20GB/week of log data for pd with settings below.
export RUST_LOG="info,pd=debug,penumbra=debug,jmt=debug"

To run pd, run

cargo run --release --bin pd -- start

This will start but won’t do anything yet, because CometBFT isn’t running.

Running cometbft

To run CometBFT, run

cometbft --home ~/.penumbra/testnet_data/node0/cometbft/ start

in another terminal window.

Running pcli

To interact with the chain, configure a wallet pointing at the localhost node:

cargo run --release --bin pcli -- --home ~/.local/share/pcli-localhost view reset
cargo run --release --bin pcli -- init --grpc-url http://localhost:8080 soft-kms generate
# or, to reuse an existing seed phrase:
cargo run --release --bin pcli -- init --grpc-url http://localhost:8080 soft-kms import-phrase

and then pass the --home flag to any commands you run to point pcli at your local node, e.g.,

cargo run --release --bin pcli -- --home ~/.local/share/pcli-localhost view balance

By default, pd testnet generate uses the testnet allocations from the testnets/ directory in the git repo. If you have an address included in those files, then use pcli init soft-kms import-phrase. Otherwise, edit the genesis.json to add your address.

Resetting and restarting

After making changes, you may want to reset and restart the devnet:

cargo run --release --bin pd -- testnet unsafe-reset-all

You’ll probably also want to reset your wallet state:

cargo run --release --bin pcli -- --home ~/.local/share/pcli-localhost view reset

At this point you’re ready to generate new configs, and restart both pd and cometbft. The order they’re started in doesn’t particularly matter for correctness, because cometbft will retry connecting to the ABCI server until it succeeds.

Optional: running smoke-tests

Once you have a working devnet running, you should be able to run the smoke tests successfully. This can be useful if you are looking to contribute to Penumbra, or if you need to check that your setup is correct.

To run the smoke tests:

  1. Make sure you have a devnet running (see previous steps)
  2. Run integration tests:
PENUMBRA_NODE_PD_URL= PCLI_UNLEASH_DANGER=yes cargo test --package pcli -- --ignored --test-threads 1

Find the exact commands for each binary’s smoke tests in deployments/compose/process-compose-smoke-test.yml. You can also run the entire smoke test suite end-to-end via just smoke, including setup and teardown of the network. If you want to execute the tests against an already-running devnet, however, use manual invocations like the cargo test example above. You’ll need to install process-compose to use the automated setup.