BitcoinDev Logo
Feedback

Timelocks

Timelocks prevent Bitcoin from being spent until certain time conditions are met. Bitcoin supports two types of timelocks: absolute (CLTV) and relative (CSV).

Types of Timelocks

Absolute Timelocks (CLTV)

CheckLockTimeVerify (CLTV) prevents spending until a specific block height or Unix timestamp:

Example:
"Can't spend until block 800,000"
"Can't spend until January 1, 2025"

Relative Timelocks (CSV)

CheckSequenceVerify (CSV) prevents spending until a certain time has passed since the UTXO was created:

Example:
"Can't spend until 1000 blocks after this UTXO was confirmed"
"Can't spend until 2 weeks after creation"

Use Cases

Escrow

Hold funds until a dispute period expires:

Escrow Contract:
1. Funds locked with timelock
2. Dispute period: 30 days
3. After 30 days, funds can be released

Inheritance

Time-delayed access to funds:

Inheritance Scheme:
1. Funds locked until specific date
2. Beneficiary can claim after date
3. Prevents immediate access

Lightning Network

HTLCs use timelocks for payment routing:

HTLC Timelock:
1. Payment locked with hash
2. Timelock prevents indefinite locking
3. Refund if not claimed in time

Vesting

Gradual release of funds:

Vesting Schedule:
- 25% after 1 year
- 25% after 2 years
- 50% after 3 years

Code Examples

Creating CLTV Timelock

Creating CSV Timelock

Transaction-Level Timelocks

nLockTime

Transaction-level absolute timelock:

[Transaction]
├── nLockTime: Block height or timestamp
└── nSequence: Must be < 0xFFFFFFFF for nLockTime to work

nSequence

Transaction-level relative timelock (when used with CSV):

[Transaction]
├── nSequence: Relative locktime value
└── Script: OP_CHECKSEQUENCEVERIFY

Technical Details

CLTV (BIP 65)

  • Activated: December 2015 (block 388,381)
  • Opcode: OP_CHECKLOCKTIMEVERIFY (0xb1)
  • Checks: Transaction's nLockTime field
  • Values: Block height (< 500,000,000) or Unix timestamp (≥ 500,000,000)

CSV (BIP 112)

  • Activated: July 2016 (block 419,328)
  • Opcode: OP_CHECKSEQUENCEVERIFY (0xb2)
  • Checks: Transaction's nSequence field
  • Values: Blocks (mask 0x0000FFFF) or seconds (mask 0x40000000)

Lightning Network Usage

HTLC Timelocks

Lightning uses timelocks for HTLCs:

[HTLC Structure]
├── Hash lock: Reveal preimage
└── Time lock: Refund if not claimed

Timelock ensures:

  • Payments don't get stuck forever
  • Refunds are possible
  • Routing nodes have time to respond

Channel Timelocks

Force-close channels use timelocks:

Force Close:
1. Broadcast commitment transaction
2. Wait for timelock (typically 144-2016 blocks)
3. Access funds after timelock expires

Resources