y package 

classmethod from_explorer(address, as_proxy_for=None, owner=None, silent=False, persist=True)[source]

Create a new Contract instance by fetching the ABI from a block explorer.

This method is useful for interacting with contracts that are not part of the current project, as it automatically fetches the contract’s ABI from a block explorer.

Parameters:

address (str) – The address of the deployed contract.
as_proxy_for (str | None) – The address of the implementation contract if this is a proxy contract.
owner (AccountsType | None) – The account that owns this contract instance.
silent (bool) – Whether to suppress console output during the process.
persist (bool) – Whether to persist the contract data to brownie’s db for future use.

Returns:

A new Contract instance.

Return type:

async get_code(block=None)[source]

Get the bytecode of the contract at a specific block.

Parameters:: block (optional) – The block number at which to get the bytecode. Defaults to latest block.
Returns:: The bytecode of the contract at the specified block.
Return type:: HexBytes

get_method(calldata)

Parameters:: calldata (str)
Return type:: str | None

get_method_object(calldata)

Given a calldata hex string, returns a ContractMethod object.

Parameters:: calldata (str)
Return type:: _ContractMethod | None

classmethod get_solc_version(compiler_str, address)[source]

Return the solc compiler version either from the passed compiler string or try to find the latest available patch semver compiler version.

Parameters:

compiler_str (str) – The compiler string passed from the contract metadata.
address (str) – The contract address to check for.

Return type:

Version

has_method(method, return_response=False)[source]

Check if the contract has a specific method.

Parameters:

method (str) – The name of the method to check for.
return_response (optional) – If True, return the response of the method call instead of a boolean. Default False.

Returns:

A boolean indicating whether the contract has the method, or the response of the method call if return_response is True.

Return type:

async has_methods(methods, _func=<built-in function all>)[source]

Check if the contract has all the specified methods.

Parameters:

methods (List[str]) – A list of method names to check for.
_func (optional) – The function to use for combining the results (either all() or any()). Default all().

Returns:

A boolean indicating whether the contract has all the specified methods.

Return type:

info()

Display NatSpec documentation for this contract.

Return type:: None

classmethod remove_deployment(address=None, alias=None)[source]

Removes this contract from the internal deployments db with the passed address or alias.

Parameters:

address (str | None) – An address to apply
alias (str | None) – An alias to apply

Return type:

Tuple[Dict | None, Dict | None]

set_alias(alias, persist=True)[source]

Apply a unique alias this object. The alias can be used to restore the object in future sessions.

Parameters:

alias (str | None) – An alias to apply. If None, any existing alias is removed.
persist (bool)

Return type:

None

property abi: List

property alias: str | None

events: ContractEvents

A container for various event types associated with this contract.

Provides a convenient way to query contract events with minimal code.

signatures: Dict[Method, Signature]: A dictionary mapping method names to their corresponding signatures.

topics: Dict[str, str]: A dictionary mapping event names to their corresponding topics.

verified = True: True if the contract is verified on this network’s block explorer. False otherwise.

class y.contracts.ContractEvents[source]

Bases: ContractEvents

__getattr__(name)[source]

Parameters:: name (str)
Return type:: Events

__getitem__(event_name)

Parameters:: event_name (str)
Return type:: Type[BaseContractEvent]

__hasattr__(event_name)

Parameters:: event_name (str)
Return type:: bool

__init__(contract)[source]

Parameters:: contract (_DeployedContractBase)

__iter__()

Iterate over supported

Returns:: Iterable of ContractEvent
Return type:: Iterable[Type[BaseContractEvent]]

get_sequence(from_block, to_block=None, event_type=None)[source]

Returns the logs of events of type ‘event_type’ that occurred between the blocks ‘from_block’ and ‘to_block’. If ‘event_type’ is not specified, it retrieves the occurrences of all events in the contract.

Parameters:

from_block (int) – The block from which to search for events that have occurred.
to_block (int, optional) – The block on which to stop searching for events.
specified (if not)
block (it is set to the most recently mined)
None. (between the specified blocks. Defaults to)
event_type (ContractEvent, str, optional) – Type or name of the event to be searched
None.

Returns:

[list]: List of events of type ‘event_type’ that occurred between: ’from_block’ and ‘to_block’.
else:: event_logbook [dict]: Dictionary of events of the contract that occurred between ‘from_block’ and ‘to_block’.

Return type:

if ‘event_type’ is specified

listen(event_name, timeout=0)[source]

Creates a listening Coroutine object ending whenever an event matching ‘event_name’ occurs. If timeout is superior to zero and no event matching ‘event_name’ has occured, the Coroutine ends when the timeout is reached.

The Coroutine return value is an AttributeDict filled with the following fields :

‘event_data’ (AttributeDict): The event log receipt that was caught.
‘timed_out’ (bool): False if the event did not timeout, else True

If the ‘timeout’ parameter is not passed or is inferior or equal to 0, the Coroutine listens indefinitely.

Parameters:

event_name (str) – Name of the event to be listened to.
timeout (float, optional) – Timeout value in seconds. Defaults to 0.

Returns:

Awaitable object listening for the event matching ‘event_name’.

Return type:

Coroutine

subscribe(event_name, callback, delay=2.0)[source]

Subscribe to event with a name matching ‘event_name’, calling the ‘callback’ function on new occurrence giving as parameter the event log receipt.

Parameters:

event_name (str) – Name of the event to subscribe to.
callback (Callable[[AttributeDict], None]) – Function called whenever an event occurs.
delay (float, optional) – Delay between each check for new events. Defaults to 2.0.

Return type:

None

y.contracts.Contract_erc20(address)[source]

Create a Contract instance for an ERC20 token.

This function uses the standard ERC20 ABI instead of fetching the contract ABI from the block explorer.

Parameters:: address (str | HexBytes | AnyAddress | EthAddress | Contract | int) – The address of the ERC20 token.
Returns:: A Contract instance for the ERC20 token.
Return type:: Contract

y.contracts.Contract_with_erc20_fallback(address)[source]

Create a Contract instance for an address, falling back to an ERC20 token if the contract is not verified.

Parameters:: address (str | HexBytes | AnyAddress | EthAddress | Contract | int) – The address of the contract or ERC20 token.
Returns:: A Contract instance for the contract address.
Return type:: Contract

Get the build name of a contract.

Args:
address: The address of the contract. return_None_on_failure (optional): If True, return None if the build name cannot be determined instead of raising an Exception. Default False.

Returns:
The build name of the contract, or None if the build name cannot be determined and return_None_on_failure is True.

Since build_name is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
return_None_on_failure (bool)

Return type:

str

Determine the block when a contract was created using binary search. NOTE Requires access to historical state. Doesn’t account for CREATE2 or SELFDESTRUCT.

Args:
address: The address of the contract. when_no_history_return_0: If True, return 0 when no history is found instead of raising a NodeNotSynced exception. Default False.

Returns:
The block number at which the contract was created.

Raises:
exceptions.NodeNotSynced: If the node is not fully synced. ValueError: If the contract creation block cannot be determined.

Since contract_creation_block_async is an ASyncFunctionAsyncDefault, you can optionally pass sync=True or asynchronous=False to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
when_no_history_return_0 (bool)

Return type:

ASyncFunctiony.contracts.has_method(address: str | hexbytes.main.HexBytes | AnyAddress | brownie.convert.datatypes.EthAddress, method: str, return_response: bool = False) → bool | Any[source]

Checks to see if a contract has a method view method with no inputs. return_response=True will return response in bytes if response else False

Args:
address: The address of the contract. method: The name of the method to check for. return_response: If True, return the response of the method call instead of a boolean. Default False.

Returns:
A boolean indicating whether the contract has the method, or the response of the method call if return_response is True.

Since has_method is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress)
method (str)
return_response (bool)

Return type:

async y.contracts.has_methods(address, methods, _func=<built-in function all>)[source]

Checks to see if a contract has each view method (with no inputs) in methods. Pass at_least_one=True to only verify a contract has at least one of the methods.

Args:
address: The address of the contract. methods: A tuple of method names to check for. _func: The function to use for combining the results (either all() or any()).

Returns:
A boolean indicating whether the contract has all the specified methods.

Since has_methods is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
methods (Tuple[str])
_func (Callable)

Return type:

async y.contracts.probe(address, methods, block=None, return_method=False)[source]

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
methods (List[str])
block (int | BlockNumber | None)
return_method (bool)

Return type:

Any

async y.contracts.proxy_implementation(address, block)[source]

Get the implementation address for a proxy contract.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int) – The address of the proxy contract.
block (int | BlockNumber | None) – The block number at which to get the implementation address. Defaults to latest block.

Returns:

The address of the implementation contract.

Return type:

str | HexBytes | AnyAddress | EthAddress

y.convert module

y.convert.to_address(address)[source]

Parameters:: address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
Return type:: str

y.datatypes module

class y.datatypes.UsdPrice[source]

Bases: UsdValue

Represents a USD price.

__add__(value, /): Return self+value.

__bool__(): True if self else False

__eq__(value, /): Return self==value.

__floordiv__(value, /): Return self//value.

__ge__(value, /): Return self>=value.

__getattribute__(name, /): Return getattr(self, name).

__gt__(value, /): Return self>value.

__le__(value, /): Return self<=value.

__lt__(value, /): Return self<value.

__mul__(value, /): Return self*value.

__pow__(value, mod=None, /): Return pow(self, value, mod).

__radd__(value, /): Return value+self.

__str__()

Return a string representation of the USD value.

Returns:: A string formatted as a USD value with 8 decimal places.
Return type:: str

__sub__(value, /): Return self-value.

__truediv__(value, /): Return self/value.

fromhex()

Create a floating-point number from a hexadecimal string.

>>> float.fromhex('0x1.ffffp10')
2047.984375
>>> float.fromhex('-0x1p-1074')
-5e-324

hex()

Return a hexadecimal representation of a floating-point number.

>>> (-0.1).hex()
'-0x1.999999999999ap-4'
>>> 3.14159.hex()
'0x1.921f9f01b866ep+1'

class y.datatypes.UsdValue[source]

Bases: float

Represents a USD value with custom string representation.

__add__(value, /): Return self+value.

__bool__(): True if self else False

__eq__(value, /): Return self==value.

__floordiv__(value, /): Return self//value.

__ge__(value, /): Return self>=value.

__getattribute__(name, /): Return getattr(self, name).

__gt__(value, /): Return self>value.

__le__(value, /): Return self<=value.

__lt__(value, /): Return self<value.

__mul__(value, /): Return self*value.

__pow__(value, mod=None, /): Return pow(self, value, mod).

__radd__(value, /): Return value+self.

__str__()[source]

Return a string representation of the USD value.

Returns:: A string formatted as a USD value with 8 decimal places.
Return type:: str

__sub__(value, /): Return self-value.

__truediv__(value, /): Return self/value.

fromhex()

Create a floating-point number from a hexadecimal string.

>>> float.fromhex('0x1.ffffp10')
2047.984375
>>> float.fromhex('-0x1p-1074')
-5e-324

hex()

Return a hexadecimal representation of a floating-point number.

>>> (-0.1).hex()
'-0x1.999999999999ap-4'
>>> 3.14159.hex()
'0x1.921f9f01b866ep+1'

y.datatypes.Address

A union of types used to represent Ethereum addresses.

alias of str | HexBytes | AnyAddress | EthAddress

y.datatypes.AnyAddressType

A type alias representing any valid representation of an Ethereum address. This can be an Address, a Contract, or an integer.

y.datatypes.Block

A union of types used to represent block numbers as integers.

alias of int | BlockNumber

y.datatypes.Pool

A union of types representing liquidity pools.

alias of UniswapV2Pool | CurvePool

y.exceptions module

exception y.exceptions.CallReverted[source]

Bases: Exception

Raised when a contract call is reverted.

exception y.exceptions.CalldataPreparationError[source]

Bases: Exception

Raised when there’s an error in preparing calldata for a contract interaction.

exception y.exceptions.CantFetchParam[source]: Bases: Exception

exception y.exceptions.CantFindSwapPath[source]: Bases: Exception

exception y.exceptions.ContractNotVerified[source]

Bases: _ExplorerError

Raised when attempting to fetch the ABI for an unverified contract from a block explorer.

exception y.exceptions.InvalidAPIKeyError[source]

Bases: _ExplorerError

Raised when the API key for the block explorer has been rejected. This typically occurs when making requests to a block explorer API with a missing, incorrect, or banned key.

__init__(msg='')[source]

Parameters:: msg (str)

exception y.exceptions.MessedUpBrownieContract[source]

Bases: Exception

Raised when there’s an issue initialized a Brownie contract instance, typically in the compilation step.

__init__(address, *args)[source]

Parameters:: args (object)
Return type:: None

exception y.exceptions.NoProxyImplementation[source]

Bases: Exception

Raised when the implementation address of a proxy contract cannot be determined.

This may occur when trying to interact with proxy contracts that don’t follow standard patterns.

exception y.exceptions.NodeNotSynced[source]: Bases: Exception

exception y.exceptions.NonStandardERC20[source]

Bases: Exception

Raised when an ERC20 token contract is expected but the provided address is not a standard ERC20 token.

exception y.exceptions.NotABalancerV2Pool[source]

Bases: Exception

Raised when a contract is incorrectly identified as a Balancer V2 pool.

exception y.exceptions.NotAUniswapV2Pool[source]

Bases: Exception

Raised when a contract is incorrectly identified as a Uniswap V2 pool.

__init__(non_pool)[source]

Parameters:: non_pool (UniswapV2Pool)

exception y.exceptions.PriceError[source]

Bases: Exception

Raised when a queried price is not found.

__init__(logger, symbol)[source]

Parameters:

logger (Logger)
symbol (str)

exception y.exceptions.TokenError[source]

Bases: ValueError

Raised when a token contract is not the correct contract type for the desired operation.

__init__(token, desired_type, *optional_extra_args)[source]

Parameters:

token (str | HexBytes | AnyAddress | EthAddress | Contract | int)
desired_type (str)
optional_extra_args (Any)

exception y.exceptions.TokenNotFound[source]

Bases: ValueError

Raised when a specified token cannot be found in a given container.

This is usually used when searching for a token in a liquidity pool.

__init__(token, container)[source]

exception y.exceptions.UnsupportedNetwork[source]

Bases: ValueError

Raised when an operation is attempted on an unsupported blockchain network.

exception y.exceptions.yPriceMagicError[source]

Bases: ValueError

Custom exception for ypricemagic-related errors.

This exception is raised when any error occurs inside of ypricemagic. For example, if a price fails to fetch or if there are unexpected Exceptions while calculating prices.

__init__(exc, token_address, block, symbol)[source]

Parameters:

exc (Exception)
token_address (str)
block (int | None)
symbol (str)

block: The block that was queried when the error occurred.

exception: The original Exception that was raised and wrapped with the yPriceMagicError.

token: The token that caused the error.

y.exceptions.call_reverted(e)[source]

Parameters:: e (Exception)
Return type:: bool

y.exceptions.continue_if_call_reverted(e)[source]

Parameters:: e (Exception)
Return type:: None

y.exceptions.contract_not_verified(e)[source]

Parameters:: e (Exception)
Return type:: bool

y.exceptions.out_of_gas(e)[source]

Parameters:: e (Exception)
Return type:: bool

y.exceptions.reraise_excs_with_extra_context(*extra_context, after=True)[source]

Parameters:

extra_context (Any)
after (bool)

y.networks module

class y.networks.Network[source]

Bases: IntEnum

A lightweight enum that enables lookup of chainids for popular blockchain networks.

Each network is associated with its unique integer Chain ID.

__add__(value, /): Return self+value.

__and__(value, /): Return self&value.

__bool__(): True if self else False

__eq__(value, /): Return self==value.

__floordiv__(value, /): Return self//value.

__ge__(value, /): Return self>=value.

__getattribute__(name, /): Return getattr(self, name).

__gt__(value, /): Return self>value.

__index__(): Return self converted to an integer, if self is suitable for use as an index into a list.

__invert__(): ~self

__le__(value, /): Return self<=value.

__lshift__(value, /): Return self<<value.

__lt__(value, /): Return self<value.

__mul__(value, /): Return self*value.

__or__(value, /): Return self|value.

__pow__(value, mod=None, /): Return pow(self, value, mod).

__radd__(value, /): Return value+self.

__rand__(value, /): Return value&self.

__rlshift__(value, /): Return value<<self.

__ror__(value, /): Return value|self.

__rrshift__(value, /): Return value>>self.

__rshift__(value, /): Return self>>value.

__rxor__(value, /): Return value^self.

__sizeof__(): Returns size in memory, in bytes.

__sub__(value, /): Return self-value.

__truediv__(value, /): Return self/value.

__xor__(value, /): Return self^value.

from_bytes(byteorder, *, signed=False)

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Indicates whether two’s complement is used to represent the integer.

static label(chain_id=None)[source]

Parameters:: chain_id (int | None)
Return type:: str

static name(chain_id=None)[source]

Parameters:: chain_id (int | None)
Return type:: str

static printable(chain_id=None)[source]

Parameters:: chain_id (int | None)
Return type:: str

to_bytes(length, byteorder, *, signed=False)

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

Arbitrum = 42161: The Chain ID for Arbitrum One

Aurora = 1313161554: The Chain ID for Aurora

Avalanche = 43114: The Chain ID for Avalanche C-Chain

Base = 8453: The Chain ID for Base

BinanceSmartChain = 56: The Chain ID for Binance Smart Chain

Cronos = 25: The Chain ID for Cronos Mainnet

Fantom = 250: The Chain ID for Fantom Opera Network

Gnosis = 100: The Chain ID for xDai Chain (now Gnosis Chain)

Harmony = 1666600000: The Chain ID for Harmony Mainnet Shard 0

Heco = 128: The Chain ID for Heco

Mainnet = 1: The Chain ID for Ethereum Mainnet

Moonriver = 1285: The Chain ID for Moonriver Network

OKEx = 66: The Chain ID for OKEx Chain

Optimism = 10: The Chain ID for Optimism

Polygon = 137: The Chain ID for Polygon (formerly Matic) Network

denominator: the denominator of a rational number in lowest terms

numerator: the numerator of a rational number in lowest terms

xDai = 100: The Chain ID for xDai Chain (now Gnosis Chain)

y.time module

exception y.time.NoBlockFound[source]

Bases: Exception

Raised when no block is found for a specified timestamp because the timestamp is in the future.

__init__(timestamp)[source]

Parameters:: timestamp (UnixTimestamp | datetime)

y.time.check_node()[source]

Return type:: None

y.time.check_node_async()[source]

Return type:: None

y.time.closest_block_after_timestamp(timestamp, wait_for_block_if_needed=False)[source]

Parameters:

timestamp (UnixTimestamp | datetime)
wait_for_block_if_needed (bool)

Return type:

ASyncFunctiony.time.closest_block_after_timestamp_async(timestamp: y.time.UnixTimestamp | datetime.datetime, wait_for_block_if_needed: bool = False) → int[source]

Since closest_block_after_timestamp_async is an ASyncFunctionAsyncDefault, you can optionally pass sync=True or asynchronous=False to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await.

Parameters:

timestamp (UnixTimestamp | datetime)
wait_for_block_if_needed (bool)

Return type:

ASyncFunctiony.time.get_block_at_timestamp(timestamp: datetime.datetime) → int[source]

Since get_block_at_timestamp is an ASyncFunctionAsyncDefault, you can optionally pass sync=True or asynchronous=False to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await.

Parameters:: timestamp (datetime)
Return type:: int

ASyncFunctiony.time.get_block_timestamp_async(height: int) → int[source]

Since get_block_timestamp_async is an ASyncFunctionAsyncDefault, you can optionally pass sync=True or asynchronous=False to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await.

Parameters:: height (int)
Return type:: int

Module contents

class y.Contract[source]

Bases: Contract

Though it may look complicated, a ypricemagic Contract object is simply a brownie Contract object with a few modifications:

Contracts will not be compiled. This allows you to more quickly fetch contracts from the block explorer and prevents you from having to download and install compilers.
NOTE: You must set autofetch_sources=false in your project’s brownie-config.yaml for this to work correctly.
To each contract method, a coroutine property has been defined which allows you to make asynchronous calls which are intelligently batched in the background by dank_mids to reduce overhead.
Example:
>>> contract = Contract("0xAddress")
>>> contract.methodName(*args, block_identifier=12345678)
1000000000000000000
>>> coro = contract.methodName.coroutine(*args, block_identifier=12345678)
>>> coro
<coroutine coroutine object at 0x12345678>
>>> contract.methodName(*args, block_identifier=12345678) == await coro
True
New methods:

has_method()

has_methods()

build_name()

get_code()

A few attributes were removed in order to minimize the size of a Contract object in memory:

ast

bytecode

coverageMap

deployedBytecode

deployedSourceMap

natspec

opcodes

pcMap

__eq__(other)

Return self==value.

Parameters:: other (object)
Return type:: bool

__getattribute__(name)[source]

Get a contract method attribute.

This method implements lazy initialization of contract methods. If a method object does not yet exist, it is created and cached.

Parameters:: name (str) – The name of the attribute to get.
Returns:: The contract method object.
Return type:: DankContractCall | DankContractTx | DankOverloadedMethod

__init__(address, owner=None, require_success=True, cache_ttl=<EnvironmentVariable[name=`YPRICEMAGIC_CONTRACT_CACHE_TTL`, type=int, default_value=3600, current_value=3600, using_default=True]>)[source]

Initialize the Contract instance.

This method sets up lazy initialization for contract methods.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
owner (AccountsType | None)
require_success (bool)
cache_ttl (int | None)

Return type:

None

__str__()

Return str(self).

Return type:: str

balance()

Returns the current ether balance of the contract, in wei.

Return type:: Wei

async build_name(return_None_on_failure=False)[source]

Get the build name of the contract.

Parameters:: return_None_on_failure (optional) – If True, return None if the build name cannot be determined instead of raising an Exception. Default False.
Returns:: The build name of the contract, or None if the build name cannot be determined and return_None_on_failure is True.
Return type:: str | None

async classmethod coroutine(address, require_success=True, cache_ttl=<EnvironmentVariable[name=`YPRICEMAGIC_CONTRACT_CACHE_TTL`, type=int, default_value=3600, current_value=3600, using_default=True]>)[source]

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
require_success (bool)
cache_ttl (int | None)

Return type:

Self

decode_input(calldata)

Decode input calldata for this contract.

Parameters:

calldata (str | bytes) – Calldata for a call to this contract

Returns:

str – Signature of the function that was called
Any – Decoded input arguments

Return type:

Tuple[str, Any]

classmethod from_abi(name, address, abi, owner=None, persist=True, cache_ttl=<EnvironmentVariable[name=`YPRICEMAGIC_CONTRACT_CACHE_TTL`, type=int, default_value=3600, current_value=3600, using_default=True]>)[source]

Create a Contract instance from an ABI.

Args:
name: The name of the contract. address: The address of the contract. abi: The ABI of the contract. owner (optional): The owner of the contract. Default None. persist (optional): If True, persist the contract in brownie’s local contract database. Default True. cache_ttl (optional): The time-to-live for the contract cache in seconds. Default set in ENVIRONMENT_VARIABLES.

Returns:
A Contract instance for the given ABI.

Since from_abi is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

name (str)
address (str)
abi (List)
owner (AccountsType | None)
persist (bool)
cache_ttl (int | None)

Return type:

Self

classmethod from_ethpm(name, manifest_uri, address=None, owner=None, persist=True)[source]

Create a new Contract instance from an ethPM manifest.

This method allows for the creation of a Contract instance using an ethPM manifest, which is a standardized format for Ethereum smart contract packages.

Parameters:

name (str) – The name of the contract.
manifest_uri (str) – The URI of the ethPM manifest.
address (str | None) – The address of the deployed contract (optional).
owner (AccountsType | None) – The account that owns this contract instance.
persist (bool) – Whether to persist the contract data to brownie’s local db for future use.

Returns:

A new Contract instance.

Return type:

classmethod from_explorer(address, as_proxy_for=None, owner=None, silent=False, persist=True)[source]

Create a new Contract instance by fetching the ABI from a block explorer.

This method is useful for interacting with contracts that are not part of the current project, as it automatically fetches the contract’s ABI from a block explorer.

Parameters:

address (str) – The address of the deployed contract.
as_proxy_for (str | None) – The address of the implementation contract if this is a proxy contract.
owner (AccountsType | None) – The account that owns this contract instance.
silent (bool) – Whether to suppress console output during the process.
persist (bool) – Whether to persist the contract data to brownie’s db for future use.

Returns:

A new Contract instance.

Return type:

async get_code(block=None)[source]

Get the bytecode of the contract at a specific block.

Parameters:: block (optional) – The block number at which to get the bytecode. Defaults to latest block.
Returns:: The bytecode of the contract at the specified block.
Return type:: HexBytes

get_method(calldata)

Parameters:: calldata (str)
Return type:: str | None

get_method_object(calldata)

Given a calldata hex string, returns a ContractMethod object.

Parameters:: calldata (str)
Return type:: _ContractMethod | None

classmethod get_solc_version(compiler_str, address)[source]

Return the solc compiler version either from the passed compiler string or try to find the latest available patch semver compiler version.

Parameters:

compiler_str (str) – The compiler string passed from the contract metadata.
address (str) – The contract address to check for.

Return type:

Version

has_method(method, return_response=False)[source]

Check if the contract has a specific method.

Parameters:

method (str) – The name of the method to check for.
return_response (optional) – If True, return the response of the method call instead of a boolean. Default False.

Returns:

A boolean indicating whether the contract has the method, or the response of the method call if return_response is True.

Return type:

async has_methods(methods, _func=<built-in function all>)[source]

Check if the contract has all the specified methods.

Parameters:

methods (List[str]) – A list of method names to check for.
_func (optional) – The function to use for combining the results (either all() or any()). Default all().

Returns:

A boolean indicating whether the contract has all the specified methods.

Return type:

info()

Display NatSpec documentation for this contract.

Return type:: None

classmethod remove_deployment(address=None, alias=None)[source]

Removes this contract from the internal deployments db with the passed address or alias.

Parameters:

address (str | None) – An address to apply
alias (str | None) – An alias to apply

Return type:

Tuple[Dict | None, Dict | None]

set_alias(alias, persist=True)[source]

Apply a unique alias this object. The alias can be used to restore the object in future sessions.

Parameters:

alias (str | None) – An alias to apply. If None, any existing alias is removed.
persist (bool)

Return type:

None

property abi: List

property alias: str | None

events: ContractEvents

A container for various event types associated with this contract.

Provides a convenient way to query contract events with minimal code.

signatures: Dict[Method, Signature]: A dictionary mapping method names to their corresponding signatures.

topics: Dict[str, str]: A dictionary mapping event names to their corresponding topics.

verified = True: True if the contract is verified on this network’s block explorer. False otherwise.

class y.ERC20[source]

Bases: ContractBase

Represents an ERC20 token.

ASyncFunction_decimals(block: int | eth_typing.evm.BlockNumber | NoneType = None) → int[source]

used to fetch decimals at specific block

Since _decimals is an ASyncFunctionAsyncDefault, you can optionally pass sync=True or asynchronous=False to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await.

Parameters:: block (int | BlockNumber | None)
Return type:: int

ASyncFunction_scale(block: int | eth_typing.evm.BlockNumber | NoneType = None) → int[source]

Since _scale is an ASyncFunctionAsyncDefault, you can optionally pass sync=True or asynchronous=False to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await.

Parameters:: block (int | BlockNumber | None)
Return type:: int

__eq__(_ContractBase__o)

Return self==value.

Parameters:: _ContractBase__o (object)
Return type:: bool

__init__(address, asynchronous=False, _deploy_block=None)

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
asynchronous (bool)
_deploy_block (int | None)

Return type:

None

__str__()

Return the contract address as a string.

Returns:: The contract address as a string.
Return type:: str

__build_name__: HiddenMethodDescriptor[Self, str]

Asynchronously retrieves the property value.

Args:
instance: The instance from which the property is accessed. owner: The owner class of the property.

Returns:
The property value.

The original docstring for get() is shown below:

Asynchronously retrieves the property value.

Args:
instance: The instance from which the property is accessed. owner: The owner class of the property.

Returns:
The property value.

Parameters:

instance (I)
owner (Type[I] | None)

Return type:

T

__decimals__: HiddenMethodDescriptor[Self, int]

Asynchronously retrieves the property value.

Args:
instance: The instance from which the property is accessed. owner: The owner class of the property.

Returns:
The property value.

The original docstring for get() is shown below:

Asynchronously retrieves the property value.

Args:
instance: The instance from which the property is accessed. owner: The owner class of the property.

Returns:
The property value.

Parameters:

instance (I)
owner (Type[I] | None)

Return type:

T

__name__: HiddenMethodDescriptor[Self, str] = 'ERC20'

__scale__: HiddenMethodDescriptor[Self, int]

Asynchronously retrieves the property value.

Args:
instance: The instance from which the property is accessed. owner: The owner class of the property.

Returns:
The property value.

The original docstring for get() is shown below:

Asynchronously retrieves the property value.

Args:
instance: The instance from which the property is accessed. owner: The owner class of the property.

Returns:
The property value.

Parameters:

instance (I)
owner (Type[I] | None)

Return type:

T

__symbol__: HiddenMethodDescriptor[Self, str]

Asynchronously retrieves the property value.

Args:
instance: The instance from which the property is accessed. owner: The owner class of the property.

Returns:
The property value.

The original docstring for get() is shown below:

Asynchronously retrieves the property value.

Args:
instance: The instance from which the property is accessed. owner: The owner class of the property.

Returns:
The property value.

Parameters:

instance (I)
owner (Type[I] | None)

Return type:

T

address: str | HexBytes | AnyAddress | EthAddress: The contract address of the token.

asynchronous: bool = False

balance_of[source]

Query the balance of the token for a given address at a specific block.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int) – The address to query.
block (optional) – The block number to query. Defaults to latest block.

Returns:

The balance of the token held by address at block block.

Return type:

balance_of_readable[source]

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
block (int | BlockNumber | None)

Return type:

float

build_name

Get the contract’s build name.

Returns:: The contract’s build name.

property contract: Contract

decimals[source]

The number of decimal places for the token.

Returns:: The number of decimal places for the token.

deploy_block: ASyncBoundMethod[Self, Any, int]

Parameters:: when_no_history_return_0 (bool)
Return type:: int

has_method

Parameters:

method (str)
return_response (bool)

Return type:

name[source]

The token’s name.

Returns:: The token’s name.

price[source]

Get the price of the token in USD.

Parameters:

block (optional) – The block number to query. Defaults to latest block.
return_None_on_failure (bool) – If True, return None instead of raising a yPriceMagicError on failure.
skip_cache (bool) – If True, skip using the cache while fetching price data.
ignore_pools (Tuple[UniswapV2Pool | CurvePool, ...]) – An optional tuple of pools to ignore when calculating the price.

Returns:

The price of the token in USD, or None if return_None_on_failure is True and the price cannot be retrieved.

Raises:

yPriceMagicError – If return_None_on_failure is False and the price cannot be retrieved.

Return type:

UsdPrice | None

scale[source]

Get the scaling factor for the token.

Returns:: The scaling factor for the token.

symbol[source]

The token’s symbol.

Returns:: The token’s symbol.

total_supply[source]

Get the total supply of the token.

Parameters:: block (optional) – The block number to query. Defaults to latest block.
Returns:: The total supply of the token.
Return type:: int

total_supply_readable[source]

Get the total supply of the token scaled to a human-readable decimal.

Parameters:: block (optional) – The block number to query.
Returns:: The total supply of the token scaled to a decimal.
Return type:: float

class y.Network[source]

Bases: IntEnum

A lightweight enum that enables lookup of chainids for popular blockchain networks.

Each network is associated with its unique integer Chain ID.

__add__(value, /): Return self+value.

__and__(value, /): Return self&value.

__bool__(): True if self else False

__eq__(value, /): Return self==value.

__floordiv__(value, /): Return self//value.

__ge__(value, /): Return self>=value.

__getattribute__(name, /): Return getattr(self, name).

__gt__(value, /): Return self>value.

__index__(): Return self converted to an integer, if self is suitable for use as an index into a list.

__invert__(): ~self

__le__(value, /): Return self<=value.

__lshift__(value, /): Return self<<value.

__lt__(value, /): Return self<value.

__mul__(value, /): Return self*value.

__or__(value, /): Return self|value.

__pow__(value, mod=None, /): Return pow(self, value, mod).

__radd__(value, /): Return value+self.

__rand__(value, /): Return value&self.

__rlshift__(value, /): Return value<<self.

__ror__(value, /): Return value|self.

__rrshift__(value, /): Return value>>self.

__rshift__(value, /): Return self>>value.

__rxor__(value, /): Return value^self.

__sizeof__(): Returns size in memory, in bytes.

__sub__(value, /): Return self-value.

__truediv__(value, /): Return self/value.

__xor__(value, /): Return self^value.

from_bytes(byteorder, *, signed=False)

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Indicates whether two’s complement is used to represent the integer.

static label(chain_id=None)[source]

Parameters:: chain_id (int | None)
Return type:: str

static name(chain_id=None)[source]

Parameters:: chain_id (int | None)
Return type:: str

static printable(chain_id=None)[source]

Parameters:: chain_id (int | None)
Return type:: str

to_bytes(length, byteorder, *, signed=False)

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

Arbitrum = 42161: The Chain ID for Arbitrum One

Aurora = 1313161554: The Chain ID for Aurora

Avalanche = 43114: The Chain ID for Avalanche C-Chain

Base = 8453: The Chain ID for Base

BinanceSmartChain = 56: The Chain ID for Binance Smart Chain

Cronos = 25: The Chain ID for Cronos Mainnet

Fantom = 250: The Chain ID for Fantom Opera Network

Gnosis = 100: The Chain ID for xDai Chain (now Gnosis Chain)

Harmony = 1666600000: The Chain ID for Harmony Mainnet Shard 0

Heco = 128: The Chain ID for Heco

Mainnet = 1: The Chain ID for Ethereum Mainnet

Moonriver = 1285: The Chain ID for Moonriver Network

OKEx = 66: The Chain ID for OKEx Chain

Optimism = 10: The Chain ID for Optimism

Polygon = 137: The Chain ID for Polygon (formerly Matic) Network

denominator: the denominator of a rational number in lowest terms

numerator: the numerator of a rational number in lowest terms

xDai = 100: The Chain ID for xDai Chain (now Gnosis Chain)

Since balanceOf is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

call_address (str | HexBytes | AnyAddress | EthAddress | Contract)
input_address (str | HexBytes | AnyAddress | EthAddress | Contract)
block (int | BlockNumber | None)
return_None_on_failure (bool)

Return type:

int | None

Since check_bucket is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:: token (str | HexBytes | AnyAddress | EthAddress | Contract | int)
Return type:: str

Determine the block when a contract was created using binary search. NOTE Requires access to historical state. Doesn’t account for CREATE2 or SELFDESTRUCT.

Args:
address: The address of the contract. when_no_history_return_0: If True, return 0 when no history is found instead of raising a NodeNotSynced exception. Default False.

Returns:
The block number at which the contract was created.

Raises:
exceptions.NodeNotSynced: If the node is not fully synced. ValueError: If the contract creation block cannot be determined.

Since contract_creation_block_async is an ASyncFunctionAsyncDefault, you can optionally pass sync=True or asynchronous=False to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
when_no_history_return_0 (bool)

Return type:

ASyncFunctiony.fetch_multicall(*calls: Any, block: int | eth_typing.evm.BlockNumber | NoneType = None) → List[Any | None][source]

Since fetch_multicall is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

calls (Any)
block (int | BlockNumber | None)

Return type:

List[Any | None]

ASyncFunctiony.get_block_at_timestamp(timestamp: datetime.datetime) → int[source]

Since get_block_at_timestamp is an ASyncFunctionAsyncDefault, you can optionally pass sync=True or asynchronous=False to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await.

Parameters:: timestamp (datetime)
Return type:: int

ASyncFunctiony.get_block_timestamp_async(height: int) → int[source]

Since get_block_timestamp_async is an ASyncFunctionAsyncDefault, you can optionally pass sync=True or asynchronous=False to force it to run synchronously and return a value. Without either kwarg, it will return a coroutine for you to await.

Parameters:: height (int)
Return type:: int

ASyncFunctiony.get_price(token_address: Union[str, hexbytes.main.HexBytes, ~AnyAddress, brownie.convert.datatypes.EthAddress, brownie.network.contract.Contract, int], block: Union[int, eth_typing.evm.BlockNumber, NoneType] = None, *, fail_to_None: bool = False, skip_cache: bool = <EnvironmentVariable[name=`YPRICEMAGIC_SKIP_CACHE`, type=bool, default_value=False, current_value=False, using_default=True]>, ignore_pools: Tuple[Union[ForwardRef('UniswapV2Pool'), ForwardRef('CurvePool')], ...] = (), silent: bool = False) → y.datatypes.UsdPrice | None[source]

Get the price of a token in USD.

Args:
token_address: The address of the token to price. block (optional): The block number at which to get the price. If None, uses the latest block. fail_to_None (optional): If True, return None instead of raising a yPriceMagicError on failure. Default False. skip_cache (optional): If True, bypass the cache and fetch the price directly. Defaults to ENVS.SKIP_CACHE. ignore_pools (optional): A tuple of pool addresses to ignore when fetching the price. silent (optional): If True, suppress error logging. Default False.

Returns:
The price of the token in USD, or None if the price couldn’t be determined and fail_to_None is True.

Raises:
yPriceMagicError: If the price couldn’t be determined and fail_to_None is False.

Note:
Don’t pass an int like 123 into token_address please, that’s just silly. - ypricemagic accepts ints to allow you to pass y.get_price(0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e)

so you can save yourself some keystrokes while testing in a console

(as opposed to y.get_price(“0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e”))

Since get_price is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

token_address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
block (int | BlockNumber | None)
fail_to_None (bool)
skip_cache (bool)
ignore_pools (Tuple[UniswapV2Pool | CurvePool, ...])
silent (bool)

Return type:

UsdPrice | None

ASyncFunctiony.get_prices(token_addresses: Iterable[Union[str, hexbytes.main.HexBytes, ~AnyAddress, brownie.convert.datatypes.EthAddress, brownie.network.contract.Contract, int]], block: Union[int, eth_typing.evm.BlockNumber, NoneType] = None, *, fail_to_None: bool = False, skip_cache: bool = <EnvironmentVariable[name=`YPRICEMAGIC_SKIP_CACHE`, type=bool, default_value=False, current_value=False, using_default=True]>, silent: bool = False) → List[y.datatypes.UsdPrice | None][source]

Get prices for multiple tokens in USD.

You should use this function over get_price() where possible, it is better optimized for parallel execution.

Args:
token_addresses: An iterable of token addresses to price. block (optional): The block number at which to get the prices. Defaults to the latest block. fail_to_None (optional): If True, return None for tokens whose price couldn’t be determined. Default False. skip_cache (optional): If True, bypass the cache and fetch prices directly. Defaults to ENVS.SKIP_CACHE. silent (optional): If True, suppress progress bar and error logging. This kwarg is not currently implemented.

Returns:
A list of token prices in USD, in the same order as the input token_addresses.

Since get_prices is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

token_addresses (Iterable[str | HexBytes | AnyAddress | EthAddress | Contract | int])
block (int | BlockNumber | None)
fail_to_None (bool)
skip_cache (bool)
silent (bool)

Return type:

List[UsdPrice | None]

ASyncFunctiony.has_method(address: str | hexbytes.main.HexBytes | AnyAddress | brownie.convert.datatypes.EthAddress, method: str, return_response: bool = False) → bool | Any[source]

Checks to see if a contract has a method view method with no inputs. return_response=True will return response in bytes if response else False

Args:
address: The address of the contract. method: The name of the method to check for. return_response: If True, return the response of the method call instead of a boolean. Default False.

Returns:
A boolean indicating whether the contract has the method, or the response of the method call if return_response is True.

Since has_method is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress)
method (str)
return_response (bool)

Return type:

async y.has_methods(address, methods, _func=<built-in function all>)[source]

Checks to see if a contract has each view method (with no inputs) in methods. Pass at_least_one=True to only verify a contract has at least one of the methods.

Args:
address: The address of the contract. methods: A tuple of method names to check for. _func: The function to use for combining the results (either all() or any()).

Returns:
A boolean indicating whether the contract has all the specified methods.

Since has_methods is an ASyncFunctionSyncDefault, you can optionally pass sync=False or asynchronous=True to force it to return a coroutine. Without either kwarg, it will run synchronously.

Parameters:

address (str | HexBytes | AnyAddress | EthAddress | Contract | int)
methods (Tuple[str])
_func (Callable)

Return type: