Extending BIP 174 for HTLCs

We’ve talked about BIP 174 before, this time we’re bringing a quick update and that is HTLC support.

HTLC stands for Hashed TimeLock Contracts, they are a type of payments that uses hashes and time locks to require the receiver to generate a cryptographic proof (preimage) that they did receive the payment, otherwise the payment is forfeited and sent back to the sender.

Alex Bosworth proposed adding HTLC support to PSBTs by adding an extra input.

Not sure on the best format for this, but what I have been thinking about is a new input type that defines elements that should be inserted in the final p2sh/p2wsh stack such as a preimage or a refund path flag.

Type: Additional Stack Element ADDITIONAL_STACK_ELEMENT = 0xXX

Key: The index in the stack to insert a value (uint32 LE)

{0xXX}|{Stack index}

Value: The value to push into the stack for a redeem script or witness script at the specified index.


The proposed approach by Pieter Wuille is that the updater adds a preimage request field and once the sender recognizes this field and is ok with sending the preimage, they add a preimage field and send it to the finalizer. This method requires the updater and the finalizer to be compatible with all types of Hashlocks and other scripts, so it could be inefficient.

A useful way to look at it IMHO is to see a hash as the analogue of a public key, and the preimage as the analogue of a signature.

That would suggest adding two fields to PSBT:

  • A request for the preimage of a given hash (similar to the pubkey/path field currently)
  • A revealed preimage for a given hash (similar to the partial signature field currently).

The workflow would in this case would be:

  • An “updater” recognizes an output/script as being one that requires a preimage, and adds a preimage request field to the input (along with pubkey fields for all involved keys).

  • A “signer” who knows the preimage sees the request field, verifies he’s willing to divulge the secret, and adds a preimage field (along with any signatures he may be able to create).

  • A finalizer who is compatible with the type of hashlock script combines all signatures and preimages into a final scriptSig/witness stack.

Pieter also mentioned he is working on another implementation but is yet to release any information on it.

To join further discussions on this, you can check the bitcoin-dev mailing list.


Support us and the authors of this article by donating to the following address:


Comments powered by Talkyard.