智能合约与以太坊 / 系统课时
用 nonReentrant 阻止重入
用 nonReentrant 阻止重入
当智能合约向外部地址发送 ETH 时,接收方可能通过回调再次调用提款函数,导致同一笔交易中发生嵌套执行。本课使用 OpenZeppelin 的 ReentrancyGuard 为提款入口加锁,编写攻击模拟与自动化测试,并验证两个受保护函数为什么不能互相调用。
学习目标
- 正确引入 ReentrancyGuard,理解 nonReentrant 的加锁、拒绝重入与解锁机制。
- 为 ETH 提款函数添加保护,并通过 Foundry 测试验证攻击回调被阻止。
- 识别受保护函数之间的调用限制,使用内部函数复用业务逻辑。
nonReentrant 如何阻断重复进入
重入攻击通常发生在合约执行外部调用期间。例如,用户提款时,金库合约向用户地址发送 ETH;如果接收方是恶意合约,其 receive() 函数可以再次调用金库提款入口。第一次提款尚未结束,第二次提款就可能进入同一段业务逻辑。
OpenZeppelin Contracts 5.x 提供 ReentrancyGuard,在受保护函数执行期间维护一个进入状态。其核心规则如下:
- 第一次调用
nonReentrant函数,检查当前是否已经进入受保护区域。 - 检查通过后,将状态标记为已进入,并执行函数主体。
- 如果外部回调再次进入任意受同一个 Guard 保护的函数,立即回退,抛出
ReentrancyGuardReentrantCall()。 - 正常执行结束后解除锁定。如果整个调用回退,EVM 的状态回滚也会恢复锁定状态。

这种保护作用于整个 Guard 实例,不是每个函数各有一把锁。因此,withdraw() 正在执行时,即使回调尝试进入另一个带 nonReentrant 的 withdrawAll(),也会被拒绝。
需要注意,Guard 不负责检查用户余额、授权关系或跨合约业务不变量,也不会自动保护没有添加修饰符的入口。通常仍应遵循 Checks-Effects-Interactions(先检查、更新状态、最后外部交互)模式。
编写带重入保护的提款合约
以下示例适用于 Solidity 0.8.20 及以上版本与 OpenZeppelin Contracts 5.x。使用 Foundry 项目安装对应依赖:
forge init guard-demo
cd guard-demo
forge install OpenZeppelin/openzeppelin-contracts@v5.5.0预期结果:项目初始化成功,lib/openzeppelin-contracts 目录存在,并包含 contracts/utils/ReentrancyGuard.sol。不同 Foundry 版本的安装日志和目录前缀可能不同。
在项目的 foundry.toml 中配置导入映射。如果文件已有其他配置,保留原有配置并合并对应字段:
[profile.default]
solc_version = "0.8.24"
remappings = ["@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/"]在 src/Vault.sol 中写入完整合约:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
contract Vault is ReentrancyGuard {
mapping(address => uint256) public balances;
function deposit() external payable {
require(msg.value > 0, "Zero deposit");
balances[msg.sender] += msg.value;
}
function withdraw(uint256 amount) external nonReentrant {
_withdraw(msg.sender, amount);
}
function withdrawAll() external nonReentrant {
uint256 amount = balances[msg.sender];
_withdraw(msg.sender, amount);
}
// 两个外部入口共享业务逻辑,但内部函数不重复加锁。
function _withdraw(address account, uint256 amount) private {
require(amount > 0, "Zero withdrawal");
require(balances[account] >= amount, "Insufficient balance");
// 先扣除余额,再调用不可信接收方。
balances[account] -= amount;
(bool success, ) = payable(account).call{value: amount}("");
require(success, "ETH transfer failed");
}
}这里有三层保护:nonReentrant 拒绝嵌套进入;余额检查确保用户无法超额提款;先扣余额再发送 ETH,使状态在外部回调前完成更新。
发送 ETH 使用 call{value: amount}(""),因为接收方可能是需要执行 receive() 的智能合约。它会返回成功标志,必须明确检查。接收方如果拒收 ETH,提款会整体回退,之前扣除的余额也会恢复。
执行编译:
forge build预期结果:编译成功且没有 Solidity 编译错误,Foundry 报告编译完成。实际编译器下载、警告和耗时取决于本地环境。
用恶意回调验证防护效果
仅看到代码存在 nonReentrant 不足以证明保护有效。应让接收方在收到 ETH 时主动尝试再次提款,然后验证第二次调用失败而第一次正常完成。
创建 test/Vault.t.sol。以下测试依赖 Foundry 自带的 forge-std 测试库,以及前面创建的 Vault.sol。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Test} from "forge-std/Test.sol";
import {Vault} from "../src/Vault.sol";
contract ReentryAttacker {
Vault public immutable vault;
bool public blocked;
bool public reentered;
constructor(Vault target) {
vault = target;
}
function attack() external payable {
require(msg.value == 1 ether, "Need 1 ETH");
vault.deposit{value: 1 ether}();
vault.withdraw(1 ether);
}
receive() external payable {
// 收款回调中尝试再次进入受保护的提款函数。
try vault.withdraw(1 ether) {
reentered = true;
} catch {
blocked = true;
}
}
}
contract VaultTest is Test {
Vault internal vault;
ReentryAttacker internal attacker;
function setUp() public {
vault = new Vault();
attacker = new ReentryAttacker(vault);
vm.deal(address(this), 10 ether);
}
function testReentryIsBlocked() public {
attacker.attack{value: 1 ether}();
assertTrue(attacker.blocked());
assertFalse(attacker.reentered());
assertEq(vault.balances(address(attacker)), 0);
assertEq(address(attacker).balance, 1 ether);
assertEq(address(vault).balance, 0);
}
function testWithdrawAll() public {
vault.deposit{value: 2 ether}();
vault.withdrawAll();
assertEq(vault.balances(address(this)), 0);
assertEq(address(vault).balance, 0);
}
receive() external payable {}
}执行测试:
forge test --match-contract VaultTest -vv预期结果:两个测试均通过,测试统计中的通过数为 2,失败数为 0。Foundry 的完整输出格式会随版本变化。
第一个测试尤其重要:攻击合约收到 1 ETH 后,尝试在 receive() 中再次提取 1 ETH。第二次调用被 Guard 拒绝并进入 catch,因此 blocked 为 true、reentered 为 false。攻击合约最终只收到自己存入的 1 ETH,没有重复提款。
这个测试证明的是受保护入口的重入被阻止,并不等于整个合约已经通过安全审计。真实项目还应检查其他提款入口、代币回调、跨合约调用和权限边界。
受保护函数为什么不能互相调用
一个常见错误是在两个函数上都添加 nonReentrant,然后让其中一个直接调用另一个。由于 Guard 使用同一个进入状态,外层函数持锁后,内层函数无法再次通过检查。
下面是错误写法,仅作为片段示例,依赖合约已继承 ReentrancyGuard:
function withdrawAll() external nonReentrant {
withdraw(balances[msg.sender]);
}
function withdraw(uint256 amount) public nonReentrant {
// 原有提款逻辑
}这里的 withdrawAll() 调用 withdraw() 时,会在第二次执行修饰符检查处回退。把 withdraw() 从 public 改为 external 后直接调用甚至无法按原方式编译;使用 this.withdraw() 虽然可以发起外部调用,但仍会因为重复加锁而回退,并且改变 msg.sender 的语义。
正确写法就是前面 Vault.sol 采用的结构:
withdraw()和withdrawAll()分别作为外部入口,各自添加nonReentrant。- 两个入口均调用不带修饰符的
private _withdraw()。 _withdraw()统一负责余额检查、状态更新和 ETH 转账。
这样,一个正常交易可以通过任意一个入口完成提款,但无法在其执行期间嵌套进入另一个受保护入口。
不要为了消除嵌套调用错误而简单删掉所有修饰符。应先确认哪些函数是不可信用户可调用的入口,哪些函数只是内部复用的业务实现。
部署前还要检查什么
ReentrancyGuard 解决的是特定的嵌套调用风险,不是所有外部调用风险。代码审核时可以按以下条件逐项确认:
- 所有涉及资产转移、关键余额变更的外部入口都已评估重入风险,包括 ERC-777 等可能触发回调的资产交互。
- 关键状态在外部调用前更新,转账返回值经过检查,失败时整个操作能够正确回退。
- 所有受保护的外部入口均有正常调用和攻击回调测试,不能只检查一个函数。
- 受保护函数之间不直接嵌套调用;业务复用放在
private或经过严格设计的内部实现中。 - 接收方拒绝 ETH 时,提款可能失败。对不能接受持续失败的批量支付,应考虑独立提款模式,避免单个接收方阻塞所有收款人。
本例使用的是 OpenZeppelin Contracts 5.x 的存储型 ReentrancyGuard。在支持 EIP-1153 的网络上,5.1 及以上版本还提供 ReentrancyGuardTransient,但选择它之前必须确认目标链支持瞬态存储。OpenZeppelin 5.5 文档已将存储型实现标记为弃用并计划在 6.0 移除,实际迁移应以所安装版本的官方文档为准。
参考文档:OpenZeppelin Contracts 5.x ReentrancyGuard。实际部署前应固定依赖版本,完成重入、拒绝接收、边界金额与权限测试,再安排独立安全审计。