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

编译第一个 Solidity 计数器

编译第一个 Solidity 计数器

从一个能够保存整数的 Counter 合约开始,使用 Solidity 定义状态变量和修改函数,再通过 Foundry 的 Forge 完成编译。本课最终得到可供部署与调用的 ABI、创建字节码和运行时字节码,并学会根据编译器报错定位源代码问题。

学习目标

  • 编写包含持久化状态变量、读取接口和修改接口的 Counter 合约。
  • 配置 Solidity 版本约束及 Forge 编译选项,成功生成合约产物。
  • 区分 ABI、创建字节码与运行时字节码,并根据编译错误完成修复。

初始化 Foundry 工程

以下操作适用于已安装 Foundry 的 macOS、Linux 或 Windows WSL 环境。先在终端执行 forge --version,确认命令可用。如果找不到命令,应先安装 Foundry 并确保其可执行文件目录已加入 PATH。

使用 Forge 创建独立工程。命令会初始化 Solidity 源码、测试、脚本和项目配置;首次初始化可能需要网络连接以获取依赖。

bash
# 创建工程并进入项目根目录。
forge init counter-demo
cd counter-demo

# 确认源码与配置文件已经生成。
test -f src/Counter.sol && test -f foundry.toml && printf 'project ready\n'

预期结果:初始化日志之后,最后一行输出如下内容。

text
project ready

工程中需要关注四个位置:src/ 存放合约源码,test/ 存放 Solidity 测试,foundry.toml 控制编译配置,out/ 在构建成功后保存编译产物。lib/ 通常存放项目依赖。

编写能够保存状态的 Counter

打开 src/Counter.sol,将初始化模板替换成下面的完整合约。这个计数器提供三个能力:公开读取当前数字、直接设置数字、将数字增加一。这里先不部署,因此只验证源码能够被编译。

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

contract Counter {
    // 状态变量存放在合约存储中,public 自动生成读取函数。
    uint256 public number;

    function setNumber(uint256 newNumber) external {
        number = newNumber;
    }

    function increment() external {
        // Solidity 0.8 默认检查整数运算是否溢出。
        number += 1;
    }
}

pragma solidity ^0.8.20; 表示允许使用 0.8.20 及以上、但低于 0.9.0 的 Solidity 编译器。它限制兼容范围,并不要求 Forge 必须使用 0.8.20。实际版本还取决于编译器检测与项目配置。

uint256 public number 是状态变量,初始值为 0。部署后,对它的修改会保存在链上合约存储中,而不是只存在于一次函数调用的临时内存中。public 会让编译器生成 number() 读取函数。

setNumber(uint256) 和 increment() 使用 external 可见性,允许外部账户或其他合约调用。它们会修改状态,因此真正部署后需要通过交易执行;number() 只读取状态,可以通过只读调用获取返回值。

配置编译选项并运行 Forge

打开工程根目录下的 foundry.toml,使用以下配置。这里采用 Solidity 0.8.20 兼容的 Shanghai EVM 目标,并启用优化器。让 Forge 自动选择满足源码约束的编译器版本,以避免初始化模板中其他源码与手动固定版本发生冲突。

toml
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
auto_detect_solc = true
optimizer = true
optimizer_runs = 200
evm_version = "shanghai"

这些设置的作用可以逐项验证:

配置项 取值 实际作用
src src 查找 Solidity 合约源码
out out 保存编译后的 JSON 产物
auto_detect_solc true 自动选择符合版本约束的编译器
optimizer true 启用 Solidity 优化器
optimizer_runs 200 设置优化器的预期执行次数参数
evm_version shanghai 以 Shanghai 版本的 EVM 指令集为编译目标

optimizer_runs 不是编译执行次数,也不是 Gas 上限。它影响优化器对部署体积与运行开销的取舍;修改该值后,即使合约源码不变,生成的字节码也可能不同。

在工程根目录执行构建:

bash
# 使用 foundry.toml 中的配置编译工程。
forge build

预期输出包含以下成功标志,编译器版本、耗时和其他日志可能不同。

text
Compiler run successful!

构建成功后,应能够找到 out/Counter.sol/Counter.json。这个 JSON 文件记录 ABI、字节码及其他编译信息。首次构建还可能生成缓存文件和编译器元数据,它们不属于需要部署到链上的合约代码。

可以运行 forge config 查看合并后的实际配置。需要锁定团队构建结果时,再在 foundry.toml 中指定一个与所有源码 pragma 兼容的精确 solc_version,同时固定优化器与 EVM 目标版本。

读取 ABI、创建字节码与运行时字节码

Forge 不是把 Solidity 源码直接发送到 Ethereum。它调用 Solidity 编译器,将源码转换为用于外部交互的 ABI 和由 EVM 执行的字节码,并把结果组织成合约产物。

Counter 源码经 Forge 编译生成 ABI、创建字节码和运行时字节码的数据流

三种产物的职责不同:

  • ABI:描述合约公开的函数、参数、返回值和状态可变性,供调用工具编码与解码数据。
  • 创建字节码:对应 bytecode.object,用于创建合约,包含部署时执行的初始化代码。
  • 运行时字节码:对应 deployedBytecode.object,是合约部署完成后实际留在链上供调用执行的代码。

使用下面的 Python 3 命令直接读取 Forge 生成的 JSON。脚本会筛选 ABI 中的函数项,并检查两种字节码是否具有十六进制前缀。

bash
python3 - <<'PY'
import json
from pathlib import Path

artifact = json.loads(
    Path("out/Counter.sol/Counter.json").read_text(encoding="utf-8")
)

# ABI 包含不同类型的条目,这里只提取函数名称。
functions = sorted(
    item["name"] for item in artifact["abi"] if item["type"] == "function"
)

# 分别检查部署阶段和运行阶段使用的字节码。
print("ABI functions:", ", ".join(functions))
print("Creation bytecode:", artifact["bytecode"]["object"].startswith("0x"))
print("Runtime bytecode:", artifact["deployedBytecode"]["object"].startswith("0x"))
PY

预期输出:

text
ABI functions: increment, number, setNumber
Creation bytecode: True
Runtime bytecode: True

这里的 number 不是手写的函数,而是 public 状态变量对应的自动生成读取接口。两种字节码虽然都以 0x 开头,但长度和用途通常不同,不能把运行时字节码直接当作完整的创建字节码使用。

也可以直接通过 forge inspect Counter abi 查询 ABI,或通过 forge inspect Counter bytecode 查询创建字节码。十六进制内容会随 Solidity 编译器版本和优化设置改变,验收时应检查接口结构及字节码是否存在,而不是要求所有环境生成完全相同的十六进制字符串。

根据编译错误定位并修复问题

编译失败时,先区分语法错误、类型错误与版本不兼容。Forge 会显示编译诊断,通常包含源文件位置和错误描述;只看最后一行构建失败提示,往往找不到真正的问题。

例如,将 setNumber 中原本合法的 number = newNumber; 临时替换为 number = "1";。这是片段示例,必须放在前面完整合约的函数体中,不能独立编译。"1" 是字符串字面量,不能隐式赋给 uint256。

保存修改后,在工程根目录重新执行:

bash
# 强制重新编译,检查当前源码的诊断信息。
forge build --force

预期结果:编译失败,终端出现与类型不匹配相关的诊断,指出 uint256 和字符串字面量不兼容,并定位到错误赋值语句。错误编号、排版和附带提示因 Solidity 编译器及 Forge 版本而异,不应依赖固定的完整错误文本。

修复时将赋值恢复为 number = newNumber;,保存文件后重新构建:

bash
# 修复类型错误后再次验证。
forge build

预期输出包含:

text
Compiler run successful!

如果遇到 ParserError,优先检查括号、分号、花括号及关键字;如果出现 TypeError,检查参数和赋值两侧的数据类型;如果提示编译器版本不满足要求,则检查源码中的 pragma 与 foundry.toml 中是否存在冲突的固定 solc_version。

最终验收标准是:forge build 成功、out/Counter.sol/Counter.json 存在、ABI 包含 number、setNumber 和 increment 三个函数,且创建字节码与运行时字节码均非空。满足这些条件后,Counter 已具备进入部署与链上调用阶段所需的编译产物。

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

目录与阅读设置

阅读设置

17

记录一个想法

编译第一个 Solidity 计数器

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

登录哪都通