diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index 11bd220..2340696 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -8,7 +8,7 @@ Docker Compose services (in startup order): | Service | Purpose | Port | Health Check | |---------|---------|------|-------------| -| **anvil** | Local Ethereum fork (Base Sepolia) | 8545 | JSON-RPC response | +| **anvil** | Local Ethereum fork (Base Sepolia by default; override with `FORK_URL`) | 8545 | JSON-RPC response | | **postgres** | Ponder database | 5432 | pg_isready | | **bootstrap** | Deploys contracts to anvil | — | One-shot, exits 0 | | **ponder** | On-chain indexer + GraphQL API | 42069 | HTTP /ready or GraphQL | @@ -18,6 +18,46 @@ Docker Compose services (in startup order): | **caddy** | Reverse proxy / TLS | 80/443 | — | | **otterscan** | Block explorer | 5100 | — | +## Network Contexts + +Two network contexts are relevant: the dev-stack Anvil (docker-compose) and the backtesting tools that require Base mainnet. + +### Dev stack Anvil (docker-compose) + +The `anvil` service in `docker-compose.yml` runs `containers/anvil-entrypoint.sh`, which forks: + +``` +${FORK_URL:-https://sepolia.base.org} +``` + +**Default: Base Sepolia.** The `bootstrap` service deploys all KRAIKEN protocol contracts (Kraiken, Stake, Optimizer, LiquidityManager) and creates a new KRK/WETH pool using the existing Uniswap V3 Factory already present on the forked network. Addresses are written to `tmp/containers/contracts.env`. + +To fork Base mainnet instead (required for red-team / backtesting — see below): + +```bash +FORK_URL=https://mainnet.base.org docker compose up -d +``` + +### Backtesting / red-team (`scripts/harb-evaluator/red-team.sh`) + +`red-team.sh` boots the docker-compose stack and then calls protocol operations using **Base mainnet** addresses for the Uniswap V3 periphery (V3_FACTORY, SwapRouter02, NonfungiblePositionManager). These addresses are only valid on a mainnet fork. + +`red-team.sh` calls `sudo docker compose up -d` internally. The script uses `sudo -E` so that `FORK_URL` is preserved across the sudo boundary: + +```bash +FORK_URL=https://mainnet.base.org bash scripts/harb-evaluator/red-team.sh +``` + +### FitnessEvaluator (`onchain/test/FitnessEvaluator.t.sol`) + +`FitnessEvaluator.t.sol` does **not** use Anvil. It uses Foundry's native revm backend (`vm.createSelectFork`) to fork Base mainnet in-process — no docker-compose dependency: + +```bash +BASE_RPC_URL=https://mainnet.base.org \ +FITNESS_MANIFEST_DIR=/tmp/manifest \ +forge test --match-contract FitnessEvaluator --match-test testBatchEvaluate -vv +``` + ## Quick Start ```bash diff --git a/scripts/harb-evaluator/red-team.sh b/scripts/harb-evaluator/red-team.sh index 8b51d81..9d8e784 100755 --- a/scripts/harb-evaluator/red-team.sh +++ b/scripts/harb-evaluator/red-team.sh @@ -63,11 +63,13 @@ cd "$REPO_ROOT" sudo sh -c 'echo 3 > /proc/sys/vm/drop_caches' 2>/dev/null || true # Tear down completely (volumes too — clean anvil state) -sudo docker compose down -v >/dev/null 2>&1 || true +sudo -E docker compose down -v >/dev/null 2>&1 || true sleep 3 # Bring up -sudo docker compose up -d >/dev/null 2>&1 \ +# -E preserves FORK_URL (and other env vars) across the sudo boundary so that +# anvil-entrypoint.sh honours the caller's FORK_URL override. +sudo -E docker compose up -d >/dev/null 2>&1 \ || die "docker compose up -d failed" # Wait for bootstrap to complete (max 120s)