BattleChain Development Standards

Instructions for working with BattleChain, from the Cyfrin security team.

What is BattleChain

BattleChain is a ZKSync-based L2 blockchain that inserts a battle-testing phase between testnet and mainnet: Dev -> Testnet -> BattleChain -> Mainnet. Protocols deploy audited contracts with real funds, whitehats legally attack them for bounties under Safe Harbor agreements, and surviving contracts promote to production.

Full Documentation

For up-to-date contract addresses, function signatures, struct definitions, enums, state transitions, bounty calculation rules, Safe Harbor agreement details, and all other technical reference material, fetch the full docs:

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

Always fetch this URL when you need BattleChain technical details. The docs are the single source of truth and stay current as the protocol evolves.

Deployment

Projects deploying to BattleChain (or any EVM chain) should use cyfrin/battlechain-lib:

bash
1forge install cyfrin/battlechain-lib

Add the remapping to foundry.toml:

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

Inheritance hierarchy

Key helpers

Cross-chain behavior

Only requestAttackMode is BattleChain-specific. Everything else works on any supported chain.

Foundry

When working with foundry scripts, as of today, you need to pass a flag to skip simulations, for example:

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

Otherwise, you'll run into errors about gas estimation. You can also combine this with -g:

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

If the issues persist. If using a justfile or makefile please add these flags to the targets in those files.

Verification

BattleChain uses a custom block explorer API for contract verification. The battlechain-lib ships a reusable justfile module with verification targets.

Install verification targets

Add to your justfile:

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

This gives you:

Verify manually

bash
1forge verify-contract <ADDRESS> src/MyVault.sol:MyVault \
2    --chain-id 627 \
3    --verifier-url https://block-explorer-api.testnet.battlechain.com/api \
4    --verifier custom \
5    --etherscan-api-key "1234" \
6    --rpc-url https://testnet.battlechain.com

The API key is not validated — any non-empty string works.

Verify during deployment

Add --verify to your forge script call:

bash
1forge script script/Deploy.s.sol \
2    --rpc-url https://testnet.battlechain.com \
3    --broadcast --skip-simulation -g 300 \
4    --verify \
5    --verifier-url https://block-explorer-api.testnet.battlechain.com/api \
6    --verifier custom \
7    --etherscan-api-key 1234

This verifies contracts as they're deployed. For factory-deployed contracts (via CreateX/BCDeploy), use bc-verify-broadcast after deployment instead.

Troubleshooting

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

This error means a contract exceeds the EVM contract size limit (24,576 bytes). Forge can't estimate gas for an oversized contract, so the deploy transaction fails to build.

Diagnose: Check contract sizes after compiling:

bash
1forge build --sizes

Any contract over 24,576 bytes will fail to deploy.

Fix options:

1. Split the contract into smaller pieces (libraries, separate contracts)
2. Enable the optimizer with more runs: optimizer = true and optimizer_runs = 200 in foundry.toml
3. Use --via-ir for deeper optimization (slower compile, smaller output)
4. Extract constants and large string literals into separate libraries

BattleChain does not support EIP-1559

Every forge script and cast send call must include --legacy. Without it, transactions are rejected.

Hardhat

Coming soon...