Add docs on isAttackable() util in battlechain-lib

content/battlechain/how-to/find-attackable-contracts.mdx

@@ -11,15 +11,36 @@ You can view agreement statuses and contracts currently under scope on the [Batt
 
 ## Check a Specific Contract
 
+The easiest way to check whether a contract is attackable is with `isAttackable` from `battlechain-lib`. It queries the block explorer API and handles the full scope hierarchy — including child contracts spawned by in-scope factories.
+
+**Standalone usage** (lightweight, no deploy/agreement overhead):
+
 ```solidity
-bool attackable = attackRegistry.isTopLevelContractUnderAttack(contractAddress);
+import { BCQuery } from "battlechain-lib/BCQuery.sol";
 
-if (attackable) {
-    // Safe Harbor protection applies
-    // Contract is in UNDER_ATTACK or PROMOTION_REQUESTED state
+contract CheckTarget is BCQuery {
+    function run() external {
+        bool attackable = isAttackable(targetAddress);
+
+        if (attackable) {
+            // Contract is covered by an agreement in UNDER_ATTACK or PROMOTION_REQUESTED state
+        }
+    }
 }
 ```
 
+If you're already using `BCScript` for the full deploy + agreement flow, `isAttackable` is available directly — `BCScript` inherits `BCQuery`.
+
+Run with the `--ffi` flag since the function uses `vm.ffi` to call the explorer API:
+
+```bash
+forge script script/CheckTarget.s.sol --ffi --rpc-url https://testnet.battlechain.com
+```
+
+<Note>
+`isAttackable` requires `--ffi` and `curl` on your PATH. For on-chain-only contexts where `vm.ffi` isn't available, you can use `attackRegistry.isTopLevelContractUnderAttack(address)` — but this only checks top-level contracts and will miss child contracts spawned by in-scope factories.
+</Note>
+
 ## Monitor for New Targets
 
 Watch for `AgreementStateChanged` events:

content/battlechain/quickstart/execute-first-attack.mdx

@@ -102,7 +102,7 @@ On BattleChain, any contract in **attack mode** (state `3` — `UNDER_ATTACK`) i
 **For this quickstart**, you'll attack a pre-built vulnerable vault from the starter repo. In the real world, you'd find targets through the explorer or on-chain queries.
 
 <Tip>
-**Finding real targets:** Browse all currently attackable agreements on the [BattleChain explorer](https://explorer.testnet.battlechain.com/agreements?page=1&state=UNDER_ATTACK). You can also query the [explorer API](https://block-explorer-api.testnet.battlechain.com/docs) programmatically — use `GET /battlechain/agreement/by-contract/:address` to check if a specific contract is in scope, or `GET /battlechain/agreement/:address` to see all covered contracts for an agreement. For on-chain querying via the `AttackRegistry`, see [How to Find Attackable Contracts](/battlechain/how-to/find-attackable-contracts).
+**Finding real targets:** Browse all currently attackable agreements on the [BattleChain explorer](https://explorer.testnet.battlechain.com/agreements?page=1&state=UNDER_ATTACK). To check a specific contract programmatically, use `isAttackable(address)` from `battlechain-lib` — it handles the full scope hierarchy including child contracts. See [How to Find Attackable Contracts](/battlechain/how-to/find-attackable-contracts) for details and usage examples.
 </Tip>
 
 If you just completed [Deploy and Battle-Test Your Contract](/battlechain/quickstart/deploy-your-contract), your vault is already set up — skip to Step 2.

public/CLAUDE.md

@@ -95,9 +95,10 @@ remappings = [
 
 | Contract       | Use when you need                                                 |
 | -------------- | ----------------------------------------------------------------- |
-| `BCScript`     | Full lifecycle: deploy + agreement + attack mode                  |
+| `BCScript`     | Full lifecycle: deploy + agreement + attack mode + query           |
 | `BCDeploy`     | Deploy only (via CreateX on any chain, BattleChainDeployer on BC) |
 | `BCSafeHarbor` | Agreement creation only                                           |
+| `BCQuery`      | Query helpers only (`isAttackable` via explorer API, requires `--ffi`) |
 
 ### Key helpers
 
@@ -111,6 +112,7 @@ remappings = [
 | `requestAttackMode(agreement)`                                 | Enter attack mode (BattleChain only — reverts on other chains)              |
 | `_isBattleChain()`                                             | Runtime check: `true` on chain IDs 626, 627                                 |
 | `getDeployedContracts()`                                       | All addresses deployed this session via `bcDeploy*`                         |
+| `isAttackable(address)`                                        | Check if a contract is covered by an attackable Safe Harbor agreement (requires `--ffi`) |
 
 ### Example script (works on any chain)
 

public/llms-full.txt

@@ -694,7 +694,7 @@ On BattleChain, any contract in **attack mode** (state `3` — `UNDER_ATTACK`) i
 
 **For this quickstart**, you'll attack a pre-built vulnerable vault from the starter repo. In the real world, you'd find targets through the explorer or on-chain queries.
 
-> **Tip:** **Finding real targets:** Browse all currently attackable agreements on the [BattleChain explorer](https://explorer.testnet.battlechain.com/agreements?page=1&state=UNDER_ATTACK). You can also query the [explorer API](https://block-explorer-api.testnet.battlechain.com/docs) programmatically — use `GET /battlechain/agreement/by-contract/:address` to check if a specific contract is in scope, or `GET /battlechain/agreement/:address` to see all covered contracts for an agreement. For on-chain querying via the `AttackRegistry`, see [How to Find Attackable Contracts](https://docs.battlechain.com/battlechain/how-to/find-attackable-contracts).
+> **Tip:** **Finding real targets:** Browse all currently attackable agreements on the [BattleChain explorer](https://explorer.testnet.battlechain.com/agreements?page=1&state=UNDER_ATTACK). To check a specific contract programmatically, use `isAttackable(address)` from `battlechain-lib` — it handles the full scope hierarchy including child contracts. See [How to Find Attackable Contracts](https://docs.battlechain.com/battlechain/how-to/find-attackable-contracts) for details and usage examples.
 
 If you just completed [Deploy and Battle-Test Your Contract](https://docs.battlechain.com/battlechain/quickstart/deploy-your-contract), your vault is already set up — skip to Step 2.
 
@@ -2789,15 +2789,34 @@ You can view agreement statuses and contracts currently under scope on the [Batt
 
 ## Check a Specific Contract
 
+The easiest way to check whether a contract is attackable is with `isAttackable` from `battlechain-lib`. It queries the block explorer API and handles the full scope hierarchy — including child contracts spawned by in-scope factories.
+
+**Standalone usage** (lightweight, no deploy/agreement overhead):
+
 ```solidity
-bool attackable = attackRegistry.isTopLevelContractUnderAttack(contractAddress);
+import { BCQuery } from "battlechain-lib/BCQuery.sol";
 
-if (attackable) {
-    // Safe Harbor protection applies
-    // Contract is in UNDER_ATTACK or PROMOTION_REQUESTED state
+contract CheckTarget is BCQuery {
+    function run() external {
+        bool attackable = isAttackable(targetAddress);
+
+        if (attackable) {
+            // Contract is covered by an agreement in UNDER_ATTACK or PROMOTION_REQUESTED state
+        }
+    }
 }
 ```
 
+If you're already using `BCScript` for the full deploy + agreement flow, `isAttackable` is available directly — `BCScript` inherits `BCQuery`.
+
+Run with the `--ffi` flag since the function uses `vm.ffi` to call the explorer API:
+
+```bash
+forge script script/CheckTarget.s.sol --ffi --rpc-url https://testnet.battlechain.com
+```
+
+> **Note:** `isAttackable` requires `--ffi` and `curl` on your PATH. For on-chain-only contexts where `vm.ffi` isn't available, you can use `attackRegistry.isTopLevelContractUnderAttack(address)` — but this only checks top-level contracts and will miss child contracts spawned by in-scope factories.
+
 ## Monitor for New Targets
 
 Watch for `AgreementStateChanged` events:

public/search-index.json

@@ -170,7 +170,7 @@
   {
     "id": "/battlechain/how-to/find-attackable-contracts",
     "title": "How to Find Attackable Contracts",
-    "content": "Overview The AttackRegistry tracks which contracts are in attack mode. This guide shows how to find and verify targets. You can view agreement statuses and contracts currently under scope on the BattleChain explorer. Check a Specific Contract Monitor for New Targets Watch for AgreementStateChanged events: Get Agreement Details Verify Agreement Validity Always verify before attacking: Check Time Remaining For contracts in PROMOTION_REQUESTED: Red Flags Be cautious of: - Suspiciously high bounties - Very new agreements (less community vetting) - Missing contact details - Contracts identical to mainnet protocols Next: Execute your attack properly",
+    "content": "Overview The AttackRegistry tracks which contracts are in attack mode. This guide shows how to find and verify targets. You can view agreement statuses and contracts currently under scope on the BattleChain explorer. Check a Specific Contract The easiest way to check whether a contract is attackable is with isAttackable from battlechain-lib. It queries the block explorer API and handles the full scope hierarchy — including child contracts spawned by in-scope factories. Standalone usage (lightweight, no deploy/agreement overhead): If you're already using BCScript for the full deploy + agreement flow, isAttackable is available directly — BCScript inherits BCQuery. Run with the --ffi flag since the function uses vm.ffi to call the explorer API: isAttackable requires --ffi and curl on your PATH. For on-chain-only contexts where vm.ffi isn't available, you can use attackRegistry.isTopLevelContractUnderAttack(address) — but this only checks top-level contracts and will miss child contracts s",
     "url": "/battlechain/how-to/find-attackable-contracts",
     "category": "battlechain",
     "headings": [
@@ -493,11 +493,6 @@
     "content": "Get Started The Problem Web3 has a fundamental gap in its development lifecycle. Code goes from audit to mainnet with nothing in between — and the industry pays for it. Projects go from $0 to $5M TVL overnight after an audit. Bug bounties don't attract serious testing. The industry loses billions to preventable exploits. Web3 Today Dev → Testnet → Mainnet Testnet uses fake money. Bugs are discovered after millions are at risk. With BattleChain Dev → Testnet → BattleChain → Mainnet Real funds, controlled risk. Bugs are found before they matter. How It Works BattleChain is a pre-mainnet, post-testnet environment with real funds. Protocols deploy audited contracts, whitehats legally attack them for bounties, and battle-tested contracts promote to mainnet with confidence. 1 Audit Get your contracts reviewed 2 Deploy Deploy contracts to BattleChain 3 Stress Test Whitehats attack under Safe Harbor 4 Promote DAO approves battle-tested contracts 5 Mainnet Ship with confidence Every contract on",
     "url": "/overview",
     "category": "overview.mdx",
-    "headings": [
-      "How It Works",
-      "Why an L2?",
-      "Learn More",
-      "Build with AI"
-    ]
+    "headings": ["How It Works", "Why an L2?", "Learn More", "Build with AI"]
   }
-]
+]