HTLC Mechanics

HTLCs (Hash Time Locked Contracts) are conditional payments: claim with a preimage before timeout, otherwise refund. Chained HTLCs create atomic multi-hop Lightning payments.

Why this matters

Every routed payment is an HTLC dance. Debugging failures means reading hashes, CLTV deltas, and onion errors, not guessing.

Analogy

A locked briefcase opens with a secret word (preimage). Each courier along the path holds a briefcase with the same word requirement but earlier deadlines. When the final person learns the word, it propagates back so everyone can settle.

Common mistakes

• Confusing payment hash with payment secret
• Setting timelock deltas too tight for hops
• Ignoring that held HTLCs lock liquidity

CLTV deltas

Each hop demands enough timelock margin to settle or fail safely. If deltas are too small, honest nodes risk loss under delay. Implementations enforce minimums; do not invent tighter custom deltas without reading BOLTs and peer requirements.

Payment secret

Modern invoices include a payment secret so intermediaries cannot settle to the receiver without the payer's onion path completing correctly (anti-probing / security improvement). Decode invoices and confirm secrets are handled by your library.

Held HTLCs lock capital

While an HTLC is outstanding, that balance slice cannot be used elsewhere. Long-held HTLCs (slow peers, attacks) are an operational risk. Monitor pending HTLCs on production nodes.

Try it in Polar or regtest

Pay across a 3-node path, then force a failure mid-route and observe how unlocks unwind as timeouts hit, then compare with a successful preimage settle.

Worked mental model

Re-read the diagrams in this lesson once out loud in plain language. If you cannot explain the flow to a friend without jargon, pause and revisit Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

Hands-on habit

Every protocol idea should be paired with one local experiment:

1. Reproduce the happy path on regtest (or Polar for Lightning)
2. Break it on purpose (wrong fee, expired invoice, offline peer)
3. Write down what error you saw and which layer produced it (wallet, node, mempool, peer)

That habit turns reading into builder instinct.

Glossary check

Pick three terms from this lesson and define them in one sentence each without opening notes. Weak definitions mean the lesson is not finished yet.

Resource order

Use Resources in order: narrative book chapter first, then BIP/BOLT for precision, then implementation docs for commands. Jumping straight to RPC flags without the mental model creates brittle knowledge.

Next steps

Study the full channel lifecycle, cooperative close, force close, and backups.