— —
Follow on X
LESSONS

HTLCs, step by step

A hashed timelock contract pays whoever reveals a secret before a deadline, or refunds after. Chaining them with decreasing deadlines lets payments cross strangers safely.

7 MIN READ
An HTLC chain from Alice through Bob to Carol, settled by revealing the preimage.
LEVEL · Advanced
IN THIS LESSON · 2 OF 6
BY THE END YOU WILL BE ABLE TO ANSWER
  • What does the preimage prove?
  • What happens to a routed payment if the receiver never reveals the secret?
  • A route has four hops and each hop needs a safety margin of 40 blocks. If the final hop's HTLC expires at block 900,040, when must the sender's HTLC expire at the earliest?

Then prove it: a 2-question quiz · a challenge. The lesson marks itself complete at 100%.

The contract

An HTLC is an output with two paths: pay to the recipient if they present the preimage s of a hash H before a timeout, or refund to the sender after it. On Lightning, HTLCs are added as extra outputs to the commitment transactions, so they live inside the channel until settled.

The payment, hop by hop

  1. Carol generates a random secret s and gives Alice H = hash(s) inside an invoice.
  2. Alice offers Bob an HTLC: 1,001 sats (payment plus Bob's fee) if he shows s before block T+40; otherwise refund.
  3. Bob offers Carol an HTLC: 1,000 sats if she shows s before block T+20.
  4. Carol reveals s to Bob to claim her 1,000 sats.
  5. Bob now knows s and reveals it to Alice to claim his 1,001.

Bob's deadline from Alice is later than the one he gave Carol, so he always has time to claim upstream after being claimed downstream. If Carol never reveals s, every HTLC times out and refunds; nobody loses. Bob never risks his own funds, and he never needed to trust Alice or Carol.

Why the timeouts shrink along the route

Each hop needs a margin to react. The sender's timeout is the largest; it decreases toward the receiver. This limits route length, and a payment "stuck" in flight ties up liquidity until it resolves, which is a known nuisance.

The privacy cost

Every hop on a route sees the same H, so colluding nodes can tell they are on the same payment. The fix is PTLCs (lesson 6).

On-chain fallback

If a channel force-closes with HTLCs in flight, they become real on-chain outputs that must be claimed or refunded by their timeouts. This is why Lightning needs predictable on-chain fees and why channel partners watch the chain.

MINI CHALLENGESet the timeouts

A route has four hops and each hop needs a safety margin of 40 blocks. If the final hop's HTLC expires at block 900,040, when must the sender's HTLC expire at the earliest?

block
CHECK YOURSELF
1/2 What does the preimage prove?
2/2 What happens to a routed payment if the receiver never reveals the secret?
pick an answer for each question

SOURCES

  1. The Bitcoin Lightning Network (Poon and Dryja, 2016)
Progress is saved in this browser only.