mcpField
B
battlechain

battlechain

github.com/cyfrinセキュリティ14459 回インストール19 週間前に更新
リポジトリ

battlechain について

battlechainは、BattleChainで開発する開発者向けのセキュリティとデプロイのガイドです。EVMプロトコルやコントラクトを対象に、クロスチェーンデプロイ、安全港契約、攻撃モード、検証、Foundryの問題を扱います。

主な機能

  1. 01BattleChainのネットワークとコントラクト情報
  2. 02battlechain-libによるデプロイ
  3. 03Safe Harbor契約の作成と採用
  4. 04攻撃モードの申請
  5. 05Foundryのデプロイと検証ガイド

活用シーン

  1. 01BattleChainのテストネットやメインネットへのデプロイ
  2. 02対応するEVMチェーンへのコントラクト展開
  3. 03プロトコルのSafe Harbor契約の作成
  4. 04コントラクト検証とデプロイ問題の調査

インストール

コマンドをコピーしてターミナルで実行します。

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

インストール後、Claude Code で/battlechainを入力して読み込まれたか確認します。

詳細

BattleChain 開発標準

Cyfrin のセキュリティチームによる、BattleChain の使用手順です。

BattleChain とは

BattleChain は ZKSync ベースの L2 ブロックチェーンで、テストネットとメインネットの間に実戦テスト段階を設けています。開発 -> テストネット -> BattleChain -> メインネット。プロトコルは監査済みコントラクトを実資金とともにデプロイし、ホワイトハットがセーフハーバー契約のもとで合法的にバグ報奨金を狙って攻撃します。攻撃を耐え抜いたコントラクトは本番環境へ昇格します。

ネットワーク

ネットワークチェーン IDRPCエクスプローラーCAIP-2ステータス
BattleChain626https://mainnet.battlechain.comhttps://explorer.mainnet.battlechain.com/eip155:626稼働中 — 本番ネットワーク
BattleChain Testnet627https://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 を設定します。

メインネットの主要コントラクト（チェーン 626）
コントラクトアドレス
Safe Harbor Registry（プロキシ）0xd229f4EE1bAE432010b72a9d1bD682570F4C6eBe
Registry Implementation0xBFF0ec94740c287932B50E64c2e8b380129B99a1
Agreement Factory（プロキシ）0xCdB7F5C0F708baBaabE82afE1DbA8362023AcFdd
AgreementFactory Implementation0x8d4fEDF4462E3876Ae7C70CC0C5cebA482003Ad5
Attack Registry（プロキシ）0x24876e481eC7198CAC95af739Df2a852CE65A415
AttackRegistry Implementation0x03A3228A4ce38362289E715bbc26Cac8b98e421B
BattleChainDeployer0xD12765D21dDba418B8Fc0583c4716763e03Aa078
Registry Moderator0x445d5685c4Ae71550Da0716b82B434AEA140E0c7
CreateX0xa397f06F07251A3AEd53f6d3019A2a6cbd83E53e

メインネットの CreateX は Cyfrin によってデプロイされており、既知の 0xba5Ed... アドレスにはありません。battlechain-lib はチェーンごとに正しいアドレスを解決します。BattleChain で 0xba5Ed... をハードコードしないでください。

メインネットの Safe コントラクト（チェーン 626）

Cyfrin によってデプロイされた実際の Safe コントラクトです（Safe チームによるものではありません）。

コントラクトアドレス
Safe0xFF716747B4D28EAE844Dc069387C9bFC00e51737
SafeL20xb6524C4fBcEd314EAad98Bc750B6AD76B64d7f8A
SafeProxyFactory0x8d0D56f72E266a4BfA05340f68409dEBbdbdc9e2
CreateCall0x5A499D08755a9dC90208Ef5b031a3118789EBF5A
MultiSend0x28E369665036bFe0041c1E5838A608b1a818296f
MultiSendCallOnly0xed4c81c91602CDD5c1e396a1AF28735E03EdA9e2
SignMessageLib0x95cb704BFF25b8943BcE3fAE5D1b4665f7b08115
SafeToL2Setup0xa8fB860254764C68360596f64BA841b077bebBA4
TokenCallbackHandler0x63b920c6D0B5EC07345d9810169376192654d38F
CompatibilityFallbackHandler0x2744C4f8336B6e2A8a182495FbB327Db493F303f
ExtensibleFallbackHandler0x115b290ecDe805FD846E0C347f3419A4234Fd673

テストネットのコントラクトアドレスについては、以下の完全版ドキュメントを取得してください。

完全版ドキュメント

最新のコントラクトアドレス、関数シグネチャ、構造体の定義、列挙型、状態遷移、バグ報奨金の計算ルール、セーフハーバー契約の詳細、その他すべての技術リファレンス資料については、完全版ドキュメントを取得してください。

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

BattleChain の技術的な詳細が必要な場合は、必ずこの URL を取得してください。ドキュメントは唯一の信頼できる情報源であり、プロトコルの進化に合わせて最新の状態に保たれます。

デプロイ

BattleChain（または任意の EVM チェーン）にデプロイするプロジェクトでは、cyfrin/battlechain-lib を使用してください。

forge install cyfrin/battlechain-lib

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)1 回の呼び出しで合意の作成＋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動作します動作します（そのチェーンにレジストリ／ファクトリーが必要です）

BattleChain 専用なのは requestAttackMode のみです。それ以外はすべて、サポートされている任意のチェーンで動作します。

攻撃モードの承認

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）： 承認はレジストリモデレーター（0x445d5685c4Ae71550Da0716b82B434AEA140E0c7）による管理された DAO アクションです。

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 を使用します。検証はテストネット（チェーン 627）とメインネット（チェーン 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>broadcast ファイル内のすべてのコントラクトを検証します（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 バイト）を超えていることを示します。サイズ超過したコントラクトのガスを Forge は見積もれないため、デプロイトランザクションの構築に失敗します。

診断： コンパイル後にコントラクトのサイズを確認します。

forge build --sizes

24,576 バイトを超えるコントラクトはデプロイに失敗します。

解決方法：

  1. コントラクトを小さな単位（ライブラリや個別のコントラクト）に分割します
  2. foundry.toml で optimizer = true と optimizer_runs = 200 を設定し、オプティマイザーの実行回数を増やします
  3. より高度な最適化を行うために --via-ir を使用します（コンパイルは遅くなりますが、出力サイズは小さくなります）
  4. 定数や長い文字列リテラルを別のライブラリに切り出します

Hardhat

近日公開…

コメント

Markdown 対応