degenbot.contract
=================

.. py:module:: degenbot.contract

.. autoapi-nested-parse::

   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.

   .. rubric:: 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
----------

.. toctree::
   :maxdepth: 1

   /autoapi/degenbot/contract/addresses/index






Package Contents
----------------

.. py:class:: 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.

   :param address: Contract address
   :param provider: AlloyProvider instance (optional, will use default if not provided)

   .. rubric:: 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()", []),
   ... ])


   .. py:property:: address
      :type: degenbot._ffi.ChecksummedAddress


      The contract address.


   .. py:method:: 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.

      :param function_signature: Function signature like "balanceOf(address)" or
                                 "transfer(address,uint256) returns (bool)"
      :param args: Function arguments as strings (optional)
      :param block_number: Block to query (default: latest)
                           Can be "latest", "pending", "safe", "finalized", or block number

      :returns: List of decoded return values as strings

      .. rubric:: 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



   .. py:method:: 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.

      :param calls: List of (function_signature, args) tuples
      :param block_number: Block to query (default: latest)

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

      .. rubric:: 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]



   .. py:method:: encode_function_call(function_signature: str, args: collections.abc.Sequence[str] | None = None) -> bytes
      :staticmethod:


      Encode a function call without executing it.

      Useful for manual transaction building or debugging.

      :param function_signature: Function signature
      :param args: Function arguments

      :returns: Encoded calldata as bytes

      .. rubric:: Example

      >>> calldata = contract.encode_function_call(
      ...     "transfer(address,uint256)",
      ...     ["0x742d35Cc6634C0532925a3b8D4C9db96590d6B75", "1000000000000000000"],
      ... )
      >>> print(f"0x{calldata.hex()}")
      0xa9059cbb...



   .. py:method:: get_function_selector(function_signature: str) -> str
      :staticmethod:


      Get the 4-byte function selector for a signature.

      :param function_signature: Function signature like "transfer(address,uint256)"

      :returns: 4-byte selector as hex string with 0x prefix

      .. rubric:: Example

      >>> Contract.get_function_selector("transfer(address,uint256)")
      '0xa9059cbb'
      >>> Contract.get_function_selector("balanceOf(address)")
      '0x70a08231'



   .. py:method:: decode_return_data(data: bytes, output_types: collections.abc.Sequence[str]) -> list[str]
      :staticmethod:


      Decode return data based on expected output types.

      :param data: Raw return data from eth_call
      :param output_types: List of output type strings like ["uint256", "address"]

      :returns: List of decoded values as strings

      .. rubric:: Example

      >>> decoded = Contract.decode_return_data(
      ...     data=b"...",
      ...     output_types=["uint256", "address"],
      ... )
      >>> balance, owner = decoded



.. py:function:: get_function_selector(function_signature: str) -> str

   Get the 4-byte function selector for a signature.

   :param function_signature: Function signature like "transfer(address,uint256)"

   :returns: 4-byte selector as hex string with 0x prefix

   .. rubric:: Example

   >>> get_function_selector("transfer(address,uint256)")
   '0xa9059cbb'


.. py:function:: encode_function_call(function_signature: str, args: collections.abc.Sequence[str] | None = None) -> bytes

   Encode a function call without executing it.

   :param function_signature: Function signature
   :param args: Function arguments

   :returns: Encoded calldata as bytes


.. py:function:: decode_return_data(data: bytes, output_types: collections.abc.Sequence[str]) -> list[str]

   Decode return data based on expected output types.

   :param data: Raw return data from eth_call
   :param output_types: List of output type strings like ["uint256", "address"]

   :returns: List of decoded values as strings