TYPE 0x0102 · TIMELOCK FAMILY
CSV_TIME
Relative timelock in 512-second units (BIP 68 time-based). The evaluator implicitly OR's the BIP 68 type flag (bit 22) into sequence_val, so the user does not need to set it in the conditions value — the same NUMERIC N in CSV means "N blocks", in CSV_TIME means "N × 512 seconds".
Ladder Diagram
Fields
| Field | Data Type | Size | Side | Description |
|---|---|---|---|---|
| sequence_value | NUMERIC | 1-4 B | Conditions | Number of 512-second units. The BIP 68 type flag (bit 22, 0x00400000) is OR'd in by the evaluator; setting it in the value is redundant. |
No witness fields required — evaluation uses the input sequence number and median-time-past from the transaction context.
Wire Format Breakdown
0x0102
0
1
NUMERIC · 3B
Conditions = 4 + 5 = 9 bytes
0x0102
0
0
Witness = 4 bytes (empty block)
Total
15 bytes
Evaluation Logic
1.Read the conditions NUMERIC field as an int64 sequence_val. If absent or undecodable → ERROR
2.Set sequence_val |= SEQUENCE_LOCKTIME_TYPE_FLAG (bit 22, 0x00400000) to force time-based BIP 68 interpretation regardless of the encoded value.
3.If SEQUENCE_LOCKTIME_DISABLE_FLAG (bit 31) is set in sequence_val → SATISFIED unconditionally.
4.Range check: if sequence_val < 0 or sequence_val > 0xFFFFFFFF → UNSATISFIED (guards the narrowing cast to uint32_t).
5.Call sig_checker.CheckSequence(uint32_t(sequence_val)); with the type flag set, BIP 68 interprets the low 16 bits as 512-second units. Fails → UNSATISFIED; passes → SATISFIED
Return Values
| Condition | Result |
|---|---|
| NUMERIC field missing or undecodable | ERROR |
SEQUENCE_LOCKTIME_DISABLE_FLAG (bit 31) set in sequence_val | SATISFIED |
sequence_val negative or > 0xFFFFFFFF (uint32 range guard) | UNSATISFIED |
CheckSequence fails (insufficient time elapsed since UTXO) | UNSATISFIED |
CheckSequence passes (lock satisfied) | SATISFIED |
JSON Wire Format
Conditions (relative locktime of ~24 hours = 168 × 512s)
{
"type": "CSV_TIME",
"inverted": false,
"fields": [
{ "type": "NUMERIC", "value": 168 }
]
}The value 168 is OR'd with the BIP 68 type flag (bit 22, 0x00400000) by the evaluator, so it encodes 168 × 512 s (~24 h) of relative time. The UTXO cannot be spent until this duration has elapsed from its creation. (Encoding 4194472 = 0x4000A8 with the flag pre-set works too — the OR is idempotent.)
Use Cases
Time-Based Vault Delays
Vault cooling periods measured in real-world time rather than block count, providing predictable delay windows regardless of mining variance or hash rate fluctuations.
Calendar-Aware Contracts
Escrow and payment contracts where the refund path activates after a specific duration (e.g., 48 hours) rather than a block count, giving both parties a clock-based deadline.