degenbot.registry.token
=======================

.. py:module:: degenbot.registry.token

.. autoapi-nested-parse::

   Token registry: the Python companion side of the session's token identities.

   An ERC-20 token's canonical identity is its address in the session's chain, so
   the registry is a straight delegate: ask the Rust `SessionObjectRegistry` which
   token object the session holds (or should hold) for an address, and keep the
   `Erc20Token` companion that presents it. See
   :mod:`degenbot.registry.session` for why the companion cache is not a second
   identity authority.





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

.. py:class:: TokenRegistry(*, py_bot: degenbot._ffi.Bot)

   ERC-20 token companions, keyed by the session's token identities.


   .. py:method:: get(token_address: str, chain_id: degenbot.types.aliases.ChainId) -> degenbot.erc20.erc20.Erc20Token | None

      Retrieve a token by chain and address.

      :returns: The registered token, or None if not found.



   .. py:method:: add(token_address: str, chain_id: degenbot.types.aliases.ChainId, token: degenbot.erc20.erc20.Erc20Token) -> None

      Register a token.

      :raises DegenbotValueError: A companion is already registered for this
          token identity.



   .. py:method:: get_or_add(token_address: str, chain_id: degenbot.types.aliases.ChainId, token: degenbot.erc20.erc20.Erc20Token) -> degenbot.erc20.erc20.Erc20Token

      Idempotently register a token, returning the stored instance.

      If a concurrent registration worker already built this token, return the
      canonical stored instance instead of raising — a
      distinct path sharing this token is not lossily skipped.

      :returns: The stored token instance (the existing canonical one on a duplicate).



   .. py:method:: remove(token_address: str, chain_id: degenbot.types.aliases.ChainId) -> None

      Drop the companion for this token.

      The session's identity for the token is session-lifetime and stays, so a
      later build of the same address re-files a companion under the same
      canonical identity. No live token state is touched: the Rust
      `BotState` token entry belongs to `register_token` / `build_erc20_token`.



   .. py:method:: list_all() -> collections.abc.Iterator[degenbot.erc20.erc20.Erc20Token]

      Yield every registered token.

      :Yields: Each token companion filed in this registry.



   .. py:method:: reset() -> None

      Drop every token companion. The session's identities are untouched.