Back to Details

evm-token-decimals

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

EVM Token Decimals

EVM 代币小数精度

Silent decimal mismatches are one of the easiest ways to ship balances or USD values that are off by orders of magnitude without throwing an error.
静默小数不匹配是最容易导致余额或USD价值偏差数个数量级却不会抛出错误的问题之一。

When to Use

适用场景

  • Reading ERC-20 balances in Python, TypeScript, or Solidity
  • Calculating fiat values from on-chain balances
  • Comparing token amounts across multiple EVM chains
  • Handling bridged assets
  • Building portfolio trackers, bots, or aggregators
  • 使用Python、TypeScript或Solidity读取ERC-20余额
  • 根据链上余额计算法币价值
  • 跨多条EVM链对比代币数量
  • 处理桥接资产
  • 构建投资组合追踪器、机器人或聚合器

How It Works

实现原理

Never assume stablecoins use the same decimals everywhere. Query 
decimals()
at runtime, cache by 
(chain_id, token_address)
, and use decimal-safe math for value calculations.
永远不要假设稳定币在所有场景下都使用相同的小数位数。在运行时查询
decimals()
方法，以
(chain_id, token_address)
为键进行缓存，计算数值时使用小数安全的数学运算。

Examples

示例

Query decimals at runtime

运行时查询小数位数

python
from decimal import Decimal
from 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)
Do not hardcode 
1_000_000
because a symbol usually has 6 decimals somewhere else.
python
from decimal import Decimal
from 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位小数以外的精度。

Cache by chain and token

按链和代币缓存结果

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()
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()

Handle odd tokens defensively

防御性处理特殊代币

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
Log the fallback and keep it visible. Old or non-standard tokens still exist.
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
记录降级方案并保持其可见性，因为仍存在老旧或非标准的代币。

Normalize to 18-decimal WAD in Solidity

在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);
}
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);
}

TypeScript with ethers

基于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);
}
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);
}

Quick on-chain check

快速链上查询

bash
cast call <token_address> "decimals()(uint8)" --rpc-url <rpc>
bash
cast call <token_address> "decimals()(uint8)" --rpc-url <rpc>

Rules

规则

  • Always query 
    decimals()
    at runtime
  • Cache by chain plus token address, not symbol
  • Use 
    Decimal
    , 
    BigInt
    , or equivalent exact math, not float
  • Re-query decimals after bridging or wrapper changes
  • Normalize internal accounting consistently before comparison or pricing
  • 始终在运行时查询
    decimals()
  • 按链ID+代币地址缓存，而非代币符号
  • 使用
    Decimal
    、
    BigInt
    或等效的精确数学运算，不要用浮点数
  • 在桥接或包装代币变更后重新查询小数位数
  • 对比或定价前统一对内部记账数据做一致性归一化处理