Component

Swaps

A hash-locked voucher and a Lightning HTLC that use the same secret settle together: revealing the secret to collect one makes the other redeemable. The HTLC has a deadline and the voucher does not, so the secret must come from the party the HTLC pays, and the voucher must be redeemed second.

Two legs, one secret

CLAIM^h is CLAIM with a hash lock. The voucher's signed message also names a payment hash, and redeeming it needs the 32-byte preimage of that hash. The script does not compare the preimage against a stored hash; it hashes the preimage straight into the message it checks the signature against, which costs 8 bytes of script and no new opcode. The 32-byte length matches Lightning payment preimages, so one secret can lock a voucher and a Lightning HTLC, an ordinary Lightning payment or one inside a channel leaf.

The voucher has no deadline

A script can require that a spend happen no earlier than some block, but not that it happen before one. The value behind a voucher also never leaves its source leaf, so there is nothing to refund when time runs out. A voucher therefore stays redeemable until its issuer raises the source leaf's counter, which any redemption, split or suitable update does. Deadlines in a swap live in the other leg: the HTLC's expiry.

The ordering rules

The asymmetry between the legs fixes the order of play. Section 9.6.2 of the specification makes it normative:

1. The secret is drawn by the party the HTLC pays. That party reveals it in order to collect, and the reveal is what makes the voucher redeemable.
2. The voucher resolves second. An HTLC must never wait on a secret that appears only when a voucher is redeemed on-chain, because the HTLC would expire while the voucher sat unredeemed. Where this order cannot be arranged, the parties use two HTLCs instead.
3. The issuer leaves the source leaf's counter alone from the moment an HTLC with the same hash is offered until the voucher is redeemed or the HTLC fails. Settling the HTLC does not end the obligation: an issuer who collects and then voids the voucher has been paid for nothing.
4. No script enforces rule 3, so the voucher holder redeems as soon as they learn the secret, and treats the swap as complete only once the redemption is buried deep enough to survive a reorganisation.
5. Before offering the HTLC or paying the invoice, the voucher holder checks the source leaf's lease. Eviction voids every voucher against the evicted leaf, so a source whose lease can pass before the redemption confirms is no security at all, and the holder treats such a voucher as unsecured.

What the hash lock does not remove

The hash lock orders the exchange; it does not secure it against the issuer. Between issuing the voucher and its redemption, the issuer can still void it by raising the counter, and the holder carries that risk. In the other direction, the recipient can wait to redeem, and the issuer carries the liability until then. A hash-locked voucher behaves like a hash-locked cheque: the hash lock ties it to a payment, and the cheque still depends on its issuer until it is cashed.

Arranged correctly, the HTLC leg settles off-chain when the secret changes hands, and only the voucher is redeemed on-chain, so a swap between a Lightning payment and tree balance costs one transaction. The repository's channel-leaf test suite plays the swap block by block, and shows that each forbidden ordering leaves the honest party's transaction invalid.