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

兼容 ERC-20 非标准返回值

兼容 ERC-20 非标准返回值

同样调用 transfer,有的 ERC-20 代币返回 true,有的返回 false,还有的成功执行后不返回任何数据。如果业务合约直接使用普通接口调用,可能误判成功交易或拒绝兼容旧代币。本篇通过三种模拟代币和 Solidity 测试,验证安全转账封装的真实行为。

学习目标

  • 区分 ERC-20 转账返回 true、false 和空返回数据时的处理方式。
  • 使用 OpenZeppelin SafeERC20 封装转账,并理解成功判定的边界。
  • 编写 Foundry 测试,检查资产余额、失败回滚和会计记录的一致性。

为什么普通 ERC-20 调用不够安全

标准 ERC-20 的 transfer(address,uint256) 应返回 bool。但历史代币实现并不完全一致,调用方不能仅凭交易没有报错就认定转账成功。

代币行为 返回数据 安全封装的预期处理
正常转账并返回 true ABI 编码的布尔真值 接受
返回 false ABI 编码的布尔假值 回滚
成功转账但不返回值 空返回数据 在调用未回滚且目标存在代码时接受
代币内部执行 revert 调用失败 回滚

普通 Solidity 高级接口调用通常需要按照接口声明解码返回值。遇到不返回数据的代币时,即使代币已经执行转账,外层调用也可能因返回值解码失败而整体回滚。

反过来,只检查低级调用是否成功也不够:代币可以正常返回 false,而调用本身并未回滚。忽略这一信号就可能在资产没有转出的情况下继续更新业务账本。

SafeERC20 如何处理三种结果

以下使用 OpenZeppelin Contracts 5.x 的 SafeERC20。其 safeTransfer 对正常返回值进行检查,同时兼容执行成功但未返回数据的代币。该机制不等于验证接收方实际收到的数量。

SafeERC20 转账返回值判定流程

业务合约应使用库封装,而不是自己编写只检查低级调用成功状态的代码。

solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";

contract TokenPayout {
    using SafeERC20 for IERC20;

    // 仅演示转账兼容性,不包含资金托管和访问控制。
    function pay(IERC20 token, address recipient, uint256 amount) external {
        token.safeTransfer(recipient, amount);
    }
}

这里的 safeTransfer 从 TokenPayout 合约余额转出资产,而不是从调用者钱包扣款。部署后需要先向合约存入代币,实际支付系统还必须限制 pay 的调用权限。

验证方法是部署一个返回 true 的代币,以及一个成功转账但不返回数据的代币。两种情况下,合约有足够余额时调用都应成功;返回 false 时则必须回滚。

用 Foundry 复现三种返回值

测试环境采用 Solidity 0.8.20 及以上、Foundry 和 OpenZeppelin Contracts 5.x。以下片段可放入已初始化的 Foundry 项目。安装依赖:

bash
forge init erc20-return-lab
cd erc20-return-lab
forge install OpenZeppelin/openzeppelin-contracts@v5.0.2 --no-commit

预期结果:项目包含 lib/openzeppelin-contracts 依赖目录。forge install 的下载日志、路径和耗时随环境变化。

在项目根目录的 foundry.toml 中添加或合并以下配置,避免覆盖项目已有设置:

toml
[profile.default]
solc_version = "0.8.20"
remappings = ["@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/"]

配置生效后,导入路径 @openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol 应能正常解析。接下来把完整测试保存为 test/TokenReturn.t.sol。

solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {Test} from "forge-std/Test.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";

contract ReturnToken {
    mapping(address => uint256) public balanceOf;
    uint8 public mode;

    constructor(uint8 selectedMode) {
        mode = selectedMode;
        balanceOf[address(this)] = 100;
    }

    // 使用 selector 相同但不声明返回值的函数,模拟旧代币。
    function transfer(address to, uint256 amount) external {
        if (mode == 1) {
            assembly {
                mstore(0, 0)
                return(0, 32)
            }
        }

        require(balanceOf[msg.sender] >= amount, "balance");
        balanceOf[msg.sender] -= amount;
        balanceOf[to] += amount;

        if (mode != 2) {
            assembly {
                mstore(0, 1)
                return(0, 32)
            }
        }
        // mode 2:成功执行后不返回数据。
    }
}

contract Payout {
    using SafeERC20 for IERC20;

    uint256 public completed;

    function pay(IERC20 token, address to, uint256 amount) external {
        token.safeTransfer(to, amount);
        completed += amount; // 只有安全转账没有回滚才更新记录。
    }
}

contract TokenReturnTest is Test {
    address constant RECIPIENT = address(0xBEEF);

    function testReturnsTrue() public {
        runSuccessCase(0);
    }

    function testNoReturn() public {
        runSuccessCase(2);
    }

    function runSuccessCase(uint8 mode) internal {
        ReturnToken token = new ReturnToken(mode);
        Payout payout = new Payout();
        vm.prank(address(token));
        token.transfer(address(payout), 100);

        payout.pay(IERC20(address(token)), RECIPIENT, 30);
        assertEq(token.balanceOf(RECIPIENT), 30);
        assertEq(token.balanceOf(address(payout)), 70);
        assertEq(payout.completed(), 30);
    }

    function testReturnsFalse() public {
        ReturnToken token = new ReturnToken(1);
        Payout payout = new Payout();

        vm.expectRevert();
        payout.pay(IERC20(address(token)), RECIPIENT, 30);

        assertEq(token.balanceOf(RECIPIENT), 0);
        assertEq(payout.completed(), 0);
    }
}

这个模拟代币通过底层 assembly 返回 32 字节编码值,故意复现三类历史接口行为。mode=0 返回 true 并转账,mode=1 返回 false 且不转账,mode=2 转账后无返回值。模拟合约只用于测试,不是完整的生产 ERC-20 实现。

运行测试:

bash
forge test --match-contract TokenReturnTest

预期输出(省略编译耗时和动态路径):

text
[PASS] testNoReturn()
[PASS] testReturnsFalse()
[PASS] testReturnsTrue()
Suite result: ok. 3 passed; 0 failed

不同 Foundry 版本的日志排版可能不同,应以三条测试通过、零失败为验收标准。

返回值正确不代表结算金额正确

SafeERC20 解决的是调用和返回值兼容性,不保证代币严格按照请求金额改变余额。手续费代币、特殊转账规则代币甚至恶意代币,仍可能返回 true 却少转或不转。

例如请求支付 100 个最小单位,代币扣取 2 个单位手续费,收款方可能只收到 98。若系统直接把 completed 增加 100,就会出现实际到账金额与记录不一致。

对于要求精确到账的业务,可以在转账前后比较接收方余额变化,并明确是否允许收费型代币。用于这种场景的片段示例依赖已有的 IERC20 token、address recipient 和 uint256 amount:

solidity
uint256 beforeBalance = token.balanceOf(recipient);
token.safeTransfer(recipient, amount);
uint256 afterBalance = token.balanceOf(recipient);
require(afterBalance >= beforeBalance, "balance decreased");
require(afterBalance - beforeBalance == amount, "unexpected amount");

验证方法:普通 ERC-20 支付 100 应得到余额差 100;收款余额只增加 98 时交易应回滚。对于反射型、可重基准化等余额会发生额外变化的代币,单纯余额差也未必能证明唯一的转账来源,需要单独制定资产准入规则。

审计时怎样检查转账路径

审计支付、提现和金库合约时,按以下顺序检查,每项都应能找到对应代码或测试:

  1. 搜索所有 transfer、transferFrom、safeTransfer、safeTransferFrom 调用,识别是否有未检查返回值的底层调用。
  2. 对每个转账入口分别测试返回 true、返回 false、空返回数据和内部 revert,确认失败路径不会提交会计记录。
  3. 检查目标代币地址是否来自受控白名单,避免把无代码地址或任意恶意合约当作可信资产。
  4. 对精确到账业务测试请求 100、实际收到 98 的情况,确认余额差异常时回滚,或按明确规则记录实收数量。
  5. 对会触发外部代币合约的路径检查重入风险,必要时结合 Checks-Effects-Interactions、ReentrancyGuard 和业务不变量测试。

特别注意:OpenZeppelin Contracts 5.x 的安全封装会检查目标合约的相关调用结果,但非标准返回值兼容并不能替代会计校验。通过本篇三种返回值测试后,至少还应增加手续费代币和恶意返回行为的对抗测试,才能判断结算路径是否满足业务要求。

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

目录与阅读设置

阅读设置

17

记录一个想法

兼容 ERC-20 非标准返回值

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

登录哪都通