degenbot.provider.sync
======================

.. py:module:: degenbot.provider.sync

.. autoapi-nested-parse::

   Synchronous Alloy provider: the mixin trees and :class:`AlloyProvider`.

   The async twin lives in :mod:`degenbot.provider.async_provider`. The two
   trees are deliberately parallel: 20 of the 22 methods they share are
   logic-identical modulo ``await``, and nearly all of those are single-line
   pass-throughs to the wrapped Rust pyclass -- the sync/await duality IS the
   code. The multi-line logic both trees need (block-tag resolution,
   block-timestamp extraction) lives once in
   :mod:`degenbot.provider.block_helpers`. ``get_logs`` genuinely differs: the
   sync surface accepts a :class:`LogFilter` or individual keyword arguments
   with range validation; the async surface takes keyword arguments only.





Module Contents
---------------

.. py:class:: LogFilter

   Filter criteria for log fetching.

   :param from_block: Starting block number (inclusive)
   :param to_block: Ending block number (inclusive)
   :param addresses: Contract addresses to filter (optional)
   :param topics: Event topic signatures, nested by position (optional)

   .. rubric:: Example

   >>> filter = LogFilter(
   ...     from_block=18_000_000,
   ...     to_block=18_010_000,
   ...     addresses=["0xContractAddress..."],
   ...     topics=[["0xTransfer..."]],  # Match first topic
   ... )


   .. py:attribute:: from_block
      :type:  degenbot.types.aliases.BlockNumber


   .. py:attribute:: to_block
      :type:  degenbot.types.aliases.BlockNumber


   .. py:attribute:: addresses
      :type:  list[str]
      :value: []



   .. py:attribute:: topics
      :type:  list[list[str]]
      :value: []



.. py:class:: AlloyProvider(rpc_url: str, max_retries: int = 10, max_blocks_per_request: int = 5000, chain_id: int | None = None)

   Bases: :py:obj:`_AlloyEndpointMixin`, :py:obj:`_AlloyQueryMixin`, :py:obj:`_AlloyIntrospectionMixin`


   High-performance Ethereum RPC provider using Alloy.

   Backs log fetching and basic RPC calls with a Rust HTTP client using
   connection pooling for optimal performance. The public surface is
   assembled from the query mixins; this class owns construction and
   teardown of the wrapped Rust provider.

   :param rpc_url: HTTP/HTTPS endpoint URL
   :param max_retries: Maximum retry attempts (default: 10)
   :param max_blocks_per_request: Maximum logs per request (default: 5000)
   :param chain_id: Chain to bind the endpoint to. The Rust core reads
                    ``eth_chainId`` once at construction and raises :class:`ValueError`
                    when the endpoint serves another chain; ``None`` constructs the
                    provider with no binding.

   .. rubric:: Example

   >>> provider = AlloyProvider("https://eth-mainnet.example.com")
   >>>
   >>> # Properties
   >>> chain_id = provider.chain_id
   >>> block_number = provider.block_number
   >>>
   >>> # Methods
   >>> block = provider.get_block(18_000_000)
   >>> logs = provider.get_logs(from_block=18_000_000, to_block=18_010_000)
   >>> code = provider.get_code("0x...")
   >>> result = provider.call("0x...", calldata)