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

用 ethers v6 读取合约状态

用 ethers v6 读取合约状态

DApp 显示代币余额、计数器数值或合约配置时,需要通过 RPC 调用链上的只读函数。本课使用 ethers v6 创建 BrowserProvider 和 Contract,以 Ethereum 主网 USDC 合约为例,完成钱包连接、ABI 调用、bigint 处理和页面显示,并验证整个读取过程不发送交易。

学习目标

  • 使用浏览器注入的钱包创建 BrowserProvider,并区分 Provider 与 Signer 的职责。
  • 使用最小 ABI 创建 Contract,调用 view 函数读取链上状态。
  • 正确处理 uint256 返回的 bigint,通过 formatUnits 转换为可显示的余额。

准备浏览器环境与合约 ABI

本例使用 JavaScript、Vite、ethers v6 和支持 EIP-1193 的浏览器钱包。需要提前安装 Node.js、npm 和浏览器钱包,并将钱包切换到 Ethereum 主网。只读取余额,不需要账户持有 ETH,也不需要准备 USDC。

在终端创建一个 Vanilla JavaScript 项目:

bash
npm create vite@latest ethers-read-demo -- --template vanilla
cd ethers-read-demo
npm install
npm install ethers@6
npm run dev

预期结果:Vite 启动本地开发服务器,终端显示类似下面的地址,实际端口可能不同。

text
Local: http://localhost:<PORT>/

使用浏览器打开终端显示的地址。后续修改 src/main.js,Vite 会自动更新页面。

本例选用 Ethereum 主网原生 USDC 合约,地址为 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48。USDC 使用 6 位小数,因此不能直接按 ETH 的 18 位小数格式化余额。

ABI 是前端理解合约函数签名、输入参数和返回值的描述。读取 USDC 余额只需以下三个函数,不必导入完整合约 ABI。

函数 参数 返回类型 用途
balanceOf(address) 账户地址 uint256 查询最小单位余额
decimals() 无 uint8 查询代币小数位数
symbol() 无 string 查询代币符号

这些都是只读函数。ethers 会使用 ABI 编码调用数据,再通过 RPC 发起 eth_call,最后根据 ABI 解码返回值。

创建 BrowserProvider 并完成只读调用

BrowserProvider 用来包装钱包注入的 window.ethereum 对象。它负责将 ethers 的读取请求交给钱包提供的 EIP-1193 接口。

Contract 接收三个参数:合约地址、ABI 和执行调用的 Provider。本例将 Provider 作为第三个参数,所以可以读取状态,但不需要获取 Signer。

ethers v6 浏览器合约读取的数据流

将 src/main.js 的内容替换为下面的完整示例:

js
import { BrowserProvider, Contract, formatUnits } from "ethers";

const USDC_ADDRESS = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";

const ABI = [
  "function balanceOf(address account) view returns (uint256)",
  "function decimals() view returns (uint8)",
  "function symbol() view returns (string)"
];

const app = document.querySelector("#app");
app.innerHTML = `
  <h1>USDC 余额查询</h1>
  <button id="read">连接钱包并读取余额</button>
  <pre id="result">尚未读取</pre>
`;

const result = document.querySelector("#result");

document.querySelector("#read").addEventListener("click", async () => {
  if (!window.ethereum) {
    result.textContent = "未检测到浏览器钱包";
    return;
  }

  result.textContent = "正在读取...";

  try {
    const provider = new BrowserProvider(window.ethereum);
    const network = await provider.getNetwork();

    // 示例地址属于主网,先阻止错误网络上的合约调用。
    if (network.chainId !== 1n) {
      result.textContent = "请切换到 Ethereum 主网后重新读取";
      return;
    }

    // 申请查看当前钱包账户,读取合约本身不需要签名。
    const accounts = await provider.send("eth_requestAccounts", []);
    if (accounts.length === 0) {
      throw new Error("钱包没有返回账户地址");
    }

    const account = accounts[0];
    const contract = new Contract(USDC_ADDRESS, ABI, provider);

    // 并发读取三个独立的 view 函数。
    const [rawBalance, decimals, symbol] = await Promise.all([
      contract.balanceOf(account),
      contract.decimals(),
      contract.symbol()
    ]);

    const balance = formatUnits(rawBalance, decimals);

    result.textContent =
      `账户:${account}\n` +
      `原始余额:${rawBalance.toString()}\n` +
      `显示余额:${balance} ${symbol}`;
  } catch (error) {
    result.textContent = `读取失败:${error.shortMessage ?? error.message}`;
  }
});

保存文件后,在浏览器点击“连接钱包并读取余额”。首次连接时,钱包可能弹出账户访问授权窗口。允许访问后,页面查询该账户的 USDC 余额。

这里有两个容易混淆的操作:

  • eth_requestAccounts:请求用户授权 DApp 查看账户地址,钱包可能弹窗,但这不是链上交易。
  • contract.balanceOf(account):经由 Provider 发出只读调用,RPC 查询合约状态并返回编码结果,不要求钱包签署交易。

provider.getSigner() 主要用于需要账户签名的操作;读取公开合约状态时并非必要。实际 DApp 也可以直接查询一个已知地址的余额,从而完全跳过账户授权步骤。

验证读取结果与 bigint 格式化

页面读取成功后,应显示账户地址、原始余额和格式化余额。如果当前账户的 USDC 余额为零,预期结果类似:

text
账户:<ID>
原始余额:0
显示余额:0.0 USDC

其中 <ID> 表示实际钱包地址。对于非零余额,原始余额与显示余额取决于链上实时状态,不应预设固定数值。

ethers v6 将 Solidity 的 uint256 等整数返回值解码为 JavaScript bigint。例如原始余额为 123456789n,USDC 小数位为 6,则显示余额应为 123.456789。

可以使用以下独立代码验证格式化规则:

js
import { formatUnits } from "ethers";

const rawBalance = 123456789n;
const decimals = 6n;

// 保持原始值为 bigint,仅在显示时转成十进制字符串。
console.log(typeof rawBalance);
console.log(rawBalance.toString());
console.log(formatUnits(rawBalance, decimals));

预期输出:

text
bigint
123456789
123.456789

formatUnits 返回字符串,不是浮点数。业务代码应保留 bigint 参与整数运算,在 UI 显示时再做单位转换,这样可以避免大整数精度损失。

需要注意以下边界:

  • 不要直接执行 Number(rawBalance):超过 JavaScript 安全整数范围时可能丢失精度。
  • 不要直接使用 JSON.stringify(rawBalance):原生 JSON 不支持 bigint,需要先调用 toString()。
  • 不要固定使用 formatEther() 处理代币余额:该函数按 18 位小数解释数值,USDC 实际使用 6 位。应优先读取合约的 decimals()。
  • 不要把显示字符串当成精确计算值:需要进行代币金额运算时,应继续使用原始整数,必要时通过 parseUnits() 转换输入。

例如,若将 123456789 个 USDC 最小单位错误地按 18 位小数转换,结果会变为 0.000000000123456789,与真实的 123.456789 USDC 相差巨大。

排查网络、ABI 与钱包读取异常

如果按钮点击后没有得到余额,应按照从环境到合约的顺序定位,不要先怀疑 formatUnits()。

现象 常见原因 检查与修复
未检测到浏览器钱包 没有注入 window.ethereum 确认已安装并启用兼容钱包,刷新页面
钱包授权被拒绝 用户拒绝账户访问请求 重新点击按钮,在钱包中允许连接
提示切换 Ethereum 主网 当前 chainId 不是 1 手动切换到 Ethereum Mainnet,再点击读取
BAD_DATA 或无法解码 地址无合约代码、网络错误或 ABI 不匹配 检查合约地址、chainId 和函数返回类型
CALL_EXCEPTION 合约调用执行失败 检查参数、函数是否存在及合约是否回滚
RPC 超时或请求限流 钱包 RPC 不可用或请求过于频繁 检查网络连接、切换可靠 RPC、降低查询频率
余额为零 该账户没有 USDC 检查账户是否正确,并与区块浏览器查询结果对照

还要注意:钱包在页面打开后可能发生账户或网络切换。本例是点击按钮时读取一次的最小实现,因此切换账户或网络后必须重新点击查询。正式应用应监听 EIP-1193 的 accountsChanged、chainChanged 事件,在变化时更新账户状态、重新检查网络并刷新查询结果。

完成验证后,可以将本例的 USDC 地址替换为自己部署的合约地址,同时把 ABI 改成合约实际暴露的只读函数。务必让 Provider 所连接的网络与合约部署网络一致,并让 ABI 的函数名称、参数和返回类型与链上实现匹配。更多 API 细节可参考 ethers v6 官方文档。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 ethers v6 读取合约状态

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

登录哪都通