智能合约与以太坊 / 系统课时
限制循环结算的 Gas 消耗
限制循环结算的 Gas 消耗
当智能合约需要向数百甚至数千个地址分发代币时,一次遍历全部接收者的结算函数可能超过区块 Gas 限制,导致交易整体回滚。本课通过构造不断扩大的接收者集合,观察 Gas 增长,随后使用游标和分批处理改造结算逻辑,并验证不会重复支付或遗漏接收者。
学习目标
- 理解循环结算的 Gas 增长规律,以及交易失败对资金和状态的影响。
- 使用 Foundry 测量不同接收者数量下的 Gas 消耗。
- 实现有批次上限、结算游标和会计不变量的 ERC-20 分批结算。
为什么接收者越多越容易结算失败
假设奖励合约维护一个接收者数组,每次结算都遍历数组,向每个地址转账 10 个代币。每次转账都涉及外部合约调用和 ERC-20 余额更新,因此循环成本会随着接收者数量增加。
下面是存在风险的片段示例,依赖已定义的 token、recipients 和 amounts,其中 token 为支持 safeTransfer 的 ERC-20 实例:
function settleAll() external {
// 每增加一个接收者,本次交易都要多执行一次转账。
for (uint256 i = 0; i < recipients.length; ++i) {
token.safeTransfer(recipients[i], amounts[i]);
}
}此示例还缺少结算状态记录、重复调用保护和资金核算,只用于展示无界循环风险,不能用于生产环境。
使用下面的假设数据理解数量级。这些数字是计算示例,不是实际测量值:
| 接收者数量 | 假设每人增量 Gas | 增量 Gas 合计 |
|---|---|---|
| 10 | 35,000 | 350,000 |
| 100 | 35,000 | 3,500,000 |
| 500 | 35,000 | 17,500,000 |
| 1,000 | 35,000 | 35,000,000 |
实际消耗取决于代币实现、存储冷热访问、接收者余额状态及链的执行环境。不能直接把表格中的假设值当成链上结果。
如果交易执行超出可用 Gas,EVM 会回滚该交易中的状态变化,包括此前已经执行的代币转账;但已经消耗的执行 Gas 不会退还。即使交易没有立即超过限制,无界循环也会使后续新增接收者最终无法在单笔交易内结算。
用 Foundry 测量循环的增长边界
使用 Foundry 和 Solidity 0.8.24。先准备一个独立基准合约,只记录接收者地址,并对每个地址进行一次存储写入,用来观察循环与状态写入带来的增长规律。它不是代币转账的 Gas 测量替代品。
在 Foundry 项目中创建 test/LoopGas.t.sol:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import {Test} from "forge-std/Test.sol";
contract LoopSettlement {
address[] public recipients;
mapping(address => bool) public settled;
constructor(uint256 count) {
for (uint256 i = 0; i < count; ++i) {
recipients.push(address(uint160(i + 100)));
}
}
function settleAll() external {
// 模拟逐个结算时产生的持久化状态写入。
for (uint256 i = 0; i < recipients.length; ++i) {
settled[recipients[i]] = true;
}
}
}
contract LoopGasTest is Test {
function testGasGrowth() public {
uint256[3] memory sizes = [uint256(10), 100, 500];
for (uint256 i = 0; i < sizes.length; ++i) {
LoopSettlement target = new LoopSettlement(sizes[i]);
uint256 beforeGas = gasleft();
target.settleAll();
uint256 used = beforeGas - gasleft();
emit log_named_uint("recipients", sizes[i]);
emit log_named_uint("settlement gas", used);
}
}
}执行测试:
forge test --match-test testGasGrowth -vv预期结果:测试通过,并依次输出 recipients 为 10、100、500 的三组记录。对应 settlement gas 会随数量明显增长;具体数值取决于编译器、优化器与 EVM 配置,不应硬编码为固定值。
测试命令最终应报告 1 个测试通过。使用 -vv 可以查看测试中输出的命名日志。
注意,部署合约时构造函数也会消耗 Gas。500 个接收者的创建成本可能很高,但这里通过在测试内部部署,将创建成本排除在 settleAll() 的单次测量区间之外。记录的测量值还包含调用及测量代码开销,并非纯粹的函数执行 Gas。
真实项目应对实际 ERC-20 的转账行为进行同样的测试,分别覆盖首次转入余额为零的账户、已有余额的账户以及不同数量的接收者。
使用游标限制单次结算数量
分批处理的关键是把结算进度保存在链上。假设共有 105 个接收者,每批最多 20 人,那么需要 6 笔成功的结算交易,最后一批处理 5 人。

下面是使用 OpenZeppelin Contracts 5.x SafeERC20 的完整结算合约。合约在部署时固定接收者和应付金额;部署后应提前向合约转入足额代币,然后再调用结算函数。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
contract BatchSettlement {
using SafeERC20 for IERC20;
IERC20 public immutable token;
uint256 public constant MAX_BATCH = 20;
uint256 public cursor;
uint256 public totalOwed;
uint256 public totalPaid;
address[] private recipients;
uint256[] private amounts;
event BatchProcessed(uint256 from, uint256 to, uint256 paid);
constructor(
IERC20 token_,
address[] memory recipients_,
uint256[] memory amounts_
) {
require(address(token_) != address(0), "invalid token");
require(recipients_.length == amounts_.length, "length mismatch");
require(recipients_.length > 0, "empty batch");
token = token_;
for (uint256 i = 0; i < recipients_.length; ++i) {
require(recipients_[i] != address(0), "invalid recipient");
recipients.push(recipients_[i]);
amounts.push(amounts_[i]);
totalOwed += amounts_[i];
}
}
function processBatch(uint256 maxItems) external {
require(maxItems > 0 && maxItems <= MAX_BATCH, "invalid size");
uint256 start = cursor;
require(start < recipients.length, "completed");
uint256 remaining = recipients.length - start;
uint256 count = maxItems < remaining ? maxItems : remaining;
uint256 end = start + count;
uint256 paid;
// 先推进游标,外部代币调用期间不允许重复处理当前批次。
cursor = end;
for (uint256 i = start; i < end; ++i) {
paid += amounts[i];
token.safeTransfer(recipients[i], amounts[i]);
}
totalPaid += paid;
emit BatchProcessed(start, end, paid);
}
function recipientCount() external view returns (uint256) {
return recipients.length;
}
function remainingOwed() external view returns (uint256) {
return totalOwed - totalPaid;
}
}示例的关键约束如下:
MAX_BATCH = 20:限制单笔最多处理 20 人,但必须通过目标链上的真实代币测试确认安全边界。cursor:表示下一位尚未处理的接收者索引,成功交易只会向前推进。totalPaid:累计已经执行成功的应付转账金额。remainingOwed():反映尚未结算的账面义务,不代表合约当前一定拥有足够余额。
这里不要求接收者地址唯一,因为每个数组位置都对应一笔独立应付义务;同一个地址重复出现时,会按对应条目分别支付。
SafeERC20 可以兼容常见的返回布尔值或不返回值的 ERC-20 实现,但不能解决收取转账手续费、重基准代币或者恶意代币导致的实际到账金额与账面金额不一致问题。生产场景应采用经过审查的代币白名单,或额外实现余额差额核算。
验证结算游标与会计不变量
测试不能只检查函数成功执行,还要验证边界批次、重复处理和应付余额。
为运行上述合约,项目需要安装 Foundry 标准库及 OpenZeppelin Contracts 5.x,并将合约保存为 src/BatchSettlement.sol。以下测试使用一个本地测试代币,直接为结算合约铸造足额资金。
创建 test/BatchSettlement.t.sol:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import {Test} from "forge-std/Test.sol";
import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import {BatchSettlement} from "../src/BatchSettlement.sol";
contract MockToken is ERC20 {
constructor() ERC20("Mock", "MOCK") {}
function mint(address to, uint256 amount) external {
_mint(to, amount);
}
}
contract BatchSettlementTest is Test {
function testBatchAccounting() public {
MockToken token = new MockToken();
address[] memory users = new address[](45);
uint256[] memory amounts = new uint256[](45);
for (uint256 i = 0; i < 45; ++i) {
users[i] = address(uint160(i + 100));
amounts[i] = 10 ether;
}
BatchSettlement settlement = new BatchSettlement(
token, users, amounts
);
token.mint(address(settlement), 450 ether);
// 三笔交易分别结算20、20、5人。
settlement.processBatch(20);
assertEq(settlement.cursor(), 20);
settlement.processBatch(20);
assertEq(settlement.cursor(), 40);
settlement.processBatch(20);
assertEq(settlement.cursor(), 45);
assertEq(settlement.totalPaid(), 450 ether);
assertEq(settlement.remainingOwed(), 0);
assertEq(token.balanceOf(address(settlement)), 0);
assertEq(token.balanceOf(users[44]), 10 ether);
// 结算完成后,不允许再次支付同一批次。
vm.expectRevert(bytes("completed"));
settlement.processBatch(20);
}
}执行:
forge test --match-test testBatchAccounting -vv预期结果:testBatchAccounting() 通过,测试报告显示 1 个测试通过。所有断言均成立,最终游标为 45,总支付金额为 450 个精度为 18 位的代币单位,合约代币余额为零,重复结算调用按预期回滚。
在不考虑手续费、重基准和意外额外转账的普通 ERC-20 模型中,重点检查两个会计关系:
totalPaid + remainingOwed == totalOwed。- 在预先足额注资、没有额外资金进出的条件下,
token.balanceOf(address(settlement)) == remainingOwed()。
还应增加资金不足时的回滚测试:只注资 10 个代币,却尝试结算两笔各 10 个代币的款项,预期整个批次回滚,cursor 和 totalPaid 均保持原值。
确定生产环境的批次边界
固定每批 20 人只是起点,不应将它当成所有链和所有 ERC-20 的通用安全值。真实项目需要以目标网络的交易 Gas 预算及代币最坏情况转账成本为依据。
例如,假设团队为结算交易预留 6,000,000 Gas,实际测量发现单个接收者平均增加 55,000 Gas,函数固定开销约 80,000 Gas。理论上约可处理 107 人,但这不包含最坏情况和安全冗余。可以先设置 MAX_BATCH = 50,再对余额状态不同的接收者进行压力测试。
实际验收建议采用以下顺序:
- 用 10、20、50、100、500 个接收者分别部署测试数据,测量结算函数而不是仅测构造函数。
- 对设定的批次上限测量最高 Gas 消耗,保留足够裕量,并确认低于目标链实际允许的交易预算。
- 测试最后一批不足上限、调用者重复执行、代币余额不足、转账回滚等情况。
- 检查每次成功交易后的
cursor、totalPaid、remainingOwed()和实际代币余额。 - 部署后由后端任务或任何可调用者逐批执行
processBatch,直到cursor == recipientCount()。
分批结算把单笔交易的工作量限制在可测量的范围内,同时用链上游标保存进度。验收时应同时满足单笔 Gas 不超预算、全部接收者最终完成结算,以及任何失败或重复调用都不会破坏资金会计不变量。