Looking at the settings of some nodes on 1ml.com, I noticed the Time Lock Delta variable could vary a lot. How does it affect a node, and what is considered to be a decent value for it?

2 Answers 2


How does TimeLockDelta affect a node?

TimeLockDelta (or cltv_expiry_delta) is the minimum number of blocks a node requires to be added to the expiry of HTLCs. In other words, this value represents the required gap between the timelocks of the incoming and outgoing HTLC to this node. Once an HTLC times out, it can either be fulfilled or timed-out which means the node must take care to be around this transition and fulfill both the offered and received HTLCs. If the node does not fulfill this in due period of time, the peer will be able to get its funds back by spending the time-out transaction.

To illustrate this with an example, say your peer that you forwarded the HTLC to (outgoing HTLC) sends you the pre-image of the HTLC that was added sometime back. You make a payment to your peer for providing the pre-image successfully. Now it is up to you to redeem this payment from the peer through which you received the HTLC (incoming HTLC). If you wait long enough such that the expiry times out, then you are at risk of losing your funds because the peer who sent you the HTLC will use the time-out transaction to get its funds. So you are in a scenario where you have paid the outgoing HTLC, but you cannot claim the funds from the incoming HTLC.

So the value of the TimeLockDelta should be chosen in such a way that it is not too large such that other nodes do not send payments through you, but also not too small that you might risk losing your funds because you did not have enough time to satisfy the incoming HTLC. The below calculation shows the various cases that can crop up when fulfilling HTLCs and the optimum value that needs to be chosen for it.

what is considered to be a decent value for it?

Below is the text from BOLT #2 which has the calculations and various cases needed for determining what the cltv_expiry_delta a node should set for itself.

The worst-case number of blocks between outgoing and incoming HTLC resolution can be derived, given a few assumptions:

  • a worst-case reorganization depth R blocks
  • a grace-period G blocks after HTLC timeout before giving up on an unresponsive peer and dropping to chain
  • a number of blocks S between transaction broadcast and the transaction being included in a block

The worst case is for a forwarding node (B) that takes the longest possible time to spot the outgoing HTLC fulfillment and also takes the longest possible time to redeem it on-chain:

  1. The B->C HTLC times out at block N, and B waits G blocks until it gives up waiting for C. B or C commits to the blockchain, and B spends HTLC, which takes S blocks to be included.
  2. Bad case: C wins the race (just) and fulfills the HTLC, B only sees that transaction when it sees block N+G+S+1.
  3. Worst case: There's reorganization R deep in which C wins and fulfills. B only sees transaction at N+G+S+R.
  4. B now needs to fulfill the incoming A->B HTLC, but A is unresponsive: B waits G more blocks before giving up waiting for A. A or B commits to the blockchain.
  5. Bad case: B sees A's commitment transaction in block N+G+S+R+G+1 and has to spend the HTLC output, which takes S blocks to be mined.
  6. Worst case: there's another reorganization R deep which A uses to spend the commitment transaction, so B sees A's commitment transaction in block N+G+S+R+G+R and has to spend the HTLC output, which takes S blocks to be mined.
  7. B's HTLC spend needs to be at least R deep before it times out, otherwise another reorganization could allow A to timeout the transaction.

Thus, the worst case is 3R+2G+2S, assuming R is at least 1. Note that the chances of three reorganizations in which the other node wins all of them is low for R of 2 or more. Since high fees are used (and HTLC spends can use almost arbitrary fees), S should be small; although, given that block times are irregular and empty blocks still occur, S=2 should be considered a minimum. Similarly, the grace period G can be low (1 or 2), as nodes are required to timeout or fulfill as soon as possible; but if G is too low it increases the risk of unnecessary channel closure due to networking delays.

There are four values that need be derived:

  1. The cltv_expiry_delta for channels, 3R+2G+2S: if in doubt, a cltv_expiry_delta of 12 is reasonable (R=2, G=1, S=2).
  2. The deadline for offered HTLCs: the deadline after which the channel has to be failed and timed out on-chain. This is G blocks after the HTLC's cltv_expiry: 1 block is reasonable.
  3. The deadline for received HTLCs this node has fulfilled: the deadline after which the channel has to be failed and the HTLC fulfilled on-chain before its cltv_expiry. See steps 4-7 above, which imply a deadline of 2R+G+S blocks before cltv_expiry: 7 blocks is reasonable.
  4. The minimum cltv_expiry accepted for terminal payments: the worst case for the terminal node C is 2R+G+S blocks (as, again, steps 1-3 above don't apply).

The default value for cltv_expiry_delta in BOLT #11 is 9, which is slightly more conservative than the 7 that the above calculation suggests.


The timelock value can be up to 14*144 = 2016 or the expected amounts of blocks to be mined with 14 days.

Generally the cltv delta is a trade of:

The higher you choose this value the longer your node can be offline without you rising to lose funds. However other nodes might select not to route payments through you as the routing process if hiring the chain can technically last as long as the cltv delta.

The reason why you will see various values in the gossip update_channel messages (which 1ml depicts) is probably implementations use different default values and have also changed the defaults with various versions. I think it was 144 for one of the implementations and it came down to 6 or 9. Eclair mobile wallet which mainly creates private channels that you don't see on 1ml users 2016 because mobile phones might have longer downtimes

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.