degenbot.registry.deployment_records
====================================

.. py:module:: degenbot.registry.deployment_records

.. autoapi-nested-parse::

   Deployment data records: read + merge the shipped JSON and operator overlay.

   Data layer only (ADR-005): this module knows the JSON schema and the valid
   ``pool_type`` keys, and resolves nothing to Python classes — the companion
   class map and the registry registration live in
   :mod:`degenbot.registry.deployment_loader`. It is a leaf module: importing it
   must not pull in any pool implementation, which is what lets
   :mod:`degenbot.uniswap.deployments` bind its constants at import time and
   lets the loader import the pool classes eagerly.

   Schema (``deployments.json``):

   .. code-block:: json

       {
         "deployments": [
           {
             "name": "Uniswap V2",
             "chain_id": 1,
             "pool_type": "uniswap-v2",
             "variant": null,
             "dex_variant": "uniswap-v2",
             "family": null,
             "factory": "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f",
             "deployer": null,
             "init_hash": "0x96e8ac4277..."
           }
         ]
       }

   Field semantics:

   - ``pool_type``: string key into the loader's companion class map. The JSON
     carries only the string; the loader resolves it to a class.
   - ``variant``: the DB-kind variant. ``null`` means "use the class's
     ``variant`` ClassVar" (``register()`` calls ``getattr(cls, "variant",
     None)``). A string is an explicit override (e.g. ``"pancakeswap"`` on
     ``UniswapV2Pool``, whose own ``variant`` is ``None``).
   - ``dex_variant``: the ``DexIdentity`` preset string (e.g.
     ``"camelot-v2-volatile"``). ``null`` means no ``dex_identity`` (V3,
     Aerodrome V2, Balancer).
   - ``family``: override for ``_derive_family`` (Balancer needs this — its
     classes have ``tokens`` without ``fee_token0`` and would misclassify).
     ``null`` means auto-derive. One of ``"weighted"`` / ``"stableswap"``.
   - ``factory``: EIP-55 checksummed factory address.
   - ``deployer``: CREATE2 deployer. ``null`` → ``factory`` (the
     ``register()`` default).
   - ``init_hash``: CREATE2 init code hash. ``null`` / ``""`` → no CREATE2
     (Aerodrome, Balancer).









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

.. py:data:: KNOWN_POOL_TYPES

.. py:class:: DeploymentRecord

   A single deployment row loaded from JSON.


   .. py:attribute:: name
      :type:  str


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


   .. py:attribute:: pool_type
      :type:  str


   .. py:attribute:: variant
      :type:  str | None


   .. py:attribute:: dex_variant
      :type:  str | None


   .. py:attribute:: family
      :type:  str | None


   .. py:attribute:: factory
      :type:  str


   .. py:attribute:: deployer
      :type:  str | None


   .. py:attribute:: init_hash
      :type:  str | None


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



.. py:function:: load_deployments(*, overlay_path: pathlib.Path | str | None = None) -> list[DeploymentRecord]

   Load deployment records from the shipped JSON, merged with an optional overlay.

   The overlay is resolved in this order:

   1. The ``overlay_path`` argument (programmatic — used by tests).
   2. The ``[deployments] overlay`` setting in ``~/.config/degenbot/config.toml``.

   Shipped defaults load first; overlay entries override on
   ``(chain_id, factory)`` conflict (overlay wins). The merged list preserves
   insertion order (shipped order, with overlays replacing in-place).

   :returns: The merged deployment records.


.. py:function:: load_json_deployments(path: pathlib.Path | str) -> list[DeploymentRecord]

   Load deployment records from an explicit JSON file path.

   Convenience wrapper around the internal JSON reader — exposed for tests
   and programmatic callers that want to load a specific file without the
   shipped-defaults merge.

   :returns: The parsed deployment records.