Skip to main content

Railgun CLI

About​

Railgun CLI is a terminal wallet focused on RAILGUN privacy features. It also provides basic configuration screens for networks/RPC, custom tokens, POI nodes, and compliance exports (POI bundle + shareable viewing key).

Key features​

  • Wallet management: create/import/backup mnemonic

  • Network/RPC config:

    • Enable/disable supported networks
    • Enable/disable RPC URLs
    • Add/remove custom RPC URLs

  • Tokens: add a custom token by address

  • Transfers:

    • Shield (public → 0zk)
    • Unshield (0zk → public)
    • Private transfer (0zk → 0zk)

  • Compliance:

    • Export POI proofs/status bundle
    • Export a Shareable Viewing Key

  • POI nodes:

    • Add/remove custom POI node URLs
    • Reset to default list (currently empty)

How to use​

1. First run: authorization screen​

On first launch you’ll see the authorization screen:

  • Create Wallet — generates a new mnemonic.
  • Import From Mnemonic — restores an existing wallet.
  • Exit
Backup your mnemonic

When creating a wallet, back up the mnemonic immediately. Anyone with the mnemonic can control the funds. Losing it means losing access.

2. Home screen (main menu)​

After authorization, you’re redirected to the Home screen:

  • Create Wallet
  • Import From Mnemonic
  • Backup Mnemonic
  • Network and RPC Config
  • Tokens
  • Transfer
  • Compliance
  • POI Nodes
  • About
  • Exit
Overwrite prompt

Because this is a single-wallet app, choosing Create or Import when a wallet already exists will ask whether to overwrite the current wallet.

3. Backup mnemonic​

Backup Mnemonic shows the mnemonic for the currently stored wallet.

Use this if you:

  • didn’t back it up on creation,
  • want to confirm your backup,
  • plan to migrate to another device.

4. Network and RPC config​

Supported networks (currently 4 chains):

  • Ethereum (1)
  • BNB Smart Chain (56)
  • Polygon (137)
  • Arbitrum (42161)

After selecting a chain, you can perform:

  • Toggle network enabled/disabled The enabled network is available across other screens. Disabled ones are ignored.

  • Enable/disable an RPC URL Disabled RPC URLs are never used.

  • Add custom RPC URL Adds an RPC endpoint for the selected network.

  • Remove custom RPC URL Removes a previously added custom endpoint.

5. Tokens​

Tokens currently supports:

  • Add custom token by address

This makes a token available for transfers on the selected network.

6. Transfer​

The Transfer screen supports:

A) Shield (public → 0zk)​

Moves funds from a public address into a private RAILGUN balance.

  • ERC-20 tokens may require an approval transaction first.
  • Native tokens are typically handled as “wrap + shield” (e.g., ETH → WETH → shield).

B) Unshield (0zk → public)​

Moves funds from private balance to a public address.

  • Requires proof generation.
  • Private balances can be split into states/buckets (e.g., spendable vs POI/pending states). If your total is non-zero but spendable is zero, funds may not be transferable yet.

C) Private transfer (0zk → 0zk)​

Sends a private transfer between RAILGUN addresses.

  • Requires proof generation.
  • Uses spendable private balance.
Fees & confirmation

Before sending, the CLI shows a confirmation summary (network, addresses, token/amount, estimated network fee). Make sure the details are correct before confirmation.

Compliance​

Export POI proofs/status bundle​

Generates a JSON bundle you can share/archive:

{
  "network": {
    "name": "...",
    "id": "..."
  },
  "railgunWalletAddress": "...",
  "metadata": {
    "version": 1,
    "walletSource": "extra-wallet-railgun-cli",
    "timestampIso": "..."
  },
  "railgunBuckets": {
    "bucketName": "bucketInfo"
  }
}

This is intended to capture the wallet’s POI/spendability-relevant status at a given time.

Export a Shareable Viewing Key​

Exports a viewing key that can be given to an auditor for view-only verification.

How it works conceptually:

  • A viewing key lets a third party observe relevant wallet history/balances in compatible tooling.
  • It does not grant spending control.
  • In many products, auditors import it into a view-only wallet experience.
View-only wallet screen?

The CLI view-only mode currently is in development. If you want auditors to use the viewing key, they can use this key in wallets supporting the view-only mode.

POI nodes​

POI (Proof of Innocence) depends on querying configured POI nodes.

Actions:

  • Add custom POI node URL
  • Remove custom POI node URL
  • Reset to default list
Required right now

There are currently no default POI nodes bundled, so you must add at least one custom POI node URL for POI-related features to work.

Validation & tips​

  • Start small: test with small amounts before large transfers.
  • RPC reliability matters: flaky RPC endpoints cause balance refresh/proof/tx failures.
  • POI nodes are required: add at least one POI node URL.
  • Mnemonic safety: do not store mnemonics in plain text; don’t share them.

FAQ​

Why do I only see one wallet? This is currently a single-wallet CLI. Create/import may overwrite existing wallet data.

Why is my private balance not spendable? Private balances may be in non-spendable buckets (pending/POI-related). You can have total funds but 0 spendable. Also, if you didn't provide any POI node URL, your funds will be mistakenly marked as non-spendable.

Why do transfers fail randomly? Most common causes are RPC instability, missing/invalid POI node URLs.

Developer Info​