degenbot.registry.pool ====================== .. py:module:: degenbot.registry.pool .. autoapi-nested-parse:: Pool registry: the Python companion side of the session's pool identities. Canonical identity for a session's pools is owned by the Rust `SessionObjectRegistry`; these registries delegate to it. What lives here is the *presentation* object: a `UniswapV2Pool` / `BalancerV2Pool` / … companion wrapping live Rust state, which is not a session object. The split matters because a companion is a Python value that `release_python_state` drops and a later build re-mints, while the identity behind it is session-lifetime. Module Contents --------------- .. py:type:: PoolId :canonical: bytes .. py:class:: ManagedPoolRegistry(*, py_bot: degenbot._ffi.Bot) V4 pool companions, keyed by the session's `(PoolManager, pool_id)` identities. A V4 pool is named by its pair, never by the `PoolManager` address alone, so every read here carries both. This is the registry `Bot.managed_pools` and the one `PoolRegistry` delegates its V4 branch to, so the two are one companion store for the session's V4 pools. .. py:method:: get(chain_id: degenbot.types.aliases.ChainId, pool_manager_address: degenbot.types.chain.ChecksummedAddress, pool_id: PoolId) -> degenbot.types.pool_protocols.ConcentratedLiquidityPool | None Retrieve a V4 pool by chain, manager address, and pool ID. :returns: The registered V4 pool, or None if not found. .. py:method:: add(pool: degenbot.types.pool_protocols.ConcentratedLiquidityPool, chain_id: degenbot.types.aliases.ChainId, pool_manager_address: degenbot.types.chain.ChecksummedAddress, pool_id: PoolId) -> None Register a V4 pool. :raises DegenbotValueError: A companion is already registered for this identity. .. py:method:: get_or_add(pool: degenbot.types.pool_protocols.ConcentratedLiquidityPool, chain_id: degenbot.types.aliases.ChainId, pool_manager_address: degenbot.types.chain.ChecksummedAddress, pool_id: PoolId) -> degenbot.types.pool_protocols.ConcentratedLiquidityPool Idempotently register a V4 pool, returning the stored instance. If a concurrent registration worker already built this pool, return the canonical stored instance instead of raising — a distinct path sharing this pool is not lossily skipped. :returns: The stored pool instance (the existing canonical one on a duplicate). .. py:method:: remove(chain_id: degenbot.types.aliases.ChainId, pool_manager_address: degenbot.types.chain.ChecksummedAddress, pool_id: PoolId) -> None Drop the V4 companion for this identity. The session's identity for the pool is session-lifetime and stays; only the Python companion goes. .. py:method:: list_all() -> collections.abc.Iterator[degenbot.types.pool_protocols.ConcentratedLiquidityPool] Yield every registered V4 pool. :Yields: Each V4 pool companion filed in this registry. .. py:method:: reset() -> None Drop every V4 companion. The session's V4 identities are untouched. .. py:class:: PoolRegistry(*, py_bot: degenbot._ffi.Bot, managed_pool_registry: ManagedPoolRegistry | None = None) Address-keyed pool companions, delegating identity to the session registry. The non-V4 families are address-keyed, which is why reads here are family-agnostic: the session resolves the address to whichever family registered it first. Registering a pool, by contrast, names the family — read off the companion's live handle — so a V3 pool and a Balancer pool at one address stay two identities, as they are in the core. .. py:method:: get(chain_id: degenbot.types.aliases.ChainId, pool_address: degenbot.types.chain.ChecksummedAddress, pool_id: None = None) -> degenbot.types.abstract.AbstractLiquidityPool | None get(chain_id: degenbot.types.aliases.ChainId, pool_address: degenbot.types.chain.ChecksummedAddress, pool_id: PoolId) -> degenbot.types.pool_protocols.ConcentratedLiquidityPool | None Retrieve a pool by chain and address. :returns: The registered pool, or None if not found. .. py:method:: add(pool: degenbot.types.abstract.AbstractLiquidityPool, chain_id: degenbot.types.aliases.ChainId, pool_address: degenbot.types.chain.ChecksummedAddress, pool_id: PoolId | None = None) -> None Register a pool. When pool_id is provided, the pool must satisfy the ConcentratedLiquidityPool protocol and is registered in the managed pool sub-registry. Otherwise, it is registered as a standard pool. :raises TypeError: If pool_id is provided but pool does not satisfy ConcentratedLiquidityPool. :raises DegenbotValueError: A companion is already registered for this identity. .. py:method:: get_or_add(pool: degenbot.types.abstract.AbstractLiquidityPool, chain_id: degenbot.types.aliases.ChainId, pool_address: degenbot.types.chain.ChecksummedAddress, pool_id: PoolId | None = None) -> degenbot.types.abstract.AbstractLiquidityPool | degenbot.types.pool_protocols.ConcentratedLiquidityPool Idempotently register a pool, returning the stored instance. Used by the concurrent registration build path: if another worker already built this pool, return the canonical stored instance instead of raising, so a distinct path sharing the pool is not lossily skipped. Mirrors :meth:`add`'s managed/V4 dispatch. :returns: The stored pool instance (the existing canonical one on a duplicate). :raises TypeError: If ``pool_id`` is provided but pool does not satisfy ConcentratedLiquidityPool. .. py:method:: remove(chain_id: degenbot.types.aliases.ChainId, pool_address: degenbot.types.chain.ChecksummedAddress, pool_id: PoolId) -> None remove(chain_id: degenbot.types.aliases.ChainId, pool_address: degenbot.types.chain.ChecksummedAddress, pool_id: None = None) -> None Remove a pool. For V2/V3 pools (``pool_id`` is ``None``), propagates to the Rust ``BotState`` via ``py_bot.unregister_pool`` so the Rust-owned state stays symmetric with the Python registry (ADR-007). V4 pools (``pool_id`` is bytes) are Python-only here — V4 unregister is engine-side (see ADR-007 Deferred). The removal is of the *companion* and the live pool state; the session's identity for the pool is session-lifetime and is not withdrawn, so a later build of the same address re-files a companion under the same canonical identity. .. py:method:: list_all() -> collections.abc.Iterator[degenbot.types.abstract.AbstractLiquidityPool] Yield every registered address-keyed pool. :Yields: Each address-keyed pool companion filed in this registry. .. py:method:: reset() -> None Drop every companion, V4 included. The session's identities are untouched.