Quickstart
Deploy a vulnerable contract to BattleChain and open it for whitehat attack.
Deploy a vulnerable vault, create a Safe Harbor agreement, and open it for attack — the core BattleChain workflow. Pick your path and follow along.
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
A Test Wallet
You need a dedicated wallet for BattleChain testing — do not use a wallet that holds real funds.
Fund Your Test Wallet
1. Add BattleChain to your wallet
BattleChain Testnet
| Network Name | BattleChain Testnet |
| Chain ID | 627 |
| RPC URL | https://testnet.battlechain.com:3051 |
| Explorer | https://explorer.testnet.battlechain.com/ |
| Currency | ETH |
| CAIP-2 ID | eip155:627 |
2. Get free Sepolia ETH from the Google Cloud faucet — 0.05 ETH is plenty.
3. Bridge to BattleChain at portal.battlechain.com/bridge — select Sepolia to BattleChain Testnet and bridge your ETH.
Once your BattleChain balance shows ETH, you're ready.
Your Tool
An AI coding tool with terminal access. This guide uses Claude Code, but the same prompts work in Cursor, Windsurf, Codex, or any agent that can run terminal commands.
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 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 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
Run `just setup` to deploy MockToken and VulnerableVault to BattleChain Testnet.
After deployment, add TOKEN_ADDRESS and VAULT_ADDRESS to my .env file.
Then, give me the explorer link with the deployed vault, and give me the vault address.
Enter your keystore password when prompted.
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.
Ask your AI for the explorer link — it has the vault address from the deploy output. You should see the deployment transaction and the vault's token balance on the BattleChain explorer.
Step 4 — Create a Safe Harbor Agreement
Run `just create-agreement` to create a Safe Harbor agreement for the deployed vault.
After it runs, add AGREEMENT_ADDRESS to .env and set RECOVERY_ADDRESS to my wallet address.
This creates an on-chain agreement that defines the rules of engagement: 10% bounty, 30-day commitment window, your wallet as the recovery address for returned funds.
Step 5 — Open for Attack
Do the following in order:
1. Run `just request-attack-mode` to submit the vault for DAO review
2. On testnet, approve the request immediately using the MockRegistryModerator:
cast send 0x6C2DFbdF0714FC8CE065039911758b2821818745 "approveAttack(address)" $AGREEMENT_ADDRESS --account battlechain --rpc-url https://testnet.battlechain.com:3051 --legacy
3. Run `just check-state` and confirm the output is 3
On testnet, the MockRegistryModerator lets you approve your own request immediately. On mainnet, this is a real DAO governance action.
Once you see 3, your vault is live and attackable. Whitehats on BattleChain can now attempt to drain it.
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 Tutorial
Now exploit the vault you just deployed
Configure AI Tools
Add BattleChain context to your AI tools so they deploy here by default
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 --legacy and --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.