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 setup

Enter your keystore password when prompted. Expected output:

MockToken deployed: 0x...
VulnerableVault deployed: 0x...
Vault seeded with 1000 tokens

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.

✅

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...
Commitment window extended 30 days
Safe Harbor adopted

Copy AGREEMENT_ADDRESS into your .env and set RECOVERY_ADDRESS to your wallet address:

AGREEMENT_ADDRESS=0x...
RECOVERY_ADDRESS=0x...your_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

Run these commands yourself in your terminal (each will prompt for your keystore password):

just request-attack-mode

On testnet, the DAO moderator is a permissionless contract — approve your own request immediately:

cast send 0x1bC64E6F187a47D136106784f4E9182801535BD3 \
  "approveAttack(address)" $AGREEMENT_ADDRESS \
  --account battlechain \
  --rpc-url https://testnet.battlechain.com

Verify the state:

just check-state
OutputMeaning
2ATTACK_REQUESTED — waiting for DAO
3UNDER_ATTACK — approved, vault is open
ℹ️

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 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.