Median time past

Nodes take the timestamps of the eleven blocks before the one they are validating, sort them, and use the middle value as the current time. That median sits about six blocks back, so it trails the wall clock by roughly an hour. A coin you lock until noon therefore becomes spendable closer to one in the afternoon.

How it works

Median time past comes out of a function called GetMedianTimePast, which walks back through eleven block entries, copies each timestamp into an array, sorts it, and returns the middle element.

The constant BIP-113 defines is nMedianTimeSpan = 11, so the answer is always the sixth smallest of eleven numbers. Sorting is what makes the result trustworthy. One block's timestamp can sit earlier than its parent's, but the consensus rules already force every new timestamp above the median of the eleven before it, so the median can only move forward. Skewing a single timestamp therefore buys a miner almost nothing.

The problem BIP-113 fixed was an incentive rather than a bug. Under the old rule, a transaction's eligibility was judged against the timestamp of the block including it, a number the miner writes, which the BIP's motivation section calls "a perverse incentive for miners to lie about the time of their blocks in order to collect more fees". The fix was one substitution: consensus calls to IsFinalTx take GetMedianTimePast of the previous block instead of the block's own time, and the rule covers every transaction, the coinbase included.

It shipped as a BIP9 versionbits soft fork on bit 0, with mainnet signalling opening at midnight on 1 May 2016 UTC and timing out a year later, and it was deployed alongside BIP68 and BIP112 so that the three timelock rules arrived as one package.

Where you see it

Median time past appears in Bitcoin Core's RPC output as a field named mediantime, sitting directly beside the raw time field.

getblock returns both for any block, and getblockchaininfo reports the tip's median time next to the tip's timestamp, which is the quickest way to watch the hour of lag on a live node. getchaintxstats goes further and measures the span of its window as the difference between two blocks' median times rather than their header times, so one skewed timestamp at either end barely moves the result.

The place it bites is the mempool. Bitcoin Core's CheckFinalTxAtTip evaluates a candidate against the median time past of the current tip and a height one above it, so a wallet that broadcasts the instant a deadline passes gets a rejection instead of a relay, and has to keep retrying until the median catches up with the clock on your wall.

Relative timelocks inherit the same clock at both ends. BIP-68 measures a time-based sequence lock, counted in units of 512 seconds, from the median time past of the block before the one that mined the coin to the median time past of the block before the spend, so the lag appears twice and mostly cancels out.

Median time past vs the block header timestamp

Median time past is calculated from eleven header timestamps but is stored in no block, while a header timestamp is a field the miner writes and every node keeps forever.

Bitcoin uses both, for different jobs. Locktimes use the median, because it advances monotonically and cannot be dragged forward for fee income. Difficulty retargeting still reads raw header times: Bitcoin Core takes the block time of the last block in the 14 day window, subtracts the block time of the first, and rescales the target from that difference. Two clocks on one chain look untidy, and that is deliberate. A retarget wants the honest elapsed time across a fortnight of blocks, while a locktime wants a number that no single miner can move.