ape.api

Accounts

class ape.api.accounts.AccountAPI(container: AccountContainerAPI, _provider: Optional[ape.api.providers.ProviderAPI] = None, **kwargs)

Bases: ape.api.address.AddressAPI

An API class representing an account.

__dir__()List[str]

Display methods to IPython on a.[TAB] tab completion.

Returns

Method names that IPython uses for tab completion.

Return type

List[str]

property alias

A shortened-name for quicker access to the account.

call(txn: ape.api.providers.TransactionAPI, send_everything: bool = False)ape.api.providers.ReceiptAPI

Make a transaction call.

Raises
  • AccountsError – When the nonce is invalid or the sender does not have enough funds.

  • TransactionError – When the required confirmations are negative.

  • SignatureError – When the user does not sign the transaction.

Parameters
  • txn (TransactionAPI) – The transaction to submit in a call.

  • send_everything (bool) – True will send the value difference from balance and fee.

Returns

ReceiptAPI

deploy(contract: ContractContainer, *args, **kwargs)ContractInstance

Create a smart contract on the blockchain. The smart contract must compile before deploying and a provider must be active.

Parameters

contract (ContractContainer) – The type of contract to deploy.

Returns

An instance of the deployed contract.

Return type

ContractInstance

abstract sign_message(msg: eth_account.messages.SignableMessage)Optional[ape.types.signatures.MessageSignature]

Sign a message.

Parameters

msg (SignableMessage) – The message to sign. See these docs # noqa: E501 for more type information on this type.

Returns

The signed message.

Return type

MessageSignature (optional)

abstract sign_transaction(txn: ape.api.providers.TransactionAPI)Optional[ape.types.signatures.TransactionSignature]

Sign a transaction.

Parameters

txn (TransactionAPI) – The transaction to sign.

Returns

The signed transaction.

Return type

TransactionSignature (optional)

transfer(account: Union[str, ChecksumAddress, ape.api.address.AddressAPI], value: Optional[Union[str, int]] = None, data: Optional[Union[bytes, str]] = None, **kwargs)ape.api.providers.ReceiptAPI

Send funds to an account.

Parameters
  • account (str) – The account to send funds to.

  • value (str) – The amount to send.

  • data (str) – Extra data to include in the transaction.

Returns

ReceiptAPI

class ape.api.accounts.AccountContainerAPI(data_folder: pathlib.Path, account_type: Type[ape.api.accounts.AccountAPI], config_manager: ConfigManager, **kwargs)

Bases: object

An API class representing a collection of AccountAPI instances.

__contains__(address: ChecksumAddress)bool

Check if the address is an existing account in ape.

Raises

IndexError – When the given account address is not in this container.

Parameters

address (AddressType) – An account address.

Returns

True if ape manages the account with the given address.

Return type

bool

__delitem__(address: ChecksumAddress)

Delete an account.

Raises

NotImplementError – When not overridden within a plugin.

Parameters

address (address AddressType) – The address of the account to delete.

__getitem__(address: ChecksumAddress)ape.api.accounts.AccountAPI

Get an account by address.

Raises

IndexError – When there is no local account with the given address.

Returns

AccountAPI

abstract __iter__()Iterator[ape.api.accounts.AccountAPI]

Iterate over all accounts.

Returns

Iterator[AccountAPI]

abstract __len__()int

Number of accounts.

abstract property aliases

Iterate over all available aliases.

Returns

Iterator[str]

append(account: ape.api.accounts.AccountAPI)

Add an account to the container.

Raises

AccountsError – When the account is already in the container.

Parameters

account (AccountAPI) – The account to add.

remove(account: ape.api.accounts.AccountAPI)

Delete an account.

Raises

AccountsError – When the account is not known to ape.

Parameters

account (AccountAPI) – The account to remove.

class ape.api.accounts.TestAccountAPI(container: AccountContainerAPI, _provider: Optional[ape.api.providers.ProviderAPI] = None, **kwargs)

Bases: ape.api.accounts.AccountAPI

Test accounts for ape test (such accounts that use GeneratedDevAccounts) should implement this API instead of AccountAPI directly. This is how they show up in the accounts test fixture.

class ape.api.accounts.TestAccountContainerAPI(data_folder: pathlib.Path, account_type: Type[ape.api.accounts.AccountAPI], config_manager: ConfigManager, **kwargs)

Bases: ape.api.accounts.AccountContainerAPI

Test account containers for ape test (such containers that generate accounts using GeneratedDevAccounts) should implement this API instead of AccountContainerAPI directly. This is how they show up in the accounts test fixture.

Address

class ape.api.address.Address(_address: ChecksumAddress, _provider: Optional[ape.api.providers.ProviderAPI] = None, **kwargs)

Bases: ape.api.address.AddressAPI

A generic blockchain address. Typically, this is used when we do not know the contract type at a given address, or to refer to an EOA the user doesn’t personally control.

property address

The raw address type.

Returns

AddressType

class ape.api.address.AddressAPI(_provider: Optional[ape.api.providers.ProviderAPI] = None, **kwargs)

Bases: object

A base address API class. All account-types subclass this type.

abstract property address

The address of this account. Subclasses must override and provide this value.

property balance

The total balance of the account.

property code

The raw bytes of the smart-contract code at the address.

property codesize

The number of bytes in the smart contract.

property is_contract

True when there is code associated with the address.

property nonce

The number of transactions associated with the address.

property provider

The current active provider if connected to one.

Raises

AddressError – When there is no active provider at runtime.

Returns

ProviderAPI

Compiler

class ape.api.compiler.CompilerAPI(config: ape.api.config.ConfigItem, **kwargs)

Bases: object

Compiler plugins, such as for languages like Solidity or Vyper, implement this API. See the repository for the ape-solidity plugin or the ape-vyper plugin as example implementations of this API.

abstract compile(contract_filepaths: List[pathlib.Path], base_path: Optional[pathlib.Path])List[ethpm_types.contract_type.ContractType]

Compile the given source files. All compiler plugins must implement this function.

Parameters
  • contract_filepaths (List[pathlib.Path]) – A list of source file paths to compile.

  • base_path (Optional[pathlib.Path]) – Optionally provide the base path, such as the project contracts/ directory. Defaults to None. When using in a project via ape compile, gets set to the project’s contracts/ directory.

Returns

List[ContractType]

config: ape.api.config.ConfigItem

The ape.api.config.ConfigItem for this compiler plugin.

abstract get_versions(all_paths: List[pathlib.Path])Set[str]

Retrieve the set of available compiler versions for this plugin to compile all_paths.

Parameters

all_paths (List[pathlib.Path]) – The list of paths.

Returns

A set of available compiler versions.

Return type

Set[str]

Config

class ape.api.config.ConfigDict

Bases: ape.api.config.ConfigItem

A config class that is generic and key-value based.

class ape.api.config.ConfigEnum(value)

Bases: str, enum.Enum

A configuration Enum type. Use this to limit the values of a config item, such as colors "RED", "BLUE", "GREEN", rather than any arbitrary str.

class ape.api.config.ConfigItem

Bases: object

A base plugin configuration class. Each plugin that includes a config API must register a subclass of this class.

__getitem__(attrname: str)Any

Get a configuration setting property by name. Use get() when it is ok for the key not to exist in the config.

Raises

KeyError – When the attribute name is not a key in the config.

Parameters

attrname (str) – The configuration setting key.

Returns

The value from the config.

Return type

Any

get(attrname: str, default_value: Optional[Any] = None)Optional[Any]

Get a configuration setting property by name.

Parameters
  • attrname (str) – The configuration setting key.

  • default_value (Optional[Any]) – The value to return if the key does not exist. Defaults to None.

Returns

The default value if the key is not in the config, the value otherwise.

Return type

Optional[Any]

serialize()Dict

Serialize the config item into a raw dict format for storing on disk.

Returns

Dict

Convert

class ape.api.convert.ConverterAPI(config: ape.api.config.ConfigItem, networks: NetworkManager, converter: ConversionManager, **kwargs)

Bases: Generic[ape.api.convert.ConvertedType]

abstract convert(value: Any)ConvertedType

Convert the given value to the type specified as the generic for this class. Implementations of this API must throw a ConversionError when the item fails to convert properly.

abstract is_convertible(value: Any)bool

Returns True if string value provided by value is convertible using ape.api.convert.ConverterAPI.convert().

Parameters

value (str) – The value to check.

Returns

True when the given value can be converted.

Return type

bool

Explorers

class ape.api.explorers.ExplorerAPI(name: str, network: ape.api.networks.NetworkAPI, request_header: str, **kwargs)

Bases: object

An API class representing a blockchain explorer for a particular network in a particular ecosystem.

abstract get_account_transactions(address: ChecksumAddress)Iterator[ape.api.providers.ReceiptAPI]

Get a list of list of transactions performed by an address.

Parameters

address (AddressType) – The account address.

Returns

Iterator[ReceiptAPI]

abstract get_address_url(address: ChecksumAddress)str

Get an address URL, such as for a transaction.

Parameters

address (AddressType) – The address to get the URL for.

Returns

str

abstract get_contract_type(address: ChecksumAddress)Optional[ethpm_types.contract_type.ContractType]

Get the contract type for a given address if it has been published in an explorer.

Parameters

address (AddressType) – The contract address.

Returns

If not published, returns None.

Return type

Optional[ContractType]

abstract get_transaction_url(transaction_hash: str)str

Get the transaction URL for the given transaction.

Parameters

transaction_hash (str) – The transaction hash.

Returns

str

Networks

class ape.api.networks.EcosystemAPI(name: str, network_manager: NetworkManager, config_manager: ConfigManager, plugin_manager: pluggy.manager.PluginManager, data_folder: pathlib.Path, request_header: str, transaction_types: Dict[TransactionType, Type[TransactionAPI]], receipt_class: Type[ReceiptAPI], block_class: Type[BlockAPI], _default_network: str = 'development', *args, **kwargs)

Bases: object

A set of related networks, such as Ethereum.

__getattr__(network_name: str)ape.api.networks.NetworkAPI

Get a network by name using . access.

Usage example:

from ape import networks
mainnet = networks.ecosystem.mainnet
Raises

NetworkNotFoundError – When there is no network with the given name.

Parameters

network_name (str) – The name of the network to retrieve.

Returns

NetworkAPI

__getitem__(network_name: str)ape.api.networks.NetworkAPI

Get a network by name.

Raises

NetworkNotFoundError – When there is no network with the given name.

Parameters

network_name (str) – The name of the network to retrieve.

Returns

NetworkAPI

__iter__()Iterator[str]

Iterate over the set of all valid network names in the ecosystem.

Returns

Iterator[str]

add_network(network_name: str, network: ape.api.networks.NetworkAPI)

Attach a new network to an ecosystem (e.g. L2 networks like Optimism).

Raises

ape.exceptions.NetworkError – When the network already exists.

Parameters

network_name (str) – The name of the network to add.

Returns

NetworkAPI

block_class: Type[BlockAPI]

The block class for this ecosystem.

property config

The configuration of the ecosystem. See ape.managers.config.ConfigManager for more information on plugin configurations.

Returns

ape.api.config.ConfigItem

config_manager: ConfigManager

A reference to the global config manager.

data_folder: pathlib.Path

The path to the .ape directory.

property default_network

The name of the default network in this ecosystem.

Returns

str

get_network_data(network_name: str)Dict

Get a dictionary of data about providers in the network.

NOTE: The keys are added in an opinionated order for nicely translating into yaml.

Parameters

network_name (str) – The name of the network to get provider data from.

Returns

A dictionary containing the providers in a network.

Return type

dict

name: str

The name of the ecosystem. This should be set the same name as the plugin.

network_manager: NetworkManager

A reference to the global network manager.

property networks

A dictionary of network names mapped to their API implementation.

Returns

Dict[str, NetworkAPI]

plugin_manager: pluggy.manager.PluginManager

A reference to the global plugin manager.

receipt_class: Type[ReceiptAPI]

The receipt class for this ecosystem.

request_header: str

A shareable HTTP header for network requests.

set_default_network(network_name: str)

Change the default network.

Raises

NetworkError – When the network does not exist.

Parameters

network_name (str) – The name of the default network to switch to.

transaction_types: Dict[TransactionType, Type[TransactionAPI]]

The available types of transaction API this ecosystem supports.

class ape.api.networks.NetworkAPI(name: str, ecosystem: ape.api.networks.EcosystemAPI, config_manager: ConfigManager, plugin_manager: pluggy.manager.PluginManager, data_folder: pathlib.Path, request_header: str, _default_provider: str = '')

Bases: object

A wrapper around a provider for a specific ecosystem.

property block_time

The approximate amount of time it takes for a new block to get mined to the chain. Configure in your ape-config.yaml file.

Config example:

ethereum:
  mainnet:
    block_time: 15
Returns

int

property chain_id

The ID of the blockchain.

NOTE: Unless overridden, returns same as ape.api.providers.ProviderAPI.chain_id.

Returns

int

property config

The configuration of the network. See ConfigManager for more information on plugin configurations.

config_manager: ConfigManager

A reference to the global config manager.

data_folder: pathlib.Path

The path to the .ape directory.

property default_provider

The name of the default provider.

Returns

str

ecosystem: ape.api.networks.EcosystemAPI

The ecosystem of the network.

property explorer

The block-explorer for the given network.

Returns

ape.api.explorers.ExplorerAPI, optional

get_provider(provider_name: Optional[str] = None, provider_settings: Optional[dict] = None)

Get a provider for the given name. If given None, returns the default provider.

Parameters
  • provider_name (str, optional) – The name of the provider to get. Defaults to None. When None, returns the default provider.

  • dict (provider_settings) – Settings to apply to the provider. Defaults to None.

  • optional) – Settings to apply to the provider. Defaults to None.

Returns

ProviderAPI

name: str

The name of the network.

property network_id

The ID of the network.

NOTE: Unless overridden, returns same as chain_id.

Returns

int

plugin_manager: pluggy.manager.PluginManager

A reference to the global plugin manager.

property providers

The providers of the network, such as Infura, Alchemy, or Geth.

Returns

Dict[str, partial[ProviderAPI]]

request_header: str

A shareable network HTTP header.

property required_confirmations

The default amount of confirmations recommended to wait before considering a transaction “confirmed”. Confirmations refer to the number of blocks that have been added since the transaction’s block.

Returns

int

set_default_provider(provider_name: str)

Change the default provider.

Raises

NetworkError – When the given provider is not found.

Parameters

provider_name (str) – The name of the provider to switch to.

use_default_provider(provider_settings: Optional[Dict])ape.api.networks.ProviderContextManager

Temporarily connect and use the default provider. When entering the context, it calls method ape.api.providers.ProviderAPI.connect() and when exiting, it calls method ape.api.providers.ProviderAPI.disconnect().

NOTE: If multiple providers exist, uses whatever was “first” registered.

Usage example:

from ape import networks
mainnet = networks.ethereum.mainnet  # An instance of NetworkAPI
with mainnet.use_default_provider():
    ...
Parameters

provider_settings (dict, optional) – Settings to override the provider.

Returns

ProviderContextManager

use_provider(provider_name: str, provider_settings: Optional[dict] = None)ape.api.networks.ProviderContextManager

Use and connect to a provider in a temporary context. When entering the context, it calls method ape.api.providers.ProviderAPI.connect() and when exiting, it calls method ape.api.providers.ProviderAPI.disconnect().

Usage example:

from ape import networks

mainnet = networks.ethereum.mainnet  # An instance of NetworkAPI
with mainnet.use_provider("infura"):
    ...
Parameters
  • provider_name (str) – The name of the provider to use.

  • provider_settings (dict, optional) – Settings to apply to the provider. Defaults to None.

Returns

ape.api.networks.ProviderContextManager

class ape.api.networks.ProviderContextManager(network_manager: NetworkManager, provider: ProviderAPI)

Bases: object

A context manager for temporarily connecting to a network. When entering the context, calls the ape.api.providers.ProviderAPI.connect() method. And conversely, when exiting, calls the ape.api.providers.ProviderPAI.disconnect() method.

The method ape.api.networks.NetworkAPI.use_provider() returns an instance of this context manager.

Usage example:

from ape import networks

mainnet = networks.ethereum.mainnet  # An instance of NetworkAPI
with mainnet.use_provider("infura"):
    ...
__init__(network_manager: NetworkManager, provider: ProviderAPI)

Initialize self. See help(type(self)) for accurate signature.

ape.api.networks.create_network_type(chain_id: int, network_id: int)Type[ape.api.networks.NetworkAPI]

Easily create a ape.api.networks.NetworkAPI subclass.

Providers

class ape.api.providers.BlockAPI(gas_data: ape.api.providers.BlockGasAPI, consensus_data: ape.api.providers.BlockConsensusAPI, hash: hexbytes.main.HexBytes, number: int, parent_hash: hexbytes.main.HexBytes, size: int, timestamp: int, **kwargs)

Bases: object

An abstract class representing a block and its attributes.

abstract classmethod decode(data: Dict)ape.api.providers.BlockAPI

Decode data to a BlockAPI.

Parameters

data (dict) – A dictionary of data to decode.

Returns

BlockAPI

class ape.api.providers.BlockConsensusAPI(difficulty: Optional[int] = None, total_difficulty: Optional[int] = None, **kwargs)

Bases: object

An abstract class representing block consensus-data, such as PoW-related information regarding the block. EIP-3675.

abstract classmethod decode(data: Dict)ape.api.providers.BlockConsensusAPI

Decode data to a BlockConsensusAPI.

Parameters

data (dict) – A dictionary of data to decode.

Returns

BlockConsensusAPI

class ape.api.providers.BlockGasAPI(gas_limit: int, gas_used: int, base_fee: Optional[int] = None, **kwargs)

Bases: object

An abstract class for representing gas data for a block.

abstract classmethod decode(data: Dict)ape.api.providers.BlockGasAPI

Decode data to a BlockGasAPI.

Parameters

data (dict) – A dictionary of block-gas properties.

Returns

BlockGasAPI

class ape.api.providers.ConfirmationsProgressBar(confirmations: int)

Bases: object

A progress bar tracking the confirmations of a transaction.

property confs

The number of confirmations that have occurred.

Returns

The total number of confirmations that have occurred.

Return type

int

class ape.api.providers.ProviderAPI(name: str, network: ape.api.networks.NetworkAPI, config: ape.api.config.ConfigItem, provider_settings: dict, data_folder: pathlib.Path, request_header: str, _chain: Optional[ChainManager] = None, **kwargs)

Bases: object

An abstraction of a connection to a network in an ecosystem. Example ProviderAPI implementations include the ape-infura plugin or the ape-hardhat plugin.

property base_fee

The minimum value required to get your transaction included on the next block. Only providers that implement EIP-1559 will use this property.

Raises

NotImplementedError – When this provider does not implement EIP-1559.

abstract property chain_id

The blockchain ID. See ChainList for a comprehensive list of IDs.

config: ape.api.config.ConfigItem

The provider’s configuration.

abstract connect()

Connect a to a provider, such as start-up a process or create an HTTP connection.

data_folder: pathlib.Path

The path to the .ape directory.

abstract disconnect()

Disconnect from a provider, such as tear-down a process or quit an HTTP session.

abstract estimate_gas_cost(txn: ape.api.providers.TransactionAPI)int

Estimate the cost of gas for a transaction.

Parameters

txn (TransactionAPI) – The transaction to estimate the gas for.

Returns

The estimated cost of gas.

Return type

int

abstract property gas_price

The price for what it costs to transact (pre-EIP-1559).

abstract get_balance(address: str)int

Get the balance of an account.

Parameters

address (str) – The address of the account.

Returns

The account balance.

Return type

int

abstract get_block(block_id: Union[str, int, hexbytes.main.HexBytes, Literal[earliest, latest, pending]])ape.api.providers.BlockAPI

Get a block.

Parameters

block_id (BlockID) – The ID of the block to get. Can be "latest", "earliest", "pending", a block hash or a block number.

Returns

The block for the given ID.

Return type

BlockID

abstract get_code(address: str)bytes

Get the bytes a contract.

Parameters

address (str) – The address of the contract.

Returns

The contract byte-code.

Return type

bytes

abstract get_events(**filter_params)Iterator[dict]

Get all logs matching a given set of filter parameters.

Parameters

filter_params – Filter which logs you get.

Returns

A dictionary of events.

Return type

Iterator[dict]

abstract get_nonce(address: str)int

Get the number of times an account has transacted.

Parameters

address (str) – The address of the account.

Returns

int

abstract get_transaction(txn_hash: str)ape.api.providers.ReceiptAPI

Get the information about a transaction from a transaction hash.

Parameters

txn_hash (str) – The hash of the transaction to retrieve.

Returns

The receipt of the transaction with the given hash.

Return type

ReceiptAPI

name: str

The name of the provider (should be the plugin name).

network: ape.api.networks.NetworkAPI

A reference to the network this provider provides.

property priority_fee

A miner tip to incentivize them to include your transaction in a block.

Raises

NotImplementedError – When the provider does not implement EIP-1559 typed transactions.

provider_settings: dict

The settings for the provider, as overrides to the configuration.

request_header: str

A header to set on HTTP/RPC requests.

abstract send_call(txn: ape.api.providers.TransactionAPI)bytes

Execute a new transaction call immediately without creating a transaction on the block chain.

Parameters

txnTransactionAPI

Returns

The result of the transaction call.

Return type

str

abstract send_transaction(txn: ape.api.providers.TransactionAPI)ape.api.providers.ReceiptAPI

Send a transaction to the network.

Parameters

txn (TransactionAPI) – The transaction to send.

Returns

ReceiptAPI

abstract update_settings(new_settings: dict)

Change a provider’s setting, such as configure a new port to run on. May require a reconnect.

Parameters

new_settings (dict) – The new provider settings.

class ape.api.providers.ReceiptAPI(provider: ProviderAPI, txn_hash: str, status: ape.api.providers.TransactionStatusEnum, block_number: int, gas_used: int, gas_price: int, gas_limit: int, sender: str, receiver: str, nonce: int, logs: List[dict] = [], contract_address: Optional[str] = None, required_confirmations: int = 0, **kwargs)

Bases: object

An abstract class to represent a transaction receipt. The receipt contains information about the transaction, such as the status and required confirmations.

NOTE: Use a required_confirmations of 0 in your transaction to not wait for confirmations.

Get a receipt by making transactions in ape, such as interacting with a ape.contracts.base.ContractInstance.

await_confirmations()ape.api.providers.ReceiptAPI

Wait for a transaction to be considered confirmed.

Returns

The receipt that is now confirmed.

Return type

ReceiptAPI

abstract classmethod decode(data: dict)ape.api.providers.ReceiptAPI

Convert data to ReceiptAPI.

Parameters

data (dict) – A dictionary of Receipt properties.

Returns

ReceiptAPI

raise_for_status()

Handle provider-specific errors regarding a non-successful TransactionStatusEnum.

property ran_out_of_gas

Check if a transaction has ran out of gas and failed.

Returns

True when the transaction failed and used the same amount of gas as the given gas_limit.

Return type

bool

class ape.api.providers.TestProviderAPI(name: str, network: ape.api.networks.NetworkAPI, config: ape.api.config.ConfigItem, provider_settings: dict, data_folder: pathlib.Path, request_header: str, _chain: Optional[ChainManager] = None, **kwargs)

Bases: ape.api.providers.ProviderAPI

An API for providers that have development functionality, such as snapshotting.

abstract mine(num_blocks: int = 1)

Advance by the given number of blocks.

Parameters

num_blocks (int) – The number of blocks allotted to mine. Defaults to 1.

abstract revert(snapshot_id: Union[str, int, bytes])

Regress the current call using the given snapshot ID. Allows developers to go back to a previous state.

Parameters

snapshot_id (str) – The snapshot ID.

abstract set_timestamp(new_timestamp: int)

Change the pending timestamp.

Parameters

new_timestamp (int) – The timestamp to set.

Returns

The new timestamp.

Return type

int

abstract snapshot()Union[str, int, bytes]

Record the current state of the blockchain with intent to later call the method revert() to go back to this point. This method is for development networks only.

Returns

The snapshot ID.

Return type

SnapshotID

class ape.api.providers.TransactionAPI(chain_id: int = 0, sender: str = '', receiver: str = '', nonce: Optional[int] = None, value: int = 0, gas_limit: Optional[int] = None, data: bytes = b'', type: ape.api.providers.TransactionType = <TransactionType.STATIC: '0x00'>, required_confirmations: Optional[int] = None, signature: Optional[ape.types.signatures.TransactionSignature] = None, **kwargs)

Bases: object

An API class representing a transaction. Ecosystem plugins implement one or more of transaction APIs depending on which schemas they permit, such as typed-transactions from EIP-1559.

as_dict()dict

Create a dict representation of the transaction.

Returns

dict

abstract encode()bytes

Take this object and produce a hash to sign to submit a transaction

property max_fee

The total amount in fees willing to be spent on a transaction. Override this property as needed, such as for EIP-1559 differences.

See StaticFeeTransaction and DynamicFeeTransaction as examples.

Raises

NotImplementedError – When setting in a class that did not override the setter.

Returns

int

property total_transfer_value

The total amount of WEI that a transaction could use. Useful for determining if an account balance can afford to submit the transaction.

class ape.api.providers.TransactionStatusEnum(value)

Bases: enum.IntEnum

An Enum class representing the status of a transaction.

FAILING = 0

The transaction has failed or is in the process of failing.

NO_ERROR = 1

The transaction is successful and is confirmed or is in the process of getting confirmed.

class ape.api.providers.TransactionType(value)

Bases: enum.Enum

Transaction enumerables type constants defined by EIP-2718.

class ape.api.providers.UpstreamProvider(name: str, network: ape.api.networks.NetworkAPI, config: ape.api.config.ConfigItem, provider_settings: dict, data_folder: pathlib.Path, request_header: str, _chain: Optional[ChainManager] = None, **kwargs)

Bases: ape.api.providers.ProviderAPI

A provider that can also be set as another provider’s upstream.

abstract property connection_str

The str used by downstream providers to connect to this one. For example, the URL for HTTP-based providers.

class ape.api.providers.Web3Provider(name: str, network: ape.api.networks.NetworkAPI, config: ape.api.config.ConfigItem, provider_settings: dict, data_folder: pathlib.Path, request_header: str, _chain: Optional[ChainManager] = None, _web3: web3.main.Web3 = None, **kwargs)

Bases: ape.api.providers.ProviderAPI

A base provider mixin class that uses the [web3.py](https://web3py.readthedocs.io/en/stable/) python package.

property base_fee

The minimum value required to get your transaction included on the next block. Only providers that implement EIP-1559 will use this property.

Raises

NotImplementedError – When this provider does not implement EIP-1559.

property chain_id

The blockchain ID. See ChainList for a comprehensive list of IDs.

estimate_gas_cost(txn: ape.api.providers.TransactionAPI)int

Estimate the cost of gas for a transaction.

Parameters

txn (TransactionAPI) – The transaction to estimate the gas for.

Returns

The estimated cost of gas.

Return type

int

property gas_price

The price for what it costs to transact (pre-EIP-1559).

get_balance(address: str)int

Get the balance of an account.

Parameters

address (str) – The address of the account.

Returns

The account balance.

Return type

int

get_block(block_id: Union[str, int, hexbytes.main.HexBytes, Literal[earliest, latest, pending]])ape.api.providers.BlockAPI

Get a block.

Parameters

block_id (BlockID) – The ID of the block to get. Can be "latest", "earliest", "pending", a block hash or a block number.

Returns

The block for the given ID.

Return type

BlockID

get_code(address: str)bytes

Get the bytes a contract.

Parameters

address (str) – The address of the contract.

Returns

The contract byte-code.

Return type

bytes

get_events(**filter_params)Iterator[dict]

Get all logs matching a given set of filter parameters.

Parameters

filter_params – Filter which logs you get.

Returns

A dictionary of events.

Return type

Iterator[dict]

get_nonce(address: str)int

Get the number of times an account has transacted.

Parameters

address (str) – The address of the account.

Returns

int

get_transaction(txn_hash: str, required_confirmations: int = 0)ape.api.providers.ReceiptAPI

Get the information about a transaction from a transaction hash.

Parameters

txn_hash (str) – The hash of the transaction to retrieve.

Returns

The receipt of the transaction with the given hash.

Return type

ReceiptAPI

property priority_fee

A miner tip to incentivize them to include your transaction in a block.

Raises

NotImplementedError – When the provider does not implement EIP-1559 typed transactions.

send_call(txn: ape.api.providers.TransactionAPI)bytes

Execute a new transaction call immediately without creating a transaction on the block chain.

Parameters

txnTransactionAPI

Returns

The result of the transaction call.

Return type

str

send_transaction(txn: ape.api.providers.TransactionAPI)ape.api.providers.ReceiptAPI

Send a transaction to the network.

Parameters

txn (TransactionAPI) – The transaction to send.

Returns

ReceiptAPI

update_settings(new_settings: dict)

Change a provider’s setting, such as configure a new port to run on. May require a reconnect.

Parameters

new_settings (dict) – The new provider settings.