Finding an Ethereum Block Near a Timestamp
Find a block near a timestamp with an explicit boundary rule, then verify the result before using it for a historical snapshot or report.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A report often starts with a date, while a state query expects a block. Translating between them requires a boundary rule. The block at or before a timestamp is a different choice from the first block after it.
Define the time boundary first
Normalise the requested instant to an unambiguous time zone and precision. Specify whether a snapshot uses the last block with timestamp less than or equal to that instant. Do not estimate the answer only by dividing elapsed time by an average block interval. Skipped slots and network-specific timing make that estimate unsuitable as final evidence.
Worked example: a cutoff between blocks
Block A is timestamped 12:00:00 and its successor B is timestamped 12:00:12. For an at-or-before cutoff of 12:00:05, select A. For a first-after query, select B. Persist the original instant, chosen rule and resulting block hash so that a later reviewer can reproduce the choice.
Search, verify and pin
Use an efficient range search, then verify neighbouring timestamps satisfy the selected rule. Avoid the still-changing head when the report requires settled history. Handle a cutoff before genesis or beyond available data explicitly. On networks with different timestamp guarantees, check the chain rules before assuming the same search algorithm or monotonicity properties apply.
A practical acceptance test
Place the requested instant between two adjacent block timestamps and assert both supported boundary policies separately. Add a cutoff exactly equal to a block timestamp to reveal inclusive-boundary errors. The stored result should contain the requested instant, chosen rule and selected hash, allowing the test to verify the reasoning rather than only a guessed height.
Questions about the topic
Frequently asked questions
Should a date use local time or UTC?
Convert a declared time zone to an exact instant; do not rely on a machine locale.
Can average block time identify the exact block?
No. Use it only as a search estimate and verify the boundary.
Standards & technical documentation
