mcpField
B
battlechain

battlechain

github.com/cyfrin安全14459 次安装19 周前更新
代码仓库

关于 battlechain

battlechain 是面向 BattleChain 开发的安全与部署指引，供部署 EVM 协议和智能合约的开发者使用。它涵盖跨链部署、安全港协议、攻击模式、合约验证及常见 Foundry 问题。

主要功能

  1. 01BattleChain 网络与合约参考
  2. 02通过 battlechain-lib 部署
  3. 03创建并采用安全港协议
  4. 04申请攻击模式
  5. 05Foundry 部署与合约验证指引

适用场景

  1. 01向 BattleChain 测试网或主网部署
  2. 02在支持的 EVM 链部署合约
  3. 03为协议创建安全港协议
  4. 04验证合约并排查部署问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cyfrin/solskill --skill battlechain

安装后在 Claude Code 中输入/battlechain确认已加载。

详细介绍

BattleChain 开发标准

与 BattleChain 配合工作时的说明，来自 Cyfrin 安全团队。

什么是 BattleChain

BattleChain 是基于 ZKSync 的 L2 区块链，在测试网和主网之间加入了一个实战测试阶段：开发 -> 测试网 -> BattleChain -> 主网。协议会部署经过审计的合约并存入真实资金，白帽黑客可根据 Safe Harbor 协议合法攻击合约并获取赏金，成功存续的合约则会晋升至生产环境。

网络

网络Chain IDRPC浏览器CAIP-2状态
BattleChain626https://mainnet.battlechain.comhttps://explorer.mainnet.battlechain.com/eip155:626已上线 — 生产网络
BattleChain 测试网627https://testnet.battlechain.comhttps://explorer.testnet.battlechain.com/eip155:627已上线 — 工具默认网络

两个网络都提供区块浏览器、API 和合约验证（主网 API：https://block-explorer-api.mainnet.battlechain.com/api，测试网 API：https://block-explorer-api.testnet.battlechain.com/api）。模拟依赖合约（代币、Chainlink、Uniswap 等）仅供测试网使用。battlechain-lib 工具默认使用测试网；设置 NETWORK=mainnet 可将目标设为主网。

主网核心合约（chain 626）
合约地址
Safe Harbor 注册表（代理）0xd229f4EE1bAE432010b72a9d1bD682570F4C6eBe
注册表实现0xBFF0ec94740c287932B50E64c2e8b380129B99a1
协议工厂（代理）0xCdB7F5C0F708baBaabE82afE1DbA8362023AcFdd
AgreementFactory 实现0x8d4fEDF4462E3876Ae7C70CC0C5cebA482003Ad5
攻击注册表（代理）0x24876e481eC7198CAC95af739Df2a852CE65A415
AttackRegistry 实现0x03A3228A4ce38362289E715bbc26Cac8b98e421B
BattleChainDeployer0xD12765D21dDba418B8Fc0583c4716763e03Aa078
注册表版主0x445d5685c4Ae71550Da0716b82B434AEA140E0c7
CreateX0xa397f06F07251A3AEd53f6d3019A2a6cbd83E53e

主网 CreateX 由 Cyfrin 部署，地址并非广为人知的 0xba5Ed...。battlechain-lib 会根据链解析正确的地址 — 请勿在 BattleChain 上硬编码 0xba5Ed...。

主网 Safe 合约（chain 626）

由 Cyfrin 部署的真实 Safe 合约（并非由 Safe 团队部署）：

合约地址
Safe0xFF716747B4D28EAE844Dc069387C9bFC00e51737
SafeL20xb6524C4fBcEd314EAad98Bc750B6AD76B64d7f8A
SafeProxyFactory0x8d0D56f72E266a4BfA05340f68409dEBbdbdc9e2
CreateCall0x5A499D08755a9dC90208Ef5b031a3118789EBF5A
MultiSend0x28E369665036bFe0041c1E5838A608b1a818296f
MultiSendCallOnly0xed4c81c91602CDD5c1e396a1AF28735E03EdA9e2
SignMessageLib0x95cb704BFF25b8943BcE3fAE5D1b4665f7b08115
SafeToL2Setup0xa8fB860254764C68360596f64BA841b077bebBA4
TokenCallbackHandler0x63b920c6D0B5EC07345d9810169376192654d38F
CompatibilityFallbackHandler0x2744C4f8336B6e2A8a182495FbB327Db493F303f
ExtensibleFallbackHandler0x115b290ecDe805FD846E0C347f3419A4234Fd673

测试网合约地址请参阅完整文档（见下文）。

完整文档

如需获取最新合约地址、函数签名、结构体定义、枚举、状态转换、赏金计算规则、Safe Harbor 协议详情以及其他所有技术参考资料，请获取完整文档：

https://docs.battlechain.com/llms-full.txt

需要 BattleChain 技术详情时，请务必获取此 URL。随着协议不断演进，文档始终保持更新，是唯一可信的信息来源。

部署

向 BattleChain（或任何 EVM 链）部署的项目应使用 cyfrin/battlechain-lib：

forge install cyfrin/battlechain-lib

将 remapping 添加到 foundry.toml：

remappings = ["battlechain-lib/=lib/battlechain-lib/src/"]

继承层级

合约适用场景
BCScript完整生命周期：部署 + 协议 + 攻击模式
BCDeploy仅部署（在任意链上通过 CreateX，在 BC 上通过 BattleChainDeployer）
BCSafeHarbor仅创建协议

关键辅助函数

辅助函数功能
bcDeployCreate(bytecode)在 BattleChain 上通过 BattleChainDeployer 部署，在其他 190 多条链上通过 CreateX 部署
bcDeployCreate2(salt, bytecode)确定性部署——在不同链上使用相同地址
bcDeployCreate3(salt, bytecode)地址仅取决于 salt，与字节码无关
defaultAgreementDetails(name, contacts, contracts, recovery)根据每条链构建包含正确范围和 URI 的协议
createAndAdoptAgreement(details, owner, salt)一次调用即可创建协议、承诺 14 天并采纳协议
requestAttackMode(agreement)进入攻击模式（仅限 BattleChain——在其他链上会回滚）
_isBattleChain()运行时检查：在链 ID 为 626、627 时返回 true
getDeployedContracts()本次会话中通过 bcDeploy* 部署的所有地址

跨链行为

BattleChain（626/627）其他 EVM 链（190 多条）
bcDeployCreate*BattleChainDeployer（CreateX + AttackRegistry）直接使用 CreateX（0xba5Ed...）
defaultAgreementDetailsBattleChain 范围 + BATTLECHAIN_SAFE_HARBOR_URI当前链的 CAIP-2 范围 + SAFE_HARBOR_V3_URI
requestAttackMode可用回滚并提示 BCSafeHarbor__NotBattleChain
createAndAdoptAgreement可用可用（需要该链上有注册表/工厂）

只有 requestAttackMode 是 BattleChain 专用的。其他功能都可在任何受支持的链上使用。

攻击模式审批

requestAttackMode 会将协议转为 ATTACK_REQUESTED；注册表审核员必须批准，协议才能进入 UNDER_ATTACK 状态。

  • 测试网（627）： 审核员是无需许可的 MockRegistryModerator，地址为 0x3DdA228A38b4d7438bBF5D5137c8D1090DcaF6bF——任何人都可以立即批准自己的攻击请求：

    cast send 0x3DdA228A38b4d7438bBF5D5137c8D1090DcaF6bF \
    "approveAttack(address)" <AGREEMENT_ADDRESS> \
    --rpc-url https://testnet.battlechain.com --account <your-account>

  • 主网（626）： 审批由注册表审核员通过受控的 DAO 操作完成（0x445d5685c4Ae71550Da0716b82B434AEA140E0c7）。

Foundry

使用 Foundry 脚本时，截至目前需要传入一个标志以跳过模拟，例如：

forge script scripts/Deploy.s.sol --skip-simulation

否则会遇到燃料估算错误。也可以将此标志与 -g 结合使用：

forge script scripts/Deploy.s.sol --skip-simulation -g 300

如果问题仍然存在，请检查是否使用了 justfile 或 makefile，并将这些标志添加到对应文件的目标中。

验证

BattleChain 使用自定义区块浏览器 API 验证合约。两个网络均支持验证：测试网（链 ID 627）和主网（链 ID 626）。以下示例针对测试网；要用于主网，请将链 ID 替换为 626，将验证器 URL 替换为 https://block-explorer-api.mainnet.battlechain.com/api，并将 RPC 替换为 https://mainnet.battlechain.com。`battlechain-lib` 附带可复用的 justfile 模块，其中包含验证目标。

安装验证目标

添加到你的 justfile：

import "lib/battlechain-lib/battlechain.just"

这将提供以下目标：

目标用法
bc-verify <addr> <path:name>验证单个合约
bc-verify-broadcast <script>验证广播文件中的所有合约（支持通过 CreateX/BCDeploy 工厂创建的合约）
bc-deploy <script> <account> <sender>使用标准 BC 标志部署
bc-deploy-verify <script> <account> <sender>一步完成部署和验证

这些目标会根据网络自动调整：默认使用测试网，设置 NETWORK=mainnet 可切换到主网 RPC 和区块浏览器 API。

手动验证
forge verify-contract <ADDRESS> src/MyVault.sol:MyVault \
    --chain-id 627 \
    --verifier-url https://block-explorer-api.testnet.battlechain.com/api \
    --verifier custom \
    --etherscan-api-key "1234" \
    --rpc-url https://testnet.battlechain.com

API 密钥不会经过验证——任何非空字符串都可使用。

部署时验证

在 forge script 调用中添加 --verify：

forge script script/Deploy.s.sol \
    --rpc-url https://testnet.battlechain.com \
    --broadcast --skip-simulation -g 300 \
    --verify \
    --verifier-url https://block-explorer-api.testnet.battlechain.com/api \
    --verifier custom \
    --etherscan-api-key 1234

这会在部署合约时进行验证。对于通过 CreateX/BCDeploy 工厂部署的合约，请在部署后使用 bc-verify-broadcast。

故障排除

AnyTxType(2) transaction can't be built due to missing keys: ["gas_limit"]

此错误表示合约超过了 EVM 合约大小限制（24,576 bytes）。Forge 无法估算超大合约的 gas，因此部署交易无法构建。

**诊断：**编译后检查合约大小：

forge build --sizes

任何超过 24,576 bytes 的合约都将无法部署。

解决方案：

  1. 将合约拆分成更小的部分（库、独立合约）
  2. 在 foundry.toml 中启用优化器并增加运行次数：optimizer = true 和 optimizer_runs = 200
  3. 使用 --via-ir 进行更深入的优化（编译速度较慢，但输出更小）
  4. 将常量和较大的字符串字面量提取到独立库中

Hardhat

即将推出……

评论

支持 Markdown