degenbot.runner.config
======================

.. py:module:: degenbot.runner.config

.. autoapi-nested-parse::

   Driver configuration for the settlement-arbitrage ``BotRunner``.

   This module owns the Python-companion, ``stays-python`` surface that the
   runtime driver (``BotRunner``) and its tests consume:

   - :class:`ArbitrageConfig` — the unified frozen config value object (built from
     the resolved verdict + CLI flags via :meth:`ArbitrageConfig.build`;
     the operator/executor identity it carries is read from the process
     environment; the deployment defaults and the checksum helper live in
     :mod:`degenbot.runner.identity`).

   The display renderers (sim-diag / sim-fail / failure-breakdown) live in
   :mod:`degenbot.runner._render`. The thin-margin solver-result pre-filter of the
   legacy ``main()`` path is core-owned: the drop lives in the Rust dispatch leaf
   alongside its basis-points denominator and candidate tuple, so this module
   carries no filtering state.





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

.. py:class:: RpcCascadeOverrides

   The :func:`degenbot.config.resolve_rpc_uris` inputs for :meth:`ArbitrageConfig.build`.

   The chain identity and the explicit-override endpoint travel together: they
   are exactly the arguments the RPC cascade consumes, so bundling them keeps
   the factory's keyword surface one concept per parameter. One ``node`` fills
   one transport slot and the core classifies which, so a driver that needs
   both an HTTP and a WS endpoint declares one of them here and takes the other
   from the file or the environment.


   .. py:attribute:: chain_id
      :type:  int
      :value: 1



   .. py:attribute:: node
      :type:  str | None
      :value: None



.. py:class:: ArbitrageConfig

   Unified settlement-arbitrage configuration — one object for the ~20 tunables `main()` reads.

   Replaces the scattered config sources (the example's dotenv file,
   module-top constants, and CLI flags) with a single frozen value object.
   Construct via :meth:`build`; the bridge onto ``main()`` lives in the
   ``BotRunner`` orchestration. The operational stances resolve through the
   core verdict, and the operator/executor identity is read from the process
   environment. Live defaults reproduce ``main()``'s behavior exactly — no
   new defaults invented.


   .. py:attribute:: operator_address
      :type:  str


   .. py:attribute:: operator_private_key
      :type:  str


   .. py:attribute:: chain_id
      :type:  int


   .. py:attribute:: node_http
      :type:  str


   .. py:attribute:: node_ws
      :type:  str


   .. py:attribute:: executor_address
      :type:  str


   .. py:attribute:: executor_owner
      :type:  str


   .. py:attribute:: inject_executor_code
      :type:  bool


   .. py:attribute:: injected_address
      :type:  str


   .. py:attribute:: permutation_filter
      :type:  frozenset[str] | None


   .. py:attribute:: verification_retry_policy
      :type:  degenbot.arbitrage.RetryPolicy


   .. py:attribute:: erc6909_profit
      :type:  bool


   .. py:attribute:: reg_progress_secs
      :type:  float


   .. py:attribute:: max_registered_paths
      :type:  int


   .. py:attribute:: discovery_batch_size
      :type:  int


   .. py:attribute:: contracts_dir
      :type:  str


   .. py:attribute:: sim_exit_on_fail
      :type:  bool


   .. py:attribute:: sim_exit_ignore_buckets
      :type:  str


   .. py:attribute:: dry_run
      :type:  bool


   .. py:attribute:: diag
      :type:  degenbot.runner.diag.DiagConfig


   .. py:attribute:: executor_runtime
      :type:  str | pathlib.Path | None
      :value: None



   .. py:method:: build(*, live: bool, permutation: str | None, rpc: RpcCascadeOverrides | None = None, values: degenbot.config.ConfigValues | None = None) -> ArbitrageConfig
      :classmethod:


      Build an ArbitrageConfig from the resolved verdict + CLI flags + process identity.

      The dotenv file is no longer a source: operator/executor identity is
      read from the process environment (the launch shell exports it from
      ``bot.env``), and every ``DEGENBOT_*`` operational stance is a declared
      schema key that arrives from :func:`degenbot.config.resolved_config`
      and reaches the operator file as well as the environment; nothing here
      re-resolves a layer.

      Behavior:
      - operator: live mode requires both OPERATOR_ADDRESS/OPERATOR_PRIVATE_KEY
        from the process environment and refuses a known placeholder key
        (raises ValueError); dry-run defaults to a valid throwaway key + its
        derived address.
      - nodes: delegated to :func:`degenbot.config.resolve_rpc_uris`, so the
        four-layer cascade (explicit ``node`` > OS env
        ``DEGENBOT_RPC_{IPC,WS,HTTP}_CHAINID_{cid}`` > the operator file's
        ``[nodes.*]`` tables > a declared default) applies, per capability.
        There is **no ``localhost`` default** — a chain with no configured
        endpoint in any layer raises :class:`RpcNotConfiguredError`.
      - executor: zero address is a fatal ``ValueError`` (a factory cannot
        return early like ``main()``'s ``return``).
      - inject code: when ``simulation.inject_executor_code`` resolves true,
        the executor address is overridden to ``INJECTED_EXECUTOR_ADDRESS``.
      - permutation: a CLI string becomes a singleton frozenset; ``None`` stays ``None``.

      :returns: A frozen ``ArbitrageConfig`` with cascade-resolved ``node_http``/``node_ws``.

      :raises ValueError: missing or placeholder operator in live mode, zero-address executor, a
          retired knob present, or ``RpcNotConfiguredError`` (a
          ``ValueError`` subclass) when no RPC endpoint is configured for
          ``chain_id`` in any cascade layer.