Wallet Overview

The Harmoniis Wallet (hrmw) is a self-custodial command-line wallet built in Rust. It manages identities, bearer cash, Bitcoin, ARK off-chain payments, RGB contracts, and marketplace interactions — all derived deterministically from a single BIP39 master mnemonic.

Current version: harmoniis-wallet v0.1.25

Capabilities

Feature Description
Ed25519 Identity Up to 1000 signing keypairs with labels, registered on the marketplace
Webcash Wallet Insert, pay, check, recover, and merge bearer e-cash tokens
Bitcoin On-chain Taproot (BIP86) primary, SegWit (BIP84) fallback, Esplora-synced
Bitcoin Off-chain (ARK) Fast VTXO payments via Arkade ASP with boarding, send, and settle
RGB21 Contracts Issue, accept, deliver, replace, burn, and settle bearer contracts with ZKP witness commitments
Mining SHA256 midstate PoW with CUDA, Vulkan/wgpu, and CPU backends
Timeline Post, comment, list, and rate directly from the CLI
Password Manager macOS Keychain integration with optional iCloud sync

Key Model

Everything derives from a single 12-word BIP39 mnemonic (128-bit entropy) through BIP32 hierarchical deterministic derivation.

Derivation Path

m / 83696968' / 0' / family' / index'
      |          |       |        |
  0x4F8AD768   purpose  slot    slot
  ("HARM")     fixed    family  index

Slot Families

Family ID Derived Keys
Root 0 Master root key
RGB 1 Contract witness secrets
Webcash 2 Webcash wallet state
Bitcoin 3 BIP86 Taproot / BIP84 SegWit keys
PGP (Ed25519) 4 Identity signing keys, index 0..999

The "PGP" family name is a legacy label. These are Ed25519 signing keypairs, not PGP/GPG keys. Each key's fingerprint is its 64-character public key hex.

Architecture

┌──────────────────────────────────────────────────────┐
│  hrmw CLI (Rust binary)                              │
├──────────────────────────────────────────────────────┤
│  BIP39 Mnemonic (12 words / 128-bit entropy)         │
│  └── BIP32 Derivation: m/83696968'/0'/family'/index' │
│       ├── pgp[0..999]   Ed25519 identity keys        │
│       ├── rgb[0]         Contract witness keys        │
│       ├── webcash[0]     Bearer e-cash wallet         │
│       └── bitcoin[0]     Taproot + SegWit keys        │
├──────────────────────────────────────────────────────┤
│  Payment Rails                                       │
│  ├── Webcash  (X-Webcash-Secret header, wats)        │
│  └── Bitcoin  (X-Bitcoin-Secret header, sats/ARK)    │
├──────────────────────────────────────────────────────┤
│  Marketplace API Client                              │
│  Mining Engine (SHA256 midstate, CUDA/Vulkan/CPU)    │
└──────────────────────────────────────────────────────┘

Database Files

All wallet state is stored in ~/.harmoniis/:

File Contents
master.db Root key entropy, mnemonic, identity registry (Ed25519 keys), wallet slots, nickname
rgb.db Contracts, certificates, timeline posts, comments, bids
webcash.db Webcash balance state and token inventory
bitcoin.db Bitcoin/ARK wallet state, boarding outputs, UTXOs
miner.log Mining activity log
miner_status.json Current miner status and statistics
miner_pending_keeps.log Pending mined keeps awaiting insertion

Identity

Each identity is an Ed25519 keypair derived from the PGP slot family (family 4). The wallet supports up to 1000 keys (index 0 through 999), each with an optional label.

  • Fingerprint: 64-character hex of the Ed25519 public key
  • Multi-key: Create named keys with identity pgp-new --label
  • Switching: Activate a key with identity pgp-use --label
  • Registration: identity register --nick publishes to the marketplace server

Payment Rails

The wallet supports two payment rails. Each marketplace listing locks to one rail at inception — all subsequent operations on that listing must use the same rail.

Rail Header Unit Format
Webcash X-Webcash-Secret wats e{amount}:secret:{hex}
Bitcoin X-Bitcoin-Secret sats On-chain txid or ark:{vtxo_txid}:{amount_sats}

Sending payment on the wrong rail returns HTTP 402 with code payment_rail_mismatch.

Password Manager Integration

On macOS, the wallet can store the master secret in the system Keychain with optional iCloud sync.

Mode Behavior
required Keychain storage mandatory (default)
best-effort Use Keychain if available, fall back to file-only
off File-only storage, no Keychain interaction

Configure during setup: hrmw setup --password-manager required

Contracts (RGB21 Bearer)

Contracts use a witness commitment scheme with envelope encryption (X25519 + ChaCha20-Poly1305):

  • WitnessSecret (confidential): n:{contract_id}:secret:{hex64}
  • WitnessProof (public): n:{contract_id}:public:{sha256_hex64}
  • Contract types: Service, ProductDigital, ProductPhysical
  • Status lifecycle: Issued, Active, Delivered, Burned, Refunded
  • The replace command rotates witness state, invalidating the old secret

Backup and Recovery

The master mnemonic is the single point of recovery. All keys, wallets, and identities re-derive deterministically.

Method Command
Full filesystem backup tar -C ~ -czf harmoniis_backup_$(date +%Y%m%d_%H%M%S).tar.gz .harmoniis
Export mnemonic hrmw key export --format mnemonic
Export hex entropy hrmw key export --format hex
Import mnemonic hrmw key import --mnemonic "word1 word2 ... word12" --force
Recover all derived keys hrmw recover deterministic --pgp-start 0 --pgp-end 999

Next Steps