EVM 代幣小數位數

EVM 代幣小數位數 是做什麼的？

靜默的小數位數不匹配是導致餘額或美元價值出現數量級錯誤而不拋出錯誤的最容易的方式之一。

何時使用

• 在 Python、TypeScript 或 Solidity 中讀取 ERC-20 餘額
• 根據鏈上餘額計算法定價值
• 跨多個 EVM 鏈比較代幣數量
• 處理跨鏈資產
• 構建投資組合追踪器、機器人或聚合器

運作方式

永遠不要假設穩定幣在各處使用相同的小數位數。在運行時查詢 decimals()，按 (chain_id, token_address) 進行快取，並在數值計算中使用小數安全的數學運算。

範例

在運行時查詢小數位數

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)

不要因為某個符號在其他地方通常有 6 位小數就硬編碼 1_000_000。

按鏈和代幣進行快取

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

防禦性地處理異常代幣

try:
    decimals = contract.functions.decimals().call()
except Exception:
    logging.warning(
        "decimals() 在 %s (鏈 %s) 上回滾，預設為 18",
        token_address,
        chain_id,
    )
    decimals = 18

記錄此回退並保持其可見。舊的或非標準的代幣仍然存在。

在 Solidity 中標準化為 18 位小數的 WAD

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

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

在鏈上快速檢查

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

規則

• 始終在運行時查詢 decimals()
• 按鏈加上代幣地址（而非符號）進行快取
• 使用 Decimal、BigInt 或等效的精確數學運算，避免使用浮點數
• 在跨鏈或包裝器變更後重新查詢小數位數
• 在比較或定價前，一致地標準化內部會計