Foundry Solidity 开发

使用 Foundry 1.5.0 和 Solidity 0.8.30 构建安全、高效智能合约的完整指南。

适用场景

• 开发 Ethereum/EVM 智能合约
• 编写 Forge 测试（单元测试、模糊测试、不变式测试、分叉测试）
• 通过脚本部署合约
• 使用 Foundry 工具（forge、cast、anvil、chisel）
• 处理 foundry.toml、*.t.sol、*.s.sol 文件
• 调试交易与合约交互

快速开始

# 创建新项目
forge init my-project && cd my-project

# 编译合约
forge build

# 运行测试
forge test

# 部署（预执行）
forge script script/Deploy.s.sol --rpc-url sepolia

# 部署（广播上链）
forge script script/Deploy.s.sol --rpc-url sepolia --broadcast --verify

项目结构

my-project/
├── foundry.toml          # 配置文件
├── src/                  # 合约源码目录
│   └── Counter.sol
├── test/                 # 测试文件（*.t.sol）
│   └── Counter.t.sol
├── script/               # 部署脚本（*.s.sol）
│   └── Deploy.s.sol
└── lib/                  # 依赖库目录
    └── forge-std/

核心命令

编译与测试

forge build                          # 编译合约
forge test                           # 运行全部测试
forge test -vvvv                     # 显示执行轨迹（trace）
forge test --match-test testDeposit  # 按测试函数名过滤
forge test --match-contract Vault    # 按合约名过滤
forge test --fork-url $RPC_URL       # 分叉测试
forge test --gas-report              # 输出 Gas 消耗报告

部署

# 单合约部署
forge create src/Token.sol:Token --rpc-url sepolia --private-key $KEY --broadcast

# 脚本化部署（推荐方式）
forge script script/Deploy.s.sol:Deploy --rpc-url sepolia --broadcast --verify

# 验证已部署合约
forge verify-contract $ADDRESS src/Token.sol:Token --chain sepolia

Cast —— 区块链交互工具

cast call $CONTRACT "balanceOf(address)" $USER --rpc-url mainnet
cast send $CONTRACT "transfer(address,uint256)" $TO $AMOUNT --private-key $KEY
cast decode-tx $TX_HASH
cast storage $CONTRACT 0 --rpc-url mainnet

Anvil —— 本地节点模拟器

anvil                           # 启动本地节点
anvil --fork-url $RPC_URL       # 分叉主网状态
anvil --fork-block-number 18000000

基础测试合约示例

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

import {Test, console} from "forge-std/Test.sol";
import {Counter} from "../src/Counter.sol";

contract CounterTest is Test {
    Counter public counter;
    address public user;

    function setUp() public {
        counter = new Counter();
        user = makeAddr("user");
        deal(user, 10 ether);
    }

    function test_Increment() public {
        counter.increment();
        assertEq(counter.number(), 1);
    }

    function test_RevertWhen_Unauthorized() public {
        vm.expectRevert("Unauthorized");
        vm.prank(user);
        counter.adminFunction();
    }

    function testFuzz_SetNumber(uint256 x) public {
        x = bound(x, 0, 1000);
        counter.setNumber(x);
        assertEq(counter.number(), x);
    }
}

关键 Cheatcodes

// 账户与 ETH 操作
address alice = makeAddr("alice");          // 创建带标签的地址
deal(alice, 10 ether);                      // 向地址发放 ETH
deal(address(token), alice, 1000e18);       // 向地址发放 ERC20 代币

// 账户伪装（Impersonation）
vm.prank(alice);                            // 下一次调用以 alice 身份执行
vm.startPrank(alice);                       // 后续所有调用均以 alice 身份执行
vm.stopPrank();

// 时间与区块控制
vm.warp(block.timestamp + 1 days);          // 设置区块时间戳
vm.roll(block.number + 100);                // 设置区块高度

// 断言与预期行为
vm.expectRevert("Error message");           // 预期发生 revert 并匹配错误消息
vm.expectRevert(CustomError.selector);      // 预期发生自定义错误
vm.expectEmit(true, true, false, true);     // 预期下一次 emit 的事件（参数：logTopic1, logTopic2, logData, logAddress）
emit Transfer(from, to, amount);            // 必须紧随其后，用于匹配预期事件

// 存储读写
vm.store(addr, slot, value);                // 写入存储槽
vm.load(addr, slot);                        // 读取存储槽

部署脚本示例

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

import {Script, console} from "forge-std/Script.sol";
import {Counter} from "../src/Counter.sol";

contract Deploy is Script {
    function run() external {
        uint256 deployerKey = vm.envUint("PRIVATE_KEY");

        vm.startBroadcast(deployerKey);
        Counter counter = new Counter();
        counter.setNumber(42);
        vm.stopBroadcast();

        console.log("已部署至:", address(counter));
    }
}

现代 Solidity 编程模式（Solidity 0.8.30）

// 自定义错误（更省 Gas）
error InsufficientBalance(uint256 available, uint256 required);

// 瞬态存储（Transient Storage，0.8.28+）——低成本重入防护
bool transient locked;
modifier nonReentrant() {
    require(!locked, "Reentrancy");
    locked = true;
    _;
    locked = false;
}

// 不可变变量（immutable，读取成本低）
address public immutable owner;

// 命名映射键（Named mapping parameters）
mapping(address user => uint256 balance) public balances;

// require 配合自定义错误（0.8.26+）
require(amount <= balance, InsufficientBalance(balance, amount));

配置文件（foundry.toml）

[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc = "0.8.30"
optimizer = true
optimizer_runs = 200
evm_version = "prague"

fuzz.runs = 256
invariant.runs = 256
invariant.depth = 50

[rpc_endpoints]
mainnet = "${MAINNET_RPC_URL}"
sepolia = "${SEPOLIA_RPC_URL}"

[etherscan]
mainnet = { key = "${ETHERSCAN_API_KEY}" }
sepolia = { key = "${ETHERSCAN_API_KEY}" }

[profile.ci]
fuzz.runs = 10000
invariant.runs = 1000

参考资料

详细指南请参阅：

• 测试：参阅 references/testing.md，涵盖完整测试模式（单元、模糊、不变式、分叉）、全部 Cheatcodes 及最佳实践
• forge-std API：参阅 references/forge-std-api.md，完整函数参考（150+ 个函数）
• Solidity 0.8.30：参阅 references/solidity-modern.md，了解新特性与现代语法
• 部署：参阅 references/deployment.md，涵盖脚本编写、合约验证与多链部署
• 配置：参阅 references/configuration.md，详述所有 foundry.toml 配置项
• Gas 优化：参阅 references/gas-optimization.md，涵盖存储打包、编译器设置与性能分析
• 设计模式：参阅 references/patterns.md，涵盖访问控制、重入防护、工厂模式及常见编程范式
• 安全：参阅 references/security.md，涵盖常见漏洞、防御性编码模式与审计准备要点
• 资源：参阅 references/resources.md，含官方文档、常用库、安全工具与学习路径
• 调试：参阅 references/debugging.md，涵盖执行轨迹（traces）、断点、console.log 及交互式调试器使用方法
• 依赖管理：参阅 references/dependencies.md，涵盖 forge install、remappings 与 Soldeer 包管理器
• CI/CD：参阅 references/cicd.md，涵盖 GitHub Actions 工作流、缓存策略与 Gas 消耗追踪
• Chisel：参阅 references/chisel.md，了解交互式 Solidity REPL 的使用
• Cast 进阶功能：参阅 references/cast-advanced.md，涵盖数据解码/编码、钱包管理与批量操作
• Anvil 进阶功能：参阅 references/anvil-advanced.md，涵盖账户伪装、状态操控与挖矿模式