harmoniis-wallet

Reference CLI wallet for Harmoniis contracts plus Webcash mining.

Credits

• Webminer architecture/perf direction inspired by maaku/webminer.
• RGB model inspired by RGB-WG/rgb.
• Witness custody/replace flow inspired by Webcash server semantics (replace invalidates old secret).

Key Model (Current)

The wallet stores one BIP39 master mnemonic/entropy pair and derives every slot using hardened BIP32 paths:

• RGB identity key (wallet contract identity)
• Webcash master secret
• Bitcoin deterministic slot key
• PGP-style signing identities (multiple, labeled, selectable)

PGP identities are managed with labels:

hrmw identity pgp-list
hrmw identity pgp-new --label ops-signing
hrmw identity pgp-use --label ops-signing

hrmw identity register signs with the active PGP label by default.

Master key backup / restore:

hrmw key export --format mnemonic
hrmw key export --format hex --output ./master.hex
hrmw key import --mnemonic "word1 word2 ... word12"
hrmw key fingerprint

Password manager storage at setup time:

hrmw setup --password-manager required

Modes:

• required (default): setup fails if no supported password manager is available.
• best-effort: continue setup if password-manager storage fails.
• off: skip password-manager storage.

On macOS, this stores in Keychain under a harmoniis service label. If iCloud Keychain sync is enabled in macOS settings, those entries sync; hrmw cannot force iCloud sync from CLI.

Deterministic slot map:

• pgp[i] for i=0..999 (identity scan range)
• webcash[0] deterministic webcash master
• rgb[0] deterministic RGB identity root
• bitcoin[0] deterministic Bitcoin slot seed material

This allows reconstruction from only the master mnemonic (or entropy hex) plus server discovery.

Database model:

• master.db stores root material metadata, slot registry, and PGP identity registry.
• rgb.db stores wallet-level contract/certificate/local timeline state.
• webcash.db stores Webcash balance state.
• bitcoin.db stores Bitcoin/ARK wallet persistence (including ARK boarding outputs).

Important:

• RGB contract state is wallet-scoped (rgb.db), not partitioned by active PGP key label.
• PGP identities are signing keys derived from master key slots; switching active PGP label does not switch to a different RGB state database.

Install

1) Install Rust

Ubuntu/Debian:

curl https://sh.rustup.rs -sSf | sh -s -- -y
source ~/.cargo/env

macOS:

curl https://sh.rustup.rs -sSf | sh -s -- -y
source "$HOME/.cargo/env"

Windows (PowerShell):

winget install Rustlang.Rustup
rustup default stable

FreeBSD:

pkg install -y rust cargo

NetBSD:

pkgin -y install rust cargo

2) Install harmoniis-wallet

cargo install harmoniis-wallet
hrmw --version

Default Paths

• Master wallet DB: ~/.harmoniis/master.db
• RGB DB: ~/.harmoniis/rgb.db
• Webcash DB: ~/.harmoniis/webcash.db
• Bitcoin DB: ~/.harmoniis/bitcoin.db
• Miner log (daemon): ~/.harmoniis/miner.log
• Miner status JSON: ~/.harmoniis/miner_status.json
• Pending mined keeps: ~/.harmoniis/miner_pending_keeps.log

Quick Start

hrmw setup
hrmw info

# Optional: create/select additional labeled signing keys
hrmw identity pgp-new --label team-main --active
hrmw identity pgp-list

hrmw identity register --nick alice
hrmw webcash info

Contract Usage

Buyer flow:

hrmw contract buy --post POST_ID --amount 1.0 --type service
hrmw contract bid --post POST_ID --contract CONTRACT_ID

Seller/holder flow:

hrmw contract insert 'n:CONTRACT_ID:secret:<hex>'
hrmw contract accept --id CONTRACT_ID
hrmw contract deliver --id CONTRACT_ID --text 'delivered work'

Transfer custody safely:

hrmw contract replace --id CONTRACT_ID

replace rotates witness state: the old secret is invalid after replacement.

Webcash Usage

hrmw webcash info
hrmw webcash insert 'e1.0:secret:<hex>'
hrmw webcash pay --amount 0.2 --memo 'payment'
hrmw webcash check
hrmw webcash recover --gap-limit 20
hrmw webcash merge --group 20

Payment Rails

• Both rails are supported; backend config controls which rails are enabled.
• Webcash rail uses X-Webcash-Secret with wats.
• Bitcoin rail uses X-Bitcoin-Secret with sats.
• In ARK mode, X-Bitcoin-Secret must be ark:<vtxo_txid>:<amount_sats>.
• Backend ARK mode verifies incoming VTXOs via ASP/wallet state before settlement.
• Client API exposes payment-header abstractions so either rail can be used cleanly.

CLI rail flags:

# default (webcash)
hrmw --payment-rail webcash timeline post --content "hello"

# bitcoin header mode (requires explicit secret and backend support)
hrmw --payment-rail bitcoin --bitcoin-secret "<vtxo-or-ark-secret>" timeline post --content "hello"

# or via env
HRMW_BITCOIN_SECRET="<vtxo-or-ark-secret>" hrmw --payment-rail bitcoin timeline post --content "hello"

ARK helper commands (Arkade ASP):

hrmw bitcoin ark info
hrmw bitcoin ark board
hrmw bitcoin ark settle
hrmw bitcoin ark balance
hrmw bitcoin ark send <ark_address> <amount_sats>

Deterministic Bitcoin Wallet (Taproot + SegWit Fallback)

The wallet derives a deterministic Bitcoin slot (bitcoin[0]) from the root key and exposes:

• Taproot (BIP86) as the primary receive path.
• SegWit (BIP84) as compatibility fallback for payers without Taproot support.

# show descriptors + deterministic address and sync balances
hrmw bitcoin info

# explicit sync settings
hrmw bitcoin sync --network bitcoin --stop-gap 40 --parallel-requests 8

# deterministic taproot address at index N
hrmw bitcoin address --network bitcoin --kind taproot --index 0

# deterministic segwit fallback address at index N
hrmw bitcoin address --network bitcoin --kind segwit --index 0

Notes:

• This is deterministic reconstruction support (no separate seed file needed).
• hrmw bitcoin info and hrmw bitcoin sync report both Taproot and SegWit next receive addresses.
• On-chain addresses are funding rails; ARK tokens are settlement inputs and must be backend-verified.
• Default esplora endpoints are auto-selected by network and can be overridden with --esplora.

Mining

Foreground (recommended for live logs):

hrmw webminer run --accept-terms

Backend order in auto: CUDA -> Vulkan/wgpu -> CPU.

Examples:

hrmw webminer run --backend auto --accept-terms
hrmw webminer run --backend gpu --accept-terms
hrmw webminer run --backend cpu --cpu-threads 8 --accept-terms
hrmw webminer bench --cpu-threads 8

Accepted mined keeps are inserted into wallet with replace semantics (old secret invalidated). If insert fails after acceptance, pending keeps are stored in miner_pending_keeps.log.

Backup and Restore

Backup the entire wallet directory:

tar -C ~ -czf harmoniis_backup_$(date +%Y%m%d_%H%M%S).tar.gz .harmoniis

Restore:

tar -C ~ -xzf harmoniis_backup_YYYYMMDD_HHMMSS.tar.gz

Then validate:

hrmw info
hrmw webcash recover --wallet ~/.harmoniis/master.db --gap-limit 40
hrmw recover deterministic --pgp-start 0 --pgp-end 999

If you accidentally pass --wallet .../webcash.db, hrmw now auto-corrects to the sibling master.db path.

For deterministic restore on a new machine:

hrmw setup
hrmw key import --mnemonic "word1 word2 ... word12" --force
hrmw recover deterministic --pgp-start 0 --pgp-end 999

Project test wallets (Alice/Bob with recovery verification):

cd harmoniis-wallet
./scripts/prepare_project_test_wallets.sh

This creates wallets/mainnet-test/{alice,bob} and recovered verification wallets under the project root.

Full mnemonic rebuild proof (root + RGB + Webcash + Bitcoin + ARK + PGP identities):

cd harmoniis-wallet
./scripts/prove_mnemonic_rebuild.sh

This writes wallets/rebuild-proof/RESULT.txt plus source/restored snapshots for parity checks.

Build and Test

cargo build --release
cargo test --test unit_tests