fetcher.erc20_metas

Module for fetching and caching ERC20 tokens metadata (name, symbol, decimals).

The main class of this module is ERC20MetasService. It fetches token metadata from the preloaded cache or directly from the blockchain.

Example

from web3cat.fetcher.erc20_metas import ERC20MetasService

service = ERC20MetasService.create()
dai_meta = service.get("Dai")
# => ERC20Meta({"chainId": 1, "address": "0x6b175474e89094c44da98b954eedeac495271d0f", "name": "dai stable coin", "symbol": "dai", "decimals": 18})
usdc_meta = service.get("USDC")
# => ERC20Meta({"chainId": 1, "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "name": "usd coin", "symbol": "usdc", "decimals": 6})
weth_meta = service.get("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2")
# => ERC20Meta({"chainId": 1, "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "name": "weth", "symbol": "weth", "decimals": 18})

class web3cat.fetcher.erc20_metas.ERC20MetasService(erc20_metas_repo: ERC20MetasRepo, **kwargs)

Bases: Core

Service for fetching ERC20 tokens metadata (name, symbol, decimals).

The sole purpose of this service is to fetch ERC20 tokens metadata from web3, cache it, and read from the cache on subsequent calls.

The exact flow goes like this

Request/Response flow

            +-------------------+                     +-------+ +---------------+ +-----------------+
            | ERC20MetasService |                     | Web3  | | PreloadedData | | ERC20MetasRepo  |
            +-------------------+                     +-------+ +---------------+ +-----------------+
 -------------------  |                                   |             |                  |
 | Metadata request |-|                                   |             |                  |
 |------------------| |                                   |             |                  |
                      |                                   |             |                  |
                      | Find metadata                     |             |                  |
                      |------------------------------------------------>|                  |
                      |                                   |             |                  |
                      | If cache miss: Find metadata      |             |                  |
                      |------------------------------------------------------------------->|
                      |                                   |             |                  |
                      | If cache miss: Fetch metadata     |             |                  |
                      |---------------------------------->|             |                  |
                      |                                   |             |                  |
                      | Save metadata                     |             |                  |
                      |------------------------------------------------------------------->|
--------------------  |                                   |             |                  |
| Metadata response |-|                                   |             |                  |
|-------------------| |                                   |             |                  |
                      |                                   |             |                  |

Parameters:

• erc20_metas_repo – ERC20MetasRepo instance

• kwargs – Args for the fetcher.core.Core

static create(**kwargs) → ERC20MetasService

Create an instance of ERC20MetasService

Parameters:

kwargs – Args for the fetcher.core.Core

Returns:

An instance of ERC20MetasService

get(token: str) → web3cat.fetcher.erc20_metas.erc20_meta.ERC20Meta | None

Get metadata by token symbol or token address.

Getting token metadata by symbol only works for cached metadata. The preloaded cache is large and contains major tokens for all evm chains.

Parameters:

token – token symbol or token address

Returns:

An instance of ERC20Meta or None if not found.

clear_cache()

Delete all cached entries

class web3cat.fetcher.erc20_metas.ERC20Meta(chain_id: int, address: str, name: str, symbol: str, decimals: int, contract: Contract)

Bases: object

ERC20 token metadata (name, symbol, decimals).

Note

The convention is to use address, name and symbol in lowercase format. This is not in line with EIP55 but makes things more uniform and simpler.

chain_id: int

Ethereum chain_id

address: str

Token address (lowercase)

name: str

Token name (lowercase)

symbol: str

Token symbol (lowercase)

decimals: int

Token decimals

contract: Contract

web3.Contract for the token

static from_row(row: Tuple[int, str, str, str, int]) → ERC20Meta

Deserialize from web3cat.database row

Parameters:

row – database row

to_row() → Tuple[int, str, str, str, int]

Serialize to database row

Returns:

database row

to_dict() → Dict[str, Any]

Convert ERC20Meta to dict

static from_dict(dct: Dict[str, Any])

Create Call from dict

class web3cat.fetcher.erc20_metas.ERC20MetasRepo(rpc: Optional[str] = None, cache_path: Optional[str] = None, block_grid_step: int = 1000, w3: Optional[Web3] = None, conn: Optional[Connection] = None)

Bases: Core

Reading and writing ERC20Meta to database.

find(token: str) → web3cat.fetcher.erc20_metas.erc20_meta.ERC20Meta | None

Find a ERC20Meta.

Parameters:

token – token symbol or address

Returns:

An instance of ERC20Meta or None if not found

Examples

repo.find("DAI")
repo.find("0x6B175474E89094C44Da98b954EedeAC495271d0F")
# => same results

save(erc20_metas: List[ERC20Meta])

Save ERC20Meta to database.

Parameters:

erc20_metas – a list of ERC20Meta to save

purge()

Clear all database entries