degenbot.erc20

ERC-20 token with on-chain metadata and balance tracking.

Submodules

• degenbot.erc20.erc20
• degenbot.erc20.ether_placeholder

Package Contents

degenbot.erc20.UNKNOWN_DECIMALS = 18

degenbot.erc20.UNKNOWN_NAME = 'Unknown Token'

degenbot.erc20.UNKNOWN_SYMBOL = 'UNKNOWN'

class degenbot.erc20.Erc20Token(*args: Any, **kwargs: Any)

Bases: degenbot.types.abstract.AbstractErc20Token

An ERC-20 token contract.

Constructed from pre-fetched data only. Use Bot.build_erc20token() to fetch from chain. Balance, approval, and total supply queries go through Bot.get_token_balance() etc.

classmethod from_handle(py_token: degenbot._ffi.Erc20Token, *, oracle_address: str | None = None, state_cache_depth: int = 8) → Self

Wrap a Rust-owned _TokenHandle handle as a Python companion.

Internal seam (ADR-005, Polars-style _from_pydf pattern). Rust owns the token metadata (address, name, symbol, decimals, chain_id) as a TokenEntry; this companion reads it through self._py_token on every access and holds no metadata copy. Price oracle + balance/approval/total-supply caches stay Python (I/O constructs that cannot move to Rust).

Only Bot.get_token() / Bot.build_erc20token() (production) and make_erc20 (tests) should call this — they have already registered the token metadata in a Bot and obtained the handle. cls is used so subclasses that only set ClassVars inherit this seam and produce instances of the subclass.

Returns:

A cls instance wrapping py_token.

property address: degenbot.types.chain.ChecksummedAddress

Token contract address (EIP-55 checksum).

Rust holds the address bytes; get_checksum_address applies the codebase-wide EIP-55 display convention.

property name: str

Token name (read from Rust-owned TokenEntry).

property symbol: str

Token symbol (read from Rust-owned TokenEntry).

property decimals: int

Token decimals (read from Rust-owned TokenEntry).

get_cached_balance(address: degenbot.types.chain.ChecksummedAddress, block_number: int) → int | None

Return cached balance.

Returns:

The computed value.

set_cached_balance(address: degenbot.types.chain.ChecksummedAddress, block_number: int, balance: int) → None

Set cached balance.

get_cached_approval(block_number: int, owner: degenbot.types.chain.ChecksummedAddress, spender: degenbot.types.chain.ChecksummedAddress) → int | None

Return cached approval.

Returns:

The computed value.

set_cached_approval(block_number: int, owner: degenbot.types.chain.ChecksummedAddress, spender: degenbot.types.chain.ChecksummedAddress, amount: int) → None

Set cached approval.

get_cached_total_supply(block_number: int) → int | None

Return cached total supply.

Returns:

The computed value.

set_cached_total_supply(block_number: int, total_supply: int) → None

Set cached total supply.

property price: float

Price.

Raises:

NoPriceOracle – See function documentation.

property chain_id: int

Chain ID (read from Rust-owned TokenEntry).

class degenbot.erc20.EtherPlaceholder

Bases: degenbot.erc20.Erc20Token

An Erc20Token-like adapter for the ‘all Es’ or zero address placeholder.

Used by pools to represent native Ether. Under ADR-005, metadata (name=”Ether Placeholder”, symbol=”ETH”, decimals=18) is registered in the Rust Bot when an EtherPlaceholder is built; the inherited delegating properties read it back through the Rust Erc20Token handle.

Direct construction is forbidden (inherited from Erc20Token). Use Erc20Token.from_handle() — which produces an EtherPlaceholder instance when called on the subclass — after registering the metadata in a Bot.

addresses