degenbot.registry.deployment_records

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 degenbot.registry.deployment_loader. It is a leaf module: importing it must not pull in any pool implementation, which is what lets degenbot.uniswap.deployments bind its constants at import time and lets the loader import the pool classes eagerly.

Schema (deployments.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

degenbot.registry.deployment_records.KNOWN_POOL_TYPES

class degenbot.registry.deployment_records.DeploymentRecord

A single deployment row loaded from JSON.

name: str

chain_id: int

pool_type: str

variant: str | None

dex_variant: str | None

family: str | None

factory: str

deployer: str | None

init_hash: str | None

implementation_address: str | None = None

degenbot.registry.deployment_records.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.

degenbot.registry.deployment_records.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.