智能合约与以太坊 / 系统课时
安装 Echidna 并运行属性测试
安装 Echidna 并运行属性测试
本课使用 Docker 安装 Echidna,编写一个包含故意缺陷的 Solidity 合约,并通过随机交易序列验证安全属性。完成后,你将能够运行属性测试、区分通过与失败结果,并根据 Echidna 给出的反例定位违反约束的调用。
学习目标
- 安装并验证 Echidna、Solidity 编译器及运行环境。
- 编写符合 `echidna_` 命名规则的布尔属性测试。
- 运行模糊测试,读取失败属性及最小化后的反例交易。
准备 Echidna 运行环境
Echidna 是面向以太坊智能合约的属性模糊测试工具。它会生成交易调用序列,改变合约状态,再检查开发者定义的不变量是否始终成立。本课使用官方 Docker 镜像,避免手动安装 Haskell 工具链。
准备 Docker Engine 或 Docker Desktop,并确认 Docker 服务已经启动。以下命令适用于 Linux、macOS 或 Windows WSL2 的 Bash 环境;Windows PowerShell 的路径挂载写法需要相应调整。
docker --version
docker info --format '{{.ServerVersion}}'
docker pull ghcr.io/crytic/echidna/echidna:latest
docker run --rm ghcr.io/crytic/echidna/echidna:latest echidna --version预期结果:Docker 返回客户端和服务端版本,镜像拉取成功,最后一条命令输出 Echidna 版本信息,例如包含 `Echidna` 和版本号。具体版本由镜像标签决定,不应固定为某个数值。
官方镜像还包含 `solc-select`、`crytic-compile` 和 Foundry 工具。为了让实验能够重复,下面明确选用 Solidity 0.8.26,不依赖镜像中可能变化的默认编译器版本。
编写最小属性测试合约
建立独立目录,在其中创建 `BalanceInvariant.sol`。合约模拟一个初始资金为 20 单位的账户,允许任何调用者提取不超过当前余额的金额。为了展示反例,我们故意增加一个并未由业务逻辑保证的最低余额属性。
mkdir -p echidna-demo
cd echidna-demo
cat > BalanceInvariant.sol <<'EOF'
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;
contract BalanceInvariant {
uint256 public balance = 20;
// 允许余额减少到零,故意不保证最低余额为 10。
function withdraw(uint256 amount) public {
require(amount <= balance, "insufficient balance");
balance -= amount;
}
// 正确属性:余额不能超过初始值。
function echidna_balance_at_most_twenty() public view returns (bool) {
return balance <= 20;
}
// 待验证属性:余额必须始终不少于 10。
function echidna_balance_at_least_ten() public view returns (bool) {
return balance >= 10;
}
}
EOF预期结果:当前目录生成 `BalanceInvariant.sol`,包含一个修改状态的函数和两个属性函数。文件创建成功时,Shell 通常没有额外输出。
Echidna 默认使用 `property` 测试模式,识别名称以 `echidna_` 开头、没有参数并返回 `bool` 的属性函数。返回 `true` 表示当前状态满足属性,返回 `false` 表示发现反例。
这里存在两个不同的判断:
- `balance <= 20`:由于没有增加余额的入口,初始化后的所有可达余额都不超过 20。
- `balance >= 10`:调用 `withdraw(11)` 后余额变为 9,明显违反属性。
注意,`withdraw` 本身并没有因为余额变成 9 而回滚。安全属性失败不等于 Solidity 运行时抛出了异常,而是测试发现业务约束未成立。
配置并运行随机调用
为避免不同运行环境使用完全不同的测试预算,创建 `echidna.yaml`,显式配置测试模式、交易序列长度和测试次数。
testMode: property
testLimit: 2000
seqLen: 10将以上内容保存为 `echidna.yaml`,与 Solidity 文件放在同一目录。其中 `testLimit` 控制测试生成的交易序列数量上限,`seqLen` 控制单个序列的最大交易长度。它们不表示必然执行 2000 次成功交易,因为生成的调用可能回滚,且测试过程还可能包含反例缩减。
在 `echidna-demo` 目录执行以下命令。容器把当前目录挂载到 `/src`,切换到指定编译器后运行 Echidna。
docker run --rm -v "$PWD:/src" -w /src ghcr.io/crytic/echidna/echidna:latest bash -lc 'solc-select install 0.8.26 && solc-select use 0.8.26 && echidna BalanceInvariant.sol --contract BalanceInvariant --config echidna.yaml --format text'预期结果:编译通过后,Echidna 发现至少一个能令最低余额属性返回 `false` 的交易序列。最终结果中的关键内容应类似:
echidna_balance_at_most_twenty: passed!
echidna_balance_at_least_ten: failed!这是便于阅读的结果摘录,不是完整终端日志。实际输出还会包含交易调用、测试统计等信息,排列顺序与呈现形式可能随版本变化。首次执行时安装编译器会产生额外日志。
如果镜像已经具有正确的编译器版本,可以省略重复安装步骤。也可以通过官方支持的 `brew install echidna` 在 macOS 或 Linux 上安装原生版本,再使用同样的合约和配置文件执行测试。
读取失败反例并定位缺陷
Echidna 不只报告属性失败,还会尝试缩减触发失败的交易序列。对本例来说,一个合法的反例是从初始状态调用 `withdraw(11)`,随后检查最低余额属性。实际随机测试可能找到其他金额或其他等价调用序列。
反例可以按以下顺序复核:
- 初始余额是 20,两个属性均为 `true`。
- 执行 `withdraw(11)`,前置条件 `11 <= 20` 成立,交易成功。
- 余额更新为 9,仍满足 `balance <= 20`。
- 检查 `balance >= 10` 得到 `false`,最低余额属性失败。
这里没有复杂的权限控制或重入漏洞,失败原因是业务属性与实现规则不一致。修复前必须先确认真实需求。如果产品确实要求始终保留至少 10 单位余额,就需要修改提取逻辑;如果允许账户全部提空,则应删除或调整错误的属性,而不是为了让测试通过随意修改合约。
若要求保留最低余额,可以把原来的 `withdraw` 实现替换为以下片段。
// 片段示例:替换 BalanceInvariant 合约原有的 withdraw 函数。
function withdraw(uint256 amount) public {
require(amount <= balance, "insufficient balance");
require(balance - amount >= 10, "minimum reserve");
balance -= amount;
}这里第二个判断执行时已经保证 `amount <= balance`,因此减法不会发生下溢。重新运行同一条 Echidna 命令,预期两个属性都通过;但 `passed!` 只表示在当前测试预算内未发现反例,不构成对所有可能交易序列的形式化证明。
处理常见执行问题
首次运行时通常会遇到三类问题,可以按照报错发生的位置进行检查。
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| Docker 无法连接守护进程 | Docker Engine 未运行 | 启动 Docker Desktop 或 Docker 服务后重新执行 `docker info` |
| Solidity 编译失败 | 编译器版本不满足 `pragma` | 在容器内运行 `solc-select use 0.8.26`,并检查源文件语法 |
| 没有检测到属性 | 函数命名、签名或测试模式错误 | 检查 `echidna_` 前缀、无参数、`bool` 返回值以及 `testMode: property` |
| 属性没有失败 | 交易生成不足,或触发路径不可达 | 检查状态修改入口,增加 `testLimit`,并确认属性确实能被违反 |
若要直接检查编译器及 Echidna 的实际版本,可以在容器中执行:
docker run --rm ghcr.io/crytic/echidna/echidna:latest bash -lc 'echidna --version && solc-select versions'预期结果:显示 Echidna 版本及 Solidity 编译器安装列表。具体版本号和可用编译器列表取决于当前镜像。若 Solidity 0.8.26 尚未安装,应先执行前面的编译器安装命令。
最后建议保留一份故意失败的测试用例,作为工具链验收样例。升级 Echidna、编译器或 CI 镜像后,重新运行该样例,应仍能观察到一个通过属性和一个失败属性。这可以验证测试工具确实在执行状态探索和反例检测,而不仅仅是成功完成合约编译。