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

通过 payable 接收 ETH

通过 payable 接收 ETH

用一个最小收款合约区分两类支付:空调用数据的 ETH 转账进入 receive(),携带 deposit() 函数选择器的交易进入指定函数。完成后,你能用本地测试核对 msg.value、两条路径的累计收款额和合约实际余额。

学习目标

  • 解释 payable、msg.value 与 receive() 的作用及单位。
  • 编写同时接收普通转账和函数调用付款的 Solidity 合约。
  • 使用 Foundry 测试两条收款路径和未匹配调用的失败行为。

收款入口由调用数据决定

payable 表示函数允许随调用接收 ETH;没有标记 payable 的普通函数,附带非零 ETH 调用会回退。msg.value 是当前调用携带的金额,单位为 wei:1 ether = 1000000000000000000 wei。

对同一合约地址发送 ETH,会因调用数据不同进入不同入口:

  • 空 calldata:优先执行 receive() external payable;没有 receive() 时,才可能执行可收款的 fallback()。
  • 包含 deposit() 选择器:执行匹配的 deposit() 函数,并把本次金额放入 msg.value。
  • 非空但未匹配任何函数:尝试进入 fallback();本例不实现它,因此调用回退。

普通 ETH 转账与携带调用数据付款的入口分流

创建收款合约

前置条件:已安装 Foundry(forge 命令可用)。在终端创建项目;执行成功后应能看到 foundry.toml、src/、test/ 和 lib/forge-std/。不同 Foundry 版本的初始化日志可能不同。

bash
forge init payable-lab --no-git
cd payable-lab

预期结果:生成 payable-lab 工程目录,终端所在目录切换至该工程。

将下面的完整合约保存为 src/PayableBox.sol(适用于 Solidity 0.8.20 及兼容的 0.8.x 编译器):

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

contract PayableBox {
    uint256 public directWei;
    uint256 public depositWei;

    event Payment(address indexed sender, uint256 amount, string entry);

    // 没有调用数据时执行,金额已经随交易进入合约。
    receive() external payable {
        directWei += msg.value;
        emit Payment(msg.sender, msg.value, "receive");
    }

    // 只有匹配 deposit() 的调用才会走这条路径。
    function deposit() external payable {
        require(msg.value > 0, "zero payment");
        depositWei += msg.value;
        emit Payment(msg.sender, msg.value, "deposit");
    }
}

directWei 和 depositWei 分别记录两个入口累计收到的 wei;Payment 事件留下付款者、金额和入口。两个数是合约维护的账本字段,不能直接代替 address(this).balance:真实余额还可能受非普通调用路径的强制入金影响。合约没有提款功能,收到的测试 ETH 不可从该合约取出,因此仅用于本地实验。

测试两条付款路径

将测试保存为 test/PayableBox.t.sol。vm.deal 为测试地址准备 1 ETH;第一次低级调用传入空字节数据,第二次用 ABI 编码 deposit()。测试还用未知选择器验证本例没有 fallback() 时会回退。

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

import {Test} from "forge-std/Test.sol";
import {PayableBox} from "../src/PayableBox.sol";

contract PayableBoxTest is Test {
    PayableBox box;
    address payer = address(0xA11CE);

    function setUp() public {
        box = new PayableBox();
        vm.deal(payer, 1 ether);
    }

    function testTwoPaymentPaths() public {
        vm.startPrank(payer);

        // 空 calldata 触发 receive()。
        (bool directOk, ) = address(box).call{value: 0.1 ether}("");
        assertTrue(directOk);

        // ABI 函数选择器触发 deposit()。
        (bool depositOk, ) = address(box).call{value: 0.2 ether}(
            abi.encodeCall(PayableBox.deposit, ())
        );
        assertTrue(depositOk);

        // 无匹配函数且无 fallback:付款回退。
        (bool unknownOk, ) = address(box).call{value: 0.01 ether}(
            hex"deadbeef"
        );
        assertFalse(unknownOk);
        vm.stopPrank();

        assertEq(box.directWei(), 100000000000000000);
        assertEq(box.depositWei(), 200000000000000000);
        assertEq(address(box).balance, 0.3 ether);
    }
}

运行指定测试:

bash
forge test --match-contract PayableBoxTest -vv

预期输出(Gas 数值及外围日志随环境变化):

text
[PASS] testTwoPaymentPaths() (gas: <GAS>)
Suite result: ok. 1 passed; 0 failed; 0 skipped

断言分别证明普通转账累计 0.1 ETH、函数付款累计 0.2 ETH,合约余额为 0.3 ETH;未知选择器附带的 0.01 ETH 没有入账。修改 deposit() 的 payable 为无修饰的普通函数后再运行,第二笔付款将失败,测试不会通过。

处理接收失败与安全边界

容易误判的是:receive() 存在就一定能接收任何转账。本例的 receive() 会写入存储,消耗超过 2300 Gas;如果其他合约使用只提供 2300 Gas 的 transfer() 或 send() 付款,可能回退。测试采用的 .call{value: ...}("") 能转发更多 Gas,因此路径成立。

如果付款失败,按以下顺序核查:是否传入了正确的函数选择器;目标入口是否标记 payable;require(msg.value > 0) 是否满足;发送方余额是否覆盖转账金额与 Gas;接收执行获得的 Gas 是否足够。区分交易执行回退与交易根本未广播,不要只凭钱包的“发送失败”字样判断合约逻辑。

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

目录与阅读设置

阅读设置

17

记录一个想法

通过 payable 接收 ETH

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

登录哪都通