Skip to content
Financial Context Wiki

HTLC

A hashed time-locked contract makes a payment claimable with a preimage before an expiry and refundable through a different spend path after expiry. Learn how HTLCs coordinate payment channels and atomic swaps, and where they can still fail.

Updated

For educational purposes only; not investment, legal, or security advice. HTLC safety depends on the exact scripts or contracts, chain rules, confirmation policy, fees, monitoring, and timely action.

Direct answer

A hashed time-locked contract (HTLC) is a conditional payment with two competing spend paths. Before an expiry, the receiver can claim by revealing a value x whose hash matches a committed value h = H(x) and by satisfying the required signatures or authorization. After the expiry, the sender can use the refund path. The exact ordering at the boundary is determined by the chain and contract, not by the English word “before.”

The hash lock links actions: learning the same preimage can let a participant settle a related incoming payment after paying an outgoing one. The time lock bounds how long funds remain conditional. Payment-channel protocols use these properties to forward payments, while atomic-swap protocols can use them to coordinate transfers on separate systems.

An HTLC is not automatically trustless, atomic, private, or self-executing. Safety also depends on correct scripts or contracts, compatible hash and preimage encoding, staggered expiries, finality assumptions, fee access, live monitoring, and transactions confirming before deadlines. Lightning’s HTLC construction is one specified Bitcoin design; another chain’s contract can have materially different semantics.

  • Hash branch: disclose the required preimage and satisfy the success-path authorization while that path is valid.
  • Timeout branch: satisfy the refund-path authorization once the applicable absolute or relative lock has matured.

How it works

For a single conditional payment, suppose Bob chooses a fresh, unpredictable preimage x, computes h = H(x), and gives h to Alice. Alice locks funds under rules that commit to h, identify the authorized parties, and define expiry T.

  • Alice verifies the hash algorithm, byte encoding, amount, asset, recipient, refund destination, chain, and expiry before funding.
  • Bob verifies the actually funded output or deployed contract rather than trusting a transaction draft or interface display.
  • If Bob claims through the success branch, he supplies x; the spending logic checks that H(x) = h and checks the required authorization.
  • Publication or protocol delivery of x may allow Alice or an intermediary to settle another HTLC carrying the same payment hash.
  • If the success branch is not used in time, the refund branch becomes eligible at T; eligibility does not itself broadcast or confirm a refund.
  • A participant must still construct or retain the correct transaction, pay a sufficient fee, submit it, monitor replacements and conflicts, and obtain the needed confirmation depth.
  • Once x is revealed to a counterparty or a public chain, treat it as disclosed and do not reuse it for an unrelated condition.

Bitcoin distinguishes absolute and relative locks. BIP 65’s OP_CHECKLOCKTIMEVERIFY constrains spending until a block height or block time encoded through transaction lock time; BIP 112’s OP_CHECKSEQUENCEVERIFY constrains spending until an input’s relative age is sufficient. Scripts must also set compatible transaction fields. A time lock is therefore a validation rule, not a scheduler.

In Lightning, update_add_htlc carries an amount, a payment_hash, and a cltv_expiry. Each forwarding hop offers an outgoing HTLC with an earlier expiry than the corresponding incoming HTLC, preserving time to learn the preimage and claim upstream. BOLT 3 defines commitment-output, HTLC-success, and HTLC-timeout paths, including signatures, revocation handling, dust trimming, and additional delays; the two-branch sketch alone is not a complete Lightning channel implementation.

Example

Consider a teaching example in which Alice exchanges 1 BTC for Bob’s 20 ETH. It illustrates ordering only; production Bitcoin and Ethereum implementations need chain-specific reviewed code and should not copy these nominal durations.

  • Alice generates fresh x and h = H(x), then locks 1 BTC so Bob has a preimage claim and Alice has a refund path after 48 hours.
  • After checking the Bitcoin transaction and the chosen confirmation policy, Bob locks 20 ETH under compatible hash and encoding rules, with Alice’s success path ending after 24 hours and Bob’s later refund path.
  • Alice verifies the Ethereum chain ID, contract bytecode and address, token or native asset, amount, participants, h, and both callable paths before revealing x to claim 20 ETH.
  • Bob learns x from the successful claim or agreed protocol message and attempts the Bitcoin success path before its later deadline.
  • If the exchange stops before disclosure, each refund becomes eligible only under its own chain’s rules; each party must submit and confirm the relevant refund transaction.

The 48 hours versus 24 hours gap is a response buffer, not a universal safe setting. Reorganizations, block-time variability, finality, contract execution, relayer assumptions, mempool policy, fee spikes, censorship, and operational latency must be modeled for both systems. The party acting second must not proceed merely because an interface says “confirmed.”

Risks

  • Wrong commitment: the hash algorithm, preimage length or encoding differs between legs, so the same x does not satisfy both.
  • Wrong artifact: the funded output, chain ID, contract address, bytecode, asset, amount, recipient, or refund destination is not what the interface claimed.
  • Unsafe expiry order: equal or insufficiently separated deadlines leave an intermediary or swap counterparty unable to claim upstream after paying downstream.
  • Boundary mistakes: block height, block time, timestamp, relative age, and contract comparisons such as < versus <= do not mean the same thing.
  • No automatic refund: maturity only makes a spend valid; a wallet, node, user, or watch service still has to act.
  • Fee and dust failure: a claim can be uneconomic, trimmed from a Lightning commitment, stuck at a low fee, or impossible without the chain’s native fee asset.
  • Confirmation and reorganization risk: seeing a transaction or preimage is not the same as irreversible settlement on either chain.
  • Race and congestion risk: a success spend, timeout spend, replacement, conflict, or adversarial delay can consume the response window.
  • Implementation risk: script, smart-contract, wallet, signing, nonce, RPC, or client bugs can invalidate the intended paths.
  • Monitoring risk: an offline participant may miss disclosure, expiry, a force-close, a replacement, or the last practical broadcast time.
  • Privacy leakage: reused payment hashes, public preimages, amounts, timing, and channel events can help correlate transfers or routes.
  • Optionality and griefing: a party may lock the other’s liquidity and then abort; conditional settlement does not guarantee completion or compensate delay.

Before risking value, test both the success and refund paths with a negligible amount, record the exact artifacts and deadlines, maintain fee reserves, and define who monitors and broadcasts under failure.

Common misconceptions

  • “The funds return automatically at timeout.” Usually timeout only enables a refund spend; someone must broadcast it and it must confirm.
  • “Matching H(x) = h is the whole contract.” Signatures, script branches, transaction fields, chain rules, revocation logic, and contract authorization also matter.
  • “The same expiry on both legs is fair.” A forwarding node or second mover needs a deliberate upstream buffer after learning x.
  • “A visible preimage guarantees time to claim.” Confirmation delays, reorganization, congestion, fees, and censorship can exhaust the remaining window.
  • “Atomic means both chains change in one indivisible transaction.” A cross-chain swap coordinates separate state transitions; abort and refund paths remain, and temporary one-sided states can occur.
  • “HTLCs are anonymous and remove all trust.” They can leak correlation signals and still rely on protocol code, chain behavior, keys, monitoring, and operational assumptions.

Sources

Navigation

Search the wiki...