external links open in new tabs + AI Quickstart

app/[product]/[...slug]/page.tsx

@@ -20,6 +20,17 @@ import { Pre } from '@/components/mdx/Pre'
 import remarkGfm from 'remark-gfm'
 import rehypePrismPlus from 'rehype-prism-plus'
 
+function MdxLink({ href, ...props }: React.AnchorHTMLAttributes<HTMLAnchorElement>) {
+  const isExternal = href?.startsWith('http://') || href?.startsWith('https://')
+  return (
+    <a
+      href={href}
+      {...(isExternal ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+      {...props}
+    />
+  )
+}
+
 const components = {
   Card,
   CardGroup,
@@ -41,6 +52,7 @@ const components = {
   SnippetIntro,
   BattlechainHero,
   pre: Pre,
+  a: MdxLink,
 }
 
 export const dynamicParams = false;

config/docs.json

@@ -46,6 +46,7 @@
               {
                 "group": "Quickstart",
                 "pages": [
+                  "battlechain/quickstart/ai-quickstart",
                   "battlechain/quickstart/deploy-first-contract",
                   "battlechain/quickstart/execute-first-attack",
                   "battlechain/quickstart/review-first-request",

content/battlechain/quickstart/ai-quickstart.mdx

@@ -0,0 +1,213 @@
+---
+title: "BattleChain in 5 Prompts"
+description: "Deploy a vulnerable contract, open it to whitehat attack, and exploit it yourself — no coding required. Just paste these prompts into Claude Code or any AI coding tool."
+---
+
+<div className="flex items-start gap-4 mb-10 p-5 rounded-xl border border-violet-500/40 bg-violet-950/20">
+  <div className="text-4xl mt-1">🤖</div>
+  <div>
+    <div className="text-xs font-bold uppercase tracking-widest text-violet-400 mb-1">No coding required</div>
+    <div className="text-base font-semibold text-gray-100 mb-1">Your AI is the developer. You're the protocol owner.</div>
+    <div className="text-sm text-gray-400">You'll deploy a real vulnerable contract to BattleChain, open it under a Safe Harbor agreement, then turn around and exploit it yourself — all by pasting prompts into Claude Code.</div>
+  </div>
+</div>
+
+## What You'll Need
+
+Before you start, get two things in order:
+
+**1. An AI coding tool**
+
+This guide is written for [Claude Code](https://claude.ai/claude-code), but the same prompts work with Cursor, Windsurf, or any agent that can run terminal commands. If you don't have one, [install Claude Code](https://docs.anthropic.com/en/docs/claude-code/getting-started) — it takes about two minutes.
+
+**2. A wallet with BattleChain Testnet ETH**
+
+You need an EVM wallet (MetaMask, Rabby, etc.) with a small amount of ETH on BattleChain Testnet. Here's how to get it:
+
+1. **Add BattleChain to your wallet**
+
+| Field | Value |
+|-------|-------|
+| Network Name | BattleChain Testnet |
+| RPC URL | `https://testnet.battlechain.com:3051` |
+| Chain ID | `627` |
+
+2. **Get free Sepolia ETH** from the [Google Cloud faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) — paste your address and request some. 0.05 ETH is plenty.
+
+3. **Bridge to BattleChain** at [portal.battlechain.com/bridge](https://portal.battlechain.com/bridge) — select Sepolia → BattleChain Testnet and bridge your ETH over.
+
+Once your BattleChain balance shows ETH, you're ready.
+
+---
+
+## Before the First Prompt — Import Your Key
+
+Your AI will be running transactions on your behalf, but it should never touch your private key. Foundry's encrypted keystore handles signing locally — you import your key once, set a password, and from that point your AI just asks for the password when it needs to sign.
+
+Do this step yourself in a terminal **before** starting the prompts:
+
+```bash
+cast wallet import battlechain --interactive
+```
+
+You'll be asked to 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 or passed to any tool.
+
+Verify it worked:
+
+```bash
+cast wallet list
+```
+
+You should see `battlechain` listed. From here on, your AI will prompt you for the password when it needs to sign a transaction — that's the only thing you need to provide.
+
+---
+
+## How This Works
+
+You're going to paste five prompts into your AI tool. Each one does a concrete thing: set up the project, deploy your contracts, create a Safe Harbor agreement, open for attack, then exploit the vault and collect the bounty.
+
+Your AI handles all the commands. You enter your keystore password when prompted — that's it.
+
+**Optional: give your AI a head start**
+
+If you run this in an existing project folder, drop in the BattleChain context file first so your AI already knows the workflow, contract addresses, and gotchas without needing the docs URL in every prompt:
+
+```bash
+curl -o CLAUDE.md https://docs.battlechain.com/CLAUDE.md
+```
+
+Then open Claude Code in that folder — it will load the file automatically.
+
+---
+
+## Prompt 1 — Setup
+
+Open Claude Code in a new empty folder and paste this:
+
+```
+Read https://docs.battlechain.com/llms-full.txt to understand BattleChain, then do the following:
+
+1. Clone https://github.com/Cyfrin/battlechain-starter into the current directory
+2. cd into it and run `forge install`
+3. Copy .env.example to .env and set SENDER_ADDRESS to my wallet address
+
+My wallet address is: [paste your wallet address here]
+```
+
+<Check>
+When setup is done, confirm your wallet address is set in `.env` and `forge install` completed without errors.
+</Check>
+
+---
+
+## Prompt 2 — Deploy
+
+```
+Run `just setup` to deploy MockToken and VulnerableVault to BattleChain Testnet.
+Make sure all forge script calls use --legacy (BattleChain Testnet requires it).
+After deployment, add TOKEN_ADDRESS and VAULT_ADDRESS to my .env file.
+```
+
+You'll be prompted for your keystore password. Enter it to sign the transaction.
+
+Expected output from your AI:
+
+```
+MockToken deployed: 0x...
+VulnerableVault deployed: 0x...
+Vault seeded with 1000 tokens
+```
+
+<Check>
+Search your `VAULT_ADDRESS` on the [BattleChain explorer](https://explorer.testnet.battlechain.com/) — you should see the deployment transaction and the vault's token balance.
+</Check>
+
+---
+
+## Prompt 3 — Create a Safe Harbor Agreement
+
+```
+Run `just create-agreement` to create a Safe Harbor agreement for the deployed vault.
+Use --legacy for all forge script calls.
+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 for whitehats: 10% bounty, 30-day commitment window, your wallet as the recovery address for any returned funds.
+
+<Check>
+Search your `AGREEMENT_ADDRESS` on the [BattleChain explorer](https://explorer.testnet.battlechain.com/) to see the agreement contract and its creation transaction.
+</Check>
+
+---
+
+## Prompt 4 — Open for Attack
+
+```
+Run `just request-attack-mode` to submit the vault for DAO review.
+Then poll with `just check-state` every few minutes until you see state 3.
+State 2 means waiting for DAO approval. State 3 means approved and open for attack.
+```
+
+The DAO checks that your contract is a new deployment (not a mainnet copy) and that the terms are reasonable. On testnet this typically takes a few hours. Reach out in [Discord](https://discord.gg/cyfrin) if you're waiting.
+
+<Note>
+While you wait, this is a good time to read [what the exploit actually does](/battlechain/quickstart/execute-first-attack#understand-the-exploit). You'll see the reentrancy vulnerability in the vault code — the same bug class that's drained hundreds of millions from real protocols.
+</Note>
+
+Once your AI reports `3`, your vault is live and open. Whitehats on BattleChain can now attempt to drain it. You're about to become one of them.
+
+---
+
+## Prompt 5 — Execute the Attack
+
+```
+Run `just attack` to execute the reentrancy exploit against the vault.
+```
+
+Watch the output:
+
+```
+Vault balance before: 1000 tokens
+Deploying attacker...
+
+--- Vault drained ---
+Vault before:          1000 tokens
+Vault after:              0 tokens
+Bounty kept:            100 tokens
+Returned to protocol:   900 tokens
+```
+
+<Check>
+Search your `VAULT_ADDRESS` on the [BattleChain explorer](https://explorer.testnet.battlechain.com/) — you'll see the attack transaction, the vault balance drop to zero, and the bounty transfer to your wallet.
+</Check>
+
+---
+
+## What Just Happened
+
+You played both sides of a BattleChain engagement in one session:
+
+- **As the protocol**: you deployed a vulnerable contract, created a Safe Harbor agreement, and opened it to whitehat attack
+- **As the whitehat**: you identified the vulnerability and exploited it under legal, structured terms
+
+The same workflow applies to real mainnet deployments. Protocols that go through BattleChain before shipping know their contracts have been stress-tested by real economic incentives — not just a static review.
+
+If you want to go deeper on either side, see:
+- [Deploy Your First Contract](/battlechain/quickstart/deploy-first-contract) — the full protocol walkthrough with technical detail
+- [Execute Your First Attack](/battlechain/quickstart/execute-first-attack) — the whitehat walkthrough with exploit mechanics
+
+---
+
+## Troubleshooting
+
+### My AI is running commands but transactions keep failing
+
+Add `--legacy` to any failing `forge script` command. BattleChain Testnet doesn't support EIP-1559 — all transactions must use legacy format. Tell your AI: *"All forge script commands need the --legacy flag."*
+
+### I have a 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."* You can find your pending nonce by looking at your wallet or searching your address on the [explorer](https://explorer.testnet.battlechain.com/).
+
+### Claude Code is asking about things I don't understand
+
+That's fine — just tell it you're not a developer and ask it to handle the technical details. Claude Code is designed to work autonomously. You only need to provide your wallet address and enter your keystore password when prompted.

content/battlechain/quickstart/configure-ai-tools.mdx

@@ -43,6 +43,16 @@ Full documentation: https://docs.battlechain.com/llms-full.txt
 - Read the BattleChain documentation before writing deploy or agreement scripts
 ```
 
+## Quickstart: Download the Pre-Built File
+
+Rather than copy-pasting, you can download a ready-made configuration file that includes the full workflow, contract addresses, network info, and critical gotchas:
+
+```bash
+curl -o CLAUDE.md https://docs.battlechain.com/CLAUDE.md
+```
+
+This works for Claude Code out of the box. For other tools, rename the file to match the table below and drop it in your project root.
+
 ## Where to Add It
 
 Each AI tool reads instructions from a different file. Add the prompt above to whichever tools your team uses:

public/CLAUDE.md

@@ -0,0 +1,118 @@
+# BattleChain
+
+BattleChain is a pre-mainnet L2 where protocols deploy their contracts under a Safe Harbor agreement and whitehats legally attack them for bounties. The goal is to find vulnerabilities before mainnet with real economic incentives — not just a static audit.
+
+Full documentation: https://docs.battlechain.com/llms-full.txt
+
+---
+
+## Network
+
+| Field | Value |
+|-------|-------|
+| Chain ID | `627` |
+| RPC | `https://testnet.battlechain.com:3051` |
+| Explorer | `https://explorer.testnet.battlechain.com` |
+| Bridge | `https://portal.battlechain.com/bridge` (Sepolia → BattleChain) |
+
+---
+
+## Deployed Contracts (Testnet)
+
+| Contract | Address |
+|----------|---------|
+| AttackRegistry (Proxy) | `0x9E62988ccA776ff6613Fa68D34c9AB5431Ce57e1` |
+| SafeHarborRegistry (Proxy) | `0xCb2A561395118895e2572A04C2D8AB8eCA8d7E5D` |
+| AgreementFactory (Proxy) | `0x0EbBEeB3aBeF51801a53Fdd1fb263Ac0f2E3Ed36` |
+| BattleChainDeployer | `0x8f57054CBa2021bEE15631067dd7B7E0B43F17Dc` |
+
+---
+
+## Workflow
+
+1. **Deploy** contracts via `BattleChainDeployer` — this registers them with `AttackRegistry` automatically
+2. **Create a Safe Harbor agreement** via `AgreementFactory` — defines scope, bounty terms, and recovery address
+3. **Extend commitment window** — minimum 30 days (`agreement.extendCommitmentWindow(block.timestamp + 30 days)`)
+4. **Adopt Safe Harbor** — `safeHarborRegistry.adoptSafeHarbor(agreementAddress)`
+5. **Request attack mode** — `attackRegistry.requestUnderAttack(agreementAddress)` → state becomes `ATTACK_REQUESTED`
+6. **DAO approves** → state becomes `UNDER_ATTACK` — whitehats can now attack
+7. **Promote to production** — `attackRegistry.promote(agreementAddress)` → 3-day countdown, then `PRODUCTION`
+8. **Deploy to mainnet**
+
+---
+
+## Contract States
+
+| Value | State | Meaning |
+|-------|-------|---------|
+| `0` | `INACTIVE` | Not registered |
+| `1` | `REGISTERED` | Deployed, no agreement yet |
+| `2` | `ATTACK_REQUESTED` | Awaiting DAO approval |
+| `3` | `UNDER_ATTACK` | Approved — whitehats can attack |
+| `4` | `PROMOTING` | 3-day promotion countdown |
+| `5` | `PRODUCTION` | Battle-tested, ready for mainnet |
+
+---
+
+## Critical Requirements
+
+### Always use `--legacy`
+BattleChain Testnet does not support EIP-1559. Every `forge script` call must include `--legacy` or the transaction will fail.
+
+```bash
+forge script script/Deploy.s.sol --rpc-url https://testnet.battlechain.com:3051 --account battlechain --broadcast --legacy
+```
+
+### Gas estimation
+Forge estimates gas locally and consistently underestimates for BattleChain. If a transaction fails without a clear reason, retry with `-g 300` (3× gas multiplier) or `--skip-simulation`.
+
+### Private keys
+Never write a private key to a file or environment variable. Use Foundry's encrypted keystore:
+
+```bash
+# Import once
+cast wallet import battlechain --interactive
+
+# Use in scripts
+forge script ... --account battlechain
+```
+
+The keystore lives at `~/.foundry/keystores/battlechain`. The user will be prompted for their password at signing time.
+
+---
+
+## Starter Repo
+
+```bash
+git clone https://github.com/Cyfrin/battlechain-starter
+cd battlechain-starter
+forge install
+```
+
+### Justfile commands
+
+| Command | Action |
+|---------|--------|
+| `just setup` | Deploy MockToken + VulnerableVault, seed vault |
+| `just create-agreement` | Create Safe Harbor agreement |
+| `just request-attack-mode` | Submit for DAO review |
+| `just check-state` | Poll agreement state (`2` = pending, `3` = open) |
+| `just attack` | Execute reentrancy exploit and collect bounty |
+
+### `.env` structure
+
+```bash
+SENDER_ADDRESS=0x...          # Your public wallet address — never the private key
+TOKEN_ADDRESS=                # Set after: just setup
+VAULT_ADDRESS=                # Set after: just setup
+AGREEMENT_ADDRESS=            # Set after: just create-agreement
+RECOVERY_ADDRESS=             # Set to your wallet address
+```
+
+---
+
+## Rules
+
+- **Never deploy directly to mainnet** without going through BattleChain first
+- **Always use `BattleChainDeployer`** for deployments — direct deployment bypasses `AttackRegistry` registration
+- **Read the docs** before writing deployment or agreement scripts: https://docs.battlechain.com/llms-full.txt