Skip to main content

Railgun CLI

About​

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

License​

Licensed under the PolyForm Noncommercial License 1.0.0. Commercial use requires a separate written commercial license agreement from the licensor — contact alex@vir-tec.net.

Key features​

  • Wallet management: create/import/backup mnemonic

  • Network/RPC config:

    • Enable/disable supported networks
    • Enable/disable RPC URLs
    • Select active RPC URL
    • Add/remove custom RPC URLs (recommended)

  • 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 run​

Railgun CLI can be run without installing anything globally, or locally from the repository if you are developing it.

This is the recommended way for most users.

Requirements​

  • Node.js (v22)

Run​

npx @extra-wallet/railgun-wallet

This will:

  • download the CLI on demand,
  • start the interactive terminal UI,
  • store wallet data in a OS-specific user data directory.

You can run the command from any directory — your wallet data will always stay in the same place.

Option 2: Run locally from the repository (development)​

Use this if you want to:

  • inspect the code,
  • modify the CLI,
  • contribute or debug.

Requirements​

  • Node.js (v22)
  • pnpm

1. Install dependencies​

From the repository root:

pnpm install

2. Build the CLI​

cd packages/railgun-wallet-cli
pnpm build

3. Run locally​

npx railgun-wallet

Data directory & persistence​

Railgun CLI stores all wallet-related data (database, artifacts, config) in an OS-specific user data directory:

  • macOS /Users/demurgos/Library/Application Support/.extra-wallet-cli/railgun

  • Linux /home/demurgos/.config/.extra-wallet-cli/railgun

  • Windows C:\Users\demurgos\AppData\Roaming\.extra-wallet-cli\railgun

This ensures:

  • wallet data is not tied to your current working directory,
  • balances and POI state remain consistent,
  • you can safely run the CLI from anywhere.

How to use​

1. First run: authorization screen​

On first launch, you will 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​

This is a single-wallet CLI.

If you choose Create or Import while a wallet already exists, you’ll be asked whether to overwrite the current wallet data.

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)

For each network, you can:

  • Enable or disable the network
  • Enable or disable specific RPC URLs
  • Add custom RPC URLs (strongly recommended)
  • Remove custom RPC URLs

Disabled networks or RPCs are ignored by all other screens.

Railgun balance refresh and privacy operations rely heavily on eth_getLogs and repeated block scanning.

Free/public RPC endpoints often:

  • rate-limit log queries,
  • truncate large responses,
  • stall on long block ranges,
  • cause partial or failed balance refreshes.

Using a reliable custom RPC provider significantly improves:

  • balance refresh reliability,
  • proof generation stability,
  • overall UX.

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.
  • Requires RPCs capable of handling log-heavy queries.
  • 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)​

Transfers funds between two RAILGUN wallets.

  • Requires proof generation.
  • Uses spendable private balance only.

Compliance​

Export POI proofs / status bundle​

Exports a JSON snapshot of wallet POI-related state, suitable for sharing or archiving.

Export Shareable Viewing Key​

Exports a view-only key for audit and compliance use.

  • Grants visibility only
  • Does not allow spending
  • Intended for compatible view-only tooling

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 with small test amounts.
  • Use reliable RPC endpoints.
  • Always configure at least one POI node.
  • Never share your mnemonic.

FAQ​

Why is my private balance not spendable? Funds may be pending POI validation, RPC issues may have interrupted refresh, or no POI node is configured.

Why do transfers fail randomly? Most failures are caused by:

  • RPC rate limits,
  • unreliable public RPC endpoints,
  • missing POI node configuration.

Developer Info​