The Problem: Unique Addresses at Scale
To detect which customer made a payment, each customer needs their own unique deposit address. Storing and managing thousands of private keys individually is a security and operational nightmare.
HD (Hierarchical Deterministic) wallets solve this: one seed generates unlimited addresses deterministically. Back up the seed, and you can regenerate every address forever.
BIP39: The Master Seed
Paychainly uses a 12 or 24-word mnemonic (configured via MASTER_SEED). This mnemonic encodes 128 or 256 bits of entropy, transformed into a 512-bit seed via PBKDF2.
BIP44: Derivation Path
Addresses are derived at path:
m/44'/60'/0'/0/{index}Where index is the customer's assigned address index, stored in the address_indexes table. Index 0 is the first address, index 1 the second, and so on — infinitely.
Security Properties
- The master seed never touches the blockchain or any external service
- Individual deposit address private keys are derived on demand for sweep operations, then discarded from memory
- An attacker who compromises one deposit address private key cannot derive the master seed or other addresses
- The master seed is the single secret to protect — store it in a hardware security module in production
Address Reuse Policy
Paychainly never reuses deposit addresses. After a session expires, the address is marked inactive but never reassigned. This prevents payment attribution errors if a customer sends funds to an old address.