hypersync.hypersync_timestamp

Documentation for eth_defi.hypersync.hypersync_timestamp Python module.

Block timestamp and hash bulk loading using Hypersync API.

Replace slow and expensive eth_getBlockByNumber calls with Hypersync API.

Example:

blocks = get_block_timestamps_using_hypersync(
    hypersync_client,
    chain_id=1,
    start_block=10_000_000,
    end_block=10_000_100,
)

# Blocks missing if they do not contain transactions
# E.g https://etherscan.io/block/10000007
assert len(blocks) == 101

block = blocks[10_000_100]

assert block.block_number == 10_000_100
assert block.block_hash == "0x427b4ae39316c0df7ba6cd61a96bf668eff6e3ec01213b0fbc74f9b7a0726e7b"
assert block.timestamp_as_datetime == datetime.datetime(2020, 5, 4, 13, 45, 31)

Functions

fetch_block_timestamps_using_hypersync_cached(...)

Sync wrapper with retry and exponential backoff.

fetch_block_timestamps_using_hypersync_cached_async(...)

Quickly get block timestamps using Hypersync API and a local cache file.

get_block_timestamps_using_hypersync(client, ...)

Quickly get block timestamps using Hypersync API.

get_block_timestamps_using_hypersync_async(...)

Read block timestamps using Hypersync API.

get_hypersync_block_height(client)

Get the latest block known to Hypersync.

Exceptions

HypersyncFlaky

Hypersync stream flaky error, e.g.
exception HypersyncFlaky

Bases: Exception

Hypersync stream flaky error, e.g. timeout or rate limit.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

fetch_block_timestamps_using_hypersync_cached(client, chain_id, start_block, end_block, cache_path=PosixPath('/home/runner/.tradingstrategy/block-timestamp'), display_progress=True, attempts=5)

Sync wrapper with retry and exponential backoff.

See fetch_block_timestamps_using_hypersync_cached_async() for documentation.

Parameters

  • attempts – Work around Hypersync timeout issues

  • client (hypersync.HypersyncClient) –

  • chain_id (int) –

  • start_block (int) –

  • end_block (int) –

  • display_progress (bool) –

Return type

eth_defi.event_reader.timestamp_cache.BlockTimestampSlicer

async fetch_block_timestamps_using_hypersync_cached_async(client, chain_id, start_block, end_block, cache_path=PosixPath('/home/runner/.tradingstrategy/block-timestamp'), display_progress=True, chunk_size=100000)

Quickly get block timestamps using Hypersync API and a local cache file.

  • Ultra fast, used optimised Hypersync streaming and DuckDB local cache.

  • Large ranges are split into chunks of chunk_size blocks so that each chunk opens a separate Hypersync stream() call. This keeps individual requests small, lets the Python-side rate limiter pace them, and — crucially — saves progress after each chunk so that a 429 failure only loses the current chunk, not all prior work.

Parameters

  • chunk_size (int) – Maximum number of blocks per Hypersync streaming request. Defaults to 100 000 (~2 days on Polygon, ~3 days on Binance).

  • client (hypersync.HypersyncClient) –

  • chain_id (int) –

  • start_block (int) –

  • end_block (int) –

  • display_progress (bool) –

Returns

Block number -> datetime mapping

Return type

eth_defi.event_reader.timestamp_cache.BlockTimestampSlicer

get_block_timestamps_using_hypersync(client, chain_id, start_block, end_block, display_progress=True)

Quickly get block timestamps using Hypersync API.

Wraps get_block_timestamps_using_hypersync_async().

You want to use fetch_block_timestamps_using_hypersync_cached() cached version.

Returns

Block number -> header mapping

Parameters

  • client (hypersync.HypersyncClient) –

  • chain_id (int) –

  • start_block (int) –

  • end_block (int) –

  • display_progress (bool) –

Return type

dict[eth_typing.evm.BlockNumber, eth_defi.event_reader.block_header.BlockHeader]

async get_block_timestamps_using_hypersync_async(client, chain_id, start_block, end_block, timeout=120.0, display_progress=True, progress_throttle=10000, validate_chain_id=True, reason=None)

Read block timestamps using Hypersync API.

Instead of hammering eth_getBlockByNumber JSON-RPC endpoint, we can get block timestamps using Hypersync API 1000x faster.

Parameters

  • chain_id (int) – Expected chain ID. Validated against the client unless validate_chain_id is False.

  • start_block (int) – Start block, inclusive

  • end_block (int) – End block, inclusive

  • client (hypersync.HypersyncClient) – Hypersync client to use

  • validate_chain_id (bool) – When True (default), verify the client is connected to the expected chain before streaming. Set to False when the caller has already validated (e.g. the cached path).

  • reason (Optional[str]) – Human-readable label for this request, included in log and error messages to help track which caller is consuming API quota.

  • timeout (float) –

  • display_progress (bool) –

Return type

AsyncIterable[eth_defi.event_reader.block_header.BlockHeader]

get_hypersync_block_height(client)

Get the latest block known to Hypersync.

Wrapped around the async function.

Parameters

client (hypersync.HypersyncClient) –

Return type

int