Cannon

⚠️ 重要提示：请先阅读此部分内容

部分 Cannon 命令具有不可逆性，且直接操作真实资产。 请谨慎使用以下命令：

• cannon build（不带 --dry-run 参数）—— 在真实网络上部署合约
• cannon publish —— 发布至链上注册表（永久性操作）
• cannon register —— 在链上注册包名称
• cannon publishers —— 管理包发布者的权限

安全命令：cannon build --dry-run、cannon inspect、cannon run、cannon test、cannon decode、cannon trace、cannon clean

操作规范：

1. 始终优先使用 --dry-run —— 在真实网络执行前先进行模拟
2. 确保所有操作对用户完全透明 —— 执行前明确告知将发生什么
3. 部署前必须获得确认 —— 未经显式授权，不得使用真实私钥
4. 优先本地测试 —— 在目标链之前，先在链 ID 13370（Cannon Network）上测试
5. 保护私钥 —— 推荐使用 CANNON_PRIVATE_KEY 环境变量或 --impersonate 参数

模型推荐

为 Cannon 相关任务选用当前最先进的模型。 部署脚本处理真实资产 —— 切勿因节省成本而降低模型能力。优先选用 Claude、GPT-4 或具备同等能力的高阶模型，而非更廉价的替代方案。

Schema 参考

如需完整的 cannonfile 语法校验与编辑器自动补全，请参考官方 JSON Schema：

• 完整 Schema： https://raw.githubusercontent.com/usecannon/cannon/refs/heads/dev/packages/lsp/src/schema.json
• 片段 Schema： https://raw.githubusercontent.com/usecannon/cannon/refs/heads/dev/packages/lsp/src/schema-fragment.json

如需在编辑器中启用校验，请在 cannonfile.toml 文件顶部添加 Schema 引用：

#:schema https://raw.githubusercontent.com/usecannon/cannon/refs/heads/dev/packages/lsp/src/schema.json

name = "my-package"
version = "1.0.0"
...

此举可在支持 TOML LSP 的编辑器（例如 taplo）中启用自动补全与语法校验功能。

Cannon 是一个面向以太坊智能合约的包管理器与部署系统。它采用声明式的 cannonfile 定义部署工作流，同时支持本地开发与链上部署。

前提条件

使用本技能前，请确保已安装以下工具：

• Node.js 18+ 与 pnpm — npm install -g pnpm
• Foundry（forge、anvil、cast）— curl -L https://foundry.paradigm.xyz | bash && foundryup
• Cannon CLI — pnpm add -g @usecannon/cli

验证安装是否成功：

node --version && pnpm --version
forge --version && anvil --version
cannon --version

快速参考

完整 CLI 参数说明详见 references/cli.md。

CLI 命令

cannon build              # 本地构建包（启动 anvil 并部署合约）
cannon run       # 运行已部署的包（简写形式：cannon ）
cannon test               # 在部署上下文中运行 forge 测试
cannon inspect   # 查看包详情
cannon publish            # 发布至链上注册表 + IPFS ⚠️ 不可逆
cannon clean              # 删除缓存目录
cannon verify             # 在 Etherscan/Sourcify 上验证合约

包引用格式

:@

示例：

greeter-foundry:2.24.0
safe:1.4.1
synthetix-omnibus:3.1.4@main

Cannonfile 语法
包元数据与文件包含
name = "my-package"
version = "1.0.0"
description = "My package description"
tags = ["defi", "token"]
preset = "main"

# 包含额外的动作定义文件（适用于大型包）
include = ["./deposits.toml", "./withdrawals.toml"]

使用 include 可将大型 cannonfile 拆分为多个文件。被包含的文件遵循 fragment schema，可包含任意动作（deploy、invoke、clone 等）。
现代语法使用 [var.label] 定义配置项（已弃用旧语法：[setting.name]）。
变量
[var.chainId]
defaultValue = 1

[var.owner]
defaultValue = "0x..."

部署合约
[deploy.MyContract]
artifact = "MyContract"
args = ["<%= settings.owner %>"]

调用函数
[invoke.initialize]
target = ["<%= contracts.MyContract.address %>"]
func = "initialize"
args = ["<%= settings.owner %>"]

导入 / 克隆包
[clone.safe]
source = "safe:1.4.1"
target = "safe"

何时使用 clone 与 import：

clone — 将另一个包作为“蓝图”重新部署。务必正确设置 target（若你拥有该包，则可与 source 相同；否则应指定新名称）。
import — 从已部署的包中拉取数据，无需重复部署。

从包中拉取数据
[pull.usdc]
source = "usdc:1.0.0@main"

访问方式：<%= imports.usdc.contracts.USDC.address %>
模板字符串
使用 ERB 风格模板引用各类值：

<%= settings.varName %> —— 设置项
<%= contracts.ContractName.address %> —— 已部署合约地址
<%= contracts.ContractName.abi %> —— 合约 ABI
<%= imports.pkg.contracts.Contract.address %> —— 已导入合约

动作（Actions）



动作
描述



deploy
部署合约


invoke
调用合约函数


clone
以另一包为蓝图部署新包


import
从已部署包中拉取数据


pull
（已弃用）import 的别名


var
定义计算型变量


router
创建 router 合约以绕过合约大小限制（常与 UUPS 代理配合使用）


diamond
创建符合 EIP-2535 标准的 Diamond 合约及其 facets


本地开发
⚠️ 在向目标链部署前，请务必使用链 ID 13370（Cannon Network）进行本地测试。
默认链 ID：13370（Cannon Network）
# 使用本地 anvil 构建
cannon build

# 为特定链构建
cannon build --chain-id 1 --rpc-url $RPC_URL

# 模拟运行（仅仿真）
cannon build --dry-run --impersonate-all

# 本地运行某包
cannon run greeter-foundry:2.24.0

链上部署
⚠️ 执行链上部署前，务必先使用 --dry-run 进行验证。
# 部署至主网
cannon build --chain-id 1 --rpc-url $RPC_URL --private-key $KEY

# 发布至注册表
cannon publish --chain-id 1 --rpc-url $RPC_URL --private-key $KEY

# 实际部署前的模拟
cannon build --chain-id 1 --rpc-url $RPC_URL --dry-run

测试
# 使用 forge 运行测试
cannon test

# 测试特定合约
cannon test --match-path "test/MyContract.t.sol"

在 Forge 测试中使用 cannon-std：
import {Cannon} from "cannon-std/Test.sol";

contract MyTest is Cannon {
    function setUp() public {
        // 加载已部署合约
        address myContract = getAddress("MyContract");
    }
}

存储路径



目录
内容



~/.local/share/cannon/tags/
包引用文件


~/.local/share/cannon/ipfs_cache/
缓存的 IPFS 资源


~/.local/share/cannon/build_results/
构建输出


~/.local/share/cannon/blobs/
大型二进制数据块


常用模式
Router 模式（绕过合约大小限制）
创建一个 router 合约，高效地将调用转发至下游合约。与 UUPS 代理结合时尤为强大。
[deploy.CoreImplementation]
artifact = "Core"

[deploy.AnotherImplementation]
artifact = "Another"

[router.CoreRouter]
dependencies = ["CoreImplementation", "AnotherImplementation"]

Diamond 模式（EIP-2535）
[deploy.Diamond]
artifact = "Diamond"

[deploy.FacetA]
artifact = "FacetA"

[deploy.FacetB]
artifact = "FacetB"

[diamond.Diamond]
facets = ["FacetA", "FacetB"]

链接库（Linked Libraries）
[deploy.Library]
artifact = "Library"

[deploy.Contract]
artifact = "Contract"
libraries = { Library = "<%= contracts.Library.address %>" }

调试工具
Cannon 提供了用于解码字节码、追踪交易及与已部署合约交互的命令。
decode
利用包的 ABI 解码十六进制数据（函数调用、事件、错误等）：
cannon decode synthetix-omnibus --chain-id 8453 --preset main 0x...

trace
获取交易的人类可读堆栈追踪信息：
cannon trace  --chain-id 1 --rpc-url $RPC_URL

interact
通过 CLI 向已部署合约发送交易：
cannon interact synthetix-omnibus --chain-id 8453 --contract CoreProxy

包状态操作（alter）
alter 命令可在常规构建流程之外修改已有 Cannon 包。适用于故障排查、迁移或修复损坏的包状态。
⚠️ 仅当无其他可行方案时才使用 alter。
子命令



命令
描述



import
将现有资源导入部署步骤（适用于迁移场景）


set-contract-address
修改部署中某合约的地址


mark-complete
将某部署步骤标记为已完成


mark-incomplete
将某部署步骤标记为未完成


set-url
更新部署 URL 引用


set-misc
更新杂项数据 URL


clean-unused
移除未使用的部署状态


migrate-212
将包从 2.12 版本格式迁移


示例：导入已有部署
# 通过创建交易哈希导入已部署合约
cannon alter my-package:1.0.0 --chain-id 1 import deploy MyContract 0x...txhash

# 导入已执行的交易
cannon alter my-package:1.0.0 --chain-id 1 import invoke initialize 0x...txhash

GitOps 工作流
Cannon 通过网站界面支持 GitOps 风格的部署。
通过 GitOps 排队部署
可通过 Cannon 网站直接从 GitHub 仓库或 IPFS 哈希部署包：

执行前预览交易
查看变更的 Git Diff
通过 Safe 多签钱包执行
部署完成后发布至注册表

参见：https://usecannon.com/deploy
部署仓库
为部署配置单独建立一个 Git 仓库（与源代码仓库分离）：

在保持智能合约源码私有的前提下，实现部署过程透明化
支持团队协作管理部署
保留清晰的审计轨迹

从其他工具迁移
从 hardhat-deploy、Foundry 脚本或其他部署框架迁移：

手动重建部署为 cannonfile.toml（通常较快）
本地构建生成模板：cannon build（保存其 IPFS 哈希）
针对每个网络，导入已有部署：
# 将包 URL 设为本地模板
cannon alter my-package --chain-id 1 set-url 

# 导入各已部署合约/交易
cannon alter my-package --chain-id 1 import deploy MyContract 0x...txhash


验证：运行构建命令（不应执行任何步骤）：cannon build --chain-id 1

高级主题
详细信息请参阅：

CLI 参考：参见 references/cli.md
Cannonfile 规范：参见 references/cannonfile.md
测试模式：参见 references/testing.md
注册表与发布：参见 references/registry.md

故障排查



问题
解决方案



“deployment not found”
该链 ID 下未发布对应包。请检查 --chain-id


构建失败并提示 “artifact not found”
请先运行 forge build，或检查 artifact 路径是否正确


IPFS 超时
检查网络连接，可能需要配置 IPFS 网关


注册表发布失败
请确认你对该包名称具有写入权限


部署到了错误链
务必反复核对 --chain-id —— 部署操作无法撤销


发布了错误的包
注册表发布是永久性的 —— 请务必先验证版本号与资源内容


开发工作流

使用 Foundry 开发合约
编写 cannonfile.toml 定义部署逻辑
本地构建：cannon build（链 ID 13370）
测试：cannon test
目标链模拟：--dry-run ⚠️ 此步必须首先执行
部署：cannon build --chain-id  ⚠️ 在非本地网络上不可逆（链 ID 13370 上安全）
验证：使用 cannon verify 在 Etherscan 上验证合约
发布：cannon publish ⚠️ 链上操作永久生效

关键文件



文件
用途



cannonfile.toml
包定义


cannonfile.lock
锁定依赖项


.cannon/
构建缓存（已加入 .gitignore）


deployments/
部署产物