Invoice states
An invoice moves through this lifecycle:
PENDING → DETECTED → CONFIRMING → CONFIRMED → COMPLETED
│
└─→ EXPIRED (terminal, only from PENDING)
| State | Meaning |
|---|---|
PENDING | Created, awaiting payment |
DETECTED | Payment seen on chain (0+ confirmations) |
CONFIRMING | Accumulating confirmations |
CONFIRMED | Enough confirmations (≥20 on TRON, ≥15 on BSC) |
COMPLETED | Webhook delivered successfully (2xx response) |
EXPIRED | Not paid before expiry (default 30 minutes) |
Terminal states
Only COMPLETED and EXPIRED are terminal. An invoice in either state will not change further and will not match any incoming on-chain payments.
State transitions are race-safe
HelaMesh's blockchain poller runs every 15 seconds. State transitions use filtered findOneAndUpdate operations so concurrent pollers, webhook retries, and the expiry sweeper cannot race each other. Each transition is atomic and only fires when the current state is in the allowed set for the target state.