T14 · Web3 Frontend

一个现实问题

用户点了「兑换」。

钱包弹出来，他确认了。弹窗关掉，页面上出现一个转圈的图标，文案写着「处理中」。

然后是十几秒。对一个用惯了 App 的人来说，十几秒是很长的时间——长到他会怀疑是不是卡住了，长到他会切到别的应用再切回来，长到他会再点一次那个按钮。

而这十几秒里，你的界面其实什么都不知道：

• 用户到底签了没有？他可能在钱包里点了拒绝，而你的页面还在转圈。
• 交易广播出去了，但它进内存池了吗？会不会因为手续费太低一直卡着？
• 它进区块了吗？进了区块是不是就成功了？
• 用户在钱包里点了「加速」，你手上那个交易哈希还有效吗？

任何一个问题答错，界面就会显示一个和事实不符的状态。最贵的那个错误是：交易失败了，你的界面显示成功了。

这不是一个 UI 细节。Web2 的请求要么成功要么失败，几百毫秒内有答案；链上交易有六种终局、十几秒到几分钟的中间态，而且中间态还会倒退。用画 Web2 页面的方式画它，一定会错。

思想实验

把一笔交易想成一封挂号信，而不是一次 HTTP 请求。

你把信投进邮筒。从这一刻起：

• 你手里有一张回执单号。有了它，你才能查询。没有它，你什么都做不了。
• 信在分拣中心排队。付的邮资越高排得越靠前，邮资太低可能排上好几天。
• 信被装上某一辆车了。但车还在路上，可能出事故，可能被退回来。
• 车到站了。这时候你才知道结果——而结果有两种：送达，或者送达失败并退回。

最后一点是关键，也是最反直觉的一点：「信到站了」和「信送成了」是两回事。

链上的对应关系是这样的：交易被打包进区块，只说明矿工/验证者执行了它，不说明执行成功了。一笔在执行中报错的交易，照样会被打包、照样会扣光你付的手续费，只是它在回执里标记为失败。

这件事在 T1 已经说过一次，这里要说第二次，因为它是这一行最常见的 bug：

查一笔交易成没成功，看回执的 status，不是看它在不在区块里。

还有一件挂号信没有的事：你可以用同一个单号，把这封信换成另一封。 在链上，同一个 nonce 只会有一笔交易最终上链。用户在钱包里点「加速」或「取消」，实际是用同一个 nonce 发了一笔新的交易。原来那个哈希，从此永远查不到了。

你的界面如果还在等它，就会永远转圈。

你来决定

要给这十几秒设计界面。你怎么做？

观察结果

四个选项的差别，可以归结成一句话：前三个在画页面，第四个在建模型。

画页面的做法，每多一种异常就要加一个 if，加到第五个的时候没人能说清界面到底有几种可能。建模型的做法，异常是状态机里的一个节点，加进去就完了。

把一笔交易可能的终局摊开，一共六个：

再加两条容易被忽略的规则：

用户拒签不是失败。 它应该安静地退回「空闲」，不弹错误提示。把拒签做成红色报错，会让用户觉得自己做错了事——而他只是改了主意。

「成功」也可能退回去。 链头会重组（T1 最后一个案例）。确认数不够就显示成功，重组之后这个成功是假的。所以「成功」在确认数达标之前都不是真正的终态。

建立模型

主路径是一条线：

用类型把状态写出来。语言不重要，重要的是每个状态携带的数据不同——这正是用联合类型而不是布尔标志的原因：

type TxState =
  | { kind: 'idle' }
  | { kind: 'awaitingSignature'; intent: TxIntent }
  | { kind: 'broadcast';  hash: string; nonce: number; submittedAt: number }
  | { kind: 'pending';    hash: string; nonce: number; blockNumber: number; confirmations: number }
  | { kind: 'confirmed';  hash: string; blockNumber: number; confirmations: number }
  | { kind: 'failed';     hash?: string; reason: FailureReason }
  | { kind: 'replaced';   originalHash: string; replacementHash: string; by: 'speedup' | 'cancel' | 'unknown' };

type FailureReason =
  | 'userRejected'        // 用户在钱包里拒绝了，严格说不算失败
  | 'insufficientFunds'   // 余额不够付手续费或转账金额
  | 'reverted'            // 上链了，但执行被回滚
  | 'slippage'            // 报价过期或滑点超限，属于 reverted 的一种
  | 'nonceConflict'       // nonce 被别的交易占了
  | 'dropped'             // 长时间没进区块，被内存池丢弃
  | 'unknown';

如果你用的是 isLoading、isSuccess、isError 三个布尔值，那么 isLoading && isSuccess 这种不可能的组合在类型上是合法的，而它一定会在某个分支里出现。联合类型让非法状态无法表示，这是这套设计最实际的收益。

转移表

每一条转移都是一个可以单独测试的用例：

最后两行是这张表的价值所在。状态机必须允许倒退。 只能前进的状态机在重组面前会卡死在一个错误的终态上，而用户看到的那个「成功」永远不会被纠正。

三件容易写错的事

第一，跟踪要以 nonce 为主、哈希为辅。 哈希会变（加速、取消），nonce 不会。正确的检测方式是：如果这个地址的已确认 nonce 已经超过了你这笔交易的 nonce，但你的哈希查不到回执，那就是被替换了——去找那个 nonce 上真正上链的哈希，继续跟它。

第二，等待要能被中断和恢复。 用户会刷新页面、关标签页、切设备。待跟踪的交易要持久化到本地，页面加载时把未完成的交易恢复成跟踪中。只活在内存里的状态机，刷新一次就全丢了。

第三，按钮要在「待签名」就禁用，而不是在「已广播」才禁用。 这两者之间有一个几秒的窗口，用户在这个窗口里重复点击，会产生第二次签名请求。重复提交是这个窗口的必然产物，不是小概率事件。

错误翻译表

把底层错误映射成「一句人话 + 一个动作」。表里只有三列，但第三列最重要：

两条写文案的硬规则：

• 不要在没拿到回执之前说「成功」。 「已提交」「已广播」「确认中」都可以，「成功」不行。
• 不要说「失败，请重试」然后什么也不解释。 用户重试的结果大概率是再失败一次，再扣一次手续费。

它叫什么

动手

AI Lab

第一步：
列出一笔链上交易从构造到确认可能出现的全部失败情形。
对每一种给出：触发条件、用户视角看到的现象、判断依据（具体看哪个字段）。
包括用户拒签、手续费不足、执行回滚、滑点超限、nonce 冲突、
交易被丢出内存池、交易被同 nonce 的新交易替换。

第二步：
为上面每一种写一条给普通用户看的中文提示，要求：
- 不超过 20 个字
- 说清发生了什么
- 给出一个用户现在就能做的动作
然后逐条自我审查：这条文案会不会让用户误以为交易已经成功，
或者误以为钱已经到账、已经扣掉、还能撤回？

真实案例

改一个变量

带走的问题

本章自测