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: txn – TransactionAPI
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: txn – TransactionAPI
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.