Block Timestamps

Block timestamps are the only on-chain clock an Avalanche C-Chain smart contract has, so vesting schedules, auction windows, staking lockups, and time-weighted price logic all lean on them — and off-chain indexers use the same timestamps to order and chart activity. But that clock is approximate: a validator sets each block's timestamp within bounded limits, not a precise atomic time. This guide explains how C-Chain timestamps are produced via https://avalanche.therpc.io/YOUR_API_KEY, what accuracy you can and cannot count on, and how to write time-based logic that stays safe under manipulation and network drift. It is aimed at smart contract developers and the backend engineers who index C-Chain data.

Understanding Block Timestamps

• Who sets them: the validator that proposes a C-Chain block stamps it with a Unix timestamp (seconds) in the timestamp field. There is no global atomic clock; the value reflects that one validator's view of time, constrained by protocol rules.
• Accuracy guarantees: the timestamp is approximate, not exact. It must move forward relative to the parent block and stay within an accepted window of real time, but it can differ from your wall clock by seconds. Treat it as roughly correct, never as a precise measurement.
• Manipulation bounds: a validator has limited freedom to nudge a timestamp — it cannot be earlier than the parent block's and cannot run too far ahead of network time before peers reject it. Within that small window a validator can shift the value, so any contract logic that turns on a few seconds of timestamp difference is exploitable.
• Network time drift: because timestamps come from independent validators, consecutive C-Chain blocks can show slightly uneven gaps even though blocks target a ~1-2s cadence. Drift manifests as timestamps that do not advance in perfectly even steps, so never assume a fixed seconds-per-block when converting heights to time.

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: never gate C-Chain logic on second-level timestamp differences. A validator's small leeway plus drift means a value that looks exact is not, so design windows that tolerate a few seconds of slack.
• Account for manipulation: in time-sensitive contracts — auctions, randomness seeds, expiry checks — assume a validator may push the timestamp to the edge of its allowed window in their favor. Avoid using block.timestamp as a source of randomness and add margins so a few seconds of nudging cannot flip an outcome.
• Prefer block numbers for ordering: to order events or measure elapsed intervals deterministically, use block numbers, which increase by exactly one per block and cannot be manipulated. Reserve timestamps for genuine wall-clock needs like a real-world deadline.
• Handle drift off-chain: in indexers or cross-chain flows, do not assume a fixed block time when mapping C-Chain heights to real time — read the actual timestamp of each block, and when correlating with another chain account for both chains' independent drift rather than aligning by block count.
• Safe buffers: size time buffers in the seconds-to-minutes range rather than sub-second. For a C-Chain deadline, add a buffer comfortably larger than the validator's manipulation window and expected drift — a margin of, say, a minute is cheap insurance against a few seconds of skew.

See also

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