fix: repair fresh npm install + document that local forking is unsupported

README.md

@@ -10,7 +10,7 @@
   - [Whitehat Role](#whitehat-role)
   - [Utilities](#utilities)
 - [Address tracking](#address-tracking)
-- [Local development against a forked node](#local-development-against-a-forked-node)
+- [Local development (forking is not supported)](#local-development-forking-is-not-supported)
 
 # About
 
@@ -132,28 +132,45 @@ deployment-tracking mechanisms**:
 | Safe Harbor agreement| On-chain registry lookup                        | Comes back from a factory call; looked up via `BCSafeHarborRegistry.getAgreement(adopter)` where `adopter = signer.address`.                              |
 | `RECOVERY_ADDRESS`   | `.env`                                          | The user's own wallet — not something a script can derive (only used by `attack.ts`).                                                                     |
 
-# Local development against a forked node
+# Local development (forking is not supported)
 
-The default network (`default`) is Hardhat's built-in in-process EDR-simulated
-node. With `BATTLECHAIN_FORK=1`, it forks BattleChain testnet so the
-`BCDeployer`, `Registry`, `AttackRegistry`, and `MockRegistryModerator` are all
-reachable. The hardhat config also pins `chainId: 627` on the fork so the lib
-resolves the canonical addresses without needing manual `setOverrides()`.
+> **Heads-up:** you cannot run this demo against a *local fork* of BattleChain.
+> The `BATTLECHAIN_FORK` / `just node-fork` paths are left in the config only to
+> document the attempt — they do **not** work. Run the end-to-end flow against
+> the **live testnet** instead (every step below, with `--network battlechain`).
 
-For multi-step flows that need persistent state across `npx hardhat run`
-invocations:
+**Why forking fails.** BattleChain is a [ZK rollup built on ZKsync OS](https://docs.battlechain.com/battlechain/reference/architecture),
+not a vanilla Ethereum L1. Hardhat's node (EDR) forks by pinning a block and
+then lazily fetching state *at that block* over JSON-RPC. BattleChain's RPC
+can't serve what EDR needs:
+
+- **Historical state is pruned.** `eth_getCode` / `eth_getBalance` return data
+  only for roughly the last ~30 blocks; older blocks come back empty. EDR pins a
+  block at startup, so as the chain advances every forked state read returns `0x`.
+- **`eth_getProof` is unsupported** — the node rejects it with *"unsupported as
+  ZKsync OS has a different storage layout than Ethereum."*
+
+The net effect: on a fork, every BattleChain contract (`BCDeployer`, `Registry`,
+`AttackRegistry`, …) reads back as **empty code**, so the first `bc.bcDeploy(...)`
+fails with a `BAD_DATA` `could not decode result data (value="0x")` error. No
+Hardhat hardfork/chainType setting changes this — it's a property of the chain's
+RPC, not the config. (Forking a ZKsync chain needs ZKsync-aware tooling such as
+`anvil-zksync`, and even that hits the same state-pruning limit.)
+
+**What to do instead — run against the live testnet.** It's free (testnet gas)
+and the only path that exercises the real protocol contracts:
 
 ```bash
-# Terminal 1 — long-lived forked node
-just node-fork    # BATTLECHAIN_FORK=1 npx hardhat node
-
-# Terminal 2 — every step against the same node
-NETWORK=localhost just setup
-NETWORK=localhost just create-agreement
-NETWORK=localhost just request-attack-mode
-NETWORK=localhost just approve-attack
-NETWORK=localhost just attack
+just import-key                 # once: store PRIVATE_KEY in the encrypted keystore
+NETWORK=battlechain just all    # full flow end-to-end on the live testnet
 ```
 
-For single-shot end-to-end testing, prefer `BATTLECHAIN_FORK=1 just all` — one
-process, no terminal-juggling.
+Or step-by-step:
+
+```bash
+NETWORK=battlechain just setup
+NETWORK=battlechain just create-agreement
+NETWORK=battlechain just request-attack-mode
+NETWORK=battlechain just approve-attack
+NETWORK=battlechain just attack
+```

hardhat.config.ts

@@ -61,13 +61,13 @@ export default defineConfig({
     requiredConfirmations: 1,
   },
   networks: {
-    // Override Hardhat's built-in "default" network (edr-simulated, chainId 31337)
-    // so that BATTLECHAIN_FORK=1 forks BattleChain testnet — making the
-    // BCDeployer / Registry / AttackRegistry reachable for local-first work.
-    //
-    // When forking, we ALSO set the local chainId to 627 (BattleChain testnet)
-    // so @cyfrin/battlechain-lib-js resolves to the canonical BCDeployer / Registry /
-    // AttackRegistry addresses without needing manual overrides.
+    // ⚠️ Local forking of BattleChain is NOT supported — see README
+    // ("Local development against a forked node"). BattleChain is a ZKsync OS
+    // rollup: its RPC prunes state to ~the last ~30 blocks and does not implement
+    // eth_getProof, so Hardhat/EDR can't fork it (every forked contract reads back
+    // as empty code, and `bcDeploy` fails with a BAD_DATA "0x" decode error).
+    // The BATTLECHAIN_FORK branch is kept only so the wiring is visible; run the
+    // real end-to-end flow against the live testnet instead (`--network battlechain`).
     default: process.env["BATTLECHAIN_FORK"]
       ? {
           type: "edr-simulated",