Skip to main content

Wallet CLI

A secure, privacy-focused command-line wallet for the Orbinum blockchain with native support for shielded transactions using Zero-Knowledge proofs.

Development Status

The Orbinum Wallet CLI is in active development (MVP stage). The wallet is functional but security-critical features are still being finalized. External contributions are not yet open (planned for Q2 2026).

Features​

The Orbinum Wallet CLI provides:

  • Private transactions - Shield, transfer, and unshield tokens with zero-knowledge proofs
  • Multi-account support - Manage multiple accounts in a single wallet
  • Strong encryption - Industry-standard encryption for your keys
  • BIP39 compatible - Import/export with standard mnemonic phrases
  • Dual key support - Works with both Ethereum (secp256k1) and Substrate (Sr25519) keys
  • Local control - Your keys never leave your device

Current Status​

Available now:

  • ✅ Create and manage wallets
  • ✅ Shielded transactions (deposit, transfer, withdraw)
  • ✅ Multi-account management
  • ✅ Encrypted local storage
  • ✅ Balance and note tracking

Coming soon:

  • 🔄 Security audit (Q1 2026)
  • 🔄 Hardware wallet support (Ledger/Trezor)
  • 🔄 Mobile companion app
Security Notice

The wallet is functional but has not yet completed a formal security audit. Use with caution for high-value transactions.

Installation​

Prerequisites​

  • Rust 1.75+ and Cargo
  • Orbinum node running and accessible via RPC
  • Operating systems: Linux, macOS, Windows
# Clone the repository
git clone https://github.com/orbinum/wallet-cli.git
cd wallet-cli

# Build in release mode
cargo build --release

# Binary location
./target/release/orbinum-wallet

# Verify build
./target/release/orbinum-wallet --version

Option 2: Download Pre-built Binary​

# Download latest release (when available)
wget https://github.com/orbinum/wallet-cli/releases/latest/download/orbinum-wallet

# Make executable
chmod +x orbinum-wallet

# Verify installation
./orbinum-wallet --version
Security Notice

Always verify binary signatures before use. See the Security section for GPG verification instructions.

Option 3: Install via Cargo​

# Install from source to system PATH
cd wallet-cli
cargo install --path .

# Now available globally
orbinum-wallet --version

Setting Up Aliases​

For development convenience, create shell aliases:

Persistent alias (zsh):

# Add to ~/.zshrc
echo 'alias orbinum-cli="/path/to/wallet-cli/target/release/orbinum-wallet"' >> ~/.zshrc
source ~/.zshrc

Persistent alias (bash):

# Add to ~/.bashrc
echo 'alias orbinum-cli="/path/to/wallet-cli/target/release/orbinum-wallet"' >> ~/.bashrc
source ~/.bashrc

Wallet Initialization​

Create New Wallet​

# Generate new Ethereum-compatible wallet (default, secp256k1)
orbinum-wallet init

# Generate Substrate wallet (Sr25519)
orbinum-wallet init -t substrate

# Import from existing mnemonic (12 or 24 words)
orbinum-wallet init -m "word1 word2 word3 ... word12"

# Force overwrite existing wallet
orbinum-wallet init --force

The wallet will prompt for a password. You must provide a strong password meeting the following requirements.

Account Types​

The wallet supports two account types:

TypeBest For
ethereumEVM compatibility (default, recommended)
substrateNative Substrate operations

Wallet Directory Structure​

Default location: ~/.orbinum/wallet/

~/.orbinum/wallet/
├── wallet.json      # Encrypted wallet state (accounts, notes, keys)
└── config.json      # Wallet configuration (optional)

Storage:

  • Encrypted with industry-standard algorithms
  • Protected by your password

Password Requirements​

The wallet enforces strong password policies to protect your keys:

RequirementMinimum
Length12 characters
Uppercase letters1
Lowercase letters1
Digits1
Special characters1
Backup Your Mnemonic

Your BIP39 mnemonic phrase is the ONLY way to recover your wallet. Write it down and store it securely offline. Never share it with anyone.

Managing Multiple Wallets​

By default, wallets save to ~/.orbinum/wallet. To manage multiple wallets, use different directories:

# Create primary wallet
orbinum-wallet init

# Create secondary wallet in different directory
orbinum-wallet --wallet-dir ~/.orbinum/wallet-trading init -t substrate

# Use specific wallet for operations
orbinum-wallet --wallet-dir ~/.orbinum/wallet-trading balance

Commands​

Global Options​

All commands accept these global flags (must be placed BEFORE the subcommand):

orbinum-wallet [GLOBAL OPTIONS] <COMMAND> [COMMAND OPTIONS]

Global Options:
  -w, --wallet-dir <PATH>   Wallet directory [default: ~/.orbinum/wallet]
  -r, --rpc-url <URL>       RPC endpoint [default: ws://localhost:9944]
  -v, --verbose             Enable verbose logging
  -h, --help                Print help
  -V, --version             Print version
Command Structure

Global options must come BEFORE the subcommand:

# ✅ Correct
orbinum-wallet --wallet-dir ~/.orbinum/wallet balance

# ❌ Wrong
orbinum-wallet balance --wallet-dir ~/.orbinum/wallet

init - Initialize Wallet​

Create or import a wallet with encrypted keystore.

orbinum-wallet init [OPTIONS]

Options:
  -m, --mnemonic <WORDS>      BIP39 mnemonic phrase (12 or 24 words)
  -p, --password <PASSWORD>   Encryption password (prompted if not provided)
  -f, --force                 Overwrite existing wallet
  -t, --account-type <TYPE>   Account type: ethereum or substrate [default: ethereum]

Examples:

# Generate new Ethereum wallet
orbinum-wallet init

# Import from mnemonic
orbinum-wallet init -m "tenant pencil drop spawn move share all rich exact father code cycle"

# Create Substrate wallet
orbinum-wallet init -t substrate

Output:

✅ Wallet created successfully!

⚠️  IMPORTANT: Save your mnemonic phrase securely!
═══════════════════════════════════════════════════
tenant pencil drop spawn move share all rich exact father code cycle
═══════════════════════════════════════════════════

📍 Wallet location: "/Users/you/.orbinum/wallet"
📋 Account type: ethereum
🔑 Address: 0x939fd1a2e6e1b30f9a92532d996df03062bdfcb1

balance - Display Balance​

Show current wallet balance (both public and shielded).

orbinum-wallet balance [OPTIONS]

Options:
  -p, --password <PASSWORD>   Wallet password (prompted if not provided)
  --show-type                 Show account type information

Example:

orbinum-wallet balance --show-type

Output:

💰 Wallet Balance
═══════════════════════════════════════════════════
Available: 1500.00 ORB
Notes:     3 unspent
Account:   0x939f...fcb1 (ethereum)

list - List Notes (UTXOs)​

Display unspent notes in your shielded pool wallet.

orbinum-wallet list [OPTIONS]

Options:
  -p, --password <PASSWORD>   Wallet password
  -a, --all                   Include spent notes

Example:

orbinum-wallet list

Output:

📋 Wallet Notes (UTXOs)
═══════════════════════════════════════════════════
  1. 100.00 ORB (asset: 0)
     Commitment: 0x1234abcd...
  2. 250.00 ORB (asset: 0)
     Commitment: 0x5678ef01...
  3. 150.00 ORB (asset: 0)
     Commitment: 0xabcd1234...

Total: 500.00 ORB

deposit - Shield Tokens​

Convert public tokens to shielded tokens (public → private).

orbinum-wallet deposit <AMOUNT> [OPTIONS]

Arguments:
  <AMOUNT>   Amount to deposit in smallest unit (e.g., wei for 18 decimals)

Options:
  -p, --password <PASSWORD>   Wallet password

Example:

# Deposit 100 ORB (assuming 18 decimals: 100 * 10^18)
orbinum-wallet deposit 100000000000000000000

Output:

📡 Preparing deposit transaction...
Amount:         100000000000000000000 ORB
Commitment:     0x1a2b3c...
Encrypted memo: 256 bytes

🔏 Signing and submitting transaction...

✅ Transaction submitted successfully!
Tx hash: 0xabcd1234...

💡 Run 'sync' to update your wallet after confirmation.

transfer - Private Transfer​

Send shielded tokens to another user privately.

orbinum-wallet transfer <RECIPIENT> <AMOUNT> [OPTIONS]

Arguments:
  <RECIPIENT>   Recipient's public key (hex format)
  <AMOUNT>      Amount to transfer (smallest unit)

Options:
  -p, --password <PASSWORD>   Wallet password
  -f, --fee <AMOUNT>          Transaction fee [default: 1000]

Example:

# Transfer 50 ORB to recipient
orbinum-wallet transfer 0x1234...abcd 50000000000000000000

Output:

🔐 Creating private transfer...
Amount:      50000000000000000000 ORB
Fee:         1000 ORB
Merkle root: 0x9876...
Input notes:  2
Output notes: 2

🔐 Generating zero-knowledge proof for transfer...
   Using real proof generation via Arkworks...
   ✅ Proof generated in 8.42s

🔏 Signing and submitting transaction...

✅ Transaction submitted successfully!
Tx hash: 0xdef456...

💡 Run 'sync' to update your wallet after confirmation.

withdraw - Unshield Tokens​

Convert shielded tokens back to public tokens (private → public).

orbinum-wallet withdraw <RECIPIENT> <AMOUNT> [OPTIONS]

Arguments:
  <RECIPIENT>   Recipient's public address
  <AMOUNT>      Amount to withdraw (smallest unit)

Options:
  -p, --password <PASSWORD>   Wallet password

Example:

# Withdraw 25 ORB to public address
orbinum-wallet withdraw 0x5678...ef01 25000000000000000000

Output:

💸 Creating withdrawal...
To:          0x5678...ef01
Amount:      25000000000000000000 ORB
Merkle root: 0x1234...
Selected note: 100000000000000000000 ORB
Nullifier:     0xabcd...

🔐 Generating zero-knowledge proof for unshield...
   Using real proof generation via Arkworks...
   ✅ Proof generated in 7.89s

🔏 Signing and submitting transaction...

✅ Transaction submitted successfully!
Tx hash: 0x987abc...

💡 Run 'sync' to update your wallet after confirmation.

sync - Synchronize Wallet​

Scan the blockchain for new notes and update wallet state.

orbinum-wallet sync [OPTIONS]

Options:
  -p, --password <PASSWORD>   Wallet password
  --from-block <NUMBER>       Start block number (default: last sync or 0)

Example:

# Sync from last checkpoint
orbinum-wallet sync

# Sync from specific block
orbinum-wallet sync --from-block 1000

Output:

🔄 Starting wallet synchronization...
📡 Scanning blockchain from block 0...

✅ Sync completed successfully!
📊 Statistics:
   • Blocks scanned: 1523
   • Events found: 47
   • Notes decrypted: 12
   • Notes added to wallet: 12
   • Current Merkle root: 0x9a8b7c...
💾 Wallet saved successfully.

export - Export Keys​

Export cryptographic material from your wallet.

orbinum-wallet export [OPTIONS]

Options:
  -p, --password <PASSWORD>     Wallet password
  -e, --export-type <TYPE>      What to export [default: seed]
                                Values: seed, spending-key, viewing-key, public-key

Export types:

  • seed - BIP39 mnemonic (full wallet recovery)
  • spending-key - Private key for spending (high risk)
  • viewing-key - Read-only key (safe to share with auditors)
  • public-key - Public key (safe to share)

Example:

# Export mnemonic
orbinum-wallet export

# Export viewing key (safe to share)
orbinum-wallet export -e viewing-key
Security Warning

Never share your seed or spending-key. Only share viewing-key with trusted auditors who need to verify your transaction history.

info - Wallet Information​

Display wallet configuration and status.

orbinum-wallet info [OPTIONS]

Options:
  -p, --password <PASSWORD>   Wallet password

Output:

ℹ️  Wallet Information
═══════════════════════════════════════════════════
Location:    "/Users/you/.orbinum/wallet"
Accounts:    2 total
Active:      0
Account Type:ethereum
Address:     0x939f...fcb1
RPC URL:     ws://localhost:9944
Balance:     1500.00 ORB
Notes:       3 unspent

account - Multi-Account Management​

Manage multiple accounts within a single wallet.

account list​

List all accounts in the wallet.

orbinum-wallet account list [OPTIONS]

Options:
  -p, --password <PASSWORD>   Wallet password

Output:

📋 Wallet Accounts
═══════════════════════════════════════════════════
* 0: Default (ethereum)
     Address: 0x939f...fcb1
  1: Trading (substrate)
     Address: 5Gxx...yzzz

2 account(s) total
* = active account

account add​

Create a new account in the wallet.

orbinum-wallet account add <NAME> [OPTIONS]

Arguments:
  <NAME>   Account name/label

Options:
  -m, --mnemonic <WORDS>      BIP39 mnemonic (generated if not provided)
  -t, --account-type <TYPE>   Account type: ethereum or substrate [default: ethereum]
  -p, --password <PASSWORD>   Wallet password

Example:

orbinum-wallet account add "Trading Account" -t substrate

account switch​

Switch the active account.

orbinum-wallet account switch <INDEX_OR_NAME> [OPTIONS]

Arguments:
  <INDEX_OR_NAME>   Account index (0, 1, 2...) or account name

Options:
  -p, --password <PASSWORD>   Wallet password

Example:

# Switch by index
orbinum-wallet account switch 1

# Switch by name
orbinum-wallet account switch "Trading Account"

Privacy Operations​

Operation Flows​

Shield Flow (Deposit)​

Transfer Flow (Private)​

Unshield Flow (Withdraw)​

How Privacy Works​

Shield (Deposit):

  1. User provides amount to shield
  2. Wallet generates new note with Poseidon commitment
  3. Note optionally encrypted with memo for recipient
  4. Transaction submitted to blockchain
  5. Commitment added to Merkle tree on-chain
  6. Note stored locally in wallet state

Transfer (Private):

  1. Wallet selects input notes (coin selection algorithm)
  2. Builds circuit witness with spending keys and Merkle proofs
  3. Generates ZK proof using Arkworks (native Rust Groth16)
  4. Proof verifies: knowledge of nullifier secret, valid Merkle path
  5. Transaction submitted with proof and new commitments
  6. Input notes marked as spent locally
  7. Output notes encrypted for recipients

Unshield (Withdraw):

  1. User specifies recipient address and amount
  2. Wallet selects note to spend
  3. Generates nullifier to prevent double-spend
  4. Creates ZK proof of note ownership
  5. Proof submitted with nullifier
  6. Blockchain verifies and releases tokens to public address

Note Selection Algorithm​

The wallet implements a greedy coin selection strategy:

1. Sort available notes by value (descending)
2. Select notes until sum >= target_amount + fee
3. If overpaying, create change note back to self
4. Optimize for minimum number of inputs (privacy)

Security​

Threat Model​

The Orbinum Wallet CLI security model is based on the following trust assumptions:

What you MUST trust:

  • ✅ The wallet binary you execute (verify GPG signature)
  • ✅ The device running the wallet (malware-free environment)
  • ✅ Your RPC endpoint (use your own node when possible)

What you DON'T need to trust:

  • ❌ The blockchain node (privacy guaranteed by ZK proofs)
  • ❌ Other network participants (transactions are private)
  • ❌ GitHub Actions (reproducible builds verify integrity)

Key Threats and Mitigations​

HIGH RISK: Compromised Wallet Binary​

Attack: Modified wallet that exfiltrates spending keys

Impact:

  • ❌ Attacker can steal ALL funds
  • ❌ Attacker can view transaction history
  • ❌ Complete loss of privacy and funds

Mitigation:

  1. Always verify GPG signature before running (see below)
  2. Build from source on trusted machine
  3. Only download from official sources

MEDIUM RISK: Viewing Key Leak​

Attack: Viewing key shared or leaked

Impact:

  • ❌ Attacker can see your transaction history
  • ✅ Your funds remain safe (cannot spend)

Mitigation:

  1. Only share viewing keys intentionally (e.g., with auditors)
  2. Monitor wallet for unexpected behavior

LOW RISK: Network Metadata​

Attack: Monitoring your network activity

Impact:

  • ⚠️ IP address may be linked to transactions
  • ✅ Transaction content remains private

Mitigation:

  1. Run your own Orbinum node locally
  2. Use VPN for RPC connections

Binary Verification​

Critical Security Step

ALWAYS verify binary signatures before first use to ensure you're running authentic wallet software.

Official GPG Key:

Primary key: 174E 9AD2 5455 9716 42B9  332D FFF7 BF02 87E3 B152
Key ID: FFF7BF0287E3B152
User ID: orbinum (orbinum-wallet-cli) <dev@orbinum.net>

Verification steps:

# 1. Import official signing key
gpg --import RELEASE_KEY.asc

# 2. Verify signature
gpg --verify orbinum-wallet.asc orbinum-wallet

# Expected output:
# Good signature from "orbinum (orbinum-wallet-cli) <dev@orbinum.net>"

# 3. Verify key fingerprint matches
gpg --fingerprint FFF7BF0287E3B152

Checksum verification:

# SHA256
sha256sum -c orbinum-wallet.sha256

# SHA512 (recommended)
sha512sum -c orbinum-wallet.sha512

Reproducible Builds​

To independently verify that the binary matches the source code:

# 1. Clone at exact release tag
git clone --branch v0.1.0 https://github.com/orbinum/wallet-cli.git
cd wallet-cli

# 2. Build in deterministic environment
docker run --rm -v $(pwd):/workspace \
  rust:1.75 bash -c "cd /workspace && cargo build --release"

# 3. Compare checksums
sha256sum target/release/orbinum-wallet
# Should match official release checksum
Development Status

Reproducible builds automation is currently in development. Manual verification process documented above.

Best Practices​

Do ✅

  • Verify wallet binary before first use
  • Store mnemonic phrase offline in secure location
  • Run your own Orbinum node for RPC
  • Keep wallet software updated
  • Create separate accounts for different purposes

Don't ❌

  • Share your mnemonic phrase with anyone
  • Store mnemonic in cloud services or email
  • Run wallet on untrusted or public computers
  • Connect to unknown RPC endpoints
  • Take screenshots of your mnemonic

Security Status​

Current security features:

  • ✅ Strong encryption for wallet storage
  • ✅ Password protection
  • ✅ BIP39 mnemonic support
  • ✅ Separate viewing keys (read-only)

Coming soon:

  • 🔄 Hardware wallet support (Ledger/Trezor)
  • 🔄 Security audit (Q1 2026)
Security Audit

No security audits have been conducted yet. Use with caution for high-value transactions.

Responsible Disclosure​

If you discover a security vulnerability:

  1. DO NOT open a public issue
  2. Email: dev@orbinum.net (GPG key available)
  3. Include detailed steps to reproduce
  4. Wait for acknowledgment (within 48 hours)
  5. Allow 90 days for fix before public disclosure

Troubleshooting​

Common Issues​

IssueProbable CauseSolution
Connection refusedRPC node not runningVerify node is running on ws://localhost:9944
Invalid passwordWrong password or rate limitWait for lockout to expire, then retry
Insufficient balanceNot enough fundsCheck balance with balance command
Wallet already existsExisting wallet in directoryUse --force flag to overwrite or change directory
Invalid mnemonicIncorrect BIP39 phraseVerify mnemonic has 12 or 24 valid words
Proof generation slowNormal behaviorZK proof generation takes ~8-10s (expected)
Notes not syncedWallet out of syncRun orbinum-wallet sync
Cannot find note to spendInsufficient shielded balanceRun list to check available notes

Performance​

ZK Proof Generation Times:

  • Transfer: 8-10 seconds
  • Unshield: 7-9 seconds
  • Shield: < 1 second (no proof required)

These times are normal for zero-knowledge proofs.

Debugging​

Enable verbose logging:

orbinum-wallet --verbose balance

Contributing​

Contribution Status

External contributions are NOT currently open.

The wallet is in early development phase. Security audit must be completed first.

Estimated opening date: Q2 2026

In the meantime, you can:

  • ⭐ Star the project to follow updates
  • 🐛 Report critical security vulnerabilities to: dev@orbinum.net
  • 💬 Participate in GitHub Discussions

Technical Specifications​

Supported Platforms​

PlatformStatus
Linux (x86_64)✅ Supported
macOS (Intel)✅ Supported
macOS (Apple Silicon)✅ Supported
Windows✅ Supported

System Requirements​

Minimum:

  • RAM: 2 GB
  • Storage: 100 MB
  • CPU: 64-bit processor

Recommended:

  • RAM: 4 GB+
  • Storage: 500 MB
  • CPU: Multi-core

Performance​

ZK Proof Generation Times:

  • Transfer: ~8-10 seconds
  • Unshield: ~7-9 seconds
  • Shield: < 1 second (no proof required)

These times are normal for zero-knowledge proof generation.

Additional Resources​