HD Wallets: Run a Seller Fleet From One Seed Phrase

ProxyBase v2 allows one active WebSocket connection per wallet address. That constraint is fine for a single node, but it breaks the moment you run the same seller image on a second machine with the same wallet. Two containers, one address, and each handshake kicks the other offline. The standard workaround is a separate wallet per node, which means another seed phrase to store and a pile of addresses to consolidate by hand.

Today the CLI ships HD wallets. Give every node the same master phrase and a different index, and each one derives a different address, using the same BIP-44 path Ethereum wallets use: m/44'/60'/0'/0/{index}. Index 0 is one address, index 1 another. One phrase backs up the entire fleet, and a replacement container with the same index re-derives the same identity and picks up the earnings it left behind.

The Derivation Math

The math is standard: PBKDF2 turns the phrase into a 64-byte seed, HMAC-SHA512 walks the hardened path components, and the address is the last 20 bytes of keccak256 of the public key. The implementation in libproxybase is pinned by tests against the official BIP-32 test vectors, and index 0 of the canonical abandon ... about test phrase derives 0x9858EfFD232B4033E47d90003D41EC34EcaEda94, the same address every other Ethereum wallet produces.

Using It

Import with --hd-index and you get the child wallet at that index. Without the flag, import keeps the legacy raw-seed derivation. Same phrase, different address. The split is deliberate, so existing wallets keep their existing addresses and balances.

Running a Fleet in Containers

The Docker image entrypoint now runs in HD mode whenever MASTER_MNEMONIC is set. The node index resolves in three steps: PROXYBASE_HD_INDEX if you set it, otherwise the trailing number in the hostname, which makes Kubernetes StatefulSet ordinals work with no configuration (proxybase-seller-4 is index 4), otherwise a cksum of the hostname modulo 10000 for ad-hoc runners. The entrypoint derives the child key, logs in, and launches the seller. Leave the mnemonic unset and it falls back to the old bootstrap, so existing deployments are untouched.

Mount the state directory as a tmpfs (emptyDir with medium: Memory in Kubernetes, tmpfs in Compose) and keys and session tokens never reach disk. A dead node comes back with the same index and the same identity. Ready-made manifests live in the CLI repo under deploy/: a StatefulSet and a Compose file. The StatefulSet starts at 10 replicas and scales with kubectl scale statefulset proxybase-seller --replicas=100. Pods update in reverse ordinal order and a replacement starts only after its ordinal has fully terminated, so no wallet ever has two live connections during an upgrade.

Sweeping Earnings

Earnings accrue per address, so you need to consolidate them. The new sweep command walks a range of indices, derives each key in memory, signs the auth challenge, and creates a payout for every child whose available earnings clear the threshold (1,000,000 microcredits is $1.00):

Your on-disk wallet and session token are not touched. deploy/fleet-sweep.sh wraps the command for cron. The sweep reads /v2/wallet/balance, not /v2/seller/status. Seller status only reports earnings for nodes currently connected to the seller pool, so an offline child would have read as zero and missed its payout. The ledger endpoint returns seller_available regardless of connection state. That was a bug in the first cut and it is fixed.

Healthchecks

The image healthcheck also changed. It now requires the backend to be reachable and the local seller process to be alive. Tunnel liveness stays out of it on purpose: the reconnect loop heals dead tunnels, and restarting a container over a transient drop would only churn the seller pool.

The full write-up, including the security practices we recommend, is in the CLI repo (docs/HD_WALLETS.md). If you run more than one seller node, this removes the last reason to hand-manage wallets.