Post-dating a bitcoin transaction
Greg Walker- Download PDF
The locktime field allows you to prevent a transaction from being mined until after a specific block height or time.
A transaction with a locktime in the future will not be accepted or relayed by nodes either, so you have to store it locally until the locktime you have set on the transaction has passed.
In other words, setting a locktime on a transaction is the equivalent of post-dating a cheque.
Usage
How does locktime work?
The locktime field is 4 bytes in size and can hold values between 0 (0x00000000) and 4294967295 (0xffffffff).
You can set a specific block height or time by using different ranges of value:
| Locktime | Description |
|---|---|
| <=499999999 | Transaction cannot be mined until after a specific height. |
| >=500000000 | Transaction cannot be mined until after a specific time. |
This is also known as "absolute locktime", as you're setting a specific height or time in the future. It's also possible to set a relative locktime on a transaction if you prefer.
For the locktime field to be enabled, at least one of the sequence values on the inputs must be set to 0xfffffffe or below. If all of the inputs' sequence values are set to the maximum value of 0xffffffff, the transaction is considered "final" and the locktime feature is disabled.
Height
0 to 499999999
By setting the locktime between 0 (0x00000000) and 499999999 (0x1dcd64ff) you can specify that the transaction can only be mined in to the blockchain after a specific height.
This is a more than suitable range, as the blockchain is not expected to reach a height of 499,999,999 for another .
Time
500000000 to 4294967295
By setting the locktime between 500000000 (0x1dcd6500) and the maximum value of 4294967295 (0xffffffff) you can specify that the transaction can only be mined in to the blockchain after a specific time.
This time value is in Unix Time:
The actual time restriction is then based on the time field inside a block header. The time set inside a block is controlled by the miner, and whilst it's usually pretty close to the current time, it can sometimes be an hour or two out.
This range of values allows you to set a locktime between and .
Examples
Here are a couple of simple examples of the locktime in action:
- b0fa60f601d5fe6fb1501aa614503b9af688492f68bcf8268d7cdb30f3534079
- Locktime:
199000 - First transaction with a valid locktime set for a specific block height. Locktime was set to a block height of 199,000, and the transaction was then mined in to block 199,002.
- Locktime:
- 648fe76b22bc1768b56facab73af046ea40fa190f2e882a7cc99a5b6fccf05de
- Locktime:
1358106524 - First transaction with a valid locktime set for a specific Unix time. Locktime was set to 1358106524 (), and the transaction was mined in to block 216,410 with a timestamp of 1358111522 ().
- Locktime:
And for good measure, here are a couple of examples where the locktime field was used, but it wasn't actually functioning because none of the sequence values were set to below the maximum value of 0xffffffff:
- 13e100dd08b6da0a7426ea520b0bb3ae54cef79dd045e2e4f7116023df3a5c95
- Locktime:
198370 - This is the first ever transaction with a setting for the locktime for a specific block height. However, the locktime feature was not actually enabled because the only sequence value was set to 0xffffffff. The locktime was set to a block height of 198,370, but it actually got mined 11 blocks earlier in to block 198,359.
- Locktime:
- 938b171fdeabc7b99d1720c1df070ba373d892cd5aec3d6dda641ce67ed37ca2
- Locktime:
1409599601 - This transaction has a locktime set for a specific Unix time, but the locktime feature was not enabled again because the only input had a sequence value of 0xffffffff. The locktime was set to 1409599601 (), but it actually got mined earlier than this time in to block 287,080 with a timestamp of 1393005249 ().
- Locktime:
Raw Transaction
The locktime field is always the last 4 bytes of a transaction:
020000000001019a40d4b676ad05adea5a0aa1d093a5c16f298c4b7e31d70fd157e262e86d08900100000000feffffff0228e227000000000017a914ae72b0ccd1a65ec89a7be021e47eccc60a440bb3874dcbf91600000000160014553be08a6faa63e4038b4627996af76637522c500247304402200d9f0f85b355a29f4c14b3ee16257d92fc67429b47a15c1658d8b6737425a1c7022000d0c64c2004b0c1c47968b94c9d24820d1df20c13d37a66d20f62b8feca67b00121021853828191c3e1a4fa29c685e5e1da4710dd1dc35c9b85d6bab23c0e00109f45500e0c00Transaction: f168381d64b32d7b03b3f0b82cadba72e815351686e3bff2b8b5ab92f65a58bf
The locktime field in a raw transaction is in little-endian. So in the example above, if we reverse the byte order of 500e0c00 we get 000c0e50, and if we convert that from hexadecimal to decimal we get 790096.
So this transaction set the locktime as a block height of 790,096 (and was mined in to the block after that).
Little-Endian
Resources
- Is my understanding of locktime correct?
- How is locktime enforced in the standard client?
- nLockTime
- validation.cpp (look for the IsFinalTx function)
