智能合约与以太坊 / 系统课时
通过 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();本例不实现它,因此调用回退。

创建收款合约
前置条件:已安装 Foundry(forge 命令可用)。在终端创建项目;执行成功后应能看到 foundry.toml、src/、test/ 和 lib/forge-std/。不同 Foundry 版本的初始化日志可能不同。
forge init payable-lab --no-git
cd payable-lab预期结果:生成 payable-lab 工程目录,终端所在目录切换至该工程。
将下面的完整合约保存为 src/PayableBox.sol(适用于 Solidity 0.8.20 及兼容的 0.8.x 编译器):
// 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() 时会回退。
// 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);
}
}运行指定测试:
forge test --match-contract PayableBoxTest -vv预期输出(Gas 数值及外围日志随环境变化):
[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 是否足够。区分交易执行回退与交易根本未广播,不要只凭钱包的“发送失败”字样判断合约逻辑。