degenbot.provider.block_helpers

Block identifier resolution helpers.

Shared shaping logic for the sync (degenbot.provider.sync) and async (degenbot.provider.async_provider) provider trees: both get_block twins resolve identifiers here, and both get_block_timestamp twins extract the timestamp here, so the block-tag contract has one home.

Module Contents

degenbot.provider.block_helpers.get_number_for_block_identifier(identifier: degenbot.types.rpc_types.BlockIdentifier | None, provider: degenbot.provider.AlloyProvider) → degenbot.types.aliases.BlockNumber

Convert a block identifier to a block number.

Parameters:

  • identifier – Block identifier (None, int, or string tag like ‘latest’)

  • provider – AlloyProvider instance

Returns:

Block number as integer

Raises:

DegenbotValueError – If the block identifier is invalid or block not found.

degenbot.provider.block_helpers.resolve_block_tag(block_identifier: int | str, current_block_number: degenbot.types.aliases.BlockNumber) → degenbot.types.aliases.BlockNumber

Resolve a provider get_block identifier to a block number.

Integer identifiers pass through unchanged; string tags resolve through the BlockTag.parse ladder against the provider’s current block number ('latest' -> head, 'earliest' -> 0, 'pending' -> head + 1). This is the mixin-level seam; get_number_for_block_identifier() above serves the broader public BlockIdentifier surface with its own error contract.

Parameters:

  • block_identifier – Block number, or one of ‘latest’, ‘earliest’, ‘pending’.

  • current_block_number – The provider’s current block number.

Returns:

The concrete block number to query.

degenbot.provider.block_helpers.block_timestamp_from(block_data: degenbot.types.rpc_types.BlockData | None, requested_block: int | None) → int

Extract a timestamp from fetched block data, failing on a missing block.

Parameters:

  • block_data – The block data returned by the provider, or None when the block was not found.

  • requested_block – The block number the caller asked for (used verbatim in the error message; None means the 'latest' default).

Returns:

The block timestamp as an integer (Unix seconds).

Raises:

ValueError – If the block data is absent.