Lightning HODL Invoices: How Conditional Payments Enable Escrow and Verification

Standard Lightning payments settle instantly: the receiver reveals a preimage, the HTLC resolves, and funds move in under a second. That speed is a feature for point-of-sale transactions, but it becomes a limitation when a payment should only complete after some real-world condition is met. HODL invoices solve this by letting the receiver delay settlement, holding the HTLC in-flight until they explicitly choose to settle or cancel.

First introduced by Joost Jager in LND pull request #2022 in 2018, HODL invoices (also called hold invoices) have become a foundational primitive for escrow services, marketplace settlement, atomic swaps, and any application where payment release should be conditional. This article explains the mechanism in detail, walks through the LND API, examines real-world use cases, and evaluates the tradeoffs that come with holding HTLCs open.

How Standard Lightning Invoices Work

Before understanding HODL invoices, it helps to review the normal payment flow. In a standard Lightning invoice, the receiver generates a random 32-byte secret (the preimage) and includes its SHA-256 hash (the payment hash) in the BOLT 11 encoded invoice. When the sender pays, each hop along the route locks funds in an HTLC conditioned on that hash.

Once the payment reaches the receiver, their Lightning node automatically reveals the preimage to the final hop, which cascades back through the route, settling each HTLC in sequence. The entire process is atomic: all hops settle or none do. The receiver never has to think about preimage management because their node handles it internally.

The HODL Invoice Mechanism

A HODL invoice inverts control over the preimage. Instead of letting the Lightning node generate and automatically reveal the secret, the application generates the preimage externally, computes its hash, and passes only the hash when creating the invoice. When payment arrives, the node accepts and locks the HTLC but does not settle it. The payment enters an "accepted" state where the sender cannot revoke it, but the receiver has not yet claimed the funds.

The receiver (or, more precisely, the application controlling the receiver's node) then has three options:

• Settle the invoice by revealing the preimage, completing the payment
• Cancel the invoice, which fails the HTLC and returns funds to the sender
• Do nothing, in which case the HTLC eventually times out via its CLTV expiry and funds return to the sender

Key distinction: With a standard invoice, the receiver's node settles automatically the moment payment arrives. With a HODL invoice, the node holds the HTLC and waits for an explicit settle or cancel instruction from the application layer. This gap between acceptance and settlement is what enables conditional payment logic.

The Preimage Flow

The critical difference is who generates and when they reveal the preimage. In a standard invoice, the receiver's node does both: it generates the preimage before creating the invoice and reveals it automatically when payment arrives. In a HODL invoice, the application generates the preimage, hands only its hash to the node for invoice creation, and retains the preimage until conditions are met.

Using the LND Hold Invoice API

LND exposes HODL invoice functionality through its Invoices gRPC service, which provides three core RPCs: AddHoldInvoice, SettleInvoice, and CancelInvoice. The equivalent lncli commands make it straightforward to experiment from the command line.

Step 1: Generate a Preimage and Hash

The application creates a cryptographically random 32-byte preimage and computes its SHA-256 hash. This happens outside of LND:

# Generate a random 32-byte preimage
preimage=$(openssl rand -hex 32)

# Compute the SHA-256 hash
hash=$(echo -n "$preimage" | xxd -r -p | sha256sum | cut -d' ' -f1)

echo "Preimage: $preimage"
echo "Hash:     $hash"

The application stores the preimage securely. It will only reveal it when the business condition is satisfied.

Step 2: Create the Hold Invoice

Pass the hash (not the preimage) to LND when creating the invoice:

# Create a hold invoice for 100,000 sats
lncli addholdinvoice --hash=$hash --amt=100000 --memo="Escrow payment"

# The response includes a BOLT 11 payment request
# Share this with the payer

You can also set a custom cltv_expiry to control the maximum time the HTLC can be held. The default in LND is 40 blocks (roughly 6.7 hours), but escrow applications often set higher values.

Step 3: Monitor Payment State

Use SubscribeSingleInvoice to watch for state changes. When the payer sends payment, the invoice transitions from OPEN to ACCEPTED. At this point, the HTLC is locked: the sender cannot revoke, but the receiver has not claimed funds.

# Subscribe to invoice state changes
lncli subscribeinvoice --payment_hash=$hash

# State transitions:
# OPEN -> ACCEPTED (payment arrived, HTLC held)
# ACCEPTED -> SETTLED (you called SettleInvoice)
# ACCEPTED -> CANCELED (you called CancelInvoice)

Step 4: Settle or Cancel

Once the condition is met (item shipped, service rendered, verification passed), reveal the preimage to settle:

# Settle: reveal the preimage to claim funds
lncli settleinvoice $preimage

# Cancel: fail the HTLC, return funds to sender
lncli cancelinvoice $hash

Settlement is irreversible. Once the preimage propagates back through the route, every hop settles and the payment is final. Cancellation is also final for that invoice: a new HODL invoice would need to be created for a retry.

Implementation note: In production applications, the preimage should be stored in a persistent database, not in memory. If your application crashes between accepting payment and settling, you need the preimage to complete settlement when you restart. Losing the preimage while an HTLC is accepted means you cannot claim the funds, and they will eventually time out back to the sender.

Use Cases for HODL Invoices

Escrow Services

The most natural application of HODL invoices is escrow. A buyer pays a HODL invoice, locking funds in the HTLC. The escrow service monitors for a condition (delivery confirmation, dispute resolution, or time-based release) and settles or cancels accordingly. Unlike traditional escrow where a third party holds actual funds, the HODL invoice model locks funds in the Lightning payment channel: the escrow service holds only the preimage, not the money.

The Shopstr marketplace on Nostr demonstrates this pattern in production. Shopstr implements a "Handshake" protocol where buyer funds are locked via HODL invoices, and settlement only occurs after the merchant confirms stock availability and verifies shipping details. The system uses NIP-17 encrypted direct messages for the order handshake and NIP-47 (Nostr Wallet Connect) for wallet interaction.

Proof-of-Delivery for Physical Goods

HODL invoices can enforce payment-on-delivery for physical goods. The buyer pays a HODL invoice when placing an order. The seller sees the payment as accepted (funds locked) and ships the item. Upon delivery, the buyer reveals a preimage to the courier (via QR code, for example), who forwards it to the seller's system to trigger settlement.

This creates an atomic link between physical delivery and payment: the courier proves delivery by obtaining the preimage, and the seller proves payment by settling the invoice. The challenge is that HTLC timeouts impose a hard deadline. If delivery takes longer than the CLTV expiry (typically hours to days, not weeks), the payment times out and returns to the buyer.

Marketplace Dispute Windows

Marketplaces can use HODL invoices to create dispute windows. After the buyer receives goods, the platform holds the invoice for a defined review period before settling. If the buyer raises a dispute during that window, the platform cancels the invoice and returns funds. This mirrors traditional marketplace escrow (like the model used by eBay or Amazon) but without the platform needing to custody funds.

Fidelity Bonds and Access Control

Services can require a HODL invoice payment as a fidelity bond: the user pays to gain access, and the service cancels the invoice when the session ends (returning funds). If the user misbehaves (spamming, abuse), the service settles the invoice as a penalty. This creates an economic deterrent without requiring identity verification or account registration.

Atomic Swaps and Submarine Swaps

Atomic swaps between on-chain Bitcoin and Lightning frequently use HODL invoices. In a submarine swap, one party locks Bitcoin on-chain in an HTLC using the same payment hash as a Lightning HODL invoice. When the Lightning payment settles (revealing the preimage), the on-chain party uses that preimage to claim the on-chain funds. The shared hash links the two legs atomically. Lightning Loop by Lightning Labs uses this exact pattern for Loop In and Loop Out operations.

Risks and Tradeoffs

Channel Liquidity Lockup

The most significant cost of HODL invoices falls on routing nodes, not on the sender or receiver. While an HTLC is held open, every node along the payment route has liquidity locked in that channel. A routing node that forwarded 500,000 sats for a HODL invoice cannot use those sats for other payments until the invoice settles or times out.

For a single small payment, this is negligible. But if a marketplace generates hundreds of HODL invoices per hour, the cumulative liquidity lockup across the payment channel network becomes substantial. Routing nodes have no way to distinguish a legitimate HODL invoice from a malicious one, and they earn no additional fees for the extended hold time.

Timeout Griefing

A malicious receiver can create HODL invoices and never settle or cancel them, forcing HTLCs to remain locked until their CLTV expiry. This griefing attack costs the attacker nothing (they receive no payment) but locks victim liquidity for the full timeout duration: potentially hours or days depending on the route's cumulative CLTV delta.

Research from Mizrahi and Zohar (2020) demonstrated that an attacker could lock a disproportionate amount of network liquidity relative to their own capital by opening channels and initiating payments they never resolve. HODL invoices make this easier because the hold behavior is by design, not a bug.

Force-Close Cascades

If an HTLC approaches its CLTV expiry without resolving, the routing node must force-close the channel to claim its funds on-chain before the timelock expires. Long-held HODL invoices increase the probability of force-closes, which are expensive (on-chain fees) and reduce network capacity. In extreme cases, a wave of expiring HODL-related HTLCs could trigger cascading force-closes across multiple channels.

Sender Experience

From the sender's perspective, a HODL invoice payment appears stuck: their wallet shows the payment as pending, and they cannot use those funds for other payments. If the sender's node crashes and restarts while the HTLC is in-flight, some implementations may require manual intervention or have edge cases around reconnection and state reconciliation.

Mitigation Efforts: HTLC Endorsement and Fees

The Lightning development community has been actively working on mitigations for channel jamming attacks, which HODL invoices can exacerbate. The most promising approach is a hybrid system combining HTLC endorsement with unconditional fees, proposed by Clara Shikhelman and Sergei Tikhomirov.

Under this model, routing nodes track the reputation of their peers based on past HTLC resolution behavior. Nodes that consistently forward payments that settle quickly earn endorsement, while nodes associated with long-held or failed HTLCs lose reputation. Additionally, a small unconditional fee (paid regardless of payment outcome) makes griefing attacks economically costly rather than free.

As of 2025, the HTLC endorsement proposal evolved into an "Outgoing reputation and HTLC Accountability" specification, with experimental implementations in LDK. Separately, John Law proposed using burnable outputs to enable upfront and hold fees, allowing nodes to charge proportionally to how long a payment is held. These proposals remain under active development and review.

PTLCs: The Next Generation of Conditional Payments

Point Time-Locked Contracts (PTLCs) represent the next evolution of the HTLC mechanism that underlies HODL invoices. Where HTLCs use hash preimages for conditional payment, PTLCs use adaptor signatures on elliptic curve points: a construction enabled by Schnorr signatures and Taproot.

The key advantage of PTLCs for conditional payments is privacy. In an HTLC-based HODL invoice, every hop along the route sees the same payment hash. A colluding set of routing nodes can correlate the sender and receiver by matching hashes across hops. PTLCs use different adaptor signatures at each hop, making this correlation impossible. Each forwarding node sees a unique cryptographic challenge unrelated to what other hops see.

PTLCs also enable more sophisticated conditional payment constructions. Because adaptor signatures can commit to arbitrary elliptic curve points, they can enforce conditions beyond simple preimage revelation: for example, proving that a Discreet Log Contract oracle attested to a specific outcome, or that a particular signature was produced.

HODL Invoices vs. Application-Layer Escrow

HODL invoices implement escrow at the protocol layer: the Lightning Network itself holds funds in-flight. An alternative approach is to settle payments instantly and implement escrow logic at the application layer, where a trusted service or smart contract holds funds after settlement and releases them based on conditions.

Each approach has distinct tradeoffs. Protocol-layer escrow (HODL invoices) avoids custodial risk since no party holds settled funds, but it locks routing liquidity and is constrained by HTLC timeouts. Application-layer escrow settles payments immediately (freeing routing liquidity) but requires trusting the escrow service with settled funds.

How Spark Approaches Conditional Payments

Spark offers a different foundation for building conditional payment flows. Because Spark transfers are atomic and settle with instant finality (no in-flight HTLC state), escrow logic is implemented at the application layer without the liquidity lockup problems inherent to HODL invoices.

A marketplace built on Spark can accept a payment (which settles immediately into a Spark balance), hold the funds in an application-level escrow account, and release them to the seller when conditions are met. The routing network is never burdened with pending HTLCs, and there are no CLTV timeouts forcing premature resolution. The tradeoff is that the escrow service must be trusted with settled funds during the hold period, but this is the same trust model used by every traditional marketplace (Airbnb, Amazon, Uber).

Developers building escrow or conditional payment features can explore the Spark SDK documentation for integration patterns. For end users, General Bread provides an example of a Spark-powered wallet where Bitcoin and stablecoin transfers settle instantly without channel management overhead.

When to Use HODL Invoices

HODL invoices remain the right tool when trustless, protocol-level conditional payment is the priority and the hold duration is short. They work best for:

• Atomic swaps where both legs must complete or neither does
• Short-duration verification checks (inventory, identity, authorization)
• Fidelity bonds where the hold period is a single user session
• Submarine swaps bridging on-chain and Lightning funds

They are less suitable for scenarios requiring extended hold periods (days or weeks), high payment volumes that would stress routing liquidity, or situations where the condition cannot be verified before the HTLC timeout. For those use cases, application-layer escrow on a fast-settling network like Spark or an on-chain smart contract is typically a better fit.

For a deeper look at Lightning payment mechanics, see our research on Lightning routing, channel jamming mitigation, and BOLT 11 and BOLT 12 invoice formats.

This article is for educational purposes only. It does not constitute financial or investment advice. Bitcoin and Layer 2 protocols involve technical and financial risk. Always do your own research and understand the tradeoffs before using any protocol.