Hold invoices are a mechanism for delaying the settlement of an invoice. Typically upon receipt of payment.

Hold invoices versus Regular Invoices

Regular invoices are created and paid on a per-transaction basis. When a payer wants to make a payment, they generate a payment request (invoice) with a specific amount and pay that exact amount. The payment is settled immediately and the payment channel is closed.

hold/hodl invoices work in a similar way to standard Lightning Network invoices, with the main difference being that the recipient of the payment does not immediately return the preimage back to the sender when they receive the payment on a given route.

Here's how the process works:

1. The sender generates a hold/hodl invoice with a specific payment amount and a payment hash.

2. The sender shares the payment request with the recipient, who then generates an invoice of their own with the same payment hash and shares it back with the sender. This creates a shared secret between the two parties, which is needed to settle the payment later.

3. The sender initiates the payment, which is routed through the Lightning Network to the recipient.

4. The recipient receives the payment and acknowledges it, but does not return the preimage back to the sender immediately. Instead, they hold onto the preimage until a later time, as defined by the terms of the hold/hodl invoice.

5. At a later time, the recipient can settle the payment by returning the preimage back to the sender, who can then use it to prove that the payment was made.

Another difference between regular invoices and hold invoices is the expiry time. Regular invoices have a fixed expiry time, typically between 1-24 hours, after which the invoice is no longer valid and cannot be paid. Hold invoices, however, can be held open indefinitely until the payment threshold is met, so there is no expiry time as long as the payment channel remains open.

In summary, while regular invoices on the Lightning Network allow for immediate settlement of a specific payment, hold invoices enable the holding of funds in a payment channel until a specific threshold is met.

Usage in Lnd using lncli

To enable hold invoice functionality, lnd needs to be built with the invoices sub-server enabled:

make tags="invoicesrpc"

Creation of a hold invoice

To add a hold invoice, invoke:

lncli addholdinvoice <hash> --amt <amt>

lncli addholdinvoice <hash> --amt <amt> is a command that can be used in the Lightning Network (LND) client to create a new hold/hodl invoice with a specific payment hash and payment amount.

Here's what each of the arguments means:

• lncli: This is the command-line interface for the LND client.

• addholdinvoice: This is the command used to create a new hold/hodl invoice.

• <hash>: This is the payment hash that is used to uniquely identify the payment. The payment hash is generated by the sender and shared with the recipient.

• --amt <amt>: This specifies the amount of the payment in satoshis. The --amt flag is followed by the payment amount in satoshis.

Waiting for acceptance

Typically an application wants to receive a notification when the htlc is accepted. This event isn't notified through the general SubscribeInvoices rpc. The reason for this is not to break backward compatibility and prevent difficulties in the interaction with the add and settle indices of that call. Instead, the new SubscribeSingleInvoice RPC can be used.

SubscribeSingleInvoice is not available through lncli. For testing, the invoice state can be observed through lncli lookupinvoice <hash>.

Settling or canceling

Once the htlc has been accepted in lnd, it is held there until either cancel or settle rpc is received. Both can be issued through lncli:

lncli cancelinvoice <hash>

When a hold/hodl invoice is created, the recipient holds onto the preimage until a later time, as defined by the terms of the invoice. If, for some reason, the recipient needs to cancel the invoice before it has been settled, they can use the lncli cancelinvoice <hash> command to do so.

Here's how the process works:

1. The recipient initiates the cancellation of the hold/hodl invoice by using the lncli cancelinvoice <hash> command, where <hash> is the payment hash of the invoice.

2. If the invoice has not yet been settled, it will be canceled and marked as such in the LND client.

3. If the invoice has already been settled, the cancellation request will be rejected, as it is not possible to cancel a settled payment.

It's worth noting that canceling a hold/hodl invoice does not automatically return the funds to the sender. Instead, the recipient must manually return the funds to the sender by settling the payment and returning the preimage. If the recipient does not do so, the funds will remain in limbo until the hold period expires, at which point they will be returned to the sender.

lncli settleinvoice <preimage>

To settle a hold/hodl invoice and claim the funds, the recipient uses the lncli settleinvoice <preimage> command.

Once the recipient has settled the invoice and returned the preimage to the sender, the sender can initiate the release of the funds.

Here's how the process works:

1. The sender creates a hold/hodl invoice and shares the payment request with the recipient.

2. The recipient initiates the payment by sending the payment along the Lightning Network route to the sender.

3. Once the payment has been sent, the recipient holds onto the preimage until a later time, as defined by the terms of the hold/hodl invoice.

4. The recipient is ready to settle the invoice, they use the lncli settleinvoice <preimage> command to release the funds.

5. The preimage is included as an argument to the lncli settleinvoice command, and is used to prove that the payment has been made and the funds should be released.

It's worth noting that hold/hodl invoices rely on the same basic Lightning Network technology as standard invoices, including HTLCs and smart contracts. The main difference is in how the payment is settled, with the recipient holding onto the preimage until a later time instead of immediately returning it to the sender.