TYPE 0x0104 · TIMELOCK FAMILY

CLTV_TIME

Absolute timelock in Unix time (BIP 65). Transaction cannot be included until median-time-past reaches the specified value. The user must encode a value ≥ 500000000 (LOCKTIME_THRESHOLD) — the evaluator does not auto-flag the field, so a value below that threshold falls back to block-height semantics (i.e. behaves like CLTV).

Timelock Invertible
Ladder Diagram
CLTV_TIME timestamp INVALID SPENDABLE median_time_past ≥ timestamp → SATISFIED
Fields
FieldData TypeSizeSideDescription
timestampNUMERIC1-4 BConditionsUnix timestamp; must be ≥ 500000000 (LOCKTIME_THRESHOLD) for BIP 65 to interpret it as time-based. The evaluator does not OR a flag bit — the threshold is enforced inside CheckLockTime only.

No witness fields required — evaluation uses the median-time-past from the evaluation context.

Wire Format Breakdown
0x0104 0 1 NUMERIC · 3B Conditions = 4 + 5 = 9 bytes
0x0104 0 0 Witness = 4 bytes (empty block)
Total 15 bytes
Evaluation Logic
1.Read the conditions NUMERIC field as an int64 locktime_val. If absent or undecodable → ERROR
2.Range check: if locktime_val < 0 or locktime_val > 0xFFFFFFFF → UNSATISFIED (guards the narrowing cast to uint32_t).
3.Call sig_checker.CheckLockTime(uint32_t(locktime_val)). CLTV_TIME shares its evaluator body with CLTV; the time-vs-height switch happens inside CheckLockTime: values ≥ LOCKTIME_THRESHOLD (500000000) are compared against MTP, values below are compared against block height. Fails → UNSATISFIED; passes → SATISFIED
Return Values
ConditionResult
NUMERIC field missing or undecodableERROR
locktime_val negative or > 0xFFFFFFFF (uint32 range guard)UNSATISFIED
CheckLockTime fails (MTP < timestamp, or input nSequence is final)UNSATISFIED
CheckLockTime passes (MTP ≥ timestamp)SATISFIED
JSON Wire Format
Conditions (locked until 2027-01-01 00:00:00 UTC = 1798761600)
{
  "type": "CLTV_TIME",
  "inverted": false,
  "fields": [
    { "type": "NUMERIC", "value": 1798761600 }
  ]
}

This locks the UTXO until January 1, 2027 (Unix timestamp 1798761600). The transaction will be rejected by consensus until the median-time-past reaches that point.

Worked Example

timestamp = 1798761600 (2027-01-01 00:00:00 UTC)

MTP 1798761599 (2026-12-31 23:59:59): 1798761599 < 1798761600 → UNSATISFIED
MTP 1798761600 (2027-01-01 00:00:00): 1798761600 ≥ 1798761600 → SATISFIED
MTP 1801440000 (2027-02-01 00:00:00): 1801440000 ≥ 1798761600 → SATISFIED
Use Cases
Calendar-Specific Unlocks
Funds that unlock on a specific calendar date — useful for grant agreements, employment contracts, or any arrangement tied to real-world dates rather than block heights.
Expiry Dates for Options/Futures
Financial contracts with hard expiry timestamps. The option or futures contract output can only be exercised after the specified Unix timestamp, enforced by consensus.
Event-Gated Spending
Outputs locked until a known future event time (e.g., end of an auction, settlement deadline). The timestamp provides a deterministic cutoff anchored to wall-clock time rather than block height.
← CLTV TAGGED_HASH →