degenbot.provider.block_helpers
===============================

.. py:module:: degenbot.provider.block_helpers

.. autoapi-nested-parse::

   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
---------------

.. py:function:: 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.

   :param identifier: Block identifier (None, int, or string tag like 'latest')
   :param provider: AlloyProvider instance

   :returns: Block number as integer

   :raises DegenbotValueError: If the block identifier is invalid or block not found.


.. py:function:: 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 :class:`BlockTag.parse` ladder against the provider's current block
   number (``'latest'`` -> head, ``'earliest'`` -> 0, ``'pending'`` -> head
   + 1). This is the mixin-level seam; :func:`get_number_for_block_identifier`
   above serves the broader public ``BlockIdentifier`` surface with its own
   error contract.

   :param block_identifier: Block number, or one of 'latest', 'earliest', 'pending'.
   :param current_block_number: The provider's current block number.

   :returns: The concrete block number to query.


.. py:function:: 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.

   :param block_data: The block data returned by the provider, or None when the
                      block was not found.
   :param 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.