Blog
Understanding Hold Invoices on the Lightning Network

Understanding Hold Invoices on the Lightning Network

Bobby Shell
Bobby Shell

September 13, 2023

Hold Invoices, or HODL Invoices, were first introduced for LND in 2019. This feature leverages the capabilities of the Lightning Network to provide a distinctive approach to handling payments, enabling a new set of use cases and applications on Bitcoin’s second layer.

In this post, we will unravel the intricacies of Hold Invoices. Starting with a clear definition of what is a Hold Invoice and how it differs from a regular invoice, we’ll then explore the inner workings of a Hold Invoice, offering a deeper understanding of its mechanism. Finally, we’ll take a look at the variety of real-world use cases enabled by Hold Invoices.

So, whether you are a developer building a cool Lightning project, a business seeking to innovate, or just someone curious about the dynamics of Hold invoices, this post is designed to help you. Let's get started.

Overview of Lightning Payments

A regular payment in the Lightning Network is a Hash-Time Locked Contract (HTLC), a smart contract written in the Bitcoin Script language that enables off-chain trustless Bitcoin payments. If we were to write the HTLC using English instead of Bitcoin script to represent a 1 BTC payment on the Lightning Network from Alice to Bob it could be written like this:

“I, Alice, will pay Bob 1 BTC if he can provide a secret message that hashes to 9ed15..232e and a valid signature to prove he’s Bob.

If I send Bob the payment and he doesn’t send me the secret within 24 hours I can get my money back.

If Bob tries to lie about the amount I owe him, I can punish him and have all the funds we’ve locked in our financial contract to me.”

To request the payment from Alice, Bob will generate a secret message and hash it. For our example let’s say that the secret message is “Run Nodes” and that it hashes to 9ed15..232e. In technical terms, the secret message is called “payment pre-image,” and the hash is called the “payment hash”. Bob adds the payment hash in the invoice he sends Alice so she can write it in the HTLC, as she did above. To receive the money, Bob must reveal the secret to settle the payment. Once he does that, he’s able to claim the money.

Understanding Hold Invoices

A Hold Invoice is an alternative type of invoice that triggers a different payment flow. Instead of immediately settling the payment by revealing the payment pre-image to the sender, the Hold Invoice enables the receiver to lock the HTLC and delay (or even cancel) the act of revealing the payment pre-image to complete the payment. This allows recipients to accept Lightning payments at their discretion. As mentioned previously, there is a finite period within which the recipient can reveal the invoice. If this specific timeframe is exceeded, the possibility of settling the payment is no longer viable.

Let’s suppose that Bob runs a clothing store. Alice wants to buy shoes from his store, so instead of sending a regular invoice, Bob sends a Hold Invoice to Alice. Instead of immediately sending the payment pre-image back to Alice, he checks that he has the sneakers Alice wants to buy before settling the payment. Once he has the item, he can return the payment pre-image and settle the invoice.

A Hold invoice can also be used when the receiver doesn't initially have access to the preimage of the payment hash. In this case, the receiver can accept the payment and take additional steps to obtain the pre-image. The payment can only be finalized once the receiver successfully obtains the preimage. We’ll see how this can be used in the following section.

Use Cases

We’ve already seen a simple use case in the previous section, but there’s much more that can be done with Hold Invoices. Let's explore some use cases:

Security Deposits

Owners of a ski equipment rental store can use Hold Invoices as safety deposits. If a customer damages the equipment, the owner reveals the payment pre-image to claim the safety deposit; otherwise, they can just let the payment expire, and the customer will have their money back.

Atomic Pizza Deliveries

In programming terms, “atomic” means an action that occurs entirely or doesn’t occur. Hold Invoices can be used to create a “no pizza no payment policy.” Here is how it works:

The customer orders a pizza and sends a payment hash for a secret it knows. The pizza place creates and sends the customer a Hold Invoice with the described payment hash. The client now pays the invoice, but since the restaurant does not know the secret, it can’t settle the payment. When the pizza is delivered to the customer, the delivery guy asks the customer the secret; once the information is revealed the pizza place can settle the payment and receive the money.

How Hold Invoices Are Used Today

RoboSats is a peer-to-peer exchange integrated with the Lightning Network. They use Hold Invoices in their Trade Escrow to secure transactions and prevent fraud when trading Bitcoin.

When a seller decides to sell Bitcoin, they create a Hold Invoice, essentially locking the amount they wish to sell in an escrow-like state. The Hold Invoice acts as a trade escrow, securing the funds for the transaction and ensuring the buyer that their funds will be protected against fraud or non-payment. The trade escrow, in this case, the Hold Invoice, is locked towards the RoboSat’s experimental coordinator node. It gets settled when the seller confirms that it got paid.

Using Hold Invoices

If you run a Voltage Node or self-host your own LND node, you can use LND’s AddHoldInvoice to create a Hold Invoice and CancelInvoice or SettleInvoice to cancel or settle the Hold Invoice, respectively. You can read their API docs for further instructions.

Drawbacks of Hold Invoices

Unfortunately, this feature doesn’t come without tradeoffs. Here are some of the drawbacks of using Hold Invoices.

Liquidity Lock-up

Since HODL invoices essentially lock up funds in a transaction, intermediate nodes on the payment route may inadvertently lock their liquidity into payments that could take a long time to settle. This could potentially hinder their ability to route more payments, thereby reducing their operational efficiency and negatively impacting the overall liquidity of the network.

Limit on Concurrent HTLC Payments

The Lightning protocol allows 483 concurrent HTLCs to conform with the standard transaction size. This implies that Hold Invoices can take up significant transaction space, even those involving small amounts.

Trust in the Receiver

There's a level of trust in the receiver to act appropriately by releasing the pre-image or not, based on other physical or virtual conditions. This adds an element of counterparty risk to the transaction, as the sender must trust that the receiver will behave as expected.

Concluding

  • Hold Invoices or HODL Invoices are a distinct type of invoice introduced for LND in 2019.
  • They leverage the capabilities of the Lightning Network, enabling new use cases for Bitcoin’s second layer.
  • Different from regular invoices, Hold Invoices allow the receiver to delay or cancel the act of revealing the payment pre-image, thus settling the payment at their discretion
  • A Hold invoice does not require immediate release of the payment pre-image, introducing a new dynamic to the payment process.
Share this post

Start Building on Bitcoin Now