智能合约与以太坊 / 系统课时
通过 ERC-20 接口读取代币余额
通过 ERC-20 接口读取代币余额
一个 DApp 要显示钱包持有多少代币,不能直接把链上整数当成用户看到的数量。本课用 ethers v6 读取 ERC-20 合约的 balanceOf 和 decimals,把最小单位余额安全转换成可展示的十进制文本,并识别网络与精度方面的常见错误。
学习目标
- 区分代币原始余额、代币精度和展示余额。
- 使用最小 ERC-20 ABI 查询指定地址的余额。
- 保留整数精度,并定位地址、网络或接口不匹配的问题。
认识查询接口与单位
ERC-20 规定 balanceOf(address) 返回一个 uint256 整数,代表该地址持有的代币最小单位数量。常见的 decimals() 返回 uint8,指定界面展示时的小数位数,但它在 ERC-20 原始规范 中属于可选元数据接口。
| 调用 | 输入 | 返回值 | 用途 |
|---|---|---|---|
balanceOf(address) |
持有者地址 | uint256 |
查询最小单位余额 |
decimals() |
无 | uint8 |
确定展示精度 |
例如原始余额为 123456789、精度为 6,展示值就是 123.456789;精度为 18 时,同样的原始余额只代表 0.000000000123456789 代币。decimals 只影响单位换算,不会修改合约中实际存储的余额。
理解 DApp 的只读调用链
读取时,DApp 使用代币合约地址和 ABI 构造调用数据,由 RPC 节点执行 eth_call,随后将 ABI 编码的返回值解码成整数。balanceOf 的参数是持有者地址,而 RPC 连接的网络和代币合约地址共同决定查到哪份余额。

两次读取不需要用户钱包授权、私钥或链上手续费;它们仍然依赖正常工作的 RPC 服务。主网与 Sepolia 的合约地址和余额不能混用。
使用 ethers v6 完成查询
准备 Node.js 20 或更新版本,以及目标网络的 HTTPS RPC 地址、ERC-20 合约地址和待查询的持有者地址。在空目录安装 ethers v6:
npm init -y
npm install ethers@6预期结果:目录中出现 package.json、package-lock.json 和已安装的 ethers 依赖;具体安装日志随 npm 版本变化。
新建 read-balance.mjs:
import { Contract, JsonRpcProvider, formatUnits, isAddress } from "ethers";
const { RPC_URL, TOKEN_ADDRESS, ACCOUNT_ADDRESS } = process.env;
if (!RPC_URL || !TOKEN_ADDRESS || !ACCOUNT_ADDRESS) {
throw new Error("请提供 RPC_URL、TOKEN_ADDRESS 和 ACCOUNT_ADDRESS");
}
if (!isAddress(TOKEN_ADDRESS) || !isAddress(ACCOUNT_ADDRESS)) {
throw new Error("代币地址或持有者地址无效");
}
const provider = new JsonRpcProvider(RPC_URL);
// 先排除地址在当前网络上根本没有合约代码的情况。
if ((await provider.getCode(TOKEN_ADDRESS)) === "0x") {
throw new Error("当前网络的代币地址没有合约代码");
}
// 只声明需要读取的方法,不必复制整个 ERC-20 ABI。
const abi = [
"function balanceOf(address account) view returns (uint256)",
"function decimals() view returns (uint8)",
];
const token = new Contract(TOKEN_ADDRESS, abi, provider);
const [raw, decimals] = await Promise.all([
token.balanceOf(ACCOUNT_ADDRESS),
token.decimals(),
]);
// 原始余额保持 bigint;formatUnits 返回精确的十进制字符串。
console.log(`raw=${raw.toString()}`);
console.log(`decimals=${decimals.toString()}`);
console.log(`balance=${formatUnits(raw, decimals)}`);预期结果:正确设置环境变量后,脚本会读取指定网络的实时余额,并输出原始单位、精度和格式化余额。用真实 RPC URL 与两种地址替换以下占位符执行:
RPC_URL="<RPC_URL>" TOKEN_ADDRESS="<TOKEN_ADDRESS>" ACCOUNT_ADDRESS="<ACCOUNT_ADDRESS>" node read-balance.mjs预期输出示例(假设链上返回原始余额 123456789、精度 6,实际数值会不同):
raw=123456789
decimals=6
balance=123.456789处理精度与异常情况
不要用 Number(raw) / 10 ** Number(decimals) 转换大额余额:JavaScript Number 对超过 9007199254740991 的整数可能丢失精度。formatUnits 返回字符串,适合直接显示;若需要金额计算,应保留 bigint 最小单位,或使用明确精度的十进制算法。
排查时按下面的顺序检查:
getCode返回0x:检查 RPC 的链是否正确,以及代币地址是否属于该链;不要误把持有者地址填成合约地址。balanceOf调用失败:检查合约是否实现该接口,地址是否正确,以及 RPC 是否正常。decimals调用失败:该元数据方法可能未实现。先保留并显示原始整数,不要擅自按18位精度换算;再向可信的项目资料确认精度。- 余额为
0:核对ACCOUNT_ADDRESS、代币合约和网络。一个地址的原生 ETH 余额与 ERC-20 余额是两种不同的数据。
如果 DApp 需要展示代币符号,可以额外查询可选的 symbol(),但代币的身份应由链 ID + 合约地址识别,不能仅凭符号判断。