A type of Hash Time-Locked Contracts that allows control 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, but the receiver still can choose whether to settle or cancel the htlc and invoice.
From the sender 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 to.
Receiver gains the ability to check a condition before settling. If the condition is not met, the invoice can still be canceled and a potential refund does not need to be given.
Example 1: web shop performing an inventory check. If the item is no longer in stock at the time the invoice is paid, the payment can be canceled.
Example 2: exchange accepting spontaneous LN deposits (building on top of #2455). The account to credit is specified as user data in the EOB and the exchange first checks whether this account is valid before settling the incoming htlc.
A service can use a hold invoice as an insurance against bad behaviour by its users, similar to a fidelity bond. The user gains access to the service by paying the hold invoice. When the session is over, the service cancels the invoice and the user regains its funds. The only cost for the user has been the time value of those funds. When the user misbehaves during the session, the service can settle the hold invoice as a penalty.
Example 3: prevention of dos attacks: A hold invoice may also be created if the preimage of the payment hash is not yet known to the receiver. Receiver can accept the payment and perform a follow up action to obtain the preimage. Only once the preimage is obtained, the receiver can settle the payment.
Example 4: pizza delivery service wanting to offer "no pizza no pay". A customer generates a random preimage and adds the hash of it to the pizza order. The delivery service creates a hold invoice tied to this hash and returns the invoice to the customer. Customer pays the invoice. At this point, the delivery service can accept the payment, but not settle it because it doesn't know the preimage yet. Then the driver goes out to deliver the pizza. At the door he asks the customer for the preimage, verifies that it is indeed the preimage of the hold invoice for this order and hands over the pizza. Verification can even be done offline. The delivery service can then settle the invoice when the driver returns with the preimage. Atomic pizza swap completed.
Example 5: parcel delivery service. Similar to pizza, but here the payer and recipient are different people. Payer pays the hold invoice of the delivery service and gives the preimage to the recipient of the parcel.
Example 6: taking this one step further in a three party example: a customer, a web shop and a delivery service. Customer generates preimage, customer sends hash of preimage to web shop, web shop creates hold invoice, customer pays hold invoice, web shop sends hash to delivery service, delivery service creates hold invoice for delivery cost, web shop pays delivery hold invoice, delivery service delivers to customer in exchange for preimage, delivery service settles delivery invoice with preimage, web shop settles customer invoice with preimage.
In this example there is a risk associated with reuse of the payment hash. Intermediate nodes on both paths may shortcut the preimage and disallow the webshop from receiving any money.
Example 7: using hold invoice to execute a trustless atomic off-chain to on-chain swap. User A creates a secret preimage and passes the hash of it to user B. User B creates a hold invoice tied to this hash. User A pays the invoice. User B publishes an on-chain htlc tied to the same hash. When user A sweeps the on-chain htlc with the preimage it knows, user B learns it too and can pull the off-chain invoice.
Instructions below are for LND
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 holdinvoice, invoke:
lncli addholdinvoice <hash> --amt <amt>
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 backwards 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 a cancel or settle rpc is received. Both can be issued through lncli:
lncli cancelinvoice <hash>
lncli settleinvoice <preimage>