Overview
A hodl invoice (also spelled "hold invoice") is a Lightning Network invoice where the recipient intentionally delays revealing the preimage that settles the HTLC, effectively holding the sender's payment in a pending state until some external condition is satisfied. Unlike a standard Lightning invoice where the recipient claims the payment immediately upon receiving the HTLC, a hodl invoice gives the recipient the ability to either settle (accept) or cancel (reject) the payment at a later time.
This mechanism transforms the Lightning Network's instant settlement property into a conditional settlement tool, enabling escrow-like functionality entirely within the Lightning protocol. The payment is cryptographically locked in transit — the sender cannot reclaim it before the timeout, and the recipient cannot claim it without deliberately choosing to settle — creating a window during which external conditions can be verified.
How It Works
In a normal Lightning payment, the recipient generates a random secret (preimage), creates an invoice containing its hash, and immediately settles the HTLC when it arrives by revealing the preimage. With a hodl invoice, the recipient generates the preimage but does not reveal it to the Lightning node software until they explicitly decide to settle.
Standard Invoice Flow:
Sender pays ──► HTLC arrives at recipient ──► Auto-settle (instant)
Total time: milliseconds
Hodl Invoice Flow:
Sender pays ──► HTLC arrives at recipient ──► HOLD ──► ...
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
Settle Cancel Timeout
(reveal (reject, (HTLC expires,
preimage, sender gets sender gets
get paid) refund) refund)
The three possible outcomes:
1. SETTLE: Recipient reveals preimage
┌────────────┐ preimage ┌────────────┐
│ Sender │ ◄──────────── │ Recipient │
│ (paid) │ │ (received) │
└────────────┘ └────────────┘
2. CANCEL: Recipient rejects the HTLC
┌────────────┐ failure ┌────────────┐
│ Sender │ ◄──────────── │ Recipient │
│ (refunded) │ │ (declined) │
└────────────┘ └────────────┘
3. TIMEOUT: HTLC expires without action
┌────────────┐ ┌────────────┐
│ Sender │ timelock │ Recipient │
│ (refunded) │ expires │ (nothing) │
└────────────┘ └────────────┘
Use Cases
Escrow and conditional payments: A marketplace can hold a buyer's payment until the seller ships a product. If shipping is confirmed, the invoice is settled; if the seller fails to ship, the invoice is canceled and the buyer is refunded.
Atomic swaps with external systems: Hodl invoices enable atomic coordination between Lightning payments and external events — for example, releasing a payment only after a corresponding on-chain transaction confirms, or after a fiat payment is received in a peer-to-peer exchange.
Pre-authorization: Similar to how credit cards authorize a hold before final settlement, hodl invoices can reserve funds while a service is being rendered, settling only after completion.
Proof of payment as access token: An API service can issue a hodl invoice, verify the HTLC is locked (proving the sender has committed funds), provide the service, and then settle the invoice. If the service fails, the invoice is canceled.
Risks and Limitations
Hodl invoices lock liquidity along the entire payment route for the duration of the hold. Every routing node between sender and recipient has funds locked in HTLCs that cannot be used for other payments until the hodl invoice is settled or times out. This has several consequences:
- Routing node costs: Intermediate nodes bear the cost of locked capital without additional compensation for the hold duration
- Channel jamming risk: Malicious actors can abuse hodl invoices to lock up channel liquidity across the network (a form of channel jamming attack)
- Timeout pressure: If the hold period approaches the HTLC timeout, there is a risk of force-closing channels as nodes need to resolve the HTLCs on-chain
- Sender uncertainty: The sender's funds are in limbo during the hold period, which can be confusing from a UX perspective
Because of these trade-offs, hodl invoices should be used judiciously and with the shortest practical hold duration. Routing nodes may also implement policies to reject or limit long-duration HTLCs to protect their liquidity.
Related Concepts
- HTLC — the cryptographic primitive that hodl invoices leverage by delaying settlement
- Lightning Invoice — the standard invoice format that hodl invoices modify
- Escrow — the trust-minimized arrangement that hodl invoices approximate on Lightning
- Liquidity — the channel capacity that is locked during the hold period