Battlechain Starter

• About
• Getting Started
  • Requirements
  • Installation
  • Quickstart
• Usage
  • Protocol Role
  • Whitehat Role
  • Utilities

About

A starter repo for interacting with the Battlechain Safe Harbor protocol. Includes scripts for deploying a vulnerable vault, creating a Safe Harbor agreement, requesting attack mode, and executing a whitehat rescue.

Getting Started

Requirements

• git
  • You'll know you did it right if you can run git --version and you see a response like git version x.x.x
• foundry
  • You'll know you did it right if you can run forge --version and you see a response like forge 0.2.0 (816e00b 2023-03-16T00:05:26.396218Z)
  • For browser wallet targets (just *-browser), you need forge >= 1.6.0-nightly (commit c1cdc6c1, 2026-03-10) or later
• just
  • You'll know you did it right if you can run just --version and you see a response like just 1.x.x

Installation

git clone <MY_REPO>
cd <MY_REPO>

Quickstart

just build

Usage

Protocol Role

# Step 1: Deploy MockToken + VulnerableVault, seed the vault
just setup

# Step 2: Create Safe Harbor agreement (requires VAULT_ADDRESS in .env)
just create-agreement

# Step 3: Request attack mode (requires AGREEMENT_ADDRESS in .env)
just request-attack-mode

Whitehat Role

# Step 4: Execute the attack (requires DAO approval first)
just attack

Utilities

# Check agreement state (2=ATTACK_REQUESTED, 3=UNDER_ATTACK)
just check-state

# Run tests
just test