evm-token-decimals

name	evm-token-decimals
description	EVM 체인 전반의 조용한 decimal mismatch 버그를 방지합니다. 런타임 decimal 조회, 체인 인지 캐시, 브리지드 토큰 정밀도 드리프트, 봇/대시보드/DeFi 도구를 위한 안전한 정규화를 다룹니다.
origin	ECC direct-port adaptation
version	1.0.0

EVM Token Decimals

조용한 decimal mismatch는 에러 없이 잔액이나 USD 값이 자릿수 단위로 틀어지는 가장 흔한 원인 중 하나입니다.

사용 시점

• Python, TypeScript, Solidity에서 ERC-20 잔액을 읽을 때
• 온체인 잔액으로 법정화폐 값을 계산할 때
• 여러 EVM 체인의 토큰 수량을 비교할 때
• 브리지 자산을 다룰 때
• 포트폴리오 트래커, 봇, 집계기를 만들 때

동작 방식

스테이블코인이 어디서나 같은 decimals를 쓴다고 가정하지 않습니다. 런타임에 decimals()를 조회하고, (chain_id, token_address) 기준으로 캐시하며, 값 계산에는 decimal-safe 수학을 사용합니다.

예시

런타임에서 decimals 조회

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 decimals인 적이 있다고 해서 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() reverted on %s (chain %s), defaulting to 18",
        token_address,
        chain_id,
    )
    decimals = 18

fallback는 로그로 남기고 눈에 보이게 유지합니다.

Solidity에서 18-decimal 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()를 조회합니다
• symbol이 아니라 chain + token address 기준으로 캐시합니다
• float가 아니라 Decimal, BigInt, 동등한 정확한 수학을 사용합니다
• 브리지나 래퍼가 바뀌면 decimals를 다시 조회합니다
• 비교나 가격 계산 전 내부 회계를 일관되게 정규화합니다