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

监听事件并更新页面数据

监听事件并更新页面数据

合约交易成功后,DApp 需要及时展示新的业务状态。本课使用 ethers v6 查询 ERC-20 历史 Transfer 日志、订阅新事件,并将事件记录与账户余额同步到浏览器页面,同时处理重复通知、异步更新和监听清理。

学习目标

  • 使用 queryFilter 查询指定区块范围内的历史事件,并通过 on 接收新事件。
  • 根据事件更新页面记录,重新读取链上余额,避免重复展示与异步覆盖。
  • 正确移除监听器,理解断线补查和链重组对页面状态的影响。

区分历史日志、实时通知与链上状态

Solidity 合约可以通过 emit 写入事件日志。例如 ERC-20 的标准转账事件:

solidity
event Transfer(address indexed from, address indexed to, uint256 value);

这是事件声明片段,依赖实现 ERC-20 的 Solidity 合约。from 和 to 是可按主题过滤的索引参数,value 表示以代币最小单位计量的数量。

ethers v6 提供两种主要访问方式:

  • contract.queryFilter(filter, fromBlock, toBlock):查询已有区块内的匹配日志,适合初始化历史记录、分页和断线补查。
  • contract.on(filter, listener):注册持续监听器,在 Provider 检测到匹配日志时执行回调,适合实时刷新页面。

事件日志说明发生过什么,但并不直接代表账户的当前余额。页面应通过 balanceOf(account) 读取余额,而不是只根据已收到的 Transfer 数量进行加减。

例如用户原有 10 个代币,发生一次转入 3 个、一次转出 2 个,正确余额为 11。如果监听器只观察转入事件并自行累加,就会错误显示 13。

ERC-20 历史日志与实时事件驱动页面更新的数据流

使用 ethers v6 查询和订阅事件

下面制作一个可运行的浏览器示例,观察 Sepolia 测试网上指定 ERC-20 合约与某个账户相关的转账,并同步展示当前余额。

准备 Node.js 20.19+ 或 22.12+、npm、可从浏览器访问且允许跨域请求的 Sepolia HTTPS RPC,以及真实部署的 ERC-20 合约地址。这里使用 Vite 创建原生 JavaScript 项目。

bash
npm create vite@latest event-ui -- --template vanilla
cd event-ui
npm install
npm install ethers@6
npm run dev

预期输出包含本地开发服务器访问地址,具体端口可能不同:

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

<PORT> 表示实际端口。打开该地址后,将项目根目录的 main.js 替换为以下完整代码。示例使用标准 ERC-20 ABI,分别过滤转入和转出事件,不要求账户拥有发送交易的私钥。

js
import {
  Contract,
  JsonRpcProvider,
  formatUnits,
  isAddress
} from 'ethers';

const abi = [
  'event Transfer(address indexed from, address indexed to, uint256 value)',
  'function balanceOf(address) view returns (uint256)',
  'function decimals() view returns (uint8)'
];

document.querySelector('#app').innerHTML = `
  <h1>ERC-20 账户事件</h1>
  <form id="config">
    <input name="rpc" placeholder="Sepolia HTTPS RPC" required>
    <input name="token" placeholder="代币合约地址" required>
    <input name="account" placeholder="观察账户地址" required>
    <button type="submit">开始监听</button>
  </form>
  <button id="stop" type="button">停止监听</button>
  <p id="status">未连接</p>
  <p id="balance">余额:--</p>
  <ol id="events"></ol>
`;

const status = document.querySelector('#status');
const balance = document.querySelector('#balance');
const list = document.querySelector('#events');
let active = null;

async function stop() {
  const old = active;
  active = null;
  if (!old) return;
  // 只移除本页面注册的回调,不影响其他模块。
  await Promise.all(
    old.filters.map((filter) => old.contract.off(filter, old.listener))
  );
  old.provider.destroy();
}

async function start(rpc, token, account) {
  await stop();
  if (!isAddress(token) || !isAddress(account)) {
    throw new Error('合约地址或账户地址无效');
  }
  const provider = new JsonRpcProvider(rpc);
  try {
    const network = await provider.getNetwork();
    if (network.chainId !== 11155111n) {
      throw new Error('RPC 必须连接 Sepolia');
    }

    const contract = new Contract(token, abi, provider);
    const decimals = Number(await contract.decimals());
    const filters = [
      contract.filters.Transfer(null, account),
      contract.filters.Transfer(account, null)
    ];
    const records = new Map();
    const session = { provider, contract, filters, listener: null, serial: 0 };
    active = session;

    function render() {
      const sorted = [...records.values()]
        .sort((a, b) => b.block - a.block || b.index - a.index)
        .slice(0, 10);
      list.replaceChildren(...sorted.map((item) => {
        const li = document.createElement('li');
        li.textContent = item.text;
        return li;
      }));
    }

    function ingest(log) {
      if (!log.args || !log.blockHash) return;
      // 相同日志可能同时命中两个过滤器或被历史查询再次返回。
      const key = `${log.blockHash}:${log.index}`;
      if (records.has(key)) return;
      const [from, to, value] = log.args;
      records.set(key, {
        block: log.blockNumber,
        index: log.index,
        text: `区块 ${log.blockNumber}:${from.slice(0, 8)} → ${to.slice(0, 8)},${formatUnits(value, decimals)}`
      });
      render();
    }

    async function refreshBalance() {
      const serial = ++session.serial;
      const raw = await contract.balanceOf(account);
      // 忽略已经失效的请求和较早返回的查询结果。
      if (active === session && serial === session.serial) {
        balance.textContent = `余额:${formatUnits(raw, decimals)}`;
      }
    }

    function showError(error) {
      if (active === session) {
        status.textContent = `读取失败:${error.shortMessage ?? error.message}`;
      }
    }

    session.listener = (_from, _to, _value, payload) => {
      if (active !== session) return;
      ingest(payload.log);
      void refreshBalance().catch(showError);
    };

    // 先订阅,再补查历史范围,降低初始化期间漏事件的风险。
    await Promise.all(filters.map((filter) => contract.on(filter, session.listener)));
    const tip = await provider.getBlockNumber();
    const fromBlock = Math.max(0, tip - 99);
    const batches = await Promise.all(
      filters.map((filter) => contract.queryFilter(filter, fromBlock, tip))
    );
    if (active !== session) return;
    for (const batch of batches) {
      for (const log of batch) ingest(log);
    }
    await refreshBalance();
    if (active === session) status.textContent = '正在监听 Sepolia';
  } catch (error) {
    if (active?.provider === provider) await stop();
    else provider.destroy();
    throw error;
  }
}

document.querySelector('#config').addEventListener('submit', async (event) => {
  event.preventDefault();
  const form = new FormData(event.currentTarget);
  status.textContent = '连接中';
  balance.textContent = '余额:--';
  list.replaceChildren();
  try {
    await start(
      String(form.get('rpc')).trim(),
      String(form.get('token')).trim(),
      String(form.get('account')).trim()
    );
  } catch (error) {
    status.textContent = `连接失败:${error.shortMessage ?? error.message}`;
  }
});

document.querySelector('#stop').addEventListener('click', async () => {
  await stop();
  status.textContent = '已停止监听';
});

window.addEventListener('pagehide', () => {
  void stop();
});

预期结果:在页面依次填入 Sepolia RPC、真实 ERC-20 合约地址和观察账户地址,点击“开始监听”,页面显示“正在监听 Sepolia”、从链上读取的余额,以及最近 100 个区块范围内最多 10 条相关转账记录。实际余额、区块高度和事件数量由链上数据决定,可能没有历史事件。

向观察账户转入代币,或者由观察账户转出代币,在交易被区块收录且 Provider 检测到事件后,最近事件列表会出现对应记录,并触发一次 balanceOf 读取。单纯启动监听不会产生新的链上交易。

处理重复通知与页面更新顺序

示例中的账户转入和转出过滤器可能同时匹配同一条事件。例如从账户 A 向账户 A 转账 5 个代币,两条过滤器都会命中,但页面应只显示一条事件,而且账户净余额不变。

ethers v6 的事件日志提供 blockNumber、blockHash、transactionHash 和 index 等信息。index 是日志在区块内的索引。同一笔交易可能产生多条 Transfer,因此不能只使用交易哈希去重。

情况 处理方式
历史查询与实时监听返回同一日志 使用 blockHash + index 判断重复
同一交易包含多条 Transfer 保留不同日志索引对应的记录
新事件先到,旧查询后完成 使用区块高度和日志索引排序展示
多次余额查询返回顺序颠倒 使用请求序号丢弃旧请求结果
页面重新进入或切换合约 清理旧监听器,并重建新会话

例如余额查询 A 开始时链上为 10,查询 B 开始后链上变成 15。假如 B 先返回 15、A 后返回 10,直接写入 DOM 会让页面倒退。示例使用递增的 serial,只接受当前会话最近一次发起的查询结果。

这里仍有一个边界:请求序号仅保证较旧的请求不会覆盖较新的请求,并不保证两个 RPC 响应使用同一链上区块。要求严格一致的业务页面,可以固定 blockTag 查询快照,并根据区块高度决定是否接受更新。

清理监听器与补查遗漏区块

contract.on 注册的是持续监听器。若页面组件每次挂载都调用 on,卸载时却没有取消,重新进入页面后可能出现同一事件重复处理、后台持续请求以及内存占用增加的问题。

ethers v6 中,on 和 off 返回 Promise,示例通过 await contract.off(filter, listener) 清理指定监听函数。不要在多个页面共用同一个 Contract 时随意调用 removeAllListeners(),否则会把其他模块注册的回调一并移除。

如果使用 React,可以将订阅放在 useEffect 中,并在清理函数中调用 off;如果使用 Vue,可以在 onMounted 中注册,在 onUnmounted 中注销。合约地址、链 ID 或观察账户发生变化时,也必须注销旧监听并重新建立过滤器。

不过,注销和重新注册监听器只能管理生命周期,不能解决网络中断期间遗漏事件的问题。生产环境需要保存同步进度并补查日志:

  1. 保存最后处理的区块高度,例如 lastProcessedBlock = 1050。
  2. 连接恢复后先读取当前最新区块,例如 latestBlock = 1080。
  3. 从 max(0, lastProcessedBlock - 12) 开始分批执行 queryFilter,一直查询到最新区块,与实时订阅结果合并去重。
  4. 如果检测到区块哈希变化或链重组,撤销受影响的旧事件记录,重新扫描受影响区间,并读取当前合约状态。
  5. 只有在日志和业务状态成功处理后,才推进持久化的同步进度。

其中回退 12 个区块是演示用策略参数,并非以太坊通用的最终确认保证。对于不能容忍回滚的业务,应根据网络最终性和产品要求选择确认策略,必要时等区块达到 finalized 状态后再视为最终记录。

部分 RPC 服务对历史日志的查询跨度或返回数量有限制。正式环境可按 500~2000 个区块一批作为初始配置,根据服务商限制缩小范围,并避免一次查询从创世区块到最新区块。WebSocket 或 HTTP 事件订阅也不应被视为可靠的永久消息队列。

验证事件更新和异常恢复

使用测试网账户和测试代币,按以下顺序完成验收:

  1. 输入有效的 Sepolia RPC 和 ERC-20 地址,确认余额显示与合约 balanceOf 的链上读取结果一致。
  2. 向观察账户转入一笔代币,确认产生一条入账日志,显示的数量已经按 decimals 换算。
  3. 从观察账户转出一笔代币,确认转出日志出现,余额随链上状态刷新。
  4. 从观察账户向自身转账,确认即使两条过滤器都匹配,也不会在页面重复显示同一日志。
  5. 点击“停止监听”,再进行一笔转账,确认页面不再接收来自旧监听器的更新。
  6. 故意使用错误链的 RPC,确认显示“RPC 必须连接 Sepolia”而不是错误地展示其他网络的数据。

还需要测试一次页面刷新或网络临时中断。刷新后,本示例会重新查询最近 100 个区块,因此能够恢复这个窗口内的事件;但超过该窗口的遗漏不会自动补齐。若项目要求完整事件历史,应实现前述持久化游标与分批补查机制。

当页面能够从历史日志恢复记录、实时展示新事件、使用链上读取值刷新余额,并在离开页面后停止旧监听时,基础事件同步功能就具备了可验证的闭环。对于资金结算、订单完成等需要强一致性的业务,还必须补充持久化进度、重组恢复和最终确认处理。

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

目录与阅读设置

阅读设置

17

记录一个想法

监听事件并更新页面数据

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

登录哪都通