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

按实际到账额计算存款

按实际到账额计算存款

用户向金库存入 100 个代币,金库未必真正收到 100 个:带转账手续费的代币可能只到账 98 个。如果仍按 100 个铸造份额,其他存款人就会承担损失。本篇通过转账前后的余额差计算实际到账量,并实现按净到账额铸造份额的 Solidity 金库。

学习目标

  • 理解按请求金额记账造成的份额稀释问题。
  • 使用余额差和存款前资产规模计算正确的铸造数量。
  • 识别零到账、精度舍入、重入及特殊代币行为的边界。

为什么不能直接使用存款参数

假设金库原有 900 个资产代币和 900 个份额,用户调用 deposit(100),代币每次转账扣除 2% 手续费,实际到账 98 个。

项目 错误记账 正确记账
存款前资产 900 900
存款前份额 900 900
请求转入 100 100
实际到账 98 98
新铸造份额 100 98
存款后资产 998 998
存款后总份额 1000 998

错误方案中,原有 900 份对应的资产价值从 900 降为 900×998/1000=898.2900\times998/1000=898.2,旧存款人无故损失 1.8 个代币的价值。攻击者还可以通过重复存取或利用其他结算漏洞放大错误记账造成的影响。

正确方案必须区分三个数值:用户请求存入的 amount、代币实际转入金库的 received、用户获得的 shares。只有后两者参与最终存款结算。

余额差如何进入份额计算

对于按比例发行份额的金库,必须先读取转账前的资产余额及份额总量,再执行代币转账,并使用余额差计算实际到账额。

金库按实际到账额铸造份额的数据流

设转账前金库资产为 AA,原有份额总量为 SS,实际到账为 RR,本次铸造份额为 MM。计算规则如下:

当 S=0S=0 时,在资产也为零的初始化条件下,采用一比一铸造:M=RM=R。

当 S>0S>0 且 A>0A>0 时:

M=⌊R×SA⌋M=\left\lfloor\frac{R\times S}{A}\right\rfloor

向下取整可避免给存款人多发份额。尤其不能在转账后直接使用增加后的资产余额作为分母,否则会把本次存款算进旧资产规模,导致份额计算偏少。

对于有不同精度、初始兑换率或者虚拟资产和虚拟份额设计的金库,需要使用其实际定义的兑换公式,不能直接套用首次一比一铸造。

实现按净到账额铸造份额

下面使用 Solidity 0.8.24 和 OpenZeppelin Contracts 5.x。示例依赖 OpenZeppelin 的 ERC20、IERC20、SafeERC20、Math 和 ReentrancyGuard,假设底层资产采用普通整数余额记账、不发生自动 Rebase,并且首次存款时金库资产为零。

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

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

contract NetReceivedVault is ERC20, ReentrancyGuard {
    using SafeERC20 for IERC20;

    IERC20 public immutable asset;

    constructor(IERC20 asset_)
        ERC20("Vault Share", "vSHARE")
    {
        require(address(asset_) != address(0), "Zero asset");
        asset = asset_;
    }

    function deposit(uint256 amount, uint256 minShares)
        external
        nonReentrant
        returns (uint256 shares)
    {
        require(amount > 0, "Zero amount");

        // 快照必须取自转账前,避免本次到账影响兑换率。
        uint256 assetsBefore = asset.balanceOf(address(this));
        uint256 supplyBefore = totalSupply();

        require(
            supplyBefore == 0 || assetsBefore > 0,
            "Invalid vault state"
        );
        require(
            supplyBefore != 0 || assetsBefore == 0,
            "Uninitialized assets"
        );

        asset.safeTransferFrom(msg.sender, address(this), amount);

        uint256 assetsAfter = asset.balanceOf(address(this));
        require(assetsAfter > assetsBefore, "Nothing received");

        uint256 received = assetsAfter - assetsBefore;

        // 使用实际到账量与存款前兑换率计算份额。
        shares = supplyBefore == 0
            ? received
            : Math.mulDiv(received, supplyBefore, assetsBefore);

        require(shares > 0, "Zero shares");
        require(shares >= minShares, "Slippage exceeded");

        _mint(msg.sender, shares);
    }
}

Math.mulDiv 使用完整精度的乘除运算,避免直接计算 received * supplyBefore 时产生不必要的乘法溢出。SafeERC20 兼容不返回布尔值但成功执行的常见代币实现;它不会自动解决手续费问题,因此仍必须读取余额差。

nonReentrant 阻止存款过程中再次进入受保护的存款函数;minShares 则由调用者指定最低可接受份额,在价格被操纵或舍入过大时撤销整笔交易。交易回滚也会撤销已经执行的代币状态变更。

预期结果:使用每次转账扣除 2% 手续费的测试代币,并在已存在 900 资产、900 份额的金库中调用 deposit(100, 98),忽略代币最小单位换算后,金库增加 98 个资产,调用者获得 98 个份额。若传入 minShares=99,交易会因 Slippage exceeded 回滚。

验证会计不变量和异常边界

基础不变量是:对于一次成功存款,在没有额外资产变化的前提下,金库底层代币余额增加值应等于本次 received,而不是用户请求转入的 amount。

可以使用 Foundry 测试一个手续费代币。以下为片段示例,依赖已有的 NetReceivedVault vault、可设置 2% 转账手续费的 IERC20 token、测试用户 alice,以及完成授权和初始金库资产准备的测试环境。

solidity
uint256 assetsBefore = token.balanceOf(address(vault));
uint256 sharesBefore = vault.balanceOf(alice);

vm.prank(alice);
uint256 minted = vault.deposit(100 ether, 98 ether);

uint256 received =
    token.balanceOf(address(vault)) - assetsBefore;

assertEq(received, 98 ether);
assertEq(minted, 98 ether);
assertEq(vault.balanceOf(alice) - sharesBefore, minted);

预期结果:在初始兑换率为 1:1、手续费精确为 2% 的测试条件下,三个断言全部通过。这里的 ether 只是 Solidity 的 101810^{18} 整数单位,测试代币需要采用兼容的精度和手续费计算规则。

此外,至少覆盖以下边界:

测试条件 预期行为
amount=0 回滚 Zero amount
转账没有增加金库余额 回滚 Nothing received
计算后 shares=0 回滚 Zero shares
铸造数量低于 minShares 回滚 Slippage exceeded
总份额大于零但资产余额为零 回滚 Invalid vault state
未初始化时金库已被直接转入资产 回滚 Uninitialized assets

最后一种情况能够阻止初始资产被直接转入后继续按照错误的首次存款汇率铸造,但不等于完整解决捐赠攻击或份额膨胀攻击。对于允许直接捐赠资产的生产金库,通常还要引入虚拟资产与虚拟份额、适当的初始份额锁定,或明确设计内部资产会计模型。

哪些代币不能只靠余额差处理

余额差方案适用于典型的转账扣费代币,但它依赖一个前提:两次 balanceOf 读取之间的余额变化能够归因于本次转账。

  • Rebasing 代币:代币可能自动改变金库余额,导致差额混入收益或损失,必须使用专门的资产计量模型。
  • 带回调的代币:执行转账时可能调用其他合约,必须检查所有外部入口与跨函数重入风险,仅保护 deposit 不一定足够。
  • 可升级或恶意代币:balanceOf 可能采用非常规逻辑,余额快照并不能保证与真实可赎回资产一致,应通过资产白名单限制支持范围。
  • 转出也收费的代币:存款净到账正确不代表提现结算正确,提现应另外定义扣费由谁承担,并验证收款人实际到账额。

还要注意:按余额差铸造份额保证的是存款记账准确,不保证整个金库的经济安全。生产实现仍需要针对抢跑、首次存款操纵、舍入方向、提现手续费以及资产价格变化进行专项测试。

对于普通转账收费代币,最直接的安全规则就是:先保存旧余额与旧总份额,再执行转账,用实际到账差额计算铸造份额,并通过最低份额约束验证结果。

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

目录与阅读设置

阅读设置

17

记录一个想法

按实际到账额计算存款

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

登录哪都通