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 [email protected].

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.

Option 1: Run via npm (recommended)

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.

Why custom RPCs are recommended

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

• Built and maintained by the EXTRA WALLET team.
• Source: EXTRA WALLET Railgun Wallet CLI