degenbot.contract¶

Smart contract interface with automatic ABI encoding/decoding.

This module provides a high-level contract interface using the Rust-based Alloy provider for automatic ABI encoding and decoding of function calls.

Example

>>> from degenbot.contract import Contract, get_function_selector
>>> from degenbot import Bot
>>>
>>> bot = Bot.from_config_file()
>>>
>>> # Create contract instance
>>> token = Contract(
...     address="0xA0b86a33E6441e3D4e4b8b8b8b8b8b8b8b8b8b8",
...     provider=bot.get_provider(chain_id=1),
... )
>>>
>>> # Call functions with automatic encoding/decoding
>>> balance = token.call("balanceOf(address)", ["0x1234..."])
>>> name, symbol, decimals = token.batch_call([
...     ("name()", []),
...     ("symbol()", []),
...     ("decimals()", []),
... ])

Submodules¶

Package Contents¶

class degenbot.contract.Contract(address: degenbot._ffi.ChecksummedAddress, provider: degenbot.provider.AlloyProvider | None = None, provider_url: str | None = None)¶

High-level contract interface with automatic ABI encoding/decoding.

Provides a Pythonic interface for calling smart contract functions with automatic ABI encoding of arguments and decoding of return values.

Parameters:

  • address – Contract address

  • provider – AlloyProvider instance (optional, will use default if not provided)

Example

>>> from degenbot.contract import Contract
>>> from degenbot import Bot
>>>
>>> bot = Bot.from_config_file()
>>>
>>> # Create contract for an ERC20 token
>>> token = Contract(
...     address="0xA0b86a33E6441e3D4e4b8b8b8b8b8b8b8b8b8b8",
...     provider=bot.get_provider(chain_id=1),
... )
>>>
>>> # Call balanceOf function
>>> balance = token.call(
...     "balanceOf(address)",
...     ["0x742d35Cc6634C0532925a3b8D4C9db96590d6B75"],
... )
>>> print(f"Balance: {balance[0]}")
Balance: 1000000000000000000
>>>
>>> # Batch multiple calls for efficiency
>>> name, symbol, decimals = token.batch_call([
...     ("name()", []),
...     ("symbol()", []),
...     ("decimals()", []),
... ])
property address: degenbot._ffi.ChecksummedAddress¶

The contract address.

call(function_signature: str, args: collections.abc.Sequence[str] | None = None, block_number: int | str | None = None) → list[str]¶

Execute a contract call with automatic encoding/decoding.

Parameters:

  • function_signature – Function signature like “balanceOf(address)” or “transfer(address,uint256) returns (bool)”

  • args – Function arguments as strings (optional)

  • block_number – Block to query (default: latest) Can be “latest”, “pending”, “safe”, “finalized”, or block number

Returns:

List of decoded return values as strings

Example

>>> # Simple call without arguments
>>> name = contract.call("name()")
>>>
>>> # Call with arguments
>>> balance = contract.call(
...     "balanceOf(address)",
...     ["0x742d35Cc6634C0532925a3b8D4C9db96590d6B75"],
... )
>>>
>>> # Call with multiple return values
>>> results = contract.call("getReserves() returns (uint112,uint112,uint32)")
>>> reserve0, reserve1, blockTimestampLast = results
batch_call(calls: collections.abc.Sequence[tuple[str, collections.abc.Sequence[str] | None]], block_number: int | str | None = None) → list[list[str]]¶

Execute multiple contract calls efficiently.

Parameters:

  • calls – List of (function_signature, args) tuples

  • block_number – Block to query (default: latest)

Returns:

List of results, where each result is a list of decoded return values

Example

>>> # Fetch multiple token properties in one batch
>>> results = contract.batch_call([
...     ("name()", []),
...     ("symbol()", []),
...     ("decimals()", []),
...     ("totalSupply()", []),
... ])
>>> name, symbol, decimals, total_supply = [r[0] for r in results]
static encode_function_call(function_signature: str, args: collections.abc.Sequence[str] | None = None) → bytes¶

Encode a function call without executing it.

Useful for manual transaction building or debugging.

Parameters:

  • function_signature – Function signature

  • args – Function arguments

Returns:

Encoded calldata as bytes

Example

>>> calldata = contract.encode_function_call(
...     "transfer(address,uint256)",
...     ["0x742d35Cc6634C0532925a3b8D4C9db96590d6B75", "1000000000000000000"],
... )
>>> print(f"0x{calldata.hex()}")
0xa9059cbb...
static get_function_selector(function_signature: str) → str¶

Get the 4-byte function selector for a signature.

Parameters:

function_signature – Function signature like “transfer(address,uint256)”

Returns:

4-byte selector as hex string with 0x prefix

Example

>>> Contract.get_function_selector("transfer(address,uint256)")
'0xa9059cbb'
>>> Contract.get_function_selector("balanceOf(address)")
'0x70a08231'
static decode_return_data(data: bytes, output_types: collections.abc.Sequence[str]) → list[str]¶

Decode return data based on expected output types.

Parameters:

  • data – Raw return data from eth_call

  • output_types – List of output type strings like [“uint256”, “address”]

Returns:

List of decoded values as strings

Example

>>> decoded = Contract.decode_return_data(
...     data=b"...",
...     output_types=["uint256", "address"],
... )
>>> balance, owner = decoded
degenbot.contract.get_function_selector(function_signature: str) → str¶

Get the 4-byte function selector for a signature.

Parameters:

function_signature – Function signature like “transfer(address,uint256)”

Returns:

4-byte selector as hex string with 0x prefix

Example

>>> get_function_selector("transfer(address,uint256)")
'0xa9059cbb'
degenbot.contract.encode_function_call(function_signature: str, args: collections.abc.Sequence[str] | None = None) → bytes¶

Encode a function call without executing it.

Parameters:

  • function_signature – Function signature

  • args – Function arguments

Returns:

Encoded calldata as bytes

degenbot.contract.decode_return_data(data: bytes, output_types: collections.abc.Sequence[str]) → list[str]¶

Decode return data based on expected output types.

Parameters:

  • data – Raw return data from eth_call

  • output_types – List of output type strings like [“uint256”, “address”]

Returns:

List of decoded values as strings