TokenDetails

Documentation for eth_defi.token.TokenDetails Python class.

class TokenDetails

Bases: object

ERC-20 token Python presentation.

  • A helper class to work with ERC-20 tokens.

  • Read on-chain data, deal with token value decimal conversions.

  • Any field can be None for non-well-formed tokens.

  • Supports one-way pickling

Example how to get USDC details on Polygon:

usdc = fetch_erc20_details(web3, "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174")  # USDC on Polygon
formatted = f"Token {usdc.name} ({usdc.symbol}) at {usdc.address} on chain {usdc.chain_id}"
assert formatted == "Token USD Coin (PoS) (USDC) at 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 on chain 137"

Attributes summary

address

The address of this token.

address_lower

The address of this token.

chain_id

The EVM chain id where this token lives.

decimals

Number of decimals

functions

Alias for underlying Web3 contract method

name

Token name e.g.

symbol

Token symbol e.g.

total_supply

Token supply as raw units

contract

The underlying ERC-20 contract proxy class instance

extra_data

Extra metadata, e.g.

Methods summary

__init__(contract[, name, symbol, ...])

approve(to, amount)

Prepare a ERC20.approve() transaction with human-readable amount.

convert_to_decimals(raw_amount)

Convert raw token units to decimals.

convert_to_raw(decimal_amount)

Convert decimalised token amount to raw uint256.

export()

Create a serialisable entry of this class.

fetch_balance_of(address[, block_identifier])

Get an address token balance.

fetch_raw_balance_of(address[, block_identifier])

Get an address token balance.

generate_cache_key(chain_id, address)

Generate a cache key for this token.

is_stablecoin_like()

Smell test for stablecoins.

transfer(to, amount)

Prepare a ERC20.transfer() transaction with human-readable amount.
contract: web3.contract.contract.Contract

The underlying ERC-20 contract proxy class instance

name: Optional[str] = None

Token name e.g. USD Circle

symbol: Optional[str] = None

Token symbol e.g. USDC

total_supply: Optional[int] = None

Token supply as raw units

decimals: Optional[int] = None

Number of decimals

extra_data: dict[str, Any]

Extra metadata, e.g. related to caching this result

property chain_id: int

The EVM chain id where this token lives.

property address: eth_typing.evm.HexAddress

The address of this token.

See also address_lower().

property address_lower: eth_typing.evm.HexAddress

The address of this token.

Always lowercase.

property functions: web3.contract.contract.ContractFunctions

Alias for underlying Web3 contract method

convert_to_decimals(raw_amount)

Convert raw token units to decimals.

Example:

details = fetch_erc20_details(web3, token_address)
# Convert 1 wei units to edcimals
assert details.convert_to_decimals(1) == Decimal("0.0000000000000001")
Parameters

raw_amount (int) –

Return type

decimal.Decimal

convert_to_raw(decimal_amount)

Convert decimalised token amount to raw uint256.

Example:

details = fetch_erc20_details(web3, token_address)
# Convert 1.0 USDC to raw unit with 6 decimals
assert details.convert_to_raw(1) == 1_000_000
Parameters

decimal_amount (decimal.Decimal) –

Return type

int

fetch_balance_of(address, block_identifier='latest')

Get an address token balance.

Parameters
Returns

Converted to decimal using convert_to_decimal()

Return type

decimal.Decimal

transfer(to, amount)

Prepare a ERC20.transfer() transaction with human-readable amount.

Example:

another_new_depositor = web3.eth.accounts[6]
tx_hash = base_usdc.transfer(another_new_depositor, Decimal(500)).transact({"from": usdc_holder, "gas": 100_000})
assert_transaction_success_with_explanation(web3, tx_hash)
Returns

Bound contract function you need to turn to a tx

Parameters
Return type

web3.contract.contract.ContractFunction

approve(to, amount)

Prepare a ERC20.approve() transaction with human-readable amount.

Example:

usdc_amount = Decimal(9.00)
tx_hash = usdc.approve(vault.address, usdc_amount).transact({"from": depositor})
assert_transaction_success_with_explanation(web3, tx_hash)
Returns

Bound contract function you need to turn to a tx

Parameters
Return type

web3.contract.contract.ContractFunction

fetch_raw_balance_of(address, block_identifier='latest')

Get an address token balance.

Parameters
Returns

Raw token amount.

Return type

decimal.Decimal

static generate_cache_key(chain_id, address)

Generate a cache key for this token.

  • Cached by (chain, address) as a string

  • Validate the inputs before generating the key

  • Address is always lowercase

Returns

Human reaadable {chain_id}-{address}

Parameters

  • chain_id (int) –

  • address (str) –

Return type

str

export()

Create a serialisable entry of this class.

Removes web3 connection and such unserialisable data.

Returns

Python dict of exported data.

Return type

dict

is_stablecoin_like()

Smell test for stablecoins.

Returns

True if we think this could be a stablecoin.

Return type

bool

__init__(contract, name=None, symbol=None, total_supply=None, decimals=None, extra_data=<factory>)
Parameters
Return type

None