Time

The time field is a 4-byte Unix timestamp: the number of seconds since 1 January 1970, UTC. The miner sets it when building the block. It is a rough clock, not an exact one, and it does not decide the order of blocks.

What does the field store?

The field is an unsigned 32-bit integer, stored in little-endian order. The genesis block has the timestamp 1231006505, which is stored as 29ab5f49. Reading that back gives 3 January 2009, 18:15:05 UTC.

The largest value, 4,294,967,295, falls on 7 February 2106 at 06:28:15 UTC. That is the field's limit.

Does the time decide the order of blocks?

No. The chain order comes from the previous block field. Timestamps are only approximate, so a block can carry a time earlier than its parent's.

Two examples from the chain show this:

• Block 790,402 is timed 19 May 2023, 04:22:58. Its parent, block 790,401, is timed 04:24:53, so the child is about two minutes earlier.
• Block 156,114 is timed 05 December 2011, 06:17:58. Its parent, block 156,113, is timed 08:16:43, so the child is almost two hours earlier.

Both blocks are valid, because the rules check time against the blocks before, not against their neighbours.

What range of times is valid?

Nodes check every block's time against two limits. The block passes only if it meets both.

The lower limit. The time must be later than the median time past (MTP) of the previous 11 blocks. To get the MTP, take the timestamps of those 11 blocks, sort them, and pick the middle one. Bitcoin Core rejects a block whose time is not after that value, with the reason time-too-old (validation.cpp).

The upper limit. The time must be no more than 7,200 seconds (two hours) ahead of the time the node's own clock shows. Bitcoin Core rejects a block that is further ahead, with the reason time-too-new.

The lower limit is about the chain itself, so it does not depend on any clock. The upper limit does depend on the clock. It is one of the few consensus rules that reads the local clock rather than the chain. The two hours leave room for clocks that drift and for blocks that take time to reach a node.

Older versions of Bitcoin Core also adjusted their clock by the median offset of their peers, called network-adjusted time. From version 28.0 that adjustment is gone, and the check uses only the node's own clock.

How does the time drive difficulty?

Every 2,016 blocks, the network compares how long those blocks really took with the two weeks they should take. Bitcoin Core measures the real time from the first and last block in the period (pow.cpp). If the blocks came too fast, the target drops. If they came too slowly, it rises.

The change is capped, so the target moves at most by a factor of four in one period. The target page shows the adjustment in full.

Can a timestamp be wrong?

Yes. Each miner sets the time from its own clock, and clocks drift. That is why the rules leave some room in both directions. A slightly wrong time does not break the chain, because the rules do not use it to order blocks.

Can a transaction wait for a time?

Yes. A transaction's locktime can be a time or a block height. Values of 500,000,000 or more are read as Unix times, and the transaction is not final until the median time past of the chain passes that time. Smaller values count block heights instead.

Do transactions have a time?

No. A transaction has no timestamp field. To learn when it was confirmed, read the time of the block that holds it. To learn when your node first saw it, ask the node. Bitcoin Core keeps that time for transactions still waiting in the memory pool, and bitcoin-cli getmempoolentry shows it.

What comes next?

Next is bits, the field that holds the target the time helps to set.