← COMP5565 全部讲次
L04b-5 · 第 4 周

L04b-5 receive / fallback、错误处理与事件

一笔调用匹配不到函数时谁来接,出错时 require、revert、assert 怎么整笔回滚,成功时怎样用事件把消息递给链下。

一句话版

合约和外界打交道有三个出口:没对上任何函数的调用交给 receive 或 fallback;条件不满足时用 require、revert、assert 让整次调用回滚;做成了一件事就 emit 一个事件,让链下的前端听见。

上一页 L04b-4 讲了普通函数怎么声明,这一页讲普通函数之外的这三件事。

先认识这几个词

词 白话意思
calldata 调用时附带的数据,开头 4 字节是函数选择器
receive 专门接纯转账的特殊函数
fallback 兜底函数,没匹配上任何函数时执行
revert 让当前调用失败并撤销状态改动
原子性 要么全部成功,要么当作没发生过
事件 / 日志 合约写进交易收据、给链下读的消息
topic 日志里可以被过滤检索的字段

一个类比:公司前台、保险柜和广播

receive 和 fallback 像前台:来人只送钱不说事,前台签收;说了一件公司没有的业务,前台兜底处理;公司连前台都没设,来人原路退回。

require 像保险柜的密码锁,输错一次,这次操作中所有动过的东西全部复原。事件像办公室的广播,喇叭响了,楼外的人都能录下来,但广播本身改不了任何账目。

类比在哪里失效:

  • 前台可以选择拒收,合约却有三种方式会被强行塞钱进来,后面会讲。
  • 广播的录音谁都能听,链上的合约自己反而听不到事件,日志只给链下读。

从零讲起

1. receive 与 fallback

它解决什么问题

有人直接往合约地址转账,或者调了一个合约里不存在的函数,总得有个地方处理。0.6.0 起 Solidity 用两个特殊函数分工处理这两种情况。

直觉

唯一的分叉点是 calldata 空不空。空的就是纯转账,先找 receive;不空就按开头 4 字节找函数,找不到交给 fallback。两个都必须是 external,不能有参数和返回值;receive 必须 payable,fallback 想收钱也要标 payable。

一步一步看

目标:跟着一笔调用走分派流程,看出 calldata 空与不空、函数匹配不上时,分别落到 receive、fallback 还是回滚。

  1. 一笔调用到达合约,先看 calldata 是否为空。

  2. 为空且有 receive(),执行 receive。

  3. 为空但没有 receive,有 payable 的 fallback() 就执行它,都没有就抛异常,钱退回。

  4. 不为空,拿前 4 字节去匹配函数选择器,匹配上就执行那个函数。

  5. 匹配不上,有 fallback 就执行它,没有就抛异常。

    receive 与 fallback 的分派决策图:一笔调用先判断 calldata 是否为空,空则优先走 receive、没有再走 payable fallback,非空则按函数选择器匹配,匹配不上走 fallback,都没有就回滚

怎么判断

问「这笔钱能不能打进这个合约」:纯转账要求有 receive 或 payable fallback;带数据调用要求目标函数是 payable,或者没匹配上时 fallback 是 payable。EOA 永远能收钱,合约必须主动声明愿意收。

常见误解

「Faucet 里空的 receive 什么都没做,可以删掉」对吗?

不能删。它的存在本身就是「允许收钱」的开关,删掉后别人直接转账会失败。

「没写 receive 和 payable fallback 的合约,余额永远不会增加」对吗?

不对。有三种方式能强制塞钱:别的合约 selfdestruct 把余额转给它;部署前就往那个地址打钱;把它设成出块奖励的接收者。所以不要用 address(this).balance == 某个精确值 做判断。

试一下

合约只有 fallback() external {}(没 payable),有人往它纯转账 1 ether,会怎样?

没有 receive,fallback 又不收钱,抛异常,钱退回。

2. 错误处理三件套

它解决什么问题

调用者可能传错参数、余额可能不够、代码可能有 bug。出错时必须保证状态不会停在半截,否则账就乱了。

直觉

Solidity 用状态回滚异常处理错误:一出错,当前调用及其子调用里改过的状态全部撤销,就像没发生过。require 防的是用户做错了,assert 防的是代码写错了,custom error 是更省 gas 的报错方式。

一步一步看

目标:对比 require、revert、assert 三种出错方式,看出失败时撤销哪些改动,已经用掉的 gas 退不退。

  1. require(cond, "msg"):条件为假就拦住,后面的代码不执行,返回 Error(string)。

  2. revert CustomError(args):在任意分支主动失败,只返回 4 字节选择器加参数。

  3. assert(cond):检查不该为假的内部不变量,0.8.0 起失败时返回 Panic(uint256) 并退还剩余 gas。

  4. 回滚的范围:当前调用帧及其子调用的状态改动和日志全部撤销。

  5. 回滚的代价:已经用掉的 gas 不退,剩余 gas 退回。

    require、revert、assert 对照表:require 检查输入权限余额并返回 Error string,revert 自定义错误在任意分支主动失败只返回 4 字节选择器加参数且该行被青绿框出,assert 检查不该发生的内部错误并返回 Panic

下面这张图说明回滚是「整次」的:

一次调用中先改余额再发事件,随后 require 失败并被青绿高亮,最终余额改动和事件都被撤销不留痕迹,只扣已用掉的 gas

怎么判断

拿到一个检查条件,问:它会不会因为用户输入正常地失败?会,就用 require 或 custom error;不会,失败就说明我的代码有 bug,用 assert。想省部署成本、又想把出错时的具体数值告诉调用者,就用 custom error。

常见误解

「require 不写消息也一样」对吗?

不写消息时,钱包和浏览器只显示一句 execution reverted,用户不知道错在哪。课件最佳实践要求写有用的错误消息。代价是字符串编译进字节码,增加部署成本,这正是 custom error 要解决的。

「子调用失败一定让整笔交易失败」对吗?

不一定。异常一直传到最外层才撤销整笔交易;外层用低层调用或 try/catch 接住失败,可以保留自己的其他操作。

试一下

require(this.balance >= amount, "...") 在 0.8 下能编译吗?

不能。要写 address(this).balance,this.balance 是 0.5.0 之前的写法。

3. 事件

它解决什么问题

合约没法主动通知任何人,前端也无法订阅「某个变量变了」。事件把消息写进交易收据的日志区,链下可以订阅和按条件检索历史;而且日志比状态变量便宜得多。

直觉

EVM 有写日志的指令 LOG0 到 LOG4,没有读日志的指令,所以事件是合约对链下的单向喇叭。每条日志有至多 4 个 topic 和一段 data:topic[0] 放事件签名的哈希,剩下 3 个给 indexed 参数,其他参数都进 data。

一步一步看

目标:从声明到 emit 走一遍 Withdrawal 事件,看出哪个参数进 topic 能按它过滤,哪个进 data 只能读。

  1. 声明:event Withdrawal(address indexed to, uint amount);

  2. 触发:在函数里写 emit Withdrawal(msg.sender, amount);

  3. topic[0] = keccak256(“Withdrawal(address,uint256)”),签名只写类型、不写参数名、不留空格。

  4. 标了 indexed 的 to 放进 topic[1],链下可以按地址过滤。

  5. 没标 indexed 的 amount 进 data 区,能读,不能按它过滤。

    事件日志结构表:topic 0 存事件签名的 keccak256,topic 1 到 3 存最多 3 个 indexed 参数并被青绿框出,可以按它过滤,data 存其余参数的 ABI 编码,不能过滤

怎么判断

想让前端按某个字段筛选日志,就把那个字段标 indexed,最多 3 个。动态类型(string、bytes)被 indexed 时,topic 里只存它的哈希,原值读不回来;要读原值就别 indexed。

常见误解

「合约可以读自己以前发的事件」对吗?

不能。EVM 没有读日志的操作码,事件只给链下用。合约要用的数据必须存在状态变量里。

「indexed 越多越好」对吗?

不对。最多 3 个,而且 indexed 的动态类型只剩哈希,原值丢了。

试一下

event Deposit(address indexed from, uint indexed amount); 一条日志有几个 topic?

3 个:签名哈希、from、amount。data 区为空。

把它们串起来

一笔调用打到合约上,先由 calldata 决定去向:匹配到函数就执行函数,没匹配上交给 fallback,纯转账交给 receive。函数执行中任何一道 require、revert、assert 没过,这次调用里改过的状态和发过的事件一起撤销,保证不会停在半截。顺利执行完,emit 出去的事件留在收据里,前端据此更新界面。

三处都用到同一套签名规则:只写类型、不写参数名、不留空格。函数选择器取哈希前 4 字节,custom error 的选择器同理,事件 topic[0] 取全部 32 字节。

课件里的坑

  • [代码写错] 余额检查的示例写成 this.balance,0.5.0 之后不合法,正确写法是 address(this).balance;同一份课件另两处写对了(p.58)
  • [只讲一半] 课件只给了 custom error 的定义语法,没给触发语法,要用 revert ErrorName(...) 触发(p.59)
  • [没讲例外] 课件说没有 receive 和 payable fallback 的合约会拒收转账,但有三种方式能强制塞钱进去(p.31)
  • [示例偏多] 示例事件把参数都标了 indexed,实际设计时只给需要过滤的字段标(p.61)

课后 10 分钟:考点复习

这 10 分钟怎么用:先默画 receive / fallback 的分派树;再默写三件套各自的用途和返回的错误类型;最后做课件例 1,练从一条真实日志反推事件结构。

必背

  1. 一笔转账进来时:calldata 为空且合约有 receive 就走 receive,否则走 payable 的 fallback,两者都没有就回滚;calldata 非空则按函数选择器匹配,匹配不上走 fallback,没有 fallback 也回滚;两者都必须是 external,receive 必须 payable。
  2. 错误处理三件套:require 校验外部输入与前置条件;assert 检查绝不应发生的内部不变量;custom error 用 revert 触发,只留 4 字节选择器,最省 gas。
  3. 状态回滚异常撤销当前调用及其子调用的全部状态改变,保证交易原子性;已消耗的 gas 不退,剩余 gas 退回。
  4. 事件的参数最多 3 个可标 indexed,因为一笔日志只有 4 个 topic,topic[0] 已被事件签名的 keccak256 哈希占用;indexed 参数可被过滤检索,非 indexed 参数放在 data 区。
  5. 签名规则三处统一(只有类型、无参数名、无空格):函数选择器取 keccak256 的前 4 字节,事件 topic[0] 取全部 32 字节。

课件例题

例 1(课件 p.63):读一条真实的事件日志

题面:事件声明为 event tokencreated(address from, address to, bytes32 name);。Remix 输出的日志里只有一个 topic:0x386fdf9fdb6a2d72611c4d57983314baf05e68bde39d45a4564e6171f7aab5fa,args.0 是 0x5B38Da6a701c568545dCfcB03FcB875f56beddC4。(1) 这个 topic 是怎么来的?(2) 为什么只有一个 topic?(3) 要是把 from 和 to 都标成 indexed,日志会变成什么样?

提示

topic[0] 永远是签名哈希;数一数声明里有几个参数标了 indexed。

解答
  1. topic 是事件签名的 keccak256 哈希:keccak256("tokencreated(address,address,bytes32)")。签名只写类型,不写参数名,逗号后没有空格。按这条规则复算的结果与课件截图一致。
  2. 三个参数都没标 indexed,所以 topics 里只有 topic[0] 这个签名哈希,三个参数值全在 data 区,显示为 args 的 0、1、2 三项。
  3. topic 变成 3 个:签名哈希加两个地址。data 里只剩 name。链下就能直接按「from 等于某地址」过滤日志。

完整例题

题面:合约 Box 只有下面这些函数。判断四笔调用各自执行哪个函数,或者是否回滚。

contract Box {
    function store(uint256 v) external {}
    receive() external payable {}
    fallback() external {}
}

(a) 纯转账 1 ether,calldata 为空;(b) 调 store(7),不带钱;(c) calldata 是 retrieve() 的选择器,不带钱;(d) calldata 是 retrieve() 的选择器,附带 1 ether。

  1. 约定:先看 calldata 空不空,再看选择器能否匹配,最后看目标函数收不收钱。
  2. (a):calldata 为空,有 receive,执行 receive,钱收下。
  3. (b):calldata 开头是 store(uint256) 的选择器,匹配成功,执行 store。没带钱,store 不是 payable 也没关系。
  4. (c):retrieve() 不在合约里,匹配失败,交给 fallback。没带钱,fallback 不是 payable 也能执行。
  5. (d):同样落到 fallback,但附带了 ether,而 fallback 没标 payable,抛异常回滚,钱退回。
  6. 反过来检查:如果把 receive 删掉,(a) 会落到 fallback,因为 fallback 不是 payable,同样回滚。
  7. 要点:判断分两层,路由由 calldata 决定,能否收钱由被路由到的那个函数是否 payable 决定。

答题格式:每笔写「calldata 空 / 非空 → 匹配结果 → 落到哪个函数 → 是否 payable → 结论」。

变式题(先自己做)

改写课件的余额检查:(1) 用 custom error 替代 require(address(this).balance >= withdraw_amount, "Insufficient balance in faucet for withdrawal request");,写出 error 声明和触发语句;(2) 说明换成 custom error 后,调用方收到的错误数据有什么不同,为什么更省 gas。

提示

custom error 用 error 声明、用 revert 触发,可以带参数。想一想原来的字符串有多长,存在哪。

判分点与答案(非官方评分标准)

判分点:① 声明和触发语法都写对;② 指出返回的是 4 字节选择器加参数;③ 指出字符串不再编译进字节码。

(1)

error InsufficientBalance(uint256 available, uint256 required);

if (address(this).balance < withdraw_amount) {
    revert InsufficientBalance(address(this).balance, withdraw_amount);
}

(2) 原来返回的是 Error(string),字符串 “Insufficient balance in faucet for withdrawal request” 有 53 个字符,要整段编译进字节码。换成 custom error 后,返回 InsufficientBalance(uint256,uint256) 签名哈希的前 4 字节加上两个参数,字节码里不再存这段字符串,部署和回滚都更省;调用方还能直接拿到当时的余额和请求额。

闪卡自测

1. 一笔带 calldata 的调用匹配不到任何函数会怎样?

交给 fallback。若合约没有定义 fallback,整笔调用回滚。calldata 为空的纯转账则优先找 receive,没有 receive 才退给 payable fallback(p.29–31)。

2. require、assert 和自定义错误各自用在什么地方?

require 校验外部输入和前置条件,是一道门;assert 检查绝不应该发生的内部不变量,触发了说明代码有 bug;自定义错误配 revert 使用,只留 4 字节选择器,最省 gas(p.55–59)。

3. 事件的参数为什么最多只能标 3 个 indexed?

一笔日志最多有 4 个 topic,其中 topic[0] 已经被事件签名的 keccak256 哈希占用,只剩 3 个位置给 indexed 参数(p.61)。

4. 合约为什么需要事件?直接读状态变量不行吗?

合约没法主动通知任何人,链下的前端也无法订阅「某个变量变了」。事件写进交易收据的日志区,链下可以按 topic 订阅和历史检索;日志的存储成本也远低于状态变量(p.60)。

5. 0.8.0 起 assert 失败和以前有什么不同?

以前用 INVALID 操作码,吃光全部 gas;0.8.0 起返回 Panic(uint256),和 revert 一样退还剩余 gas(p.59)。

6. receive 有哪些固定要求?

一个合约最多一个;必须写成 receive() external payable;不能有参数和返回值(p.30)。

下一讲

下一页 L04c-1 进入课件后半段:构造器为什么只跑一次、selfdestruct 在 Dencun 升级后还剩什么、修饰器里的 _; 是怎么展开的。

下一讲 →
L04c-1 L04c-1 合约的一头一尾:构造器、selfdestruct 与修饰器

个人整理的学习笔记,不是官方材料;数字与结论以课件和讲师为准。