degenbot.provider.factory
=========================

.. py:module:: degenbot.provider.factory

.. autoapi-nested-parse::

   Provider construction over a cascade-resolved endpoint (ADR-062 D8).

   The canonical chain-bound URL-to-provider factory. The endpoint and the chain
   both come from the installed typed config, and the chain binding itself is the
   Rust core's: the factory hands the resolved ``chain_id`` to the provider and the
   core reads ``eth_chainId`` once at construction, refusing a misconfigured
   endpoint before any pool/token I/O runs. A Rust consumer that constructs a
   provider directly gets the same refusal (see
   ``degenbot_rpc::provider::AlloyProvider::for_chain``). What is left here is
   translating the core's refusal into this package's error hierarchy.

   Lives in ``degenbot.provider`` (the lib layer) so both ``Bot.__init__`` and the
   CLI can reach it without a lib->cli reverse dependency.







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

.. py:exception:: ChainIdentityMismatchError

   Bases: :py:obj:`degenbot.exceptions.base.DegenbotValueError`, :py:obj:`ValueError`


   The core's chain-binding refusal, re-homed into this package's hierarchy.

   The check is the core's invariant; only the error class is re-homed here.
   It stays a :class:`ValueError` as well as a
   :class:`~degenbot.exceptions.base.DegenbotValueError`, so a caller that
   already handled a misconfigured endpoint keeps catching it exactly as it
   caught the core's own refusal.


.. py:function:: get_provider_from_config(*, chain_id: int | str | None = None, node: str | None = None, resolve_uri: collections.abc.Callable[..., str] = resolve_http_rpc_uri, provider_factory: collections.abc.Callable[..., degenbot.provider.sync.AlloyProvider] | None = None, chain_mismatch_error: type[degenbot.provider.ChainMismatchError] = ChainMismatchError) -> degenbot.provider.sync.AlloyProvider

   Build a chain-bound :class:`AlloyProvider` for the session chain.

   The endpoint resolves through the request scope of the four-layer cascade
   and the chain through the chain-id cascade, both from the installed typed
   config; ``chain_id``/``node`` are the explicit override layer when given.

   The constructed provider is BOUND to that chain: the Rust core verifies the
   endpoint's ``eth_chainId`` once, and its refusal is translated into a
   :class:`DegenbotValueError` here.

   ``resolve_uri``/``provider_factory``/``chain_mismatch_error`` are the DI
   seams (tests inject a recording resolver, a stand-in constructor, and a
   constructible stand-in for the PyO3 refusal class); omitted kwargs keep
   the production bindings.

   :param chain_id: The explicit chain override; resolved from the config layers
                    when absent.
   :param node: The explicit endpoint override, classified by its own value.
   :param resolve_uri: The endpoint resolver called as
                       ``resolve_uri(session_chain_id, node=node)``.
   :param provider_factory: The provider constructor called as
                            ``provider_factory(endpoint, chain_id=session_chain_id)``.
   :param chain_mismatch_error: The exception class the core's refusal is
                                caught as before re-homing.

   :returns: A chain-bound AlloyProvider over the resolved RPC endpoint.

   :raises ChainIdentityMismatchError: When the endpoint serves another chain than
       the session targets. It is both a
       :class:`~degenbot.exceptions.base.DegenbotValueError` and a
       :class:`ValueError`.


.. py:function:: get_async_provider_from_config(*, chain_id: int | str | None = None, node: str | None = None, resolve_uri: collections.abc.Callable[..., str] = resolve_http_rpc_uri, provider_factory: collections.abc.Callable[..., Any] | None = None, chain_mismatch_error: type[degenbot.provider.ChainMismatchError] = ChainMismatchError) -> degenbot.provider.async_provider.AsyncAlloyProvider
   :async:


   Build a chain-bound :class:`AsyncAlloyProvider` for the session chain.

   Async counterpart of :func:`get_provider_from_config`: the same resolution,
   the same core check, awaited on the caller's event loop. The DI seams are
   the sync factory's; an omitted ``provider_factory`` resolves to
   ``AsyncAlloyProvider.create``.

   :param chain_id: The explicit chain override; resolved from the config layers
                    when absent.
   :param node: The explicit endpoint override, classified by its own value.
   :param resolve_uri: The endpoint resolver called as
                       ``resolve_uri(session_chain_id, node=node)``.
   :param provider_factory: The awaited provider constructor called as
                            ``provider_factory(endpoint, chain_id=session_chain_id)``.
   :param chain_mismatch_error: The exception class the core's refusal is
                                caught as before re-homing.

   :returns: A chain-bound AsyncAlloyProvider over the resolved RPC endpoint.

   :raises ChainIdentityMismatchError: When the endpoint serves another chain than
       the session targets. It is both a
       :class:`~degenbot.exceptions.base.DegenbotValueError` and a
       :class:`ValueError`.