Hold Invoice

What Is a Hold Invoice?

A hold invoice is a Lightning Network invoice where the recipient deliberately delays releasing the payment preimage after receiving the incoming HTLC. In a standard Lightning payment, the receiver reveals the preimage immediately upon receiving the HTLC, and the payment settles in milliseconds. With a hold invoice, the receiver keeps the HTLC pending: funds are locked but not yet claimed. The receiver can then settle the payment (by revealing the preimage), cancel it (by rejecting the HTLC), or let it expire via the timelock.

This mechanism transforms a simple payment into a conditional one. The receiver gains a decision point between receiving funds and claiming them, enabling use cases like escrow, pay-on-delivery, and cross-layer atomic swaps that would otherwise require a trusted intermediary.

The term "hold invoice" is the formal, descriptive name for this pattern. In the Lightning community, it is often called a hodl invoice: a reference to the crypto meme "HODL" (originally a misspelling of "hold" from a 2013 Bitcoin forum post). Both terms refer to the identical mechanism. LND's original implementation used "hodl invoice" in its API naming, while Bitcoin Optech and more formal documentation tend to use "hold invoice."

How It Works

To understand hold invoices, it helps to first trace a normal Lightning payment:

1. The receiver generates a random secret (the preimage) and computes its SHA-256 hash (the payment hash)
2. The receiver encodes this hash into a BOLT 11 invoice and sends it to the payer
3. The sender routes an HTLC locked to this hash through intermediate nodes
4. When the HTLC arrives, the receiver immediately reveals the preimage, settling the payment
5. The preimage propagates back through each hop, releasing locked funds along the route

A hold invoice modifies step 4. Instead of the Lightning node automatically settling, the application layer generates the preimage externally, provides only the hash to the node, and retains control over when (or whether) to reveal it:

1. The application generates a preimage and computes its hash
2. The application creates a hold invoice on the node using only the hash
3. The sender pays the invoice normally: HTLCs lock along the route
4. The receiver's node accepts the incoming HTLC but does not settle it (invoice state transitions to ACCEPTED)
5. The application evaluates conditions: delivery confirmation, oracle data, compliance checks
6. The application calls settle (revealing the preimage) or cancel (failing the HTLC back)

From the sender's perspective, a hold invoice looks identical to any other Lightning invoice. There is no way for the sender to distinguish between the two: the BOLT 11 encoding is the same. The only observable difference is that the payment may take longer to resolve.

Three Possible Outcomes

Every hold invoice resolves in one of three ways:

• Settle: the receiver releases the preimage, claiming the funds. All routing nodes along the path settle their HTLCs in sequence.
• Cancel: the receiver explicitly rejects the HTLC without revealing the preimage. Funds return to the sender immediately rather than waiting for timeout.
• Timeout: the CLTV timelock expires before settlement. The sender recovers funds via the timeout path. This is the safety net if the receiver goes offline or fails to act.

Implementation in LND

LND provides native hold invoice support through its invoicesrpc subserver, available since March 2019. The key APIs:

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

# Create the hold invoice (note: you provide the hash, not the preimage)
lncli addholdinvoice --hash=$hash --amt=100000

# Monitor for incoming payment (state changes to ACCEPTED)
# Application logic runs here: verify delivery, check oracle, etc.

# Option A: settle the invoice (claim funds)
lncli settleinvoice $preimage

# Option B: cancel the invoice (return funds to sender)
lncli cancelinvoice $hash

The critical difference from a regular invoice: with addinvoice, LND generates the preimage internally and settles automatically. With addholdinvoice, the application provides the hash and retains the preimage, giving it full control over settlement.

Implementation in Core Lightning

Core Lightning (CLN) supports hold invoices through plugins rather than built-in RPCs. The actively maintained plugin from Boltz Exchange provides equivalent functionality:

# Create a hold invoice
lightning-cli holdinvoice amount_msat label description cltv_delta

# Settle when conditions are met
lightning-cli settleholdinvoice preimage

# Cancel if conditions fail
lightning-cli cancelholdinvoice payment_hash

CLN plugins can also intercept HTLCs via the htlc_accepted hook, enabling custom hold logic at a lower level. The Boltz plugin includes auto-cancellation safety logic that cancels pending invoices before the HTLC timelock expires (default: 6 blocks before expiry) to prevent force-close scenarios.

Hold Invoices vs. Regular Invoices

The following comparison highlights the key differences between standard Lightning invoices and hold invoices:

Use Cases

Marketplace Escrow

Peer-to-peer marketplaces like RoboSats use hold invoices to create trustless escrow. The buyer pays a hold invoice, locking funds in the HTLC. The seller sees the funds are committed and ships the goods. Once the buyer confirms receipt, the seller settles the invoice and claims payment. If the seller never ships, the HTLC times out and the buyer recovers their sats. No intermediary holds funds at any point.

Submarine Swaps

Submarine swaps move funds between on-chain Bitcoin and Lightning. Services like Loop and Boltz use hold invoices to keep the Lightning leg pending while an on-chain transaction confirms. Both legs share the same payment hash, so claiming one side reveals the preimage needed for the other: this guarantees atomic settlement.

Exchange Deposits

Cryptocurrency exchanges can accept Lightning deposits using hold invoices. The exchange holds the invoice in a pending state while running compliance checks, verifying the sender's identity, or waiting for internal account crediting workflows. If checks fail, the exchange cancels the invoice and the sender immediately recovers funds: no refund process is needed.

Conditional Delivery

Any payment conditional on an external event can use hold invoices:

• Pay-on-delivery: hold payment until shipping confirmation or proof of service completion
• Oracle-gated payments: settle only when an oracle confirms a real-world outcome (sports result, price threshold, weather event)
• Multi-party approval: wait for multiple stakeholders to authorize before releasing funds
• API verification: hold payment until an external API confirms a digital service was rendered

Risks and Considerations

Locked Liquidity and Routing Impact

While a hold invoice is pending, funds are locked not only for the sender but at every routing node along the payment path. Each hop has an HTLC consuming channel capacity. For a payment routed through five hops, six channels have liquidity locked for the entire hold duration.

Each channel direction supports a maximum of 483 concurrent in-flight HTLCs (derived from the maximum Bitcoin transaction size). Hold invoices that persist for long periods occupy these slots, potentially blocking other payments from routing through affected channels. This is why some routing nodes reject HTLCs with very long CLTV deltas or deprioritize traffic from nodes known to produce long-held HTLCs.

Channel Jamming and Griefing

Malicious actors can exploit hold invoices for channel jamming attacks. By sending payments to hold invoices they control and never settling, an attacker can lock victim routing node liquidity at zero cost. Only 483 small HTLCs are needed to completely jam a channel in one direction. The Lightning Network community is developing mitigations like HTLC endorsement, a reputation-based mechanism that would allow routing nodes to prioritize trusted traffic.

Timeout and Force-Close Risk

If a receiver fails to settle or cancel a hold invoice before the HTLC timelock expires, intermediate nodes may be forced to close channels on-chain to protect their funds. This incurs on-chain fees and takes channels offline. Well-designed implementations include auto-cancellation logic that cancels pending invoices several blocks before the CLTV expiry deadline.

For applications using hold invoices, robust monitoring and alerting are essential. A system crash during the hold period could mean the receiver misses the settlement window entirely. The preimage must be stored durably: if lost, the receiver cannot claim funds even if conditions are met.

CLTV Accumulation

Each routing hop adds its own CLTV delta to the timelock chain. For a five-hop route where each node requires a 40-block delta, the sender's total timelock exceeds 200 blocks (roughly 33 hours). Hold invoices amplify this because the hold period at the destination is additive. Setting excessively long CLTV values on hold invoices reduces the probability of successful routing, as intermediate nodes may reject the HTLC.

Why It Matters

Hold invoices unlock conditional payment logic on the Lightning Network without sacrificing the trustless properties that make Bitcoin valuable. They are the primitive behind submarine swaps, peer-to-peer exchange escrow, and any application that needs a decision point between sending and receiving funds. As the Lightning ecosystem matures, solutions like HTLC endorsement and hold fee proposals aim to reduce the negative externalities of long-held HTLCs, making hold invoices more sustainable for the broader network.

For developers building on Bitcoin Layer 2 infrastructure, understanding Lightning invoice types is essential. Hold invoices represent one approach to programmable payments on Lightning. Newer protocols like Spark take a different approach to conditional transfers by using virtual UTXOs and FROST threshold signatures, avoiding the liquidity-locking trade-offs inherent to HTLC-based hold patterns.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.