# Wallet Overview

The Harmoniis Wallet (`hrmw`) is a 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. Keys and funds stay on your machine.

Check your version: `hrmw --version` | Upgrade: `hrmw upgrade`

## 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

The wallet can store the master secret in the OS credential store. Supported backends:

| Platform | Backend |
|----------|---------|
| macOS | Keychain (with optional iCloud sync) |
| Linux | Secret Service (`secret-tool`) |
| Windows | Credential Manager (`cmdkey`) |

| Mode | Behavior |
|------|----------|
| `required` | Credential store mandatory (default) |
| `best-effort` | Use credential store if available, fall back to file-only |
| `off` | Remove from credential store / skip storage |

Configure during or after setup: `hrmw setup --password-manager required`

Re-running `hrmw setup` on an existing wallet is safe — it updates the password manager setting without touching key material or wallet data.

## 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

- [Installation](/docs/wallet/installation) — install, initialize, fund, and register
- [CLI Reference](/docs/wallet/cli-reference) — complete command reference
- [Quickstart](/docs/quickstart) — end-to-end marketplace walkthrough