Web3 前端与合约交互

Web3 前端与合约交互 = "用 JavaScript 把用户操作翻译成区块链交易" 。

下面按完整链路、逐层拆解，给你一份"从按钮到区块"的详细导航。

---

一、总览：6 步闭环

1. 用户点击按钮
2. 前端组装交易数据（calldata）
3. 钱包签名 → 生成 SignedTx
4. 节点广播 → 网络挖矿打包
5. 链上执行合约逻辑 → 更新状态
6. 前端监听事件 / 读链回显 → UI 刷新

---

二、各层角色与工具

层级	作用	常用库 / 对象
钱包	私钥保管 + 签名	MetaMask、WalletConnect、Coinbase Wallet
前端运行时	提供 Provider / Signer	ethers.js v6、web3.js、viem
RPC 节点	广播 & 查询	Infura、Alchemy、QuickNode、本地 Hardhat
链上	执行字节码	EVM
事件日志	通知前端	ethers.on(event, handler)

---

三、最小可运行范例（React + ethers v6）

① 连接钱包 → 拿到 signer

const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []); // 弹出 MetaMask
const signer = await provider.getSigner();      // 得到可签名对象

② 创建合约实例

const pool = new ethers.Contract(
  '0xEDb4C07B6AfFb61C2A2fa22cBb30552b4F7748f4', // 代理地址
  STAKE_ABI,                                     // 逻辑 ABI
  signer                                         // 必须带签名能力
);

③ 写操作：质押 0.1 ETH

const tx = await pool.depositEth(0, { value: ethers.parseEther('0.1') });
console.log('txHash', tx.hash);
await tx.wait();           // 等待链上确认
console.log('区块号', tx.blockNumber);

④ 读操作：查询已质押

const [amountWei] = await pool.users(0, signer.address);
console.log('已质押', ethers.formatEther(amountWei), 'ETH');

⑤ 监听事件（可选）

pool.on('Staked', (user, poolId, amount, stakedAt, unlockTime) => {
  if (user === signer.address) {
    console.log('我刚质押了', ethers.formatEther(amount), 'ETH');
  }
});

---

四、交易生命周期拆解

1. 构造调用数据
   depositEth(0) → ABI 编码 → calldata = 0x441a3e70...

2. 钱包签名

   MetaMask 把 calldata + gasPrice / gasLimit / nonce / chainId 打包 → 私钥签名 → 得到 rawSignedTx

3. 广播与挖矿

   前端通过 eth_sendRawTransaction 把签名交易发给 RPC → 节点 mempool → 矿工打包 → 出块

4. EVM 执行

   节点执行合约字节码：更新 storage（_amountTotal、unclaimedRewards...）、 emit 事件日志

5. 回执与事件

   交易回执（receipt）包含：status / gasUsed / logs → 前端 await tx.wait() 拿到回执 → 解析日志 → UI 刷新

---

五、常见坑速查

现象	原因	修复
contract runner does not support sending transactions	给了 provider 没给 signer	new Contract(addr, abi, signer)
revert: Not enough unlocked stakes	锁仓期未满	等 unlockTime 或只解已解锁部分
insufficient funds	钱包 ETH 不够付 gas + value	减少金额或领测试币
gas estimation failed	参数传错/合约内部 revert	用 call 静态模拟，看 revert 信息

---

六、进阶交互模式

1. 离线签名 → 用 Wallet #signTransaction，适合后端批处理
2. EIP-712 结构化签名 → 减少误导，提高可读性
3. ** multicall ** → 把多笔只读调用打包，一次 RPC 返回
4. 事件扫描 → 用 queryFilter 拉历史日志，做分页/图表
5. Gas 策略 → EIP-1559 动态 maxFeePerGas，或手动加速取消

---

七、一句话总结

Web3 前端与合约交互 = 用 ethers/js 把用户操作编码成 calldata → 让钱包签名 → 通过 RPC 广播 → 链上执行后读回 events / storage → 刷新 UI。

掌握这一条链路，就能完成 90% 的 DApp 功能。祝你编码顺利，早日上链！