Hold Invoice

What Is a Hold Invoice?

A hold invoice is a Lightning Network invoice where the recipient knows the payment preimage but deliberately delays revealing it. In a standard Lightning payment, the receiver's node automatically releases the preimage the moment the HTLC arrives, settling the payment in milliseconds. A hold invoice breaks this automatic flow: the receiver holds the HTLC in a pending state, inspects external conditions, and then decides whether to settle (claim the funds) or cancel (return the funds to the sender).

This mechanism transforms Lightning from a simple payment rail into a programmable money layer. The pending state functions like trustless escrow: the sender's funds are committed but not yet received, and the HTLC's timelock guarantees the sender can recover funds if the receiver fails to act.

The terms "hold invoice" and "hodl invoice" refer to the same mechanism. LND's original implementation (introduced by Joost Jager in 2018 via pull request #2022) used "hodl" in its API naming, while Bitcoin Optech and formal documentation typically use "hold." The community uses both interchangeably.

How It Works

A standard BOLT 11 Lightning payment follows a straightforward flow: the receiver generates a random secret (the preimage), hashes it with SHA-256 to produce the payment hash, and embeds that hash in an invoice. The sender routes an HTLC locked to this hash through the network. When the HTLC reaches the receiver, their node reveals the preimage automatically, and the payment settles as the preimage propagates back through each hop.

Hold invoices change who controls the preimage. Instead of letting the Lightning node generate the preimage internally and settle on its own, the application layer generates the preimage, computes the hash, and passes only the hash to the node when creating the invoice. The application retains the preimage and decides when to release it:

1. The application generates a cryptographically random 32-byte preimage
2. The application computes the SHA-256 hash of the preimage
3. The application calls addholdinvoice (LND) or an equivalent RPC, providing the hash and the invoice amount
4. The sender pays the invoice normally: HTLCs propagate through the route
5. The receiver's node accepts the incoming HTLC and transitions the invoice state to ACCEPTED, but does not settle
6. The application evaluates external conditions: delivery confirmation, oracle data, compliance checks, or manual approval
7. The application either calls settleinvoice (revealing the preimage to claim funds) or cancelinvoice (failing the HTLC back to the sender)

From the sender's perspective, a hold invoice looks and behaves identically to any other Lightning invoice. 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. All routing nodes along the path settle their HTLCs in sequence, and the receiver claims the funds.
• Cancel: the receiver explicitly rejects the HTLC without revealing the preimage. The sender recovers funds immediately rather than waiting for a timeout. This is the preferred path when conditions are not met.
• 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, crashes, or fails to act.

Implementation Example

In LND, hold invoices are supported natively through the invoicesrpc subserver. The REST endpoint is POST /v2/invoices/hodl:

# Step 1: Generate a preimage and compute its hash
preimage=$(openssl rand -hex 32)
hash=$(echo -n "$preimage" | xxd -r -p | sha256sum | cut -d' ' -f1)

# Step 2: Create a hold invoice locked to this hash
lncli addholdinvoice --hash=$hash --amt=50000

# Step 3: Wait for payment (invoice state transitions to ACCEPTED)
# Application logic runs here: verify conditions...

# Step 4a: Settle the invoice (claim funds)
lncli settleinvoice $preimage

# Step 4b: Or cancel the invoice (return funds to sender)
lncli cancelinvoice $hash

The critical distinction from a regular addinvoice call: the application provides the hash rather than letting LND generate the preimage internally. This gives the application full control over when settlement occurs.

Hold Invoices vs. Standard Invoices

The following table summarizes the key differences between a standard Lightning invoice and a hold invoice:

Use Cases

Marketplace Escrow

Peer-to-peer marketplaces face a classic trust problem: buyers want to pay after receiving goods, while sellers want payment before shipping. Hold invoices solve this without a trusted intermediary. The buyer pays a hold invoice, locking funds in the HTLC. The seller sees the committed funds and ships the item. 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. Platforms like RoboSats use this pattern for trustless peer-to-peer Bitcoin trading.

Atomic Swaps and Submarine Swaps

Atomic swaps exchange assets across different layers or chains with guaranteed atomicity: either both sides complete or neither does. Hold invoices enable the Lightning leg of these swaps by keeping the HTLC pending while the counterparty's on-chain transaction confirms. Both legs share the same payment hash, so claiming one side reveals the preimage needed for the other.

Submarine swaps are a specific type of atomic swap that moves funds between on-chain Bitcoin and Lightning. Services like Loop and Boltz rely on hold invoices to keep the Lightning payment pending while the on-chain leg confirms, ensuring atomic settlement across layers.

Payment-on-Delivery

Any scenario where payment should be conditional on delivery or verification can use hold invoices. A freelancer can issue a hold invoice for their fee: the client pays (locking funds), the freelancer delivers the work, and the freelancer settles the invoice upon client approval. This pattern extends to:

• Physical goods delivery: settle once shipping confirmation is received
• Digital service verification: hold until an API confirms service was rendered
• Oracle-gated payouts: settle only when an oracle confirms a real-world outcome
• Exchange deposits: hold while compliance checks run, cancel if verification fails

Liquidity Cost of Held Payments

The defining tradeoff of hold invoices is their liquidity cost. While a standard Lightning payment locks channel capacity for milliseconds, a hold invoice locks capacity for the entire hold duration at every hop along the route.

Consider a payment routed through five intermediate nodes. Six channels have their capacity reduced by the HTLC amount for as long as the invoice is held. Routing nodes earn no fee during this period because fees are only collected upon settlement. This creates a negative externality: the receiver benefits from the hold period, but routing nodes bear the liquidity cost without compensation.

Each channel direction supports a maximum of 483 concurrent in-flight HTLCs, derived from the maximum Bitcoin transaction size. Long-lived hold invoices consume these finite slots. Some routing nodes mitigate this by rejecting HTLCs with excessively long CLTV deltas, setting maximum hold durations, or deprioritizing traffic from nodes known to produce long-held HTLCs.

Channel Jamming Risk

The liquidity-locking property of hold invoices can be weaponized. Channel jamming is an attack where a malicious actor sends payments to hold invoices they control and never settles them. This locks victim routing node liquidity at near-zero cost: the attacker receives a full refund when the payments eventually time out. Only 483 small HTLCs are needed to completely jam a channel in one direction.

The Lightning Network community is developing several mitigations:

• HTLC endorsement: a reputation-based mechanism where routing nodes prioritize HTLCs vouched for by trusted peers, proposed in BOLT PR #989
• Hold fees: charging a fee proportional to the HTLC hold duration, converting a currently free attack vector into a costly one
• Upfront fees: requiring a small payment at each hop regardless of whether the HTLC settles

No single solution has been widely deployed yet. Applications using hold invoices should minimize hold durations and cancel promptly when conditions are not met.

Risks and Considerations

Timeout and Force-Close Risk

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

Preimage Storage Durability

The preimage is the key to claiming held funds. If the application crashes or its database is lost during the hold period, the preimage may be irrecoverable: the receiver cannot settle the invoice even though conditions have been met. Applications must store preimages in durable storage with backup, and implement robust monitoring to detect stuck invoices.

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). The hold period at the destination is additive on top of this. Setting excessively long CLTV values reduces the probability of successful routing, as intermediate nodes may reject the HTLC.

Why It Matters

Hold invoices are the foundational primitive for conditional payments on the Lightning Network. Without them, any transaction requiring verification, escrow, or multi-step coordination would need a trusted intermediary. With hold invoices, the HTLC mechanism provides trustless enforcement: the cryptographic link between payment hash and preimage guarantees that funds can only move when the receiver explicitly acts.

For a deeper technical exploration of how hold invoices enable conditional payment flows, see the research article on Lightning HODL invoices and conditional payments. For more on the broader invoice landscape, see Lightning invoices: BOLT 11 vs. BOLT 12.

Newer Bitcoin Layer 2 protocols take different approaches to conditional transfers. Spark, for example, uses virtual UTXOs and FROST threshold signatures instead of HTLCs, avoiding the liquidity-locking trade-offs that hold invoices introduce to the routing network.

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.