Deploy and Battle-Test Your Contract
Deploy a vulnerable contract to BattleChain, create a Safe Harbor agreement, and open it for whitehat attack.
Deploy a vulnerable vault, create a Safe Harbor agreement, and open it for whitehat attack — the core BattleChain workflow for protocol teams.
Review what your AI runs. AI coding tools execute real commands on your machine. Always read the commands before approving them, and never allow anything you don't understand. If in doubt, use the Manual tab and run each command yourself.
Choose your path
What You'll Need
- An AI coding tool with terminal access — Claude Code, Cursor, Windsurf, or any agent that can run terminal commands
- A test wallet with BattleChain Testnet ETH
Windows users: Use WSL2 and run your AI tool inside the WSL terminal.
Step 1 — Project Setup
Open Claude Code in a new empty folder (or open your AI tool of choice). Replace YOUR_WALLET_ADDRESS with your actual address and paste:
Read https://docs.battlechain.com/llms-full.txt to understand BattleChain, then:
1. Install Foundry if not already installed (https://getfoundry.sh)
2. Install just if not already installed (https://just.systems)
3. Clone https://github.com/Cyfrin/battlechain-starter-foundry into the current directory
4. cd into it and run forge install
5. Copy .env.example to .env and set SENDER_ADDRESS to YOUR_WALLET_ADDRESS
Once done, tell the user to PROCEED TO THE NEXT STEP
Your AI will install the tools, clone the repo, and configure your environment. Wait for it to finish before moving on.
Step 2 — Set Up Transaction Signing
Import your private key into Foundry's encrypted keystore. This is always a manual step — your private key should never be passed to any AI tool.
cast wallet import battlechain --interactive
Paste your private key and set an encryption password. The key is stored encrypted at ~/.foundry/keystores/battlechain — your raw private key is never written to disk.
Verify it worked:
cast wallet list
You should see battlechain listed. From here on, you'll enter the keystore password when transactions need signing.
Step 3 — Deploy
just deploy-protocol
Enter your keystore password when prompted. Expected output:
VulnerableVault deployed — it deploys and seeds its own token (1,000 tokens)
VAULT_ADDRESS=0x...
TOKEN_ADDRESS=0x...
Copy both addresses into your .env:
TOKEN_ADDRESS=0x...
VAULT_ADDRESS=0x...
Forge scripts require --skip-simulation on BattleChain. Forge's local gas estimation doesn't work reliably on BattleChain — add --skip-simulation to all forge script calls. The starter kit's justfile already includes this. For the full list of BattleChain Foundry flags and how just → battlechain-lib → BattleChainDeployer fit together, see How Deployment Works.
Search your VAULT_ADDRESS on the BattleChain explorer — you should see the deployment transaction and the vault's token balance.
Step 4 — Create a Safe Harbor Agreement
just create-agreement
Expected output:
Agreement created: 0x...
Copy AGREEMENT_ADDRESS into your .env and set RECOVERY_ADDRESS to your wallet address:
AGREEMENT_ADDRESS=0x...
RECOVERY_ADDRESS=0x...your_wallet_address...
Then lock the agreement's commitment window and adopt it:
just set-commitment-window
just adopt-agreement
Together these define the rules of engagement (10% bounty, your wallet as the recovery address), lock the terms for a 30-day commitment window — required before attack mode can be requested — and register the agreement so it's live.
Step 5 — Request Attack Mode
Request attack mode for the agreement (you'll be prompted for your keystore password):
just request-attack-mode
Verify the state:
just check-state
| Output | Meaning |
|---|---|
2 | ATTACK_REQUESTED — open for whitehats |
3 | UNDER_ATTACK — a whitehat has approved and is exploiting |
You stop at 2 (ATTACK_REQUESTED). On testnet the MockRegistryModerator is permissionless, so a whitehat's exploit approves the request and drains the vault in a single transaction (state 3) — see Execute Your First Attack. On mainnet, approval is a real DAO governance action.
Once you see 2, your vault is requested for attack and open to whitehats on BattleChain.
What You Accomplished
You deployed a contract, created a Safe Harbor agreement, and opened it to whitehat attack — all on a chain built for exactly this workflow.
- Deployed a vulnerable vault to BattleChain
- Created a Safe Harbor agreement defining scope, bounties, and recovery rules
- Opened the contract for coordinated security testing
The same process applies to real contracts. Protocols that go through BattleChain before shipping know their contracts have been stress-tested by real economic incentives — not just a static review.
Attack Your Vault
Switch to the whitehat side and exploit the vault you just deployed
The Contract Lifecycle
Learn how contracts move from attack mode through to production
Troubleshooting
Forge scripts failing
Add --skip-simulation to any failing forge script command. Forge's local gas estimation doesn't work reliably on BattleChain.
Tell your AI: "All forge script commands need the --skip-simulation flag."
Stuck pending transaction
Tell your AI: "I have a stuck transaction at nonce [N]. Send a replacement with a higher gas price using cast send with --value 0 to clear it."
Out-of-gas failures
If a forge script command fails with a vague error even with --skip-simulation, try adding -g 300 to use 3x the estimated gas.