HTLC

Anna wants to send Pavel 20,000 sat through the Lightning Network. Sat is short for satoshi, the smallest unit of bitcoin on the chain. They do not share a payment channel, but both have a suitable connection through Eva. A channel is an agreement between two participants about how bitcoins are allocated, updated without a new transaction in a block for every payment. Eva offers Pavel a conditional 20,000 sat, while Anna offers Eva 20,010 sat; the 10 sat difference is Eva’s fee in this simplified example. These are linked balance changes in two channels, not the same individual coin travelling through them. Pavel knows a secret that lets him fulfill his condition. Eva can then use the same value with Anna. She need not first pay Pavel irreversibly on his promise alone. These amounts illustrate the mechanism, not a typical or recommended fee. [1]

Pavel prepares a random 32-byte secret for the payment, the payment_preimage. SHA-256 computes its payment_hash. Checking whether a revealed value produces the right fingerprint is easy; recovering a well-chosen secret from that fingerprint alone is practically infeasible. An ordinary BOLT 11 invoice, a Lightning payment request, contains the hash in field p, not the preimage itself. When Pavel fulfills the payment, the secret passes back along the route and links the corresponding HTLCs. The invoice’s payment_secret in field s is different: it helps the recipient process the payment correctly and does not replace the preimage. None of these values is a Seed Phrase (the words used to restore a wallet) or wallet private key. [1] [4]

If both conditional payments had the same deadline, Pavel could reveal the secret so late that Eva could no longer claim her incoming payment. The incoming HTLC from Anna therefore expires later than Eva’s outgoing HTLC to Pavel. The difference, called cltv_expiry_delta, gives Eva a safety margin. She also needs it if a peer stops responding and bitcoin transactions must enforce the agreement on-chain. The margin is measured in blocks, not exact minutes, and must allow for delays and chain reorganizations. Software and channel rules handle its safe configuration; too little margin puts funds at risk. A reorganization replaces part of the chain with another valid branch, which can change earlier transaction confirmations. [1]

In Lightning, cltv_expiry is a block height, a block’s position in the chain. It is not a Unix timestamp (calendar time expressed as a count of seconds) or the BOLT 11 invoice lifetime measured in seconds. Once time conditions are met, the timeout path may become available, allowing settlement without the secret. Funds do not move by themselves: Lightning nodes, the programs managing payment channels, must properly complete the channel update or use the relevant on-chain transaction. A valid preimage does not automatically stop working at expiry either. If the same output, an amount governed by spending rules, has not already been spent another way, permitted spending paths may compete; both spends cannot confirm in one valid chain. Timely action is therefore part of security. [1] [4] [5]

An HTLC links conditions; it does not make any amount pass through any route. Eva needs enough funds in the outgoing direction, called liquidity, and room for another pending HTLC. Limits, fees or an unavailable node can stop payment. Until a pending attempt is properly resolved, some funds may remain tied up. Read the wallet’s status as information about the whole attempt, not proof based on a single message. Revealing a preimage is not the same as confirming a bitcoin transaction. An ordinary successful Lightning payment settles through channel updates, without recording every payment in a new block. [1] [3]

The following sections are technical reference. A channel state records who is entitled to each amount and which HTLCs are still pending. A commitment transaction is a signed bitcoin transaction that can enforce that state on-chain. update_add_htlc only proposes adding an HTLC; update_fulfill_htlc reports fulfillment and update_fail_htlc reports failure. Announcing a change is not enough. Through commitment_signed and revoke_and_ack, the parties exchange signatures for the new state and information that makes using the old state unsafe. Both must irrevocably commit to the relevant update under BOLT 2 before a further obligation relies on it. This agreement between participants is not a block confirmation. Funding and possible channel closure, by contrast, rely on bitcoin transactions. [1]

Fields are individual values in a message. A millisatoshi is one thousandth of a satoshi, an accounting unit inside Lightning; it is not a separately spendable fraction on the Bitcoin chain. The base update_add_htlc message contains channel_id, id, amount_msat, payment_hash, cltv_expiry and onion_routing_packet. amount_msat is in millisatoshis. The node checks channel limits, available liquidity and forwarding conditions; the outgoing HTLC has its own parameters. It must not offer the corresponding HTLC before the incoming addition is irrevocably committed under BOLT 2. [1]

Onion routing wraps each intermediary’s instructions in separate encrypted layers. Eva receives what she needs for her step, rather than a readable list of every participant. The node decrypts its own onion layer and verifies its integrity. On an ordinary unblinded route it compares amt_to_forward and outgoing_cltv_value with the incoming amount, fee and required time difference. The packet does not expose the entire route to it. This does not rule out traffic correlation or other identity inference; onion routing is not a guarantee of absolute anonymity. [3]

An output is an amount with spending rules, written in the Script language. Offered and received describe the HTLC from the channel participant’s perspective. The second stage is a following transaction; CHECKSEQUENCEVERIFY (CSV) enforces a wait measured from confirmation of the output being spent. A revocation key enables a penalty against a published old, revoked state. BOLT 3 distinguishes offered and received outputs and HTLC-success or HTLC-timeout paths. Simply knowing a hash is insufficient: the relevant signatures, preimage and time conditions apply. The local second-stage output has a CSV delay of to_self_delay, whereas the correct revocation key lets the counterparty use the penalty branch without that delay. The exact Script depends on channel type. [2] [6]

Trimming means that a small HTLC does not become a separate output when a channel state goes on-chain. Dust refers to such small amounts. Dust exposure measures the total value subject to this limitation. If the amount after the applicable second-stage fee is below dust_limit_satoshis, the commitment transaction creates no HTLC output. Rules depend on the negotiated type: option_anchors and zero_fee_commitments have no such second-stage fee; zero_fee_commitments may direct the trimmed value to shared_anchor. A missing output cannot be claimed separately on-chain. These HTLCs together form dust exposure. [2] [1]

The following check is for node operators and developers. Decoding turns a record into readable fields; it sends nothing and does not itself prove that every condition is satisfied. Compare incoming and outgoing amount_msat, payment_hash and cltv_expiry; verify the preimage using SHA-256. Also track commitment_signed, revoke_and_ack and the final state, rather than a single fulfill/fail message. For on-chain enforcement, decode the actual commitment transaction, check output existence, the selected branch and HTLC-success/HTLC-timeout. Check signatures, time conditions and confirmations; decoding alone does not establish validity. [1] [2]