HD Wallet & Addresses

PayWarden uses a Hierarchical Deterministic (HD) wallet to generate unique payment addresses for every order. This page explains how it works and why it's the right approach for payment gateways.

Why unique addresses per order?

Every payment order gets its own TRON address. This is critical for:

• Automatic matching — no need to check memo fields or amounts, one address = one order
• Privacy — payers cannot see each other's transactions
• Auditability — each address maps to exactly one order in your database
• Recovery — if the database is lost, you can re-derive all addresses from the mnemonic

BIP44 derivation path

PayWarden follows the BIP44 standard for TRON:

m / 44' / 195' / 0' / 0 / index
│     │     │    │   │    │
│     │     │    │   │    └── Address index (0, 1, 2, ...)
│     │     │    │   └─────── External chain (0 = receive)
│     │     │    └─────────── Account (always 0)
│     │     └──────────────── TRON coin type (195)
│     └────────────────────── BIP44 purpose
└──────────────────────────── Master key

Order #0 → m/44'/195'/0'/0/0 → address TXxx...0 Order #1 → m/44'/195'/0'/0/1 → address TXxx...1 Order #N → m/44'/195'/0'/0/N → address TXxx...N

Address derivation process

Mnemonic (24 words)
    │
    ▼  BIP39 PBKDF2 (2048 rounds, SHA-512)
512-bit seed
    │
    ▼  BIP32 HMAC-SHA512
Master private key + chain code
    │
    ▼  BIP44 hardened derivation (m/44'/195'/0')
Account extended key
    │
    ▼  BIP32 normal derivation (/0/{index})
Child private key
    │
    ▼  secp256k1 elliptic curve
Uncompressed public key (65 bytes)
    │
    ▼  keccak256(pubkey[1:]) → last 20 bytes
Raw address bytes
    │
    ▼  prepend 0x41 + base58check
TRON address (T...)

xpub: public key derivation

For receiving payments, PayWarden stores your extended public key (xpub) in the database — not the mnemonic or private keys.

The xpub allows derivation of all child public keys (and addresses) without access to any private key:

xpub (stored in DB)
    │
    ▼  BIP32 normal derivation (/0/{index})
Child public key
    │
    ▼  keccak256 + base58check
TRON address

This means the database can generate payment addresses for new orders even if the vault is offline or encrypted.

Address pool

PayWarden maintains an address pool in PostgreSQL. When an order is created:

1. The next unused address index is fetched (SELECT max(index) + 1)
2. The address is derived from xpub + index
3. The address is recorded in the addresses table with the order ID
4. Chain Watcher begins monitoring that specific address

After an order is completed and funds are swept, the address index is retired (never reused for security).

Recovery from mnemonic

If the database is lost, all addresses can be re-derived:

# Coming in v1.1: recovery tool
paywarden recover --mnemonic "word1 word2 ... word24" --scan-depth 10000

This scans the TRON blockchain for any TRC-20 transfers to the first 10,000 derived addresses and reconstructs order history.

Compatible hardware wallets

Your 24-word mnemonic is compatible with any BIP44-compliant wallet that supports TRON:

• Ledger (with TRON app)
• Trezor (with TRON support)
• OneKey
• SafePal

You can import the mnemonic into any of these to access your funds directly, without PayWarden.