Evm Token Decimals

affaan-m/ECC/docs/zh-CN/skills/evm-token-decimals

by affaan-mef648e01899ba3e8dc6371642deaaf64b4477775No license275K starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 4 days ago

防止跨EVM链的静默小数不匹配错误。涵盖运行时小数查找、链感知缓存、桥接代币精度漂移以及面向机器人、仪表盘和DeFi工具的安全归一化。

Instructions onlySoftware Development

AI-generated overview

Guidance for reading ERC-20 token decimals at runtime and normalizing balances safely across EVM chains.

What it does: Explains how to avoid silent decimal mismatches when reading ERC-20 balances, pricing tokens, or comparing amounts across EVM chains. It provides code patterns for querying decimals() at runtime, caching by chain ID and token address, handling non-standard tokens, and normalizing values to 18-decimal WAD precision. Examples are given in Python, Solidity, TypeScript, and a cast command.
When to use it: Use when reading ERC-20 balances, computing fiat values from on-chain amounts, comparing token quantities across multiple EVM chains, or handling bridged and wrapped assets. It suits portfolio trackers, bots, dashboards, and DeFi tooling.
Requirements: Requires an EVM RPC endpoint and, for the examples, web3.py or ethers plus a Solidity toolchain; the cast example needs Foundry. No scripts are shipped.

EVM 代币精度

静默的精度不匹配是导致余额或美元价值出现数量级偏差且不抛出错误的最常见原因之一。

适用场景

在 Python、TypeScript 或 Solidity 中读取 ERC-20 余额
根据链上余额计算法币价值
跨多条 EVM 链比较代币数量
处理跨链桥接资产
构建投资组合追踪器、机器人或聚合器

工作原理

切勿假设稳定币在所有链上使用相同的精度。在运行时查询 decimals()，按 (chain_id, token_address) 进行缓存，并使用精度安全的数学运算进行价值计算。

示例

运行时查询精度

python

from decimal import Decimalfrom web3 import Web3
ERC20_ABI = [    {"name": "decimals", "type": "function", "inputs": [],     "outputs": [{"type": "uint8"}], "stateMutability": "view"},    {"name": "balanceOf", "type": "function",     "inputs": [{"name": "account", "type": "address"}],     "outputs": [{"type": "uint256"}], "stateMutability": "view"},]
def get_token_balance(w3: Web3, token_address: str, wallet: str) -> Decimal:    contract = w3.eth.contract(        address=Web3.to_checksum_address(token_address),        abi=ERC20_ABI,    )    decimals = contract.functions.decimals().call()    raw = contract.functions.balanceOf(Web3.to_checksum_address(wallet)).call()    return Decimal(raw) / Decimal(10 ** decimals)

from decimal import Decimalfrom web3 import Web3
ERC20_ABI = [    {"name": "decimals", "type": "function", "inputs": [],     "outputs": [{"type": "uint8"}], "stateMutability": "view"},    {"name": "balanceOf", "type": "function",     "inputs": [{"name": "account", "type": "address"}],     "outputs": [{"type": "uint256"}], "stateMutability": "view"},]
def get_token_balance(w3: Web3, token_address: str, wallet: str) -> Decimal:    contract = w3.eth.contract(        address=Web3.to_checksum_address(token_address),        abi=ERC20_ABI,    )    decimals = contract.functions.decimals().call()    raw = contract.functions.balanceOf(Web3.to_checksum_address(wallet)).call()    return Decimal(raw) / Decimal(10 ** decimals)

不要硬编码 1_000_000，因为同名代币在其他链上通常有 6 位小数。

按链和代币缓存

python

from functools import lru_cache
@lru_cache(maxsize=512)def get_decimals(chain_id: int, token_address: str) -> int:    w3 = get_web3_for_chain(chain_id)    contract = w3.eth.contract(        address=Web3.to_checksum_address(token_address),        abi=ERC20_ABI,    )    return contract.functions.decimals().call()

from functools import lru_cache
@lru_cache(maxsize=512)def get_decimals(chain_id: int, token_address: str) -> int:    w3 = get_web3_for_chain(chain_id)    contract = w3.eth.contract(        address=Web3.to_checksum_address(token_address),        abi=ERC20_ABI,    )    return contract.functions.decimals().call()

防御性处理异常代币

python

try:    decimals = contract.functions.decimals().call()except Exception:    logging.warning(        "decimals() reverted on %s (chain %s), defaulting to 18",        token_address,        chain_id,    )    decimals = 18

try:    decimals = contract.functions.decimals().call()except Exception:    logging.warning(        "decimals() reverted on %s (chain %s), defaulting to 18",        token_address,        chain_id,    )    decimals = 18

记录回退值并保持可见。旧版或非标准代币仍然存在。

在 Solidity 中归一化为 18 位 WAD 精度

solidity

interface IERC20Metadata {    function decimals() external view returns (uint8);}
function normalizeToWad(address token, uint256 amount) internal view returns (uint256) {    uint8 d = IERC20Metadata(token).decimals();    if (d == 18) return amount;    if (d < 18) return amount * 10 ** (18 - d);    return amount / 10 ** (d - 18);}

interface IERC20Metadata {    function decimals() external view returns (uint8);}
function normalizeToWad(address token, uint256 amount) internal view returns (uint256) {    uint8 d = IERC20Metadata(token).decimals();    if (d == 18) return amount;    if (d < 18) return amount * 10 ** (18 - d);    return amount / 10 ** (d - 18);}

使用 ethers 的 TypeScript 示例

typescript

import { Contract, formatUnits } from 'ethers';
const ERC20_ABI = [  'function decimals() view returns (uint8)',  'function balanceOf(address) view returns (uint256)',];
async function getBalance(provider: any, tokenAddress: string, wallet: string): Promise<string> {  const token = new Contract(tokenAddress, ERC20_ABI, provider);  const [decimals, raw] = await Promise.all([    token.decimals(),    token.balanceOf(wallet),  ]);  return formatUnits(raw, decimals);}

import { Contract, formatUnits } from 'ethers';
const ERC20_ABI = [  'function decimals() view returns (uint8)',  'function balanceOf(address) view returns (uint256)',];
async function getBalance(provider: any, tokenAddress: string, wallet: string): Promise<string> {  const token = new Contract(tokenAddress, ERC20_ABI, provider);  const [decimals, raw] = await Promise.all([    token.decimals(),    token.balanceOf(wallet),  ]);  return formatUnits(raw, decimals);}

快速链上检查

规则

始终在运行时查询 decimals()
按链加代币地址进行缓存，而非按代币符号
使用 Decimal、BigInt 或等效的精确数学运算，避免使用浮点数
在跨链桥接或代币包装变更后重新查询精度
在比较或定价前，始终将内部记账归一化为一致精度

Source and attribution

Source:affaan-m/ECCindocs/zh-CN/skills/evm-token-decimalsat commitef648e0

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Evm Token Decimals

EVM 代币精度

适用场景

工作原理

示例

运行时查询精度

按链和代币缓存

防御性处理异常代币

在 Solidity 中归一化为 18 位 WAD 精度

使用 ethers 的 TypeScript 示例

快速链上检查

规则

Source and attribution

More from affaan-m/ECC

Unified Notifications Ops

Verification Loop

Ui To Vue

Unified Memory

Visa Doc Translate

Team Builder

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices