Penumbra

https://guide.penumbra.zone
Admin
Penumbra is a fully private, cross-chain proof-of-stake L1 blockchain and decentralized exchange for...
Tokens:22,937
Snippets:411
Trust Score:8.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Configure Local Development Environment

Source: https://guide.penumbra.zone/network/frontend/minifront

Setup the Buf registry and start the local development server.

```bash
npm config set @buf:registry https://buf.build/gen/npm/v1/
```

```bash
pnpm install
pnpm dev
# Will be live at https://localhost:5173/
```

--------------------------------

### Build and Start Production Cuiloa

Source: https://guide.penumbra.zone/network/frontend/noctis

Build Cuiloa for production and start the server. This command assumes normal build on your machine and will make the application accessible at http://localhost:3000.

```bash
npm run build && npm run start
```

--------------------------------

### Install protoc binary

Source: https://guide.penumbra.zone/dev/protobuf

Extract the protoc zip file to a directory on your system PATH.

```bash
unzip protoc-24.4-linux-x86_64.zip -d ~/.local/
```

--------------------------------

### Install pcli using script

Source: https://guide.penumbra.zone/usage/pcli/install

Use this one-liner script to download and install the latest pcli binary. Ensure your system is compatible with precompiled binaries.

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/penumbra-zone/penumbra/releases/latest/download/pcli-installer.sh | sh
```

--------------------------------

### Serve Protocol Docs with mdBook

Source: https://guide.penumbra.zone/dev/docs

Navigate to the protocol documentation directory and run this command to serve the docs locally. Requires mdBook to be installed.

```bash
cd docs/protocol
mdbook serve
```

--------------------------------

### Install macOS Build Prerequisites

Source: https://guide.penumbra.zone/dev/build

Installs necessary tools like Xcode command-line tools and Git LFS on macOS. Ensure Git LFS is initialized after installation.

```bash
xcode-select --install
brew install git-lfs
git lfs install
```

--------------------------------

### Start Local Firebase Emulator

Source: https://guide.penumbra.zone/dev/docs

Use this command to start a local webserver for debugging Firebase-specific functionality, such as redirects. Livereload requires rebuilding docs with appropriate tooling.

```bash
firebase emulators:start
```

--------------------------------

### Run Cuiloa Development Server

Source: https://guide.penumbra.zone/network/frontend/noctis

Start a development version of Cuiloa using npm. The application will be accessible at http://localhost:3000.

```bash
npm run dev
```

--------------------------------

### Verify pcli installation

Source: https://guide.penumbra.zone/usage/pcli/install

After installation, run this command to confirm that the pcli binary has been successfully installed and to check its version.

```bash
pcli --version
```

--------------------------------

### Set up Direnv for Automatic Environment Activation

Source: https://guide.penumbra.zone/dev/dev-env

Copy the example .envrc file and allow direnv to manage the Penumbra Nix environment automatically. This avoids manually running 'nix develop' in new terminals.

```bash
cp .envrc.example .envrc
direnv allow
```

--------------------------------

### Run Cuiloa with Docker Compose

Source: https://guide.penumbra.zone/network/frontend/noctis

Use this command to start a development instance of Cuiloa using Docker Compose. Navigate to http://localhost:3000 to view the application.

```bash
docker compose up
```

--------------------------------

### Open a Buy Liquidity Position

Source: https://guide.penumbra.zone/usage/pcli/transaction

Create a liquidity position to buy a specified amount of one asset at a given price for another asset. No fee is applied in this example.

```bash
pcli tx position order buy 10cube@1penumbra
```

--------------------------------

### Interact with Local Penumbra Node using pcli

Source: https://guide.penumbra.zone/dev/devnet-quickstart

Example of using `pcli` to view balances on the local devnet, ensuring the `--home` flag points to the correct wallet state.

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

--------------------------------

### Activate Penumbra Nix Development Environment

Source: https://guide.penumbra.zone/dev/dev-env

Navigate to the Penumbra directory and activate the development environment using 'nix develop'. This command builds and installs project dependencies and tooling.

```bash
cd penumbra
nix develop
```

--------------------------------

### Start CometBFT for archive node

Source: https://guide.penumbra.zone/network/relayers

Run CometBFT with specific flags to disable peer exchange and seeds, isolating the node for archival purposes.

```bash
cometbft --p2p.pex=false --p2p.seeds='' --p2p.persistent_peers='' --p2p.laddr="tcp://127.0.0.1:26656" --moniker archive-node-1
```

--------------------------------

### Start Hermes Relayer for Devnet

Source: https://guide.penumbra.zone/dev/ibc

Start the Hermes relayer to begin relaying IBC messages between chains for a local devnet. Ignore spurious errors about missing Penumbra keys if fees are not yet implemented.

```bash
cargo run --release --bin hermes -- --config config-devnet-osmosis.toml start
```

--------------------------------

### Run Penumbra Smoke Tests

Source: https://guide.penumbra.zone/dev/devnet-quickstart

Executes integration tests against a running devnet, useful for contributing to Penumbra or verifying setup.

```bash
PENUMBRA_NODE_PD_URL="http://127.0.0.1:8080" cargo test --release --features sct-divergence-check,download-proving-keys --package pcli -- --ignored --test-threads 1 --nocapture
```

--------------------------------

### Centralized Key Generation

Source: https://guide.penumbra.zone/usage/pcli/wallet/threshold

Generates key shares and configures pcli for a threshold setup. Specify the threshold `<T>` and provide home directories for each party. Run on a secure, disposable computer.

```bash
pcli init threshold deal --threshold <T> --home <HOME1> --home <HOME2> ...
```

--------------------------------

### Encrypted Config Generation

Source: https://guide.penumbra.zone/usage/pcli/wallet/threshold

Generates an encrypted configuration for threshold key shares using a password. This command is used during the initial setup.

```bash
$ pcli init --encrypted threshold dkg ...
```

--------------------------------

### Configure Penumbra View Database Storage in Hermes

Source: https://guide.penumbra.zone/network/relayers

Configure on-disk persistence for the Penumbra view database by specifying a directory in your `config.toml`. Ensure the directory exists before starting Hermes. This prevents the need for lengthy chain resyncs on startup.

```toml
# Update the path below as appropriate for your system,
# and make sure to create the directory before starting Hermes.
view_service_storage_dir = "/home/hermes/.local/share/pcli-hermes-1"
```

--------------------------------

### Reset Local Penumbra Network State

Source: https://guide.penumbra.zone/dev/devnet-quickstart

Stops the running node and destroys the local network state, preparing for a fresh start.

```bash
# stop the running node via process-compose:
ctrl+c
# destroy local network state:
cargo run --release --bin pd -- network unsafe-reset-all
```

--------------------------------

### pcli GLIBC error example

Source: https://guide.penumbra.zone/usage/pcli/install

This error message indicates that your system's GLIBC version is too old for the precompiled pcli binaries. You may need to build from source or use a supported platform.

```text
pcli: /lib/x86_64-linux-gnu/libstdc++.so.6: version `GLIBCXX_3.4.30' not found (required by pcli)
pcli: /lib/x86_64-linux-gnu/libstdc++.so.6: version `GLIBCXX_3.4.29' not found (required by pcli)
pcli: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.32' not found (required by pcli)
pcli: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by pcli)
pcli: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.33' not found (required by pcli)
```

--------------------------------

### Import Existing Seed Phrase to pcli

Source: https://guide.penumbra.zone/dev/testnet

Initialize a Penumbra client (pcli) wallet by importing an existing seed phrase. This is useful for reusing a wallet across different setups or nodes, ensuring the gRPC endpoint is correctly set.

```bash
# or, to reuse an existing seed phrase:
cargo run --release --bin pcli -- init --grpc-url https://testnet.plinfra.net soft-kms import-phrase
```

--------------------------------

### Initialize Validator Governance Subkey

Source: https://guide.penumbra.zone/usage/pcli/wallet

After initializing the main wallet, use this command to set up a separate custody backend for the validator's governance signing key. Requires choosing between `soft-kms` or `threshold` backends.

```bash
pcli init validator-governance-subkey
```

--------------------------------

### Deploy Minifront to Netlify

Source: https://guide.penumbra.zone/network/frontend/minifront

Use the Netlify CLI to deploy the static dist folder.

```bash
npm install netlify-cli -g # install the netlify cli
netlify login
cd ./dist
netlify deploy
```

--------------------------------

### View pcli linear liquidity help

Source: https://guide.penumbra.zone/usage/lp

Displays the help menu for the linear liquidity replication command.

```bash
pcli tx lp replicate linear --help
```

--------------------------------

### Run circuit benchmarks

Source: https://guide.penumbra.zone/dev/parameter_setup

Execute this command within the project to benchmark all proofs defined in the penumbra-bench crate.

```bash
cargo bench
```

--------------------------------

### Deploy Minifront to Github Pages

Source: https://guide.penumbra.zone/network/frontend/minifront

Manually push the static dist folder to a GitHub Pages repository.

```bash
git clone https://github.com/roboto7237/roboto7237.github.io
cp -r ./dist/* ./roboto7237.github.io/ # copies all minifront code into the new folder
git add --all
git commit -m "Initial commit"
git push -u origin main
```

--------------------------------

### Run zk-SNARK ceremony benchmarks

Source: https://guide.penumbra.zone/dev/parameter_setup

Navigate to the proof-setup directory to run performance benchmarks specifically for the zk-SNARK ceremony.

```bash
cd crates/crypto/proof-setup
cargo bench
```

--------------------------------

### Initialize and Configure Local pcli Wallet

Source: https://guide.penumbra.zone/dev/devnet-quickstart

Initializes a new `pcli` wallet or imports an existing seed phrase, pointing to the local devnet GRPC endpoint.

```bash
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
```

--------------------------------

### Deploy Minifront to Vercel

Source: https://guide.penumbra.zone/network/frontend/minifront

Use the Vercel CLI to deploy the static dist folder.

```bash
npm i -g vercel # install the Vercel cli
vercel login
vercel ./dist
```

--------------------------------

### Prepare archive node environment

Source: https://guide.penumbra.zone/network/relayers

Commands to migrate the node state and move the existing CometBFT address book to prevent peer discovery interference.

```bash
pd migrate --ready-to-start
```

```bash
mv ~/.penumbra/network_data/node0/cometbft/config/addrbook.json{,.bak}
```

--------------------------------

### Build Rust API Docs

Source: https://guide.penumbra.zone/dev/docs

Execute this script to build the Rust API documentation. Note that this requires a nightly Rust toolchain.

```bash
./deployments/scripts/rust-docs
```

--------------------------------

### Perform concurrent full sync with measure tool

Source: https://guide.penumbra.zone/dev/metrics

Simulate multiple client connections to test metrics under load.

```bash
cargo run --release --bin measure -- --node http://127.0.0.1:8080 open-connections --num-connections 50 --full-sync
```

--------------------------------

### Create Buy Orders

Source: https://guide.penumbra.zone/usage/lp

Execute a buy order using the lp order buy command, which creates a position with initial reserves.

```bash
pcli tx lp order buy 100gm@2gn --auto-close # sells 200gn at 0.5gm per gn, closing on fill
```

--------------------------------

### Initialize PostgreSQL Database Schema

Source: https://guide.penumbra.zone/network/frontend/noctis

Load the CometBFT schema into your PostgreSQL database using the psql command. Replace `$DB_NAME` with your actual database name.

```bash
psql -d $DB_NAME -f schema.sql
```

--------------------------------

### Equivalent Sell Order Representation

Source: https://guide.penumbra.zone/usage/lp

Demonstrates that buy and sell orders are protocol-equivalent, showing the underlying sell order representation of a buy order.

```bash
pcli tx lp order sell 200gn@0.5gm --auto-close
```

--------------------------------

### Configure CometBFT Indexer

Source: https://guide.penumbra.zone/network/event-indexing/configure

Update the config.toml file to enable the psql indexer and provide the connection string.

```toml
indexer = "psql"
psql-conn = "<DATABASE_URL>"
```

--------------------------------

### Migrate Wallet Balance

Source: https://guide.penumbra.zone/usage/pcli/migrating

Use this command to initiate the migration of all assets from the current wallet to a destination wallet. You will be prompted to enter the full viewing key (FVK) of the destination wallet.

```bash
pcli migrate balance
```

--------------------------------

### Open a Sell Liquidity Position with Fee

Source: https://guide.penumbra.zone/usage/pcli/transaction

Establish a liquidity position to sell a specified amount of one asset at a given price for another, including a transaction fee. The fee is appended with `/bps`.

```bash
pcli tx position order sell 100penumbra@5gm/20bps
```

--------------------------------

### Viewing asset balances

Source: https://guide.penumbra.zone/usage/pcli/balance

Displays a table of assets and their respective balances in the wallet.

```bash
pcli view balance
```

--------------------------------

### Configure Nix for Flakes

Source: https://guide.penumbra.zone/dev/dev-env

Configure Nix to enable experimental features like Nix command and flakes. This involves creating a configuration file in the user's Nix directory.

```bash
mkdir -p ~/.config/nix
echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
```

--------------------------------

### Download asset registry

Source: https://guide.penumbra.zone/usage/lp

Downloads the Prax wallet registry to the local pcli configuration directory.

```bash
wget -O PATH/TO/PCLI_HOME/registry.json https://raw.githubusercontent.com/prax-wallet/registry/main/registry/chains/penumbra-1.json
```

--------------------------------

### Create Limit Orders with pcli

Source: https://guide.penumbra.zone/usage/lp

Create liquidity positions that replicate limit order behavior. Specify fees using the bps suffix if required.

```bash
pcli tx lp order sell 100gm@1gn # sells 100 gm at 1 gn per gm
pcli tx lp order sell 100gm@1gn/50bps # sells 100gm at 1 gn per gm, with 50bps fee
```

--------------------------------

### Initialize Testnet pcli Wallet

Source: https://guide.penumbra.zone/dev/testnet

Initialize a Penumbra client (pcli) wallet configured to point at the testnet node. This command generates a new wallet using soft-kms and specifies the gRPC endpoint.

```bash
cargo run --release --bin pcli -- --home ~/.local/share/pcli-testnet view reset
cargo run --release --bin pcli -- init --grpc-url https://testnet.plinfra.net soft-kms generate
```

--------------------------------

### Generate circuit parameters

Source: https://guide.penumbra.zone/dev/parameter_setup

Use this command to generate proving and verifying keys for all circuits during development.

```bash
cargo run --release --bin penumbra-parameter-setup
```

--------------------------------

### Execute Protocol Release

Source: https://guide.penumbra.zone/dev/release

Run the cargo release command to prepare the version update.

```bash
cargo release --no-publish --execute 1.2.3
```

--------------------------------

### Initialize Encrypted Soft-KMS Wallet

Source: https://guide.penumbra.zone/usage/pcli/wallet/softkms

Initialize a new or import an existing wallet with an encrypted configuration using the `--encrypted` flag. You will be prompted for a password.

```bash
$ pcli init --encrypted soft-kms ...
```

--------------------------------

### Download Testnet Snapshot

Source: https://guide.penumbra.zone/dev/testnet

Fetch the most recent snapshot to backfill blocks from before the latest testnet chain upgrade. Ensure the target directory `~/.penumbra/network_data/node0/` exists or is created.

```bash
curl -O https://artifacts.plinfra.net/penumbra-testnet-phobos-2/penumbra-node-archive-latest.tar.gz
tar -xzf penumbra-node-archive-latest.tar.gz -C ~/.penumbra/network_data/node0/
```

--------------------------------

### Configure CometBFT Indexer for PostgreSQL

Source: https://guide.penumbra.zone/network/frontend/noctis

Update the `config.toml` file for your Penumbra node to use PostgreSQL as the transaction indexer. Replace `$YOUR_DB_URI_HERE` with your actual database connection URI.

```toml
[tx_index]
indexer = "psql"
psql-conn = "$YOUR_DB_URI_HERE"
```

--------------------------------

### Run Pindexer

Source: https://guide.penumbra.zone/network/event-indexing/pindexer

Executes the pindexer command using the original genesis file and source/destination database URLs.

```bash
pindexer --genesis-json <ORIGINAL_GENESIS_FILE> --src-database-url postgresql://localhost:5432/$DATABASE_NAME --dst-database-url postgresql://localhost:5432/$PINDEXER_DB
```

--------------------------------

### Generate a signaling proposal template

Source: https://guide.penumbra.zone/usage/pcli/governance

Creates a TOML file containing default fields for a signaling proposal.

```bash
pcli tx proposal template signaling --file proposal.toml
```

--------------------------------

### Submit a proposal

Source: https://guide.penumbra.zone/usage/pcli/governance

Submits a proposal using the configuration defined in the specified TOML file.

```bash
pcli tx proposal submit --file proposal.toml
```

--------------------------------

### Create linear liquidity positions

Source: https://guide.penumbra.zone/usage/lp

Invokes pcli to create 5 liquidity positions across a specified price range for a trading pair.

```bash
$ pcli tx lp replicate linear upenumbra:transfer/channel-2/uusdc 100000000transfer/channel-2/uusdc --lower-price 1.8 --upper-price 2.2 --fee-bps 100 --num-positions 5
```

--------------------------------

### Run Local Penumbra Devnet

Source: https://guide.penumbra.zone/dev/devnet-quickstart

Builds the local Rust code, generates genesis files, and runs the Penumbra fullnode (`pd`) and Tendermint (`cometbft`).

```bash
just dev
```

--------------------------------

### Configure PostgreSQL Database URI

Source: https://guide.penumbra.zone/network/frontend/noctis

Create a .env file to store your PostgreSQL database connection URI. Ensure all placeholders are replaced with your specific database credentials and port.

```dotenv
DATABASE_URL="postgresql://DB_USER:DB_PASSWORD@localhost:DB_PORT/DB_NAME?sslmode=disable"
```

--------------------------------

### Syncing the Penumbra client

Source: https://guide.penumbra.zone/usage/pcli/balance

Synchronizes the local wallet state with the chain. This may take a few minutes on the initial run.

```bash
pcli view sync
```

--------------------------------

### Build Snappy Static Library

Source: https://guide.penumbra.zone/dev/build

Compiles the Snappy static library (`libsnappy.a`) from source using CMake. This is an optional step for optimizing storage libraries. Ensure the `SNAPPY_LIB_DIR` environment variable points to the build directory.

```bash
# Clone the repository, and enter that directory.
git clone git@github.com:google/snappy.git && cd snappy

# Checkout the version of snappy used in `librocksdb-sys`.
git checkout 2b63814

# Initialize the submodules.
git submodule update --init

# Build snappy using cmake.
mkdir build
cd build && cmake ../ -DSNAPPY_BUILD_BENCHMARKS=OFF && make

# Add an environment variable pointing to the build/ directory.
SNAPPY_LIB_DIR=`pwd`
```

--------------------------------

### Inspect SQLite database schema and data

Source: https://guide.penumbra.zone/dev/sql

Use the sqlite3 CLI to open the database and inspect the 'tx' table structure and contents.

```bash
$ sqlite3 ~/.local/share/pcli/pcli-view.sqlite
sqlite> PRAGMA table_info(tx);
0|tx_hash|BLOB|1||1
1|tx_bytes|BLOB|1||0
2|block_height|BIGINT|1||0
3|return_address|BLOB|0||0

sqlite> SELECT json_object('tx_hash', quote(tx_hash)) FROM tx;
{"tx_hash":"X'14672F89F5B197C45D85189AE5A24C47F4F22417B5DC33B50FD263DE2E10BFD3'"}
{"tx_hash":"X'DCA7DB158D93372A0ED335924B05946F336C28BC76AC90BABEF4E1466022D2D2'"}
```

--------------------------------

### Query proposal details

Source: https://guide.penumbra.zone/usage/pcli/governance

General command structure for querying specific information about a proposal.

```bash
pcli query governance proposal [PROPOSAL_ID] [QUERY]
```

--------------------------------

### Import Existing Soft-KMS Wallet

Source: https://guide.penumbra.zone/usage/pcli/wallet/softkms

Import an existing wallet into the softkms backend using your seed phrase. You will be prompted to enter the seed phrase.

```bash
$ pcli init soft-kms import-phrase
Enter seed phrase:
Writing generated config to [PATH TO PCLI DATA]
```

--------------------------------

### Build Penumbra Binaries

Source: https://guide.penumbra.zone/dev/build

Compiles all project binaries in release mode using Cargo. This command should be run from the root of the cloned repository.

```bash
cargo build --release
```

--------------------------------

### View Balance After Opening Position

Source: https://guide.penumbra.zone/usage/pcli/transaction

After opening a liquidity position, check your balance to see the newly minted LPNFT representing the open position.

```bash
$ pcli view balance

 Account  Amount
 0        1lpnft_opened_plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr
```

--------------------------------

### Generate protobuf code

Source: https://guide.penumbra.zone/dev/protobuf

Execute the codegen script from the repository root to generate protobuf files.

```bash
./deployments/scripts/protobuf-codegen
```

--------------------------------

### Stream compact blocks with measure tool

Source: https://guide.penumbra.zone/dev/metrics

Use the measure tool to verify metrics by streaming blocks from a node.

```bash
cargo run -q --release --bin measure -- --node http://127.0.0.1:8080 stream-blocks
```

--------------------------------

### Identify Account from Address

Source: https://guide.penumbra.zone/usage/pcli/wallet

Use `pcli view address` with a Penumbra address to determine its associated account index. This requires having the viewing key.

```bash
$ pcli view address penumbra1...
Address is viewable with this full viewing key. Account index is 0.
```

--------------------------------

### Join Penumbra Testnet

Source: https://guide.penumbra.zone/dev/testnet

Generate network configurations for the testnet chain by joining the public testnet endpoint. This command initializes node state directories locally.

```bash
# generate network configs for the testnet chain
cargo run --release --bin pd -- network join http://testnet.plinfra.net:26657
```

--------------------------------

### Apply CometBFT Schema to Postgres

Source: https://guide.penumbra.zone/network/event-indexing/configure

Use the psql command to apply the required schema to your configured database.

```bash
psql -d <DATABASE_URL> -f <path/to/schema.sql>
```

--------------------------------

### Swap Assets

Source: https://guide.penumbra.zone/usage/pcli/transaction

Executes a private token swap against on-chain liquidity positions.

```bash
pcli tx swap --into gm 1penumbra
```

--------------------------------

### View Account Balance with pcli

Source: https://guide.penumbra.zone/dev/ibc

Use this command to check the available funds in your account on the Penumbra network. Ensure the pcli binary is built and the network endpoint is correct.

```bash
cargo run --release --bin pcli -- -n http://localhost:8080 view balance
```

--------------------------------

### Checkout Specific Penumbra Tag

Source: https://guide.penumbra.zone/dev/build

Navigates into the cloned repository and checks out a specific release tag for building compatible binaries. Replace `<TAG>` with the desired version.

```bash
cd penumbra && git fetch && git checkout <TAG>
```

--------------------------------

### Claim Proposal Deposit

Source: https://guide.penumbra.zone/usage/pcli/governance

Use this command to claim your proposal deposit for a concluded proposal. This action consumes the proposal deposit NFT and returns a proposal result NFT.

```bash
pcli tx proposal deposit-claim 1
```

--------------------------------

### Build RocksDB Static Library

Source: https://guide.penumbra.zone/dev/build

Compiles the RocksDB static library (`librocksdb.a`) from source. This is an optional step to optimize development builds. Ensure the `ROCKSDB_LIB_DIR` environment variable is set to the repository's root directory.

```bash
# Clone the repository, and enter that directory.
git clone git@github.com:facebook/rocksdb.git && cd rocksdb

# Checkout the version of rocksdb used in `librocksdb-sys`.
git checkout 6a43615

# Add an environment variable pointing to this repository:
ROCKSDB_LIB_DIR=`pwd`

# Compile the static `librocksdb.a` library to link against:
make static_lib
```

--------------------------------

### Viewing staked assets

Source: https://guide.penumbra.zone/usage/pcli/balance

Displays detailed information about delegation tokens and their represented stake.

```bash
pcli view staked
```

--------------------------------

### Initiate Undelegation

Source: https://guide.penumbra.zone/usage/pcli/transaction

Begin the process of undelegating tokens from a validator. This command initiates the undelegation, but funds are reclaimed later.

```bash
pcli tx undelegate-claim
```

--------------------------------

### Generate New Soft-KMS Wallet

Source: https://guide.penumbra.zone/usage/pcli/wallet/softkms

Use this command to generate a new wallet with the softkms backend. Ensure you save the provided seed phrase securely.

```bash
$ pcli init soft-kms generate
YOUR PRIVATE SEED PHRASE:
[SEED PHRASE]
Save this in a safe place!
DO NOT SHARE WITH ANYONE!
Writing generated config to [PATH TO PCLI DATA]
```

--------------------------------

### Query Total Supply with pindexer

Source: https://guide.penumbra.zone/dev/abci-events

Query the total amount of the native staking token up to the current height using pindexer. This query aggregates staked and unstaked amounts, including auction and DEX balances.

```sql
SELECT (staked_um + unstaked_um + auction + dex)::NUMERIC / 10^6 as total
FROM (
  SELECT SUM(um) as staked_um
  FROM (
    SELECT *
    FROM supply_validators
  ) validators
  LEFT JOIN LATERAL (
    SELECT um
    FROM supply_total_staked
    WHERE validator_id = id
    ORDER BY height DESC
    LIMIT 1
  ) ON TRUE
) staked
LEFT JOIN LATERAL (
  SELECT um as unstaked_um, auction, dex
  FROM supply_total_unstaked
  ORDER BY height DESC
  LIMIT 1
) on TRUE
```

--------------------------------

### Clone Penumbra Repository

Source: https://guide.penumbra.zone/dev/build

Clones the Penumbra source code repository. This is the first step after setting up build prerequisites.

```bash
git clone https://github.com/penumbra-zone/penumbra
```

--------------------------------

### Rebuild Rust Docs Index Page

Source: https://guide.penumbra.zone/dev/docs

Run this custom script to rebuild the index page if new crates were added using the `-p <crate_name>` flag with the `rust-docs` script.

```bash
./deployments/scripts/rust-docs -p <crate_name>
```

--------------------------------

### Decentralized Key Generation (DKG)

Source: https://guide.penumbra.zone/usage/pcli/wallet/threshold

Generates key shares in a decentralized manner. Each participant runs this command and exchanges information with others. No single computer holds all shares.

```bash
pcli init threshold dkg --threshold <T> --num-participants <N>
```

--------------------------------

### Create Auto-Closing Limit Orders

Source: https://guide.penumbra.zone/usage/lp

Use the --auto-close parameter to ensure the position closes automatically once filled.

```bash
pcli tx lp order sell 100gm@1gn --auto-close # sells 100 gm at 1 gn per gm, closing on fill
```

--------------------------------

### Push Release Tags

Source: https://guide.penumbra.zone/dev/release

Push the updated main branch and the specific version tag to the remote repository.

```bash
git push origin main && git push origin v1.2.3
```

--------------------------------

### Replicate UniswapV2 Pool

Source: https://guide.penumbra.zone/usage/pcli/transaction

Utilizes the built-in AMM replicator to emulate passive market-making strategies.

```bash
pcli tx lp replicate xyk <TRADING_PAIR> <QUANTITY> [--current-price AMT] [--fee-bps AMT]
```

```bash
pcli tx lp replicate xyk penumbra:test_usd 100penumbra --fee-bps 33
```

--------------------------------

### List active proposals

Source: https://guide.penumbra.zone/usage/pcli/governance

Retrieve a list of all active proposals by their ID.

```bash
pcli query governance list-proposals
```

--------------------------------

### Reset Testnet Network State

Source: https://guide.penumbra.zone/dev/testnet

Use this command to clean up any pre-existing network state before joining the testnet. Ensure you understand the implications of resetting network state.

```bash
# clean up any pre-existing network state
cargo run --release --bin pd -- network unsafe-reset-all
```

--------------------------------

### Query Postgres for Block Heights

Source: https://guide.penumbra.zone/network/event-indexing/configure

Verify that blocks are being indexed by querying the database directly.

```sql
SELECT height FROM blocks ORDER BY height DESC LIMIT 10;
```

--------------------------------

### View pcli Wallet Balance

Source: https://guide.penumbra.zone/dev/testnet

Query the balance of your Penumbra wallet using the pcli client. Ensure the `--home` flag points to your local node's configuration directory. This command is used after initializing or importing a wallet.

```bash
cargo run --release --bin pcli -- --home ~/.local/share/pcli-testnet view balance
```

--------------------------------

### Query IBC Channels

Source: https://guide.penumbra.zone/usage/pcli/transaction

Lists available IBC channels for cross-chain asset transfers.

```bash
pcli query ibc channels
```

--------------------------------

### Configure Penumbra Spend Key in Hermes

Source: https://guide.penumbra.zone/network/relayers

Add the Penumbra wallet spend key directly to the `config.toml` file. This is required because the `hermes keys add` flow is not supported for Penumbra chains. Replace 'XXXXXXXX' with your actual spend key.

```toml
# Replace "XXXXXXXX" with the spend key for the Penumbra wallet.
kms_config = { spend_key = "XXXXXXXX" }
```

--------------------------------

### Follower Signing Command

Source: https://guide.penumbra.zone/usage/pcli/wallet/threshold

Used by non-coordinator parties to participate in a threshold signature. Input coordinator information and review the transaction summary.

```bash
pcli threshold sign
```

--------------------------------

### Query Validator List

Source: https://guide.penumbra.zone/usage/pcli/transaction

Retrieve a list of available validators to stake Penumbra tokens with. Copy the validator's identity key for subsequent staking operations.

```bash
pcli query validator list
```

--------------------------------

### Create New IBC Channel for Devnet

Source: https://guide.penumbra.zone/dev/ibc

Create a new IBC channel between a Penumbra devnet and an Osmosis testnet chain using Hermes. This command sets up the necessary client, connection, and channel.

```bash
cargo run --release --bin hermes -- --config config-devnet-osmosis.toml create channel --a-chain $PENUMBRA_DEVNET_CHAIN_ID --b-chain osmo-test-5 --a-port transfer --b-port transfer --new-client-connection
```

--------------------------------

### Send Assets to Another Address

Source: https://guide.penumbra.zone/usage/pcli/transaction

Send a specified amount of an asset to another user's address. Ensure the asset amount and name are correctly formatted without a space.

```bash
pcli tx send 10penumbra --to penumbrav2t...
```

--------------------------------

### Generate Shielded Account Address

Source: https://guide.penumbra.zone/usage/pcli/wallet

Use `pcli view address` with an account index to generate its corresponding Penumbra address. Ensure `pcli` is initialized.

```bash
$ pcli view address 0
penumbrav2t1...
```

--------------------------------

### Withdraw All Liquidity Positions

Source: https://guide.penumbra.zone/usage/pcli/transaction

Withdraw reserves from all closed liquidity positions associated with your address at once. This simplifies managing multiple positions.

```bash
pcli tx position withdraw-all
```

--------------------------------

### Re-encrypt Existing Soft-KMS Config

Source: https://guide.penumbra.zone/usage/pcli/wallet/softkms

Convert an existing softkms configuration file to an encrypted one. This command will prompt for necessary information to perform the re-encryption.

```bash
$ pcli init re-encrypt
```

--------------------------------

### Close All Liquidity Positions

Source: https://guide.penumbra.zone/usage/pcli/transaction

Efficiently close all open liquidity positions associated with your address. This is useful when managing numerous individual positions.

```bash
pcli tx position close-all
```

--------------------------------

### Vote as a delegator

Source: https://guide.penumbra.zone/usage/pcli/governance

Cast a vote on a specific proposal as a delegator.

```bash
pcli tx vote yes --on 1
```

--------------------------------

### Bridge Penumbra Chain Upgrade Boundary with Hermes

Source: https://guide.penumbra.zone/network/relayers

Run a one-off Hermes command to bridge the upgrade boundary by pointing to an archive node of the pre-upgrade chain. This is a crucial step during Penumbra chain upgrades to ensure continuity. Ensure the `hermes` service is stopped before running this command.

```bash
hermes --config /etc/hermes/config-penumbra-noble.toml update client --archive-address http://localhost:26657/ --restart-height 222200 --host-chain grand-1 --client 07-tendermint-257
```

--------------------------------

### Define a metrics constant

Source: https://guide.penumbra.zone/dev/metrics

Metrics keys must follow Prometheus naming conventions and include a crate-specific prefix.

```rust
pub const MEMPOOL_CHECKTX_TOTAL: &str = "penumbra_pd_mempool_checktx_total";
```

--------------------------------

### Reset Local pcli Wallet State

Source: https://guide.penumbra.zone/dev/devnet-quickstart

Resets the wallet state for `pcli` to allow for a fresh configuration.

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

--------------------------------

### Manage and Close Positions

Source: https://guide.penumbra.zone/usage/lp

Commands to close or withdraw specific positions by ID, or to perform bulk operations on all owned positions.

```bash
pcli tx lp close plpid1tvj0vpdxhuu0tjxsskgf05f6l6dp0xqjqvywptrs0flvvvhvecjqtaxvf7
pcli tx lp withdraw plpid1tvj0vpdxhuu0tjxsskgf05f6l6dp0xqjqvywptrs0flvvvhvecjqtaxvf7
pcli tx lp close-all
pcli tx lp withdraw-all
```

--------------------------------

### View All Events in CometBFT Database

Source: https://guide.penumbra.zone/dev/abci-events

Retrieve a count of all event types stored in the CometBFT database. This is useful for understanding the variety of events being logged.

```sql
SELECT type, COUNT(*) as count
FROM events
GROUP BY type
ORDER BY count DESC;
```

--------------------------------

### Add Osmosis Key to Hermes for Devnet

Source: https://guide.penumbra.zone/dev/ibc

Add Osmosis key material to Hermes when working with a local devnet. This involves echoing the seed phrase to a file and then importing it using the Hermes CLI.

```bash
echo "SEED PHRASE" > ./mnemonic
cargo run --release --bin hermes -- --config config-devnet-osmosis.toml keys add --chain osmo-test-5 --mnemonic-file ./mnemonic
```

--------------------------------

### Add Osmosis Keys to Hermes

Source: https://guide.penumbra.zone/dev/ibc

Add your Osmosis wallet's mnemonic to Hermes for signing transactions. Ensure the configuration file and chain ID are correct.

```bash
cargo run --release --bin hermes -- \
    --config config-penumbra-osmosis.toml keys add \
    --chain osmo-test-5 --mnemonic-file ./mnemonic-osmosis-transfer
```

--------------------------------

### Trigger Outbound IBC Transfer (Osmosis to Penumbra)

Source: https://guide.penumbra.zone/dev/ibc

Initiate an IBC transfer from an Osmosis testnet chain to a Penumbra chain using Hermes. Requires specifying chain IDs, ports, channels, denomination, amount, and receiver address.

```bash
cargo run --release --bin hermes -- \
    --config ./config-penumbra-osmosis.toml tx ft-transfer \
    --dst-chain <PENUMBRA_CHAIN_ID> --src-chain osmo-test-5 --src-port transfer \
    --src-channel <CHANNEL_ID_ON_OSMOSIS_CHAIN> --denom uosmo --amount 100 \
    --timeout-height-offset 10000000 --timeout-seconds 10000000 \
    --receiver <PENUMBRA_ADDRESS>
```

--------------------------------

### View Balance After Withdrawing Position

Source: https://guide.penumbra.zone/usage/pcli/transaction

After withdrawing a closed liquidity position, check your balance to see the withdrawn LPNFT and the deposited reserves.

```bash
$ pcli view balance

 Account  Amount
 0        1lpnft_withdrawn_plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr
 0        1cube
```

--------------------------------

### Initiate IBC Withdrawal

Source: https://guide.penumbra.zone/usage/pcli/transaction

Transfers assets from the Penumbra testnet to a destination chain via a specified IBC channel.

```bash
pcli tx withdraw --to <OSMOSIS_ADDRESS> --channel <CHANNEL_ID> 5gm
```

--------------------------------

### Update buf lockfiles

Source: https://guide.penumbra.zone/dev/protobuf

Update dependencies in the buf lockfile after modifying buf.yaml.

```bash
cd proto/penumbra
# edit buf.yaml to remove the tags, i.e. suffix `:<tag>`
buf dep update
```

--------------------------------

### Query IBC assets

Source: https://guide.penumbra.zone/dev/sql

Filter the assets table for entries with a 'transfer/' prefix to identify IBC-transferred assets.

```sql
sqlite> SELECT denom, json_object('asset_id', quote(asset_id)) FROM assets WHERE denom LIKE 'transfer/%' ;
transfer/channel-0/uosmo|{"asset_id":"X'8C8A30604A6832BF8B418AA30D512740EEA1CB36FDADA5716CED462F20F19612'"}
```

--------------------------------

### Increment a metrics counter

Source: https://guide.penumbra.zone/dev/metrics

Use this macro to record events within the codebase using crate-specific constants.

```rust
metrics::increment_counter!(
    metrics::MEMPOOL_CHECKTX_TOTAL,
    "kind" => "new",
    "code" => "1"
);
```

--------------------------------

### View Penumbra Devnet Reset Status

Source: https://guide.penumbra.zone/dev/ibc

Check the reset status of a local Penumbra devnet. This command is useful for verifying the state of the local development environment.

```bash
cargo run --release --bin pcli -- -n http://localhost:8080 view reset
```

--------------------------------

### Vote as a validator

Source: https://guide.penumbra.zone/usage/pcli/governance

Cast a vote on a specific proposal as an active validator.

```bash
pcli validator vote cast yes --on 1
```

--------------------------------

### Withdraw Funds with pcli

Source: https://guide.penumbra.zone/dev/ibc

Initiate a withdrawal transaction to send funds to another address. Specify the recipient address, IBC channel, timeout height, and the amount to withdraw. Refer to IBC pcli documentation for advanced options.

```bash
cargo run --release --bin pcli -- -n http://localhost:8080 tx withdraw --to osmo1kh0fwkdy05yp579d8vczgharkcexfw582zj488 --channel 0 --timeout-height 5-2900000 100penumbra
```

--------------------------------

### View Non-Penumbra-Specific Events in CometBFT

Source: https://guide.penumbra.zone/dev/abci-events

Count all event types in the CometBFT database that do not originate from the 'penumbra.core' namespace. This helps filter out chain-specific events.

```sql
SELECT type, COUNT(*) as count
FROM events WHERE type NOT LIKE 'penumbra.core.%'
GROUP BY type
ORDER BY count DESC;
```

--------------------------------

### Withdraw a proposal

Source: https://guide.penumbra.zone/usage/pcli/governance

Withdraws a previously submitted proposal by ID, providing a reason for the action.

```bash
pcli tx proposal withdraw 0 \
    --reason "some human-readable reason for withdrawal"
```

--------------------------------

### Community pool spend transaction plan template

Source: https://guide.penumbra.zone/usage/pcli/governance

A JSON-formatted transaction plan for withdrawing funds from the community pool. Requires base64 encoding for asset IDs and addresses.

```json
{
  "fee": { "amount": { "lo": 0, "hi": 0 } },
  "actions": [
    {
      "communityPoolSpend": {
        "value": {
          "amount": { "lo": 100000000, "hi": 0 },
          "assetId": { "inner": "KeqcLzNx9qSH5+lcJHBB9KNW+YPrBk5dKzvPMiypahA=" }
        }
      }
    },
    {
      "communityPoolOutput": {
        "value": {
          "amount": { "lo": 100000000, "hi": 0 },
          "assetId": { "inner": "KeqcLzNx9qSH5+lcJHBB9KNW+YPrBk5dKzvPMiypahA=" }
        },
        "address": {
          "inner": "vzZ60xfMPPwewTiSb08jk5OdUjc0BhQ7IXLgHAayJoi5mvmlnTpqFuaPU2hCBhwaEwO2c03tBbN/GVh0+CajAjYBmBq3yHAbzNJCnZS8jUs="
        }
      }
    }
  ]
}
```

--------------------------------

### Stake Penumbra Tokens

Source: https://guide.penumbra.zone/usage/pcli/transaction

Delegate a specified amount of Penumbra tokens to a chosen validator. This action contributes to network security and earns rewards.

```bash
pcli tx delegate 10penumbra --to penumbravalid...
```

--------------------------------

### Withdraw a Closed Liquidity Position

Source: https://guide.penumbra.zone/usage/pcli/transaction

Reclaim the reserves from a closed liquidity position. This action deposits the reserves into your balance and replaces the closed LPNFT with a withdrawn LPNFT.

```bash
pcli tx position withdraw plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr
```

--------------------------------

### Close a Specific Liquidity Position

Source: https://guide.penumbra.zone/usage/pcli/transaction

Prevent further trading against a specific open liquidity position by closing it. This action replaces the open LPNFT with a closed LPNFT.

```bash
pcli tx position close plpid1hzrzr2myjw508nf0hyzehl0w0x2xzr4t8vwe6t3qtnfhsqzf5lzsufscqr
```

--------------------------------

### Define the CFMM trading function

Source: https://guide.penumbra.zone/usage/lp

The mathematical representation of the constant-sum AMM trading function used by liquidity positions.

```text
phi(R_1, R_2) = p * R_1 + q * R_2
```
Tokens:
Raw