token-data

Purpose

Provides the COMMON_TOKENS constant: a curated list of eight well-known ERC-20 tokens on Ethereum mainnet — USDT, USDC, DAI, WBTC, WETH, LINK, UNI, MATIC. The list is used as the default seed for TokenRegistry when constructed with preload = true (the default). Consumers that want a richer registry can construct new TokenRegistry(false) and call addToken themselves, or build on top of COMMON_TOKENS by spreading the array.

This module exists as a static export so consumers can dead-code-eliminate it when they don't need a token registry; the entries here are byte-identical to upstream so any consumer relying on the addresses or decimals keeps working.

Features

Eight well-known mainnet ERC-20s: USDT, USDC, DAI, WBTC, WETH, LINK, UNI, MATIC.
Every entry carries address, symbol, decimals, chainId (always "ethereum"), and name.
Stablecoins use 6 decimals (USDT, USDC), WBTC uses 8, the rest use 18.
Pure data export — no runtime initialisation, no side effects.
Mutable array — consumers can spread it to build their own seeded registries.

Usage: Basic

import { COMMON_TOKENS } from "@suaveplan/cryptocurrency";

const usdt = COMMON_TOKENS.find((t) => t.symbol === "USDT");
// { address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", symbol: "USDT", decimals: 6, ... }

Usage: Advanced

import {
    COMMON_TOKENS,
    type TokenInfo,
    TokenRegistry,
} from "@suaveplan/cryptocurrency";

const myTokens: TokenInfo[] = [
    ...COMMON_TOKENS,
    {
        address: "0x111111111117dC0aa78b770fA6A738034120C302",
        symbol: "1INCH",
        decimals: 18,
        chainId: "ethereum",
        name: "1inch",
    },
];

const registry = new TokenRegistry(false);
for (const token of myTokens) registry.addToken(token);

const oneInch = registry.getToken("ethereum", "0x111111111117dC0aa78b770fA6A738034120C302");

API Reference

Export	Type	Notes
`COMMON_TOKENS`	`TokenInfo[]`	8 entries; mainnet ERC-20s only

Implementation Notes

The array is const-bound but not as const — entries are mutable so callers can spread-merge their own overrides without TypeScript widening complaints.
All addresses are EIP-55-checksummed (the canonical upstream representation) — TokenRegistry.getToken normalises lookups to lowercase, so consumers can pass any casing.
Adding a new token to COMMON_TOKENS requires no other code changes — the token is automatically picked up by TokenRegistry's default preload.
The list is intentionally short. A more comprehensive registry (Uniswap token list, CoinGecko export) belongs in a downstream @suaveplan/cryptocurrency-tokens package; keeping the core curated avoids shipping a 200KB JSON blob in the universal package.
All entries are on ethereum chainId; multi-chain entries (USDC on Polygon, USDT on BSC, etc.) are deliberately out of scope for the core list — they belong to chain-specific catalogues.

2.9 KiB Raw Blame History