Hodl Invoice

What Is a Hodl Invoice?

A hodl invoice (sometimes spelled "hold invoice") is a Lightning Network invoice where the receiver controls when the payment settles. In a standard Lightning payment, the receiver immediately releases the preimage upon receiving the HTLC, and the payment completes in milliseconds. With a hodl invoice, the receiver deliberately holds the HTLC open, creating a pending state that can last minutes, hours, or until timeout.

This delayed settlement transforms Lightning from a pure payment rail into a programmable money layer. The receiver gains the ability to inspect conditions, verify external events, or coordinate with other systems before deciding to accept or reject the payment.

The name comes from the crypto meme "HODL" (hold on for dear life), repurposed here to describe holding a payment in limbo. The receiver "hodls" the HTLC until they're ready to settle or cancel.

How It Works

Understanding hodl invoices requires grasping how standard Lightning payments work first. In a normal payment:

1. The receiver generates a random preimage and computes its hash (payment hash)
2. The receiver creates an invoice containing this payment hash
3. The sender routes an HTLC locked to this hash through the network
4. When the HTLC reaches the receiver, they reveal the preimage
5. The preimage propagates back, settling the payment at each hop

The entire process takes seconds because the receiver immediately reveals the preimage upon receiving the HTLC. There's no decision point.

Hodl invoices modify step 4. Instead of immediately revealing the preimage, the receiver:

1. Receives the incoming HTLC
2. Holds it without settling
3. Waits for some condition to be met
4. Either settles (reveals preimage) or cancels (lets HTLC expire)

During the hold period, the sender's funds are locked in the HTLC chain. The sender cannot spend those sats elsewhere, but the receiver hasn't claimed them yet. This creates a trustless escrow state enforced by the HTLC timelock.

The Three Possible Outcomes

Every hodl invoice resolves in one of three ways:

• Settle: The receiver releases the preimage. The payment completes normally, and the receiver claims the funds. All intermediate nodes in the route also settle their HTLCs.
• Cancel: The receiver explicitly cancels without revealing the preimage. The HTLCs fail back through the route, and the sender recovers their funds.
• Timeout: The HTLC timelock expires before settlement. The sender recovers funds via the timeout path. This is the fallback if the receiver goes offline or fails to act.

Why Use Hodl Invoices?

Standard Lightning invoices work perfectly for simple payments where trust exists or isn't needed. You buy coffee, pay the invoice, receive your coffee. The instant settlement matches the instant delivery.

But many transactions require conditionality. You want to pay only if something happens. Or you need to coordinate payment across multiple systems. Hodl invoices enable these patterns:

• Pay-on-delivery: Hold payment until goods are confirmed delivered
• Atomic operations: Coordinate Lightning payments with on-chain transactions or cross-chain swaps
• Dispute windows: Allow time for buyers to verify services before payment finalizes
• External verification: Wait for oracle confirmations, API responses, or manual approval

Without hodl invoices, achieving these patterns requires trusted intermediaries. With hodl invoices, the HTLC mechanics provide trustless enforcement.

Technical Implementation

Implementing hodl invoices requires control over preimage handling at the node level. Most Lightning implementations support this through specific APIs:

LND Implementation

LND provides hodl invoice support through its invoicesrpc subserver. The key difference from regular invoices: you provide the payment hash externally instead of letting LND generate it.

# Generate a preimage externally
preimage=$(openssl rand -hex 32)
hash=$(echo -n "$preimage" | xxd -r -p | sha256sum | cut -d' ' -f1)

# Create hodl invoice with the hash
lncli addholdinvoice --hash=$hash --amt=100000

# Later, settle with the preimage
lncli settleinvoice $preimage

# Or cancel without settling
lncli cancelinvoice $hash

The application stores the preimage securely and only calls settleinvoice when conditions are met. If conditions fail, calling cancelinvoice releases the sender's funds immediately rather than waiting for timeout.

Core Lightning Implementation

CLN supports hodl invoices through the hold plugin:

# Create a hodl invoice
lightning-cli holdinvoice amount_msat label description

# When ready to settle
lightning-cli settleholdinvoice preimage

# To cancel
lightning-cli cancelholdinvoice payment_hash

Application Architecture

A typical hodl invoice flow in an application:

1. Generate preimage and hash in the application layer
2. Store preimage in secure application database
3. Create hodl invoice with the hash via node RPC
4. Monitor for incoming HTLC (invoice state changes to ACCEPTED)
5. Execute business logic (verify delivery, check oracle, etc.)
6. Call settle or cancel based on outcome

Use Cases

Marketplace Escrow

Peer-to-peer marketplaces face the classic escrow problem: buyers want to pay after receiving goods, sellers want payment before shipping. Traditional solutions require trusted intermediaries who hold funds.

Hodl invoices provide trustless escrow:

1. Seller creates hodl invoice for the item price
2. Buyer pays the invoice, locking funds in HTLC
3. Seller sees funds are locked and ships the item
4. Buyer confirms receipt
5. Seller settles the invoice and claims funds

If the buyer disputes or the seller never ships, the HTLC times out and the buyer recovers funds. No intermediary holds the money at any point.

Atomic Swaps

Atomic swaps exchange assets across different systems (chains, layers) with guaranteed atomicity: either both sides complete or neither does. Hodl invoices enable the Lightning leg of these swaps.

Example: swapping on-chain Bitcoin for Lightning sats:

1. Party A creates hodl invoice on Lightning
2. Party B pays the hodl invoice (funds now locked)
3. Party A creates on-chain HTLC using the same hash
4. Party B claims the on-chain funds by revealing the preimage
5. Party A uses that revealed preimage to settle the Lightning invoice

The shared hash links both transactions. Neither party can cheat because claiming one side reveals the secret needed for the other.

Submarine Swaps

Submarine swaps move funds between on-chain Bitcoin and Lightning. Services like Loop and Boltz use hodl invoices to make these swaps trustless. The hodl invoice holds the Lightning payment while the on-chain transaction confirms, then settles atomically.

Conditional Payments

Any payment conditional on external events can use hodl invoices:

• Oracle-based payments: Settle only if an oracle confirms a real-world event (sports outcome, price threshold, weather condition)
• Multi-signature approval: Wait for multiple parties to approve before settlement
• Service verification: Hold payment until API confirms service was rendered
• Time-delayed payments: Accept payment now, settle after a waiting period

Risks and Considerations

Channel Liquidity Lock

While a hodl invoice is pending, the sender's funds are locked. More critically, every routing node along the path also has liquidity locked in their HTLCs. Extended hold times reduce network-wide liquidity and can strain routing nodes.

Routing nodes may reject HTLCs with long timelocks or from sources known to create long-held HTLCs. Some nodes set maximum HTLC hold times and will fail HTLCs that exceed them.

Griefing Attacks

Malicious receivers can create hodl invoices and never settle, locking sender funds until timeout. This "griefing attack" costs the attacker nothing but locks victim liquidity for hours or days.

Mitigations include reputation systems, requiring deposits, and using shorter HTLC timeouts. The Lightning Network community continues developing solutions like HTLC endorsement to address this.

Timeout Risks

If the receiver fails to settle before the HTLC timeout, they lose the payment entirely. For applications using hodl invoices, robust monitoring and alerting are essential. A system crash during the hold period could mean lost funds.

Implementation Complexity

Hodl invoices require careful state management. Applications must track preimages, monitor HTLC states, handle edge cases (partial payments, retries), and manage timeouts correctly. Bugs can result in stuck payments or lost funds.

FAQ