B++ 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

Best Practices

For Developers

  1. Use appropriate timelocks: Don't lock funds too long
  2. Test timelock logic: Verify conditions work correctly
  3. Handle timelock expiry: Plan for what happens after unlock
  4. Consider median time: CSV uses median time, not block time

For Users

  1. Understand lock duration: Know when funds become available
  2. Plan ahead: Don't lock funds you need immediately
  3. Verify timelocks: Check that conditions are correct

Resources