Builder's Guide
  • Welcome to the Builder's Guide to the LND Galaxy!
  • The Lightning Network
    • Overview
    • Payment Channels
      • Lifecycle of a Payment Channel
      • Watchtowers
      • Understanding Sweeping
      • Etymology
    • The Gossip Network
      • Identifying Good Peers on the Lightning Network
    • Pathfinding
      • Finding routes in the Lightning Network
      • Channel Fees
      • Multipath Payments (MPP)
    • Lightning Network Invoices
      • Understanding Lightning Invoices
    • Making Payments
      • The Payment Cycle
      • Timelocks
      • ⭐Hashed Timelock Contract (HTLC)
      • Payment Etymology
      • ⭐What Makes a Good Routing Node
      • Understanding Submarine Swaps
      • Instant Submarine Swaps
    • Liquidity
      • ⭐Understanding Liquidity
      • Managing Liquidity on the Lightning Network
      • Liquidity Management for Lightning Merchants
      • How to Get Inbound Capacity on the Lightning Network
      • Lightning Service Provider
    • L402: Lightning HTTP 402 Protocol
      • Macaroons
      • L402
      • 📋Protocol Specification
      • Implementations and Links
    • Taproot Assets
      • Taproot Assets Protocol
      • Taproot Assets on Lightning
      • Edge Nodes
      • Taproot Assets Trustless Swap
      • FAQ
      • Glossary
  • Lightning Network Tools
    • LND
      • 🛠️Get Started
      • lnd.conf
      • First Steps With LND
      • Wallet Management
      • Sending Payments
      • Atomic Multi-path Payments (AMP)
      • Receiving Payments
      • Unconfirmed Bitcoin Transactions
      • Channel Fees
      • Inbound Channel Fees
      • Macaroons
      • Configuring Watchtowers
      • Pathfinding
      • Blinded Paths
      • Key Import
      • Secure Your Lightning Network Node
      • Configuration of a Routing Node
      • Quick Tor Setup
      • Configuring Tor
      • Enable ‘Neutrino mode’ in Bitcoin Core
      • Send Messages With Keysend
      • Partially Signed Bitcoin Transactions
      • Bulk onchain actions with PSBTs
      • Sweeper
      • Debugging LND
      • Fuzzing LND
      • LND API documentation
      • Channel Acceptor
      • RPC Middleware Interceptor
      • HTLC Interceptor
      • NAT Traversal
      • Recovery: Planning for Failure
      • Migrating LND
      • Disaster recovery
      • Contribute to LND
    • Lightning Terminal
      • What is Lightning Terminal?
      • 🛠️Get litd
      • Run litd
      • Integrating litd
      • Demo: Litd Speed Run
      • Connect to Terminal
      • Recommended Channels
      • Rankings
      • Health Checks
      • Liquidity Report
      • Opening Lightning Network Channels
      • Managing Channel Liquidity
      • Autofees
      • AutoOpen
      • LND Accounts
      • Loop and Lightning Terminal
      • Loop Fees
      • Pool and Lightning Terminal
      • Command Line Interface
      • Troubleshooting
      • Lightning Node Connect: Under the hood
      • LNC Node Package
      • LITD API Documentation
      • Privacy and Security
      • Privacy Policy
      • Terms of Use
    • Loop
      • 🛠️Get Started
      • The Loop CLI
      • Autoloop
      • Static Loop In Addresses
      • Instant Loop Outs
      • Peer with Loop
      • Loop API Documentation
    • Pool
      • Overview
      • Quickstart
      • 🛠️Installation
      • First Steps
      • Accounts
      • Orders and Asks
      • Sidecar Channels
      • Zero-confirmation Channels
      • Channel Leases
      • Batch Execution
      • Account Recovery
      • Pool API Documentation
      • FAQs
    • Taproot Assets
      • Get Started
      • First Steps
      • Taproot Assets Channels
      • Asset Decimal Display
      • Become an Edge Node
      • RFQ
      • Collectibles
      • Universes
      • Asset Loop
      • Debugging Tapd
      • Multisignature
      • Minting Assets With an External Signer
      • Lightning Polar
      • Operational Safety Guidelines
      • Taproot Assets API Documentation
    • Aperture
      • ⚒️Get Aperture
      • LNC Backend
      • LNC Mailbox
      • Pricing
    • Faraday
      • 🛠️Get Started
      • The Faraday CLI
      • Faraday API Documentation
  • LAPPs
    • Guides
      • Use Polar to Build Your First LAPP
        • Setup: Local Cluster with Polar
        • Setup: Run the Completed App
        • Setup: Run the App Without LND
      • Add Features
        • Feature 1: Connect to LND
        • Feature 2: Display Node Alias and Balance
        • Feature 3: Sign and Verify Posts
        • Feature 4: Modify Upvote Action
      • Make Your own LNC-powered Application
    • Next Steps
  • Community Resources
    • Resource List
    • Lightning Bulb 💡
    • Glossary
    • FAQ
Powered by GitBook
On this page
  • Absolute timelocks
  • nLocktime
  • Check-locktime verify (CLTV)
  • Relative timelocks (CSV)
  • nSequence
  • Check Sequence Verify (CSV)

Was this helpful?

  1. The Lightning Network
  2. Making Payments

Timelocks

Timelocks allow for limits on when bitcoin can be spent. There are absolute and relative timelocks, existing on the transactional and UTXO level.

PreviousThe Payment CycleNextHashed Timelock Contract (HTLC)

Last updated 2 years ago

Was this helpful?

A time-locked Bitcoin transaction is one that is only valid after a certain period of time. Such timelocks are used extensively in the Lightning Network and broadly fall under two categories, absolute timelocks and relative timelocks.

Absolute Timelock

Relative Timelock

Transaction Level

nLockTime

nSequence

UTXO Level

CheckLockTimeVerify

CheckSequenceVerify

(or Script Level)

CLTV

CSV

Absolute timelocks

Absolute timelocks restrict a transaction to only be valid after a certain point in time, for instance a time stamp or a block height. Today, block height is primarily used.

nLocktime

The most commonly used timelock, nLocktime, has been a feature of bitcoin since its inception. Each bitcoin transaction specifies a nLocktime close to the most recently mined bitcoin block, meaning a miner can not include this transaction as part of a block reorg concerning previous blocks. It only began to be widely used around 2016, when it was included in Bitcoin Core 0.11.

Check-locktime verify (CLTV)

Check-locktime verify (CLTV) is the timelock used in Hash Timelock Contracts (HTLC), which make up an important part of the mechanism behind Lightning Network transactions. CLTV is an absolute timelock that uses block height to determine when transactions become valid.

Differences between timelocks of incoming and outgoing HTLCs, called CLTV deltas, ensure that an incoming HTLC that is resolved on-chain can also be resolved in time in the outgoing channel.

CLTV differs from nLocktime in that it enforces the timelock on the script level, while the nLocktime timelock is enforced at the time of the signature. So while it is possible to add nLocktime when spending any coin, a CLTV condition has to be defined at the time the address is created, and the owner cannot alter it anymore.

CLTV was introduced with and activated through a soft fork in 2015. In addition to block height, the protocol also allows CLTVs to use timestamps to define the validity of transactions.

There’s no limit to how far in the future a CLTV transaction can be locked.

Relative timelocks (CSV)

A relative timelock describes a period after which a transaction becomes valid, rather than a fixed timestamp of block height. This period refers to the number of blocks or seconds between inputs being confirmed on the blockchain, and the outputs being valid.

nSequence

Analogous to nLocktime, nSequence is enforced at the transaction level, rather than the script level. That difference means that you can add information about the minimum number of blocks that need to have passed since its input was confirmed when signing the transaction that spends it.

Check Sequence Verify (CSV)

The “CSV Delay”, defined at a channels’ creation, is dependent on its size. It can also be configured manually with the –max_local_csv flag of lncli openchannel. It expresses the number of blocks that need to pass before the initiator of a force close can spend their side of the balance, while the other party can always spend their funds immediately.

Relative timelocks can also be used to prevent transactions having unconfirmed parents, or pinning attacks, in which a transaction is prevented from being confirmed by submitting large, low-paying descendants.

Unlike CLTV, CSV can only be defined for up to 65535 blocks (about 15 months).

No timelocks exist that make a transaction invalid after a certain time. This follows a design principle of bitcoin that transactions can only become more permissible over time, not more restrictive. This principle is supposed to prevent funds being destroyed by becoming locked forever.

The main timelock in use today is Check Sequence Verify (CSV), which was activated in 2016 as , and . It defines the sequence delay as part of the script, meaning it cannot be changed when the coins are spent.

CSV plays an important role in in the Lightning Network, ensuring that the funds from a non-cooperative closure can only be recovered a certain number of blocks after the force closure has been initiated. CSV is the key component of allowing Lightning Network channels to exist indefinitely, rather than for a limited time.

BIP65
Read more about HTLCs
BIP68
BIP112
BIP113
commitment transactions