Block Timestamps

Many Base contracts lean on block.timestamp — vesting unlocks, staking rewards, auction deadlines, time-locked withdrawals — and off-chain services use block timestamps to order events and reconstruct history. But a timestamp on Base is a value the sequencer assigns, not a reading from a trusted clock, so treating it as precise wall-clock time leads to subtle bugs and, occasionally, exploitable contracts. This guide is for smart contract and backend developers building on Base: it covers how timestamps are set on this OP Stack rollup, what accuracy you can and cannot count on at roughly 2-second blocks, how much a sequencer can nudge them, and the patterns that keep time-based logic safe.

Understanding Block Timestamps

• Who sets them: on Base the single Coinbase-operated sequencer assigns each block's timestamp as it produces blocks roughly every 2 seconds. There is no decentralized validator set voting on the time — it is the sequencer's value, recorded as Unix seconds and read via block.timestamp or the getBlockTimestamp helper.
• Accuracy guarantees: the protocol only requires that timestamps are non-decreasing — each block's timestamp must be greater than or equal to its parent's. It is generally close to real time and steps by about 2 seconds per block, but it is not a precise clock and should never be relied on for sub-second or exact-second accuracy.
• Manipulation bounds: the sequencer has limited room to nudge a timestamp within the protocol's monotonicity and L1-derived constraints. That window is small, but for contract logic where even a few seconds of slack could be gamed (deadlines, randomness derived from time), assume an adversarial sequencer could push the value to the unfavorable edge of the allowed range.
• Network time drift: because the timestamp comes from the sequencer rather than a synchronized global clock, the on-chain time can sit slightly ahead of or behind true UTC and the clock on your own server. Over many blocks this drift is small but real, and it surfaces when you compare a Base block.timestamp against an off-chain Date.now() or against timestamps from another chain.

Working with Timestamps

1// Get block timestamp
2const getBlockTimestamp = async (blockNumber) => {
3  const block = await web3.eth.getBlock(blockNumber);
4  return block.timestamp;
5};
6 
7// Calculate average block time
8const getAverageBlockTime = async (blockCount = 100) => {
9  const latestBlock = await web3.eth.getBlockNumber();
10  const oldBlock = await web3.eth.getBlock(latestBlock - blockCount);
11  const newBlock = await web3.eth.getBlock(latestBlock);
12 
13  return (newBlock.timestamp - oldBlock.timestamp) / blockCount;
14};

Best Practices

• Do not rely on exact precision: treat block.timestamp as approximate. Never compare it for equality (== someTime) or build logic that breaks if it is off by a few seconds; use inequalities with margin instead. Crucially, never derive randomness or high-value secrets from the timestamp — it is partly under the sequencer's control.
• Account for manipulation: in time-sensitive logic, assume the sequencer could push the timestamp to the worst-case edge of its allowed range. Design deadlines and windows so that a small forward or backward nudge cannot let an action through early or block a legitimate one — keep the safety margin larger than the plausible manipulation window.
• Prefer block numbers for ordering: when you only need to know which event came first, order by block number (and log index within a block), not by timestamp. Block numbers increase strictly by one and cannot collide or move, whereas two Base blocks could in principle share a timestamp.
• Handle drift in integrations: when reconciling Base timestamps with off-chain systems or another chain, do not assume the clocks agree. Compare against the chain's own time where possible, allow a tolerance band for drift, and avoid logic that fails if on-chain time and your server time differ by a few seconds.
• Safe buffers: size time buffers to comfortably exceed both the ~2s block interval and the manipulation window — a buffer of at least a couple of blocks (several seconds), and minutes rather than seconds for anything financially sensitive. The buffer should be large enough that normal variance and adversarial nudging together cannot cross your threshold unexpectedly.

See also

• eth_getBlockByNumber - Retrieve block information including timestamps
• Working with Blocks - General block handling
• Block Gas Management - Managing gas costs over time