Battlechain Starter — Hardhat

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

About

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

Getting Started

Requirements

• git
• Node.js >= 22.10.0 — use nvm to manage versions
  • nvm install --lts && nvm use --lts
• just (optional — all commands can be run with npx hardhat directly)

Installation

git clone <MY_REPO>
cd <MY_REPO>
npm install

Import your private key into the encrypted keystore (once):

just import-key
# prompts for a master password, then your private key — never stored in plaintext

Quickstart

just build

Usage

Protocol Role

# Step 1: Deploy MockToken + VulnerableVault, seed the vault
# Copy TOKEN_ADDRESS and VAULT_ADDRESS from output into .env
just setup

# Step 2: Create Safe Harbor agreement (requires VAULT_ADDRESS in .env)
# Copy AGREEMENT_ADDRESS from output into .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)
# Requires TOKEN_ADDRESS, VAULT_ADDRESS, RECOVERY_ADDRESS in .env
just attack

Utilities

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