本阶段课程
  1. EVM、合约、ABI 与状态
  2. Solidity 与本地合约测试
  3. ethers v6 与合约调用
  4. JSON-RPC、回执、事件与重组
  5. 链上索引与 GraphQL
  6. 预言机、价格来源与时效
  7. 合约权限、升级与安全验收
  8. DApp 发布、监控与重试
  9. 交易前端状态机 · 从点击到业务完成
  10. 合约发版验收 · 部署证据与角色交接
  11. 链上数据分析 · 事件、口径与数据延迟
  12. Solidity 事件实训 · 业务状态与索引字段
  13. Webhook 回调 · 签名核验、重复和乱序
  14. 事件索引表 · 原始记录、业务读模型与重建
本篇目录

阶段 03 · 第 3 / 14 课

Web3.js 与 ethers.js:从 SDK 到正确的链上交互

学习目标:理解 Provider、Signer、Contract 与单位转换,读懂旧版示例并避免混用 API。

来源说明:本篇承接原 README 的 SDK 对比主题。代码明确使用 ethers v6 API,不将 v5 示例混入。

先看一个场景

接口返回余额 1500000。你需要先确认资产精度,才能决定显示 1.5 还是其他数,再决定用只读 Provider 或 Signer。

读完试一试

把 ABI、地址、网络和单位四项都写进最小调用的输入。


1. SDK 帮你做什么

JavaScript SDK 对 JSON-RPC、ABI 编解码、账户和合约交互进行封装。它降低开发成本,但不会替你核验代币来源,也不能保证某笔交易执行成功。

比较库时应查目标版本、维护状态、类型支持、依赖和项目迁移成本。原稿固定的包大小和性能结论缺少构建条件,不适合作为通用结论;应在实际工程中测量。

2. 三个关键对象

对象 职责 常见操作
Provider 读取网络并提交 RPC 请求 查区块、余额、回执
Signer 表示能够授权交易的主体 请求签名、发送交易
Contract 按 ABI 封装指定地址的合约 读状态、编码调用、监听事件

只读 Provider 不等于有签名权限。钱包 Signer 把签名请求交给钱包处理,应用无需获取用户私钥。

3. ethers v6 的最小只读示例

在独立练习项目安装 ethers@6,并保存项目锁文件。下面是 ESM 模块函数,调用方传入可访问的 RPC 和地址,不包含默认主网写操作。

import { JsonRpcProvider, formatEther, isAddress } from "ethers";

export async function readNativeBalance(rpcUrl, address) {
  if (!isAddress(address)) throw new Error("地址格式不正确");
  const provider = new JsonRpcProvider(rpcUrl);
  try {
    const network = await provider.getNetwork();
    const balance = await provider.getBalance(address);
    return {
      chainId: network.chainId.toString(),
      balance: formatEther(balance),
    };
  } finally {
    provider.destroy();
  }
}

地址格式正确只说明编码有效,不说明属于预期收款人。返回链 ID 有助于发现 RPC 网络配置错误;在交易场景中应明确拒绝不匹配网络。

4. 连接钱包与读取代币

ethers v6 使用 BrowserProvider 包装 EIP-1193 Provider。以下函数在客户端调用;eip1193 来自用户选择的钱包,tokenAddress 应来自已核验的资产配置。

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

export async function readTokenBalance(eip1193, tokenAddress) {
  await eip1193.request({ method: "eth_requestAccounts" });
  const provider = new BrowserProvider(eip1193);
  const signer = await provider.getSigner();
  const account = await signer.getAddress();
  const abi = [
    "function balanceOf(address) view returns (uint256)",
    "function decimals() view returns (uint8)",
  ];
  const token = new Contract(tokenAddress, abi, provider);
  const [raw, decimals] = await Promise.all([
    token.balanceOf(account),
    token.decimals(),
  ]);
  return formatUnits(raw, decimals);
}

这假设合约实现了相应 ABI;部分代币可能缺失可选元数据或行为不标准。应用需要处理调用失败,不能默认所有资产都是 18 位精度。

5. 金额与交易生命周期

展示金额用字符串,链上原始金额用整数。parseUnits("1.25", 6) 得到 1250000n,适用于 6 位精度资产;不能先用浮点乘法再指望恢复精度。

写操作通常经历:连接 signer → 校验账户与链 → 模拟和检查费用 → 请求签名 → 获取交易哈希 → 等待回执 → 检查状态与业务结果。获取哈希后页面刷新,应能继续追踪,不能立即再发一笔。

授权和转账是不同合约调用,代币额度也应与业务需求匹配。事件是重要证据,但业务到账还需结合所用协议的状态与确认规则。

6. 旧代码迁移时重点查什么

ethers v5 常见写法 ethers v6 常见写法 迁移注意
ethers.providers.JsonRpcProvider JsonRpcProvider 命名空间发生变化
ethers.providers.Web3Provider BrowserProvider 面向浏览器钱包 Provider
ethers.utils.parseUnits parseUnits 工具函数导出位置变化
BigNumber 常用对象 原生 bigint 不与 number 混算,JSON 需转换
同步使用部分 signer 获取接口 await provider.getSigner() 检查异步调用链

Web3.js 本身也存在大版本变化,不能把旧版 callback 示例与其他版本初始化混在一起。Promise 并发、JSON-RPC 批量请求和 Multicall 合约是三种机制,具有不同一致性、错误和服务端限制。

7. 自测与参考答案

问题:Promise.all 读了两个余额,是否保证来自同一个区块?

答案:不保证。若需要一致快照,应显式指定同一块高或使用具备对应语义的批量读取方案。

练习:对一个 6 位精度和一个 18 位精度资产分别完成字符串金额转换,并解释为什么不应统一使用 parseEther。

8. 延伸阅读


← 返回学习导航 · 回到顶部

记录本课进度

完成练习后标记。进度保存在当前浏览器。

搜索课程