From dcf66ec1b3e64433ebe788944de076e8d5b6b1d2 Mon Sep 17 00:00:00 2001 From: Anton Sauchyk Date: Wed, 29 Jul 2026 15:38:47 +0200 Subject: [PATCH] docs(agents): correct stale layer chain, ruff baseline, and fund-spending script rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified every claim in CLAUDE.md against the code after the recent debugging, IDL, bot, and learning-example updates. Four were wrong: - The dependency chain listed `utils` before `interfaces`, but utils/idl_manager.py imports interfaces.core and interfaces imports nothing internal. It also made trading and monitoring peers when trading imports monitoring, and omitted cleanup and geyser entirely. - Ruff baseline said ~2400 errors; `uv run ruff check` reports 1676. - `live_*` was presented as the marker for scripts that spend real funds. Only 2 of the 13 scripts that submit transactions carry that prefix — manual_*, mint_and_buy* and cleanup_accounts.py spend too. - compare_listeners.py was cited without its path, ambiguous against listen-migrations/compare_migration_listeners.py. The protocol section (v2 account counts, BondingCurve offsets, PumpSwap i128, PDA seeds, fee-recipient sets, tx-status rules) checks out against idl/pump_fun_idl.json and src/; both offline verifiers still pass. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 65a8f26..c12d1aa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,7 +30,12 @@ Don't "fix" an example by rewiring it to import the bot. Dependency layers, low to high — don't introduce an upward import: -`utils` → `interfaces` → `core` → `platforms` → `trading` / `monitoring` → `bot_runner` +`interfaces` → `utils` → `core` → `platforms` → `monitoring` → `trading` → `bot_runner` + +`interfaces` is the leaf — it imports nothing internal, and `utils/idl_manager.py` +imports `interfaces.core`. `geyser` holds only generated stubs and likewise +imports nothing internal; `cleanup` sits on `core`/`utils` and is pulled in by +`trading`. Platform differences are resolved through `interfaces/core.py` abstractions (`AddressProvider`, curve manager, event parser, instruction builder) and a @@ -52,8 +57,12 @@ platform-agnostic (`Universal*`); anything platform-shaped belongs under `decode_from_getTransaction.py`. - Fixtures are `raw__from_.json` next to the script that reads them, under the same rules. -- `live_*` marks a script that spends real funds; `simulate_*` and `verify_*` - never do. +- `simulate_*` and `verify_*` never move funds — that half of the naming is + load-bearing and machine-checked. The inverse is **not** true: `live_*` is not + the only prefix that spends. `manual_*` (including the `pumpswap/` and + `letsbonk-buy-sell/` ones), `mint_and_buy*` and `cleanup_accounts.py` all + submit real transactions. Read the module docstring before running anything + that is not `simulate_*` or `verify_*`. ## Commands @@ -70,7 +79,7 @@ Lint and format **the files you touched**, not the whole tree: uv run ruff check --fix && uv run ruff format ``` -A bare `uv run ruff check` reports ~2400 pre-existing errors across the repo. +A bare `uv run ruff check` reports ~1700 pre-existing errors across the repo. That is the known baseline, not something your change caused — don't try to fix it wholesale, and don't read it as a failing build. Just don't add new ones in the files you edit. @@ -148,7 +157,7 @@ offline and only visible after a couple of minutes against mainnet. - **A `while True: recv()` loop must break out on `websockets.ConnectionClosed`.** Catching it in a broad `except Exception` that only logs makes the next `recv()` - raise immediately, forever: `compare_listeners.py` produced **13,090,862 error + raise immediately, forever: `listen-new-tokens/compare_listeners.py` produced **13,090,862 error lines / 888 MB in 150 s** and never reached its own 30-second report. The outer reconnect handler with its `sleep` is unreachable in that shape. A narrow `except TimeoutError` or `except json.JSONDecodeError` is fine to swallow —