智能合约与以太坊 / 系统课时

通过 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 连接的网络和代币合约地址共同决定查到哪份余额。

ERC-20 余额读取与精度换算的数据流

两次读取不需要用户钱包授权、私钥或链上手续费;它们仍然依赖正常工作的 RPC 服务。主网与 Sepolia 的合约地址和余额不能混用。

使用 ethers v6 完成查询

准备 Node.js 20 或更新版本,以及目标网络的 HTTPS RPC 地址、ERC-20 合约地址和待查询的持有者地址。在空目录安装 ethers v6:

bash
npm init -y
npm install ethers@6

预期结果:目录中出现 package.json、package-lock.json 和已安装的 ethers 依赖;具体安装日志随 npm 版本变化。

新建 read-balance.mjs:

js
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 与两种地址替换以下占位符执行:

bash
RPC_URL="<RPC_URL>" TOKEN_ADDRESS="<TOKEN_ADDRESS>" ACCOUNT_ADDRESS="<ACCOUNT_ADDRESS>" node read-balance.mjs

预期输出示例(假设链上返回原始余额 123456789、精度 6,实际数值会不同):

text
raw=123456789
decimals=6
balance=123.456789

处理精度与异常情况

不要用 Number(raw) / 10 ** Number(decimals) 转换大额余额:JavaScript Number 对超过 9007199254740991 的整数可能丢失精度。formatUnits 返回字符串,适合直接显示;若需要金额计算,应保留 bigint 最小单位,或使用明确精度的十进制算法。

排查时按下面的顺序检查:

  1. getCode 返回 0x:检查 RPC 的链是否正确,以及代币地址是否属于该链;不要误把持有者地址填成合约地址。
  2. balanceOf 调用失败:检查合约是否实现该接口,地址是否正确,以及 RPC 是否正常。
  3. decimals 调用失败:该元数据方法可能未实现。先保留并显示原始整数,不要擅自按 18 位精度换算;再向可信的项目资料确认精度。
  4. 余额为 0:核对 ACCOUNT_ADDRESS、代币合约和网络。一个地址的原生 ETH 余额与 ERC-20 余额是两种不同的数据。

如果 DApp 需要展示代币符号,可以额外查询可选的 symbol(),但代币的身份应由链 ID + 合约地址识别,不能仅凭符号判断。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

通过 ERC-20 接口读取代币余额

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通