Attacking Contracts: Whitehat Tutorial

A complete tutorial for whitehats on finding, attacking, and earning bounties on BattleChain

This tutorial teaches you the full whitehat workflow on BattleChain — from finding targets to earning bounties — and explains the legal protections that make it possible.

Why BattleChain for Whitehats?

Traditional bug bounties ask you to report vulnerabilities. BattleChain lets you exploit them:

• Legal protection: Safe Harbor agreements protect you from prosecution
• Immediate reward: Keep your bounty from recovered funds (if retainable)
• No coordination required: Attack first, no need for prior disclosure
• Real exploits: Test against contracts with real liquidity, not toy examples

Understanding Safe Harbor

Before attacking, understand what protects you. When a protocol enters attack mode:

1. They've adopted a Safe Harbor agreement committing to not pursue legal action
2. Their contracts are in UNDER_ATTACK or PROMOTION_REQUESTED state
3. You're protected as long as you:
   • Attack in-scope contracts only
   • Keep only your bounty entitlement
   • Meet any identity requirements

Read the full Safe Harbor explanation for details on what is and isn't protected.

Step 1: Find Targets

Check a Specific Contract

bool attackable = attackRegistry.isTopLevelContractUnderAttack(targetContract);

Monitor for New Targets

Watch for AgreementStateChanged events:

event AgreementStateChanged(address indexed agreementAddress, ContractState newState);
// newState = 3 (UNDER_ATTACK) → newly attackable
// newState = 4 (PROMOTION_REQUESTED) → still attackable, 3-day countdown

See How to Find Attackable Contracts for advanced querying techniques.

Step 2: Evaluate the Target

Before investing time in finding exploits, evaluate the opportunity:

address agreementAddr = attackRegistry.getAgreementForContract(targetContract);
IAgreement agreement = IAgreement(agreementAddr);

// Get bounty terms
BountyTerms memory terms = agreement.getBountyTerms();
uint256 bountyPercent = terms.bountyPercentage;
uint256 bountyCap = terms.bountyCapUsd;
bool canRetain = terms.retainable;

Checklist Before Attacking

Step 3: Execute Your Attack

There are no restrictions on exploitation methods for in-scope contracts. Common approaches:

• Reentrancy attacks
• Flash loan exploits
• Oracle manipulation
• Access control bypasses
• Logic errors in state transitions

contract Attacker {
    function attack(address target) external {
        // Your exploit logic
        IVulnerable(target).vulnerableFunction();
    }
}

Step 4: Handle Funds Correctly

This is critical. Mishandling funds can void your Safe Harbor protection.

If Retainable = true

Calculate your bounty and send the rest to the recovery address:

uint256 recovered = address(this).balance;
uint256 bounty = (recovered * bountyPercent) / 100;

// Respect the cap
// Note: Convert bountyCapUsd to token amount using current prices

// Send remainder to recovery
payable(recoveryAddress).transfer(recovered - bounty);
// Keep your bounty

If Retainable = false

Send everything to the recovery address. The protocol pays your bounty separately:

payable(recoveryAddress).transfer(address(this).balance);

Get the Recovery Address

string memory recoveryStr = agreement.getAssetRecoveryAddress("eip155:627");

See How to Claim Bounties for detailed calculation examples.

Step 5: Document Everything

Keep records of:

• Target contract and agreement addresses
• The vulnerability exploited
• All transaction hashes
• Your bounty calculation (show your work)
• Funds sent to recovery address

This protects you if there's ever a dispute about your compliance with the agreement terms.

Important: Mainnet Implications

Summary

Next Steps