Using the CLI

This guide walks you through installing and using the zERC20 command-line interface.

Installation

git clone https://github.com/zerc20io/zERC20.git
cd zERC20/cli
cargo install --path .

This installs the CLI binary as zerc20-cli (older versions may install as cli). Alternatively, run directly from the repository:

cd zERC20/cli
cargo run -r -- <command> ...

Prerequisites

Circuit Artifacts

Circuit artifacts are required for generating withdrawal proofs. Download the official published artifacts before using the withdrawal CLI flows:

cargo install --path ../circuit-setup
zerc20-circuit-setup download --version <ARTIFACTS_VERSION>

Proof of Innocence uses proof_of_innocence_nova_pp.bin and proof_of_innocence_nova_vp.bin. The currently published official artifact versions do not include those files yet, so Proof of Innocence requires locally generated artifacts until a POI-enabled version and manifest digest are published.

See Circuit Setup for more details.

Configuration

Environment Variables

Load environment variables from .env (see .env.example in the cli directory):

# Token configuration
export TOKENS_FILE_PATH=../config/tokens.json

# Internet Computer endpoints (required)
export IC_REPLICA_URL=<IC_URL>
export KEY_MANAGER_CANISTER_ID=<CANISTER_ID>
export STORAGE_CANISTER_ID=<CANISTER_ID>

# Required for receiving funds (path to downloaded circuit artifacts)
export NOVA_ARTIFACTS_DIR=/path/to/nova_artifacts

# Optional relay node URL (used for --relay / swap flows)
export RELAY_URL=http://127.0.0.1:3000

See ICP Canister IDs for mainnet/testnet values.

Basic Commands

Issue an Invoice

Generate a burn address to receive payments:

zerc20-cli invoice issue --chain-id <CHAIN_ID>

List Invoices

View your invoices:

zerc20-cli invoice ls --chain-id <CHAIN_ID>

Transfer

Send zERC20 to a burn address:

zerc20-cli transfer \
  --chain-id <CHAIN_ID> \
  --to <BURN_ADDRESS> \
  --amount <AMOUNT_IN_WEI>

Check Invoice Status

zerc20-cli invoice status --chain-id <CHAIN_ID> --invoice-id <INVOICE_ID>

Receive Funds

Generate proofs and receive:

zerc20-cli invoice receive --chain-id <CHAIN_ID> --invoice-id <INVOICE_ID>

Gasless Receive via Relay Node

Ask the relay node to submit the redeem transaction on your behalf:

zerc20-cli invoice receive \
  --chain-id <CHAIN_ID> \
  --invoice-id <INVOICE_ID> \
  --relay \
  --relay-url $RELAY_URL

Useful flags:

• --max-relay-fee <AMOUNT> to abort if the quoted fee is too high
• --yes to skip the confirmation prompt
• --local to redeem from the latest proved local root instead of the global root

Swap zERC20 into Native Gas

Use the relay node to swap zERC20 into the chain's native gas token:

zerc20-cli swap \
  --chain-id <CHAIN_ID> \
  --amount <TOKEN_AMOUNT> \
  --relay-url $RELAY_URL

Useful flags:

• --slippage-bps <BPS> sets the minimum accepted native output (0..=9999, default 100)
• --recipient <ADDRESS> sends native tokens to a different address
• --yes skips the confirmation prompt

Notes:

• The CLI prints Swap submitted. after the relay accepts the request and returns a transaction hash
• If the quote reports priceFallback, the CLI warns because fallback or stale oracle prices may be less favorable

Proof of Innocence

Generate an off-chain proof that a set of received transfers did not originate from OFAC-sanctioned addresses:

The directory in NOVA_ARTIFACTS_DIR must contain locally generated proof_of_innocence_nova_pp.bin and proof_of_innocence_nova_vp.bin files. The currently published official downloads are not enough for this command.

zerc20-cli proof-of-innocence generate \
  --nova-artifacts-dir $NOVA_ARTIFACTS_DIR \
  --recipient <GENERAL_RECIPIENT_HASH> \
  --ofac-root <OFAC_TREE_ROOT> \
  --transfer-root <TRANSFER_TREE_ROOT> \
  --transfers-file ./transfers.json \
  --exclusion-proofs-file ./exclusion_proofs.json \
  --output ./innocence_proof.bin

Verify the proof and expected public values:

zerc20-cli proof-of-innocence verify \
  --nova-artifacts-dir $NOVA_ARTIFACTS_DIR \
  --proof ./innocence_proof.bin \
  --recipient <GENERAL_RECIPIENT_HASH> \
  --total-teleported <TOTAL_VALUE> \
  --ofac-root <OFAC_TREE_ROOT> \
  --transfer-root <TRANSFER_TREE_ROOT>

The witness files must include transfer Merkle paths and OFAC exclusion paths. See Proof of Innocence for the JSON format.

Quick Start Example

# 1. Issue an invoice
zerc20-cli invoice issue --chain-id 1

# 2. List invoices to get the invoice ID and burn address
zerc20-cli invoice ls --chain-id 1

# 3. Send funds to the burn address
zerc20-cli transfer \
  --chain-id 1 \
  --to 0x1234567890abcdef1234567890abcdef12345678 \
  --amount 1000000000000000000

# 4. Check status
zerc20-cli invoice status --chain-id 1 --invoice-id inv-01

# 5. Receive
zerc20-cli invoice receive --chain-id 1 --invoice-id inv-01

# 6. Or redeem through a relay node if you have no native gas
zerc20-cli invoice receive --chain-id 1 --invoice-id inv-01 --relay --relay-url $RELAY_URL

# 7. Optionally swap zERC20 into native gas
zerc20-cli swap --chain-id 1 --amount 1000000 --relay-url $RELAY_URL

Important Notes

• Crosschain Capability: Global-mode tokens can send on one chain and receive on another. Local-mode tokens such as zJPYC settle on the connected chain.
• Processing Time: Private transfers typically take 30 minutes to 1 hour on mainnet
• Testnet Limitations: On testnets, cross-chain transfers may take longer due to LayerZero instability. Local-mode zJPYC does not wait for LayerZero, but it can still be delayed by RPC or indexer issues.

Next Steps

• FAQ — Common questions and troubleshooting
• CLI README — Full CLI documentation