What Is A Hodl Invoice?

Bitcoin HODL invoice

Share this article

The Lightning network enables fast and low-cost payments using bitcoin, which is not only ideal for streaming payments and micro-payments but for everyday purchases. The ability to clear a payment instantly works fantastically well for over-the-counter purchases but does have its limitations for certain merchants.

There will be some cases where instant settlement might not be ideal, and having the ability to set a delayed payment or a conditional payment would be more helpful, and this is where the idea of hodl invoices comes into play.

What are hodl invoices?

Hold invoices are LN invoices where the receiver doesn’t immediately release the preimage upon receiving the action of payment. Instead, the receiver performs some action and either accepts the payment, explicitly rejects it, or lets it time out.

A practical example would be trading with an eCommerce store that accepts bitcoin payments via Lightning. The merchant could automatically generate hold invoices on her website but wait until a customer paid before searching her inventory for the requested item.

This would allow the merchant to cancel the payment if they couldn’t deliver the product or if there were delays with the product shipping. Using a hodl invoice means the funds have not cleared, and the merchant has a chance to inform the client. These hodl invoices can avoid unnecessarily processing of refunds and reduce the cost of managing and processing refunds.

How do hodl invoices work?

Hold invoices require a Hash Time-Locked Contract that allows control of the receiver of an invoice to cancel the invoice. Instead of immediately locking in and settling the HTLC when the payment arrives, the HTLC for a hold invoice is only locked in and not yet settled. At that point, it is not possible anymore for the sender to revoke the payment, so the funds cannot be reversed, but the receiver can still choose whether to settle or cancel the HTLC and invoice.

From the sender’s perspective, a hold invoice payment request looks identical to a regular payment request. There is no way for the sender to know when a hold invoice is paid but the receiver will have the option to return the funds to the sender based on certain conditions.

One possible indication of a hodl invoice that it will have a longer-than-normal expiry parameter.

.A hodl invoice can be resolved in two ways:

  1. The payment is settled when the recipient releases the preimage (to the payment route)
  2. The payment is canceled if the recipient does not release the preimage and the invoice expires

hodl invoice works in the exact way that a standard invoice does, except that, when the recipient receives the payment on a given route, they do not immediately/automatically return the preimage back. 

As a reminder, a successful payment is a 2-part process consisting of sending a payment for a given invoice along a Lightning Network route from sender to recipient and receiving the secret (preimage) for the payment back up to the route.

With a hodl invoice there is also an additional option where the recipient does not have to be the same person creating the payment hash for a given invoice they will generate (as is usually the case). They can also receive a payment hash from another party to create an invoice again where that other party would be the one that will hold the secret (preimage) for the hash until some condition is met and the secret is revealed, which allows the invoice to be successfully settled.

Practical examples for hold invoices  

To give you a better idea of how hodl invoices can help lightning users and merchants, consider the following scenarios that could be solved by using different combinations of the elements of a hodl invoice.

The two elements that will be varying are:

  • who creates the preimage and generates the payment hash from it for a given invoice
  • how the preimage gets revealed to the final recipient/s for settlement

Simple delay by recipient

  1. No reveal required (because the recipient creates the preimage secret). This type of hodl invoice can be used to manage merchant returns, e.g. where the merchant can hold the invoice for a certain return period and only settle it after the return period expires. If a return is made, the merchant simply does not settle the invoice, and the funds are effectively returned to the customer. It can also be used in the opposite way where a recipient does not settle the invoice if some condition is met. In this scenario, the hodl invoice acts as a fidelity bond of sorts for the performance of some service or action, and failure to perform that service/action leads the recipient to settle the invoice (cashing the bond)

(All other examples below, trust not to reveal secret preimage to any other route participants)

Simple delay by the sender

  1. Secret revealed out-of-band by the sender, e.g. customer pays the invoice but holds the secret until delivery of service when it is revealed to the merchant allowing them to settle the paid invoice
  2. Secret revealed via on-chain transaction, e.g. submarine swap where sender must necessarily reveal the preimage when sweeping an on-chain HTLC and recipient can use revealed preimage to settle invoicecaveat: preimage is revealed before the transaction is mined. If a high enough fee isn’t used, the recipient could potentially double-spend UTXOs involved in HTLC before HTLC can be mined

Chained delay by the sender

  1. Secret revealed out-of-band by the sender, secret revealed via settlement to chain participants in this scenario, the sender (customer) can generate a single preimage and share the resulting payment hash to multiple parties for them to make invoices from. This allows for a chained settlement of sorts where the settlement of an invoice at the tip of the chain reveals the preimage progressively to other payment chain participants, who can, in turn, settle their own invoices and reveal the preimage to other participants down the chain.
    • The customer creates a payment hash and gives it to the merchant with the caveat that they will only reveal the image to a courier on delivery of the items
    • The merchant finds a courier and shares the payment hash to create a service invoice that the merchant pays to the courier. The courier can only settle this invoice by successfully delivering items to the customer and receiving the preimage from them
    • On successful delivery, the courier receives the preimage from the customer (an out-of-band reveal) and settles the invoice the merchant paid them. Once this invoice is settled, the preimage is naturally revealed to the merchant (revealed by invoice settlement), who can then use it to settle the invoice the customer, in turn, had originally paid them with Caveat: if a path participant sits on two routes, there’s a risk they can take the revealed preimage from payment of one invoice and collect a settlement on the second invoice before the recipient is able to settle their hodl invoice

Limitations of hodl invoices

There is a limit of 483 in-flight invoices that can be routed at any given time by a node (due to constraints about the on-chain transaction size limits). This is distinct from “open invoices” and only refers to invoices where the payment was started but is still incomplete, as is the case with hodl invoices.

This limitation might not affect smaller merchants, but larger ones would probably require multiple Lightning nodes to manage their invoices.

Introduction to hodl invoices

If you’d like to learn more about hodl invoices, we recommend checking out the following presentations.

Trey Griffith of Sparkswap introduces us to HODL invoice
Joost Jager going through hold invoices

Sources:

  1. https://wiki.ion.radar.tech/
  2. https://github.com/

Are you a bitcoin and lightning fan?

Have you been using Lightning to make micro-payments? Stream sats or engage with apps? Which app is your favourite? Have you tried all the forms of Lightning payments? Which one do you prefer? Let us know in the comments down below.

Disclaimer: This article should not be taken as, and is not intended to provide any investment advice. It is for educational and entertainment purposes only. As of the time posting, the writers may or may not have holdings in some of the coins or tokens they cover. Please conduct your own thorough research before investing in any cryptocurrency, as all investments contain risk. All opinions expressed in these articles are my own and are in no way a reflection of the opinions of The Bitcoin Manual

Related articles

You may also be interested in

why bitcoin mining operations fail

Why Bitcoin Miners Fail

The bitcoin mining business is not a get-rich-quick scheme that involves plugging in a magic money printer machine; it’s a worldwide competition to provide security

Sign up to our newsletter

Never Miss A Story

Get the latest bitcoin news, articles and resources.

Cookie policy
We use our own and third party cookies to allow us to understand how the site is used and to support our marketing campaigns.