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

  • Don’t construct directly, use fetch_erc20_details() to read data onchain, with optional caching

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

functions

Alias for underlying Web3 contract method

name

symbol

total_supply

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.
__init__(contract, name=None, symbol=None, total_supply=None, decimals=None, extra_data=<factory>)
Parameters
Return type

None

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.

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

property chain_id: int

The EVM chain id where this token lives.

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

export()

Create a serialisable entry of this class.

Removes web3 connection and such unserialisable data.

Returns

Python dict of exported data.

Return type

dict

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

fetch_raw_balance_of(address, block_identifier='latest')

Get an address token balance.

Parameters
Returns

Raw token amount.

Return type

decimal.Decimal

property functions: web3.contract.contract.ContractFunctions

Alias for underlying Web3 contract method

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

is_stablecoin_like()

Smell test for stablecoins.

Returns

True if we think this could be a stablecoin.

Return type

bool

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