From e288a71baef975540f9261d806f5f7d6a0399630 Mon Sep 17 00:00:00 2001 From: Anton Sauchyk Date: Tue, 17 Nov 2026 15:29:18 +0100 Subject: [PATCH] docs: make AGENTS.md the agent guide, fix the README, bump to 0.3.1 AGENTS.md replaces CLAUDE.md, which Claude Code now reads in its place. The README's wallet balance and drain lines, the endpoints table and the agentic section match the CLI again, and the work-item skill is gone. 0.3.1 carries the tokens fix. --- .../run-unit-and-surfpool-tests/SKILL.md | 1 - .claude/skills/work-item/SKILL.md | 130 ------------ .claude/skills/work-item/evals/evals.json | 47 ----- .../skills/work-item/prompts/1-investigate.md | 79 ------- .claude/skills/work-item/prompts/2-plan.md | 66 ------ .../skills/work-item/prompts/3-implement.md | 106 ---------- .claude/skills/work-item/prompts/4-verify.md | 109 ---------- .../skills/work-item/prompts/5-finalize.md | 91 -------- AGENTS.md | 197 +++++++++++++++++- CLAUDE.md | 196 ----------------- README.md | 28 ++- pyproject.toml | 2 +- src/pumpfun_cli/__init__.py | 2 +- uv.lock | 2 +- 14 files changed, 212 insertions(+), 844 deletions(-) delete mode 100644 .claude/skills/work-item/SKILL.md delete mode 100644 .claude/skills/work-item/evals/evals.json delete mode 100644 .claude/skills/work-item/prompts/1-investigate.md delete mode 100644 .claude/skills/work-item/prompts/2-plan.md delete mode 100644 .claude/skills/work-item/prompts/3-implement.md delete mode 100644 .claude/skills/work-item/prompts/4-verify.md delete mode 100644 .claude/skills/work-item/prompts/5-finalize.md mode change 120000 => 100644 AGENTS.md delete mode 100644 CLAUDE.md diff --git a/.claude/skills/run-unit-and-surfpool-tests/SKILL.md b/.claude/skills/run-unit-and-surfpool-tests/SKILL.md index 463d8ad..d96e161 100644 --- a/.claude/skills/run-unit-and-surfpool-tests/SKILL.md +++ b/.claude/skills/run-unit-and-surfpool-tests/SKILL.md @@ -86,7 +86,6 @@ When tests fail, use this decision tree to diagnose: ## Known Behaviors -- **Expected xfail:** `test_buy_then_sell_pumpswap` is marked `@pytest.mark.xfail` because PumpSwap buy/sell on forked state often hits slippage issues. If it xfails, that's normal. - **surfpool-test.sh** uses `uv run python3` (not bare `python3`) because solders/solana packages are in the uv venv. ## Interpreting Results diff --git a/.claude/skills/work-item/SKILL.md b/.claude/skills/work-item/SKILL.md deleted file mode 100644 index 5b1fca3..0000000 --- a/.claude/skills/work-item/SKILL.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -name: work-item -description: Work item pipeline for pumpfun-cli — investigate, plan, implement (TDD), verify, finalize as PR. MUST use this skill whenever the user wants to start, tackle, pick up, implement, or work on a work item. Triggers on any mention of work items by number ("item 5", "item #5", "#5", "B-06"), by name ("pre-trade balance validation", "quote command", "health check"), or by sequence ("next work item", "next item on the board", "next undone item", "next P1 item", "whatever is next"). Also triggers on phrases like "let's work on", "start implementing", "tackle item", "knock out", "pick up", "can we do item" when referring to work items. Does NOT trigger for: running tests, reviewing PRs, listing remaining items, fixing bugs, or explaining code. ---- - -# Work Item Pipeline - -Automate work item execution through a 5-stage gated pipeline. - -## Invocation - -`/work-item ` or `/work-item` (picks next undone item). - -## Step 0: Resolve the Target Item - -1. Resolve the work item from context — the user may provide a number, ID (e.g., "B-06"), title, or description. The item may come from a backlog, a conversation, or a direct request. -2. If a specific item was identified, extract its details. -3. If no specific item was given, ask the user which item to work on. -4. Extract: - - `ITEM_NUMBER`: the item number - - `ITEM_TITLE`: the short title (e.g., "Pre-trade balance validation") - - `ITEM_DESCRIPTION`: the full text of the item (Source, Problem, Proposed, Scope) -5. Announce: "Starting pipeline for **#N: TITLE**" - -## Stage 1: Investigate - -1. Read the prompt file: `.claude/skills/work-item/prompts/1-investigate.md` -2. Replace `{{ITEM_NUMBER}}` and `{{ITEM_DESCRIPTION}}` with the values from Step 0 -3. Dispatch a subagent: - ``` - Agent tool: - subagent_type: general-purpose - prompt: - description: "Investigate work item #N" - ``` -4. Store the returned output as `INVESTIGATION_OUTPUT` -5. Present the output to the user -6. **GATE:** Ask the user: **proceed** to Stage 2, **re-run** Stage 1, or **abort**? - -**If investigation recommends combining items:** Pause and ask the user whether to combine before proceeding. If yes, update `ITEM_DESCRIPTION` to include both items. - -## Stage 2: Plan - -1. Read the prompt file: `.claude/skills/work-item/prompts/2-plan.md` -2. Replace `{{ITEM_NUMBER}}`, `{{ITEM_DESCRIPTION}}`, and `{{INVESTIGATION_OUTPUT}}` -3. Dispatch a subagent: - ``` - Agent tool: - subagent_type: general-purpose - prompt: - description: "Plan work item #N" - ``` -4. Store the returned output as `PLAN_OUTPUT` -5. Extract `TEST_TIERS` from the "## Test Tiers" section of the plan output -6. Present the output to the user -7. **GATE:** Ask the user: **proceed** to Stage 3, **re-run** Stage 2, or **abort**? - -## Stage 3: Implement - -1. Read the prompt file: `.claude/skills/work-item/prompts/3-implement.md` -2. Replace `{{ITEM_NUMBER}}`, `{{ITEM_DESCRIPTION}}`, and `{{PLAN_OUTPUT}}` -3. Dispatch a subagent: - ``` - Agent tool: - subagent_type: general-purpose - prompt: - description: "Implement work item #N" - ``` -4. Store the returned output as `IMPLEMENT_OUTPUT` -5. Extract `FILES_CHANGED` and `TEST_COUNT_AFTER` from the output -6. Extract `TEST_COUNT_BEFORE` from the investigation output's "## Baseline Test Count" section -7. Present the output to the user -8. **GATE:** Ask the user: **proceed** to Stage 4, **re-run** Stage 3, or **abort**? - -**If subagent reports blockers (cannot get tests green):** Present blockers to user. Options: re-run with adjusted approach, abort, or user intervenes manually. - -## Stage 4: Verify - -1. Read the prompt file: `.claude/skills/work-item/prompts/4-verify.md` -2. Replace `{{ITEM_NUMBER}}`, `{{ITEM_DESCRIPTION}}`, `{{FILES_CHANGED}}`, `{{TEST_TIERS}}`, `{{TEST_COUNT_BEFORE}}`, and `{{TEST_COUNT_AFTER}}` -3. Dispatch a subagent: - ``` - Agent tool: - subagent_type: general-purpose - prompt: - description: "Verify work item #N" - ``` -4. Store the returned output as `VERIFICATION_OUTPUT` -5. Present the output to the user -6. **GATE:** Ask the user: **proceed** to Stage 5, **re-run** Stage 4, **loop back to Stage 3** (if regressions found), or **abort**? - -## Stage 5: Finalize - -1. Read the prompt file: `.claude/skills/work-item/prompts/5-finalize.md` -2. Replace `{{ITEM_NUMBER}}`, `{{ITEM_TITLE}}`, and `{{VERIFICATION_OUTPUT}}` -3. Dispatch a subagent: - ``` - Agent tool: - subagent_type: general-purpose - prompt: - description: "Finalize work item #N" - ``` -4. Present the PR URL to the user -5. Pipeline complete. Suggest: "Code review can be done manually or via a code review skill." - -## Variables Carried Across Stages - -| Variable | Set in | Used in | -|----------|--------|---------| -| `ITEM_NUMBER` | Step 0 | All stages | -| `ITEM_TITLE` | Step 0 | Stage 5 | -| `ITEM_DESCRIPTION` | Step 0 | Stages 1-4 | -| `INVESTIGATION_OUTPUT` | Stage 1 | Stage 2 | -| `TEST_COUNT_BEFORE` | Stage 1 (Baseline Test Count section) | Stage 4 | -| `PLAN_OUTPUT` | Stage 2 | Stage 3 | -| `TEST_TIERS` | Stage 2 (Test Tiers section) | Stage 4 | -| `FILES_CHANGED` | Stage 3 | Stage 4 | -| `TEST_COUNT_AFTER` | Stage 3 | Stage 4 | -| `VERIFICATION_OUTPUT` | Stage 4 | Stage 5 | - -## Failure Modes - -| Failure | Response | -|---------|----------| -| Item not found or unclear | Report error, ask the user to clarify | -| Item already marked Done | Report it's done, ask user to pick another | -| Stage 1 finds item not feasible | Present findings, recommend abort | -| Stage 3 cannot get tests green | Present blockers after 2 attempts, offer re-run/abort/manual | -| Stage 4 finds regressions | Loop back to Stage 3 with failure details | -| Any subagent errors/times out | Report error, offer re-run or abort | diff --git a/.claude/skills/work-item/evals/evals.json b/.claude/skills/work-item/evals/evals.json deleted file mode 100644 index 68067cb..0000000 --- a/.claude/skills/work-item/evals/evals.json +++ /dev/null @@ -1,47 +0,0 @@ -{ - "skill_name": "work-item", - "evals": [ - { - "id": 1, - "prompt": "work on item 5", - "expected_output": "Should resolve item #5 (Pre-trade balance validation), read 1-investigate.md prompt, fill {{ITEM_NUMBER}} with 5 and {{ITEM_DESCRIPTION}} with the full item text, dispatch a general-purpose subagent with the filled prompt, then present investigation output and ask user to proceed/re-run/abort.", - "files": [], - "assertions": [ - {"id": "A1", "text": "Correctly resolved to work item #5 (Pre-trade balance validation)", "type": "must_contain"}, - {"id": "A2", "text": "Read the prompt template from prompts/1-investigate.md", "type": "must_contain"}, - {"id": "A3", "text": "Filled {{ITEM_NUMBER}} with 5 and {{ITEM_DESCRIPTION}} with the full item text including Source, Problem, Proposed, Scope fields", "type": "must_contain"}, - {"id": "A4", "text": "Dispatches a general-purpose subagent (not Explore or Plan)", "type": "must_contain"}, - {"id": "A5", "text": "Presents a gate asking user to proceed, re-run, or abort", "type": "must_contain"}, - {"id": "A6", "text": "Announces starting the pipeline for item #5", "type": "must_contain"} - ] - }, - { - "id": 2, - "prompt": "next work item", - "expected_output": "Should read work-items.md, find item #5 as the next undone item (since #1-4 are all done), announce pipeline start, then proceed to Stage 1 investigation.", - "files": [], - "assertions": [ - {"id": "A1", "text": "Correctly identified #5 as the next undone item by checking which items are marked Done", "type": "must_contain"}, - {"id": "A2", "text": "Read the prompt template from prompts/1-investigate.md", "type": "must_contain"}, - {"id": "A3", "text": "Filled {{ITEM_NUMBER}} with 5 and {{ITEM_DESCRIPTION}} with the full item text", "type": "must_contain"}, - {"id": "A4", "text": "Dispatches a general-purpose subagent", "type": "must_contain"}, - {"id": "A5", "text": "Presents a gate asking user to proceed, re-run, or abort", "type": "must_contain"}, - {"id": "A6", "text": "Announces starting the pipeline for item #5", "type": "must_contain"} - ] - }, - { - "id": 3, - "prompt": "work on pre-trade balance validation", - "expected_output": "Should match the name to item #5, extract its full description, and start the pipeline with Stage 1 investigation.", - "files": [], - "assertions": [ - {"id": "A1", "text": "Matched 'pre-trade balance validation' to work item #5 by name", "type": "must_contain"}, - {"id": "A2", "text": "Read the prompt template from prompts/1-investigate.md", "type": "must_contain"}, - {"id": "A3", "text": "Filled {{ITEM_NUMBER}} with 5 and {{ITEM_DESCRIPTION}} with the full item text", "type": "must_contain"}, - {"id": "A4", "text": "Dispatches a general-purpose subagent", "type": "must_contain"}, - {"id": "A5", "text": "Presents a gate asking user to proceed, re-run, or abort", "type": "must_contain"}, - {"id": "A6", "text": "Announces starting the pipeline for item #5", "type": "must_contain"} - ] - } - ] -} diff --git a/.claude/skills/work-item/prompts/1-investigate.md b/.claude/skills/work-item/prompts/1-investigate.md deleted file mode 100644 index 617e715..0000000 --- a/.claude/skills/work-item/prompts/1-investigate.md +++ /dev/null @@ -1,79 +0,0 @@ -# Stage 1: Investigate Work Item #{{ITEM_NUMBER}} - -You are investigating a work item for the pumpfun-cli project before any code changes are made. - -## Work Item - -{{ITEM_DESCRIPTION}} - -## Your Task - -Investigate the current codebase and CLI behavior to understand the gap this work item addresses. You must NOT edit any files. You must NOT send transactions or spend SOL. - -## Project Context - -- **Root:** `/home/antonsauchyk/Documents/pump-fun-projects/pumpfun-cli` -- **Source:** `src/pumpfun_cli/` -- **Architecture:** `commands/` (Typer CLI) → `core/` (business logic) → `protocol/` (Solana) -- **Tests:** `tests/` (unit), `tests/test_surfpool/` (integration) -- **Run CLI:** `uv run pumpfun ` -- **Run tests:** `uv run pytest tests/ -q` -- **Config:** `CLAUDE.md` has full conventions - -## Steps - -1. **Read the affected files** listed in the work item's "Scope" field. Also read `CLAUDE.md` for project conventions. -2. **Trace the current code path.** For example, if the item is about buy validation, trace what happens from `commands/trade.py` → `core/trade.py` → `protocol/client.py` when a buy is executed. Note specific file:line references. -3. **Demonstrate current behavior.** Run the CLI with safe, read-only commands to show what happens today. Examples: - - `uv run pumpfun info ` (always safe) - - `uv run pumpfun wallet balance` (always safe) - - `uv run pumpfun buy 0.001 --dry-run` (safe — dry-run, if available) - - `uv run pumpfun --json ` (to see JSON output) - - NEVER run buy/sell/launch without `--dry-run` - - If `--dry-run` is not yet implemented, skip trade command demos and note this limitation - - Environment: `PUMPFUN_RPC` is in `.env`, `PUMPFUN_PASSWORD=testpass123` -4. **Identify edge cases** that the implementation must handle. -5. **Capture the baseline test count:** Run `uv run pytest tests/ -q` and note the "N passed" count. -6. **Determine test tiers needed:** - - **Unit** (always): mocked tests in `tests/test_core/`, `tests/test_commands/`, `tests/test_protocol/` - - **Surfpool** (if touches RPC/transaction logic): integration tests in `tests/test_surfpool/` - - **Mainnet** (rare — only if surfpool cannot cover it): e2e via `./scripts/mainnet-test.sh` -7. **Check for combinable items.** Check `docs/backlog.md` (if it exists) or ask the user if any other planned item shares >50% of the same code path. If so, recommend combining. - -## Output Format - -Structure your response EXACTLY as follows: - -## Current Behavior - - -## Gap Analysis - - -## Affected Files -**protocol/**: -**core/**: -**commands/**: -**tests/**: - -## Edge Cases -1. -2. -... - -## Test Tiers Needed - - -## Baseline Test Count - tests currently passing - -## Combine Recommendation -<"None" or "Recommend combining with #N because: "> - -## CONSTRAINTS — DO NOT VIOLATE - -- **DO NOT** edit, create, or delete any files -- **DO NOT** run buy/sell/launch commands without `--dry-run` -- **DO NOT** send any Solana transactions -- **DO NOT** modify the wallet or config -- You are read-only. Your job is to investigate and report, not to fix. diff --git a/.claude/skills/work-item/prompts/2-plan.md b/.claude/skills/work-item/prompts/2-plan.md deleted file mode 100644 index 11ee168..0000000 --- a/.claude/skills/work-item/prompts/2-plan.md +++ /dev/null @@ -1,66 +0,0 @@ -# Stage 2: Plan Implementation for Work Item #{{ITEM_NUMBER}} - -You are designing the implementation plan for a work item in the pumpfun-cli project. You have the investigation output from Stage 1. Your job is to produce a concrete, step-by-step plan that another agent will follow to implement the feature using TDD. - -## Work Item - -{{ITEM_DESCRIPTION}} - -## Investigation Output - -{{INVESTIGATION_OUTPUT}} - -## Project Conventions (from CLAUDE.md) - -- **Architecture:** `commands/` (thin Typer CLI) → `core/` (business logic) → `protocol/` (Solana). Never bypass layers. -- **Output:** Use `render(data, json_mode)` for success, `error(msg, hint, exit_code)` for failures. Never use `print()`. -- **Errors:** Core functions return `dict` with `"error"` key for expected failures. `error()` raises `SystemExit`. -- **Async:** All I/O is `async def`. Commands bridge with `asyncio.run()`. Close `RpcClient` in `finally`. -- **Types:** Full type hints on all public function signatures. -- **Imports:** stdlib → third-party → local. -- **Adding a command:** 1) `core/feature.py` 2) `commands/feature.py` 3) Register in `cli.py` 4) Tests in `tests/test_core/` - -## Your Task - -1. **Design the implementation bottom-up:** protocol → core → commands. Each layer should have clear inputs/outputs. -2. **Define test cases first** (TDD). For each test, specify: - - Test function name - - What it asserts - - Which tier it belongs to (unit/surfpool/mainnet) - - Which test file it goes in -3. **Order the work:** Write tests first, then implement layer by layer. -4. **Identify new dependencies or config changes** if any. -5. **Carry forward the test tiers** from the investigation. - -## Output Format - -Structure your response EXACTLY as follows: - -## Implementation Steps - -1. **File:** `exact/path/to/file.py` (create | modify) - **Change:** - -## Test Plan - -- `test_function_name` in `tests/path/test_file.py` [unit|surfpool|mainnet] - Asserts: - Setup: - -## Test Tiers - - -## API Surface - - -## Error Handling - -- **Condition:** -- **Response:** -- **User sees:** - -## CONSTRAINTS - -- DO NOT write code. You are planning only. -- DO NOT edit any files. You are read-only. -- Be specific about file paths, function names, and parameter types — the implementing agent needs exact targets. diff --git a/.claude/skills/work-item/prompts/3-implement.md b/.claude/skills/work-item/prompts/3-implement.md deleted file mode 100644 index dd558e7..0000000 --- a/.claude/skills/work-item/prompts/3-implement.md +++ /dev/null @@ -1,106 +0,0 @@ -# Stage 3: Implement Work Item #{{ITEM_NUMBER}} - -You are implementing a work item for the pumpfun-cli project using TDD. Follow the plan exactly. Write tests first, then implement. - -## Work Item - -{{ITEM_DESCRIPTION}} - -## Implementation Plan - -{{PLAN_OUTPUT}} - -## Project Root - -`/home/antonsauchyk/Documents/pump-fun-projects/pumpfun-cli` - -All commands run from this directory. Always use `uv run` prefix for Python/pytest commands. - -## Project Conventions (MUST follow) - -- **Architecture:** `commands/` → `core/` → `protocol/`. NEVER import from `protocol/` in `commands/`. -- **Output:** Use `render(data, json_mode)` and `error(msg, hint, exit_code)`. NEVER use `print()`. -- **Errors:** Core functions return `dict` with `"error"` key for expected failures. `error()` raises `SystemExit`. -- **Async:** All I/O functions are `async def`. Commands bridge with `asyncio.run()`. Close `RpcClient` in `finally` blocks. -- **Type hints:** Full type hints on all public function signatures. -- **Imports:** stdlib → third-party → local, separated by blank lines. -- **Naming:** `snake_case` functions/variables. `UPPER_CASE` constants. `_` prefix for private helpers. -- **Wallet decryption:** Catch `ValueError` in every command that decrypts the wallet. -- **Config resolution:** Use `resolve_value(key, env_var, flag)` — flag > env var > config file > default. - -## TDD Process - -### Phase 1: Create Feature Branch - -```bash -git checkout main && git pull -git checkout -b feat/ || git checkout feat/ -``` - -Use a descriptive slug derived from the item title (e.g., `feat/pre-trade-balance-validation`). If the branch already exists (e.g., from a previous re-run), reuse it. - -### Phase 2: Red — Write Failing Tests - -Follow the Test Plan from the implementation plan. Write all unit tests first. - -For each test file: -1. Write the test -2. Run it to confirm it fails: `uv run pytest tests/path/test_file.py::test_name -v` -3. Expected: FAIL (ImportError or AssertionError — the feature doesn't exist yet) - -Test patterns to follow: -- **Core tests:** Mock RPC calls, test business logic in isolation -- **Command tests:** Use `typer.testing.CliRunner`, test CLI args/output/exit codes -- **Protocol tests:** Test pure functions (PDAs, math, parsing) with no mocking - -### Phase 3: Green — Implement - -Follow the Implementation Steps from the plan. Work bottom-up: - -1. **protocol/** layer first (if needed) — pure functions, no business logic -2. **core/** layer — business logic, accepts primitives, returns dicts -3. **commands/** layer — thin Typer wiring, calls core, renders output -4. **cli.py** — register new commands if needed - -After each layer, run the relevant tests: -```bash -uv run pytest tests/test_protocol/ -q # after protocol changes -uv run pytest tests/test_core/ -q # after core changes -uv run pytest tests/test_commands/ -q # after command changes -``` - -### Phase 4: Full Suite - -Run the complete unit test suite to catch regressions: -```bash -uv run pytest tests/ -q -``` - -ALL tests must pass. If any pre-existing test fails, fix the regression before proceeding. - -## Output Format - -When you are done, structure your final response as: - -## Files Changed - - -## Test Count After - tests passing (from `uv run pytest tests/ -q` output) - -## Summary - - -## CONSTRAINTS - -- Follow the plan. Do not add features not in the plan. -- TDD: write tests BEFORE implementation. -- Run tests after every significant change. -- If tests cannot pass after 2 implementation attempts, STOP and report: - - What tests are failing - - What you tried - - What you think the blocker is -- Do NOT run buy/sell/launch commands without `--dry-run`. -- Do NOT send Solana transactions. -- Do NOT modify `.env`, `wallet.enc`, or `protocol/contracts.py` constants. -- Do NOT add dependencies without noting it in your output. diff --git a/.claude/skills/work-item/prompts/4-verify.md b/.claude/skills/work-item/prompts/4-verify.md deleted file mode 100644 index 170de17..0000000 --- a/.claude/skills/work-item/prompts/4-verify.md +++ /dev/null @@ -1,109 +0,0 @@ -# Stage 4: Verify Work Item #{{ITEM_NUMBER}} - -You are verifying the implementation of a work item for the pumpfun-cli project. Run the full test suite, integration tests if needed, and manually smoke-test the new feature. - -## Work Item - -{{ITEM_DESCRIPTION}} - -## Files Changed - -{{FILES_CHANGED}} - -## Test Tiers to Run - -{{TEST_TIERS}} - -## Baseline - -- Tests before implementation: {{TEST_COUNT_BEFORE}} -- Tests after implementation: {{TEST_COUNT_AFTER}} - -## Project Root - -`/home/antonsauchyk/Documents/pump-fun-projects/pumpfun-cli` - -All commands run from this directory. Always use `uv run` prefix for Python/pytest commands. - -## Verification Steps - -### 1. Unit Tests (always run) - -```bash -uv run pytest tests/ -q -``` - -Record the pass/fail count. If ANY test fails, report the failure with file:line and stop — do not proceed to surfpool or smoke testing. - -### 2. Surfpool Integration Tests (if "surfpool" is in Test Tiers) - -```bash -./scripts/surfpool-autodiscover.sh -``` - -This auto-discovers mints, starts surfpool, runs integration tests, stops surfpool. Record pass/fail count. `xfail` results are expected and not failures. - -If surfpool is not available (binary not installed), note this and skip. - -### 3. Mainnet E2E Tests (if "mainnet" is in Test Tiers) - -**STOP. Do NOT run mainnet tests without explicit user approval.** Report: -> "Mainnet testing is flagged for this item. This costs real SOL. Please confirm you want to proceed." - -If approved: `./scripts/mainnet-test.sh` - -### 4. Regression Check - -Compare test counts: -- Before: {{TEST_COUNT_BEFORE}} -- Current: -- Delta: should be positive (new tests added) - -If current count is LOWER than before, there is a regression. Report which tests are missing. - -### 5. Manual Smoke Test - -Run the CLI to exercise the new feature. Use safe commands only: -- Read-only commands (info, balance, tokens, config) — always safe -- Trading commands ONLY with `--dry-run` flag -- JSON mode: `uv run pumpfun --json ` -- Environment: `PUMPFUN_RPC` is in `.env`, `PUMPFUN_PASSWORD=testpass123` - -Design 3-5 smoke test commands that cover: -- The happy path (feature works as expected) -- An error case (feature returns proper error) -- JSON output mode (structured output is correct) - -## Output Format - -Structure your response EXACTLY as follows: - -## Unit Tests -**Result:** - - -## Surfpool Tests -**Result:** or "Skipped (not in test tiers)" or "Skipped (surfpool not available)" - -## Mainnet Tests -**Result:** or "Not required for this item" or "Awaiting user approval" - -## Manual Smoke Test - -### Command: `` -**Expected:** -**Actual:** -**Status:** PASS / FAIL - -## Regression Check -- Before: {{TEST_COUNT_BEFORE}} tests -- After: tests -- Delta: + tests -- Regressions: - -## CONSTRAINTS - -- Do NOT edit any files. You are verifying, not fixing. -- Do NOT send Solana transactions (no buy/sell/launch without --dry-run). -- Do NOT run mainnet tests without user approval. -- If you find failures, report them clearly — do not attempt to fix them. diff --git a/.claude/skills/work-item/prompts/5-finalize.md b/.claude/skills/work-item/prompts/5-finalize.md deleted file mode 100644 index 4f16741..0000000 --- a/.claude/skills/work-item/prompts/5-finalize.md +++ /dev/null @@ -1,91 +0,0 @@ -# Stage 5: Finalize Work Item #{{ITEM_NUMBER}} — {{ITEM_TITLE}} - -You are finalizing the implementation of a work item for the pumpfun-cli project. Commit the changes and create a PR. - -## Verification Results - -{{VERIFICATION_OUTPUT}} - -## Project Root - -`/home/antonsauchyk/Documents/pump-fun-projects/pumpfun-cli` - -## Steps - -### 1. Stage and commit - -Stage only the files that were changed during implementation. Do NOT use `git add -A` or `git add .`. Do NOT stage files in `docs/` or `idl/`. - -```bash -git add -git status -``` - -Verify no `.env`, `wallet.enc`, `idl/`, `docs/`, or credential files are staged. - -Commit with conventional commit format: -```bash -git commit -m "fix: - -<2-3 sentence explanation of what was done and why> - -Co-Authored-By: Claude Opus 4.6 (1M context) " -``` - -### 2. Push the feature branch - -```bash -git push -u origin HEAD -``` - -### 3. Create PR - -The PR description must be **self-contained** — a reviewer should understand the full context without needing to read any external files. Do NOT reference `docs/backlog.md`, `docs/work-items.md`, or any other local documentation files in the PR title or body. - -```bash -gh pr create --title "fix: {{ITEM_TITLE}}" --body "$(cat <<'EOF' -## Summary - - - -<1-3 bullet points describing what was added/changed> - -## Layers Touched - -- `commands/` — -- `core/` — -- `protocol/` — - -## Does this affect transaction construction or signing? - - - -## Test Plan - -- Unit tests: -- Surfpool: -- Mainnet: - -🤖 Generated with [Claude Code](https://claude.com/claude-code) -EOF -)" -``` - -### 4. Report - -Output the PR URL. - -## Output Format - -## PR Created -**URL:** -**Branch:** -**Title:** - -## CONSTRAINTS - -- Do NOT commit `.env`, `wallet.enc`, or credential files. -- Do NOT stage or commit files in `docs/` or `idl/`. -- Do NOT push to `main` directly. Always use feature branch + PR. -- Do NOT merge the PR. That is the user's decision. -- Do NOT reference local .md files (backlog, work-items, etc.) in the PR description. The PR must be self-contained. diff --git a/AGENTS.md b/AGENTS.md deleted file mode 120000 index 681311e..0000000 --- a/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -CLAUDE.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..66cb783 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,196 @@ +# AGENTS.md — pumpfun-cli + +CLI for trading on pump.fun and Raydium LaunchLab launchpads (Solana), and launching on pump.fun. Python 3.12+, uv, Typer, solana-py/solders. + +## Commands + +```bash +# Install / sync +uv sync + +# Run CLI (dev) +uv run pumpfun [options] +uv run pumpfun --json # force JSON output + +# Unit tests (always safe, no network) +uv run pytest tests/ -q +uv run pytest tests/ -v --cov # with coverage +uv run pytest tests/test_core -v # single module +uv run pytest tests/ -k test_name # filter + +# Surfpool integration (needs running surfpool daemon) +./scripts/surfpool-autodiscover.sh + +# E2e mainnet (COSTS REAL SOL — always confirm with user first) +./scripts/mainnet-test.sh +./scripts/mainnet-test.sh --skip-trading +``` + +pytest is configured to auto-ignore `tests/test_surfpool/` by default. Surfpool and mainnet tests require explicit invocation. + +## Architecture + +Three-layer separation — never bypass layers: + +``` +commands/ → core/ → protocol/ + (thin) (logic) (Solana) +``` + +- **`commands/`** — Typer CLI wiring only. Parse args, call core, call `render()` or `error()`. All commands are async, bridged with `asyncio.run()`. +- **`core/`** — Framework-free business logic. Accept primitives (`rpc_url: str`, `password: str`, amounts). Return `dict` with results or `"error"` key for expected failures. +- **`protocol/`** — Pure Solana/pump.fun code. PDAs, RPC client, instruction builders, curve math, pool parsing. Zero business logic. + +Entry point: `src/pumpfun_cli/cli.py` → `pyproject.toml` `[project.scripts] pumpfun = "pumpfun_cli.cli:app"` + +## Project Structure + +``` +src/pumpfun_cli/ +├── cli.py # Root Typer app, GlobalState, callback, command registration +├── group.py # JsonAwareGroup — allows --json at any argv position +├── crypto.py # AES-256-GCM wallet encryption (scrypt KDF) +├── output.py # render() + error() — TTY-aware output +├── commands/ # Thin CLI layer (config, info, launch, tokens, trade, tx_status, wallet) +├── core/ # Business logic (config, cpmm, info, launch, launchlab, pumpswap, tokens, trade, tx_status, validate, wallet) +└── protocol/ # Solana primitives (address, client, contracts, cpmm, curve, idl_parser, instructions, launchlab, pumpswap, quote) + +tests/ +├── test_commands/ # CLI smoke tests +├── test_core/ # Mocked business logic tests +├── test_protocol/ # Unit tests for protocol math/parsing +└── test_surfpool/ # Integration tests (ignored by default) +``` + +## Code Conventions + +**Output:** Use `render(data, json_mode)` for all output — returns `True` if it emitted JSON (non-TTY or `--json`), `False` in TTY mode. Commands use `if not render(...):` to branch into human-readable output. Use `error(msg, hint, exit_code)` for failures — prints to stderr and raises `SystemExit`. Never use `print()`. + +**Error handling:** `error()` raises `SystemExit` — code after it is unreachable. Core functions return `dict` with `"error"` key for expected failures (graduated tokens, not found, slippage exceeded, insufficient_balance). Catch `ValueError` for wrong wallet password in every command that decrypts. Buy/sell functions perform pre-trade balance validation — SOL for fees and rent, the quote asset for the spend, token balance for sells with specific amounts. + +**Auto-routing:** `_route` in `commands/trade.py` picks the venue from the errors core returns: `{"error": "graduated"}` from `buy_token` / `sell_token` retries on PumpSwap, `{"error": "not_found"}` retries on LaunchLab (`buy_launchlab` / `sell_launchlab`), and LaunchLab's `graduated` retries on Raydium CPMM (`buy_cpmm` / `sell_cpmm`). `--force-amm` tries PumpSwap and falls back to CPMM only when PumpSwap reports no pool (`pool_missing`); PumpSwap's error stands unless CPMM recognises the coin as LaunchLab's. Never suppress or swallow those errors in core — the routing decision belongs in the command layer. `info` falls back to LaunchLab, and to its CPMM pool, the same way in `core/info.py`. + +**Imports:** stdlib → third-party → local. Example: +```python +import asyncio +from pathlib import Path + +from solders.pubkey import Pubkey + +from pumpfun_cli.core.config import resolve_value +from pumpfun_cli.output import render, error +``` + +**Naming:** `snake_case` functions/variables/files. `UPPER_CASE` constants. Prefix private helpers with `_`. + +**Type hints:** Full type hints on all public function signatures. + +**Async:** All I/O functions are `async def`. Commands bridge with `asyncio.run()`. `RpcClient` is stateless — always call `.close()` in `finally`. + +**Config resolution:** `resolve_value(key, flag)` — flag > env var (via internal `ENV_MAP`) > config file > default. + +## Adding a New Command + +1. Add `core/my_feature.py` — `async def my_operation(rpc_url, keystore_path, password, ...) -> dict` +2. Add `commands/my_feature.py` — Typer wrapper that calls core and renders output +3. Register in `cli.py`: + - Flat command: `app.command("my-command")(my_feature_cmd)` + - Subcommand group: `app.add_typer(my_app, name="group-name")` +4. Add tests in `tests/test_core/test_my_feature.py` with mocked RPC/HTTP + +## Working with Solana Accounts + +```python +from pumpfun_cli.protocol.address import derive_bonding_curve +from pumpfun_cli.protocol.curve import parse_bonding_curve +from pumpfun_cli.protocol.instructions import build_buy_exact_quote_in_v2_instruction +from pumpfun_cli.protocol.quote import get_mint_info + +resp = await client.get_account_info(derive_bonding_curve(mint)) +state = parse_bonding_curve(bytes(resp.value.data)) +quote_program, quote_decimals = await get_mint_info(client, state["quote_mint"]) +ix = build_buy_exact_quote_in_v2_instruction(mint=mint, creator=state["creator"], ...) +sig = await client.send_tx([ix], [keypair], compute_units=..., confirm=True) +``` + +## Protocol rules + +Read `docs/pumpfun-protocol.md` in pumpfun-bonkfun-bot before changing account +lists; these are the ones this CLI depends on. + +- **Amounts are in the coin's quote asset**, read from `BondingCurve.quote_mint` + (all zeros means SOL; instructions take wrapped SOL there). Its decimals come + from the mint via `get_mint_info`; never assume 9. +- Bonding-curve trades use `buy_exact_quote_in_v2` / `sell_v2`: 27 / 26 + accounts, identical for every coin. A SOL coin's quote accounts are only + seed-checked, so don't create the user's WSOL ATA for them. +- `creator_vault` derives from `BondingCurve.creator` as stored. On holder-reward + and fee-sharing coins that is not the wallet that launched the coin. +- PumpSwap swaps carry accounts the IDL omits: cashback account(s) on a cashback + pool, then `pool-v2` **only on a canonical pool** (`coin_creator` set), then the + buyback recipient and its quote ATA last. The canonical pool is derived from the + mint and the curve's quote mint. +- `migrate_v2` also carries accounts the IDL omits: after its 27, the new pool's + boost vault authority (`["boost_vault", pool]` on PumpSwap) and that + authority's quote token account. Without them PumpSwap reverts with 6027. +- LaunchLab (`protocol/launchlab.py`) pools are keyed by base and quote mint. + The SOL pool is derived; any other quote is found by `getProgramAccounts` + on the base mint (PoolState offset 205). Swaps are the IDL's 15 accounts plus + the system program and the platform and creator fee vaults + (`[platform_config, quote]`, `[creator, quote]`). The curve fee is + GlobalConfig's trade fee plus PlatformConfig's fee and creator fee, read + live; a Token-2022 coin's transfer fee comes off what arrives. +- A graduated LaunchLab coin's CPMM pool (`protocol/cpmm.py`) is derived from + its PlatformConfig's `cpswap_config` and the two mints sorted by bytes. + Reserves are the vault balances less the protocol, fund and creator fees the + pool still owes. Both sides are `swap_base_input`, input token's accounts + first. `migrate_type` 0 (AMM v4) is refused. +- `send_tx` sends v0 and falls back to v1 when the transaction exceeds 1232 + bytes (a cashback-pool buy, a launch with a buy). v1 carries the compute budget + in its header. +- `create_v2` rejects cashback (6082). A creator fee only applies on a coin + priced in a `QuoteControl` mint, and mayhem coins must be SOL-priced; launch + refuses both before sending. + +## Environment + +```bash +PUMPFUN_RPC=https://... # Solana RPC endpoint (required for trading) +PUMPFUN_KEYFILE=/path/to/... # Path to encrypted wallet keystore +PUMPFUN_PRIORITY_FEE=200000 # Priority fee in micro-lamports +PUMPFUN_COMPUTE_UNITS=100000 # Compute unit limit +PUMPFUN_PASSWORD=... # Wallet password (read directly in wallet commands, not via resolve_value) +``` + +Config file: `~/.config/pumpfun-cli/config.toml` +Wallet keystore: `~/.config/pumpfun-cli/wallet.enc` + + +## Hooks + +Three hooks run automatically during Claude Code sessions (see `.claude/settings.json`): + +- **guard.py** (PreToolUse → Write|Edit): Blocks edits to `.env`, `wallet.enc`, `idl/`, and credential files (`.pem`, `.key`, `.secret`). Edit these files manually. +- **lint.py** (PostToolUse → Write|Edit): Runs `ruff format` + `ruff check --fix` on every edited `.py` file. If unfixable errors remain, you will see them as errors — fix them before moving on. +- **bash-guard.py** (PreToolUse → Bash): Blocks `git add` of `docs/*.md` (exit 2). Otherwise advisory: adds a note to Claude's context (JSON `additionalContext`, never blocks) when commands send Solana transactions, run mainnet tests, or delete sensitive files. The CLI must work unimpeded when run via assistants or automated workflows. + +## Boundaries + +**Always do:** +- Run `uv run pytest tests/ -q` after code changes +- Follow the three-layer separation +- Use `render()` and `error()` for all CLI output +- Catch `ValueError` on wallet decryption +- Close `RpcClient` in `finally` blocks + +**Ask first:** +- Running mainnet e2e tests (costs real SOL) +- Modifying `protocol/contracts.py` constants (program IDs, discriminators) +- Changing wallet encryption format in `crypto.py` + +**Never do:** +- Bypass layers (commands must not import from protocol directly) +- Use `print()` instead of `render()`/`error()` +- Commit `.env` or wallet files +- Run mainnet tests without explicit user confirmation +- Add dependencies without discussing first diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index fe2243d..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,196 +0,0 @@ -# CLAUDE.md — pumpfun-cli - -CLI for trading on pump.fun and Raydium LaunchLab launchpads (Solana), and launching on pump.fun. Python 3.12+, uv, Typer, solana-py/solders. - -## Commands - -```bash -# Install / sync -uv sync - -# Run CLI (dev) -uv run pumpfun [options] -uv run pumpfun --json # force JSON output - -# Unit tests (always safe, no network) -uv run pytest tests/ -q -uv run pytest tests/ -v --cov # with coverage -uv run pytest tests/test_core -v # single module -uv run pytest tests/ -k test_name # filter - -# Surfpool integration (needs running surfpool daemon) -./scripts/surfpool-autodiscover.sh - -# E2e mainnet (COSTS REAL SOL — always confirm with user first) -./scripts/mainnet-test.sh -./scripts/mainnet-test.sh --skip-trading -``` - -pytest is configured to auto-ignore `tests/test_surfpool/` by default. Surfpool and mainnet tests require explicit invocation. - -## Architecture - -Three-layer separation — never bypass layers: - -``` -commands/ → core/ → protocol/ - (thin) (logic) (Solana) -``` - -- **`commands/`** — Typer CLI wiring only. Parse args, call core, call `render()` or `error()`. All commands are async, bridged with `asyncio.run()`. -- **`core/`** — Framework-free business logic. Accept primitives (`rpc_url: str`, `password: str`, amounts). Return `dict` with results or `"error"` key for expected failures. -- **`protocol/`** — Pure Solana/pump.fun code. PDAs, RPC client, instruction builders, curve math, pool parsing. Zero business logic. - -Entry point: `src/pumpfun_cli/cli.py` → `pyproject.toml` `[project.scripts] pumpfun = "pumpfun_cli.cli:app"` - -## Project Structure - -``` -src/pumpfun_cli/ -├── cli.py # Root Typer app, GlobalState, callback, command registration -├── group.py # JsonAwareGroup — allows --json at any argv position -├── crypto.py # AES-256-GCM wallet encryption (scrypt KDF) -├── output.py # render() + error() — TTY-aware output -├── commands/ # Thin CLI layer (config, info, launch, tokens, trade, tx_status, wallet) -├── core/ # Business logic (config, cpmm, info, launch, launchlab, pumpswap, tokens, trade, tx_status, validate, wallet) -└── protocol/ # Solana primitives (address, client, contracts, cpmm, curve, idl_parser, instructions, launchlab, pumpswap, quote) - -tests/ -├── test_commands/ # CLI smoke tests -├── test_core/ # Mocked business logic tests -├── test_protocol/ # Unit tests for protocol math/parsing -└── test_surfpool/ # Integration tests (ignored by default) -``` - -## Code Conventions - -**Output:** Use `render(data, json_mode)` for all output — returns `True` if it emitted JSON (non-TTY or `--json`), `False` in TTY mode. Commands use `if not render(...):` to branch into human-readable output. Use `error(msg, hint, exit_code)` for failures — prints to stderr and raises `SystemExit`. Never use `print()`. - -**Error handling:** `error()` raises `SystemExit` — code after it is unreachable. Core functions return `dict` with `"error"` key for expected failures (graduated tokens, not found, slippage exceeded, insufficient_balance). Catch `ValueError` for wrong wallet password in every command that decrypts. Buy/sell functions perform pre-trade balance validation — SOL for fees and rent, the quote asset for the spend, token balance for sells with specific amounts. - -**Auto-routing:** `_route` in `commands/trade.py` picks the venue from the errors core returns: `{"error": "graduated"}` from `buy_token` / `sell_token` retries on PumpSwap, `{"error": "not_found"}` retries on LaunchLab (`buy_launchlab` / `sell_launchlab`), and LaunchLab's `graduated` retries on Raydium CPMM (`buy_cpmm` / `sell_cpmm`). `--force-amm` tries PumpSwap and falls back to CPMM only when PumpSwap reports no pool (`pool_missing`); PumpSwap's error stands unless CPMM recognises the coin as LaunchLab's. Never suppress or swallow those errors in core — the routing decision belongs in the command layer. `info` falls back to LaunchLab, and to its CPMM pool, the same way in `core/info.py`. - -**Imports:** stdlib → third-party → local. Example: -```python -import asyncio -from pathlib import Path - -from solders.pubkey import Pubkey - -from pumpfun_cli.core.config import resolve_value -from pumpfun_cli.output import render, error -``` - -**Naming:** `snake_case` functions/variables/files. `UPPER_CASE` constants. Prefix private helpers with `_`. - -**Type hints:** Full type hints on all public function signatures. - -**Async:** All I/O functions are `async def`. Commands bridge with `asyncio.run()`. `RpcClient` is stateless — always call `.close()` in `finally`. - -**Config resolution:** `resolve_value(key, flag)` — flag > env var (via internal `ENV_MAP`) > config file > default. - -## Adding a New Command - -1. Add `core/my_feature.py` — `async def my_operation(rpc_url, keystore_path, password, ...) -> dict` -2. Add `commands/my_feature.py` — Typer wrapper that calls core and renders output -3. Register in `cli.py`: - - Flat command: `app.command("my-command")(my_feature_cmd)` - - Subcommand group: `app.add_typer(my_app, name="group-name")` -4. Add tests in `tests/test_core/test_my_feature.py` with mocked RPC/HTTP - -## Working with Solana Accounts - -```python -from pumpfun_cli.protocol.address import derive_bonding_curve -from pumpfun_cli.protocol.curve import parse_bonding_curve -from pumpfun_cli.protocol.instructions import build_buy_exact_quote_in_v2_instruction -from pumpfun_cli.protocol.quote import get_mint_info - -resp = await client.get_account_info(derive_bonding_curve(mint)) -state = parse_bonding_curve(bytes(resp.value.data)) -quote_program, quote_decimals = await get_mint_info(client, state["quote_mint"]) -ix = build_buy_exact_quote_in_v2_instruction(mint=mint, creator=state["creator"], ...) -sig = await client.send_tx([ix], [keypair], compute_units=..., confirm=True) -``` - -## Protocol rules - -Read `docs/pumpfun-protocol.md` in pumpfun-bonkfun-bot before changing account -lists; these are the ones this CLI depends on. - -- **Amounts are in the coin's quote asset**, read from `BondingCurve.quote_mint` - (all zeros means SOL; instructions take wrapped SOL there). Its decimals come - from the mint via `get_mint_info`; never assume 9. -- Bonding-curve trades use `buy_exact_quote_in_v2` / `sell_v2`: 27 / 26 - accounts, identical for every coin. A SOL coin's quote accounts are only - seed-checked, so don't create the user's WSOL ATA for them. -- `creator_vault` derives from `BondingCurve.creator` as stored. On holder-reward - and fee-sharing coins that is not the wallet that launched the coin. -- PumpSwap swaps carry accounts the IDL omits: cashback account(s) on a cashback - pool, then `pool-v2` **only on a canonical pool** (`coin_creator` set), then the - buyback recipient and its quote ATA last. The canonical pool is derived from the - mint and the curve's quote mint. -- `migrate_v2` also carries accounts the IDL omits: after its 27, the new pool's - boost vault authority (`["boost_vault", pool]` on PumpSwap) and that - authority's quote token account. Without them PumpSwap reverts with 6027. -- LaunchLab (`protocol/launchlab.py`) pools are keyed by base and quote mint. - The SOL pool is derived; any other quote is found by `getProgramAccounts` - on the base mint (PoolState offset 205). Swaps are the IDL's 15 accounts plus - the system program and the platform and creator fee vaults - (`[platform_config, quote]`, `[creator, quote]`). The curve fee is - GlobalConfig's trade fee plus PlatformConfig's fee and creator fee, read - live; a Token-2022 coin's transfer fee comes off what arrives. -- A graduated LaunchLab coin's CPMM pool (`protocol/cpmm.py`) is derived from - its PlatformConfig's `cpswap_config` and the two mints sorted by bytes. - Reserves are the vault balances less the protocol, fund and creator fees the - pool still owes. Both sides are `swap_base_input`, input token's accounts - first. `migrate_type` 0 (AMM v4) is refused. -- `send_tx` sends v0 and falls back to v1 when the transaction exceeds 1232 - bytes (a cashback-pool buy, a launch with a buy). v1 carries the compute budget - in its header. -- `create_v2` rejects cashback (6082). A creator fee only applies on a coin - priced in a `QuoteControl` mint, and mayhem coins must be SOL-priced; launch - refuses both before sending. - -## Environment - -```bash -PUMPFUN_RPC=https://... # Solana RPC endpoint (required for trading) -PUMPFUN_KEYFILE=/path/to/... # Path to encrypted wallet keystore -PUMPFUN_PRIORITY_FEE=200000 # Priority fee in micro-lamports -PUMPFUN_COMPUTE_UNITS=100000 # Compute unit limit -PUMPFUN_PASSWORD=... # Wallet password (read directly in wallet commands, not via resolve_value) -``` - -Config file: `~/.config/pumpfun-cli/config.toml` -Wallet keystore: `~/.config/pumpfun-cli/wallet.enc` - - -## Hooks - -Three hooks run automatically during Claude Code sessions (see `.claude/settings.json`): - -- **guard.py** (PreToolUse → Write|Edit): Blocks edits to `.env`, `wallet.enc`, `idl/`, and credential files (`.pem`, `.key`, `.secret`). Edit these files manually. -- **lint.py** (PostToolUse → Write|Edit): Runs `ruff format` + `ruff check --fix` on every edited `.py` file. If unfixable errors remain, you will see them as errors — fix them before moving on. -- **bash-guard.py** (PreToolUse → Bash): Blocks `git add` of `docs/*.md` (exit 2). Otherwise advisory: adds a note to Claude's context (JSON `additionalContext`, never blocks) when commands send Solana transactions, run mainnet tests, or delete sensitive files. The CLI must work unimpeded when run via assistants or automated workflows. - -## Boundaries - -**Always do:** -- Run `uv run pytest tests/ -q` after code changes -- Follow the three-layer separation -- Use `render()` and `error()` for all CLI output -- Catch `ValueError` on wallet decryption -- Close `RpcClient` in `finally` blocks - -**Ask first:** -- Running mainnet e2e tests (costs real SOL) -- Modifying `protocol/contracts.py` constants (program IDs, discriminators) -- Changing wallet encryption format in `crypto.py` - -**Never do:** -- Bypass layers (commands must not import from protocol directly) -- Use `print()` instead of `render()`/`error()` -- Commit `.env` or wallet files -- Run mainnet tests without explicit user confirmation -- Add dependencies without discussing first diff --git a/README.md b/README.md index df50222..b1ddbca 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ pump.fun no longer accepts anonymous metadata uploads, so `launch` takes the URI ``` Token info (requires RPC): - pumpfun info Venue, price, bonding progress, reserves + pumpfun info [--timeout S] Venue, price, bonding progress, reserves Trading (requires RPC + wallet): pumpfun buy [--slippage N] [--force-amm] [--dry-run] [--confirm] @@ -113,17 +113,17 @@ Token discovery (price and progress added when an RPC is set): pumpfun tokens new [--limit N] Recently launched pumpfun tokens graduating [--limit N] Closest to bonding curve completion pumpfun tokens recommended [--limit N] Recommended by pump.fun (at most 10) - pumpfun tokens search Search by name or ticker + pumpfun tokens search [--limit N] Search by name or ticker Wallet management: pumpfun wallet create Generate + encrypt keypair pumpfun wallet import Import existing keypair pumpfun wallet show Display public key - pumpfun wallet balance SOL + token balances + pumpfun wallet balance SOL balance pumpfun wallet tokens Token accounts with balances pumpfun wallet transfer Transfer SOL or tokens (--mint for SPL) pumpfun wallet close-atas Close empty token accounts, recover rent - pumpfun wallet drain Close all ATAs + transfer remaining SOL + pumpfun wallet drain Close empty ATAs + transfer remaining SOL pumpfun wallet export --output Export as Solana keypair JSON Config: @@ -193,13 +193,14 @@ A pump.fun bonding curve pays a sell out of its real reserves, which on some coi | `tokens recommended` | `frontend-api-v3.pump.fun/coins/recommendations` | HTTPS | | `tokens search` | `frontend-api-v3.pump.fun/coins/search-unrestricted` | HTTPS | | `tokens *` with an RPC set | + Solana RPC (`getMultipleAccounts` for the bonding curves) | JSON-RPC | -| `wallet balance` | Solana RPC (`getBalance`, `getTokenAccountsByOwner`) | JSON-RPC | +| `wallet balance` | Solana RPC (`getBalance`) | JSON-RPC | +| `wallet tokens` | Solana RPC (`getTokenAccountsByOwner`) | JSON-RPC | | `wallet transfer` | Solana RPC (`sendTransaction`) | JSON-RPC | | `wallet drain` | Solana RPC (`getTokenAccountsByOwner`, `sendTransaction`) | JSON-RPC | | `wallet create/show/import/export` | None (local keystore only) | — | | `config *` | None (local config file only) | — | -The `tokens` listings use pump.fun's frontend API, which is unofficial and changes without notice; it currently refuses non-browser clients ([#33](https://github.com/chainstacklabs/pumpfun-cli/issues/33)). Listings are narrowed to pump.fun coins on Solana, and price and bonding progress come from the chain, so they need an RPC endpoint. +The `tokens` listings use pump.fun's frontend API, which is unofficial and changes without notice. Listings are narrowed to pump.fun coins on Solana, and price and bonding progress come from the chain, so they need an RPC endpoint. ## Throughput and rate limits @@ -234,7 +235,7 @@ For transactions against real program state, the integration tests use [Surfpool ## IDLs -The pump.fun IDLs under [`idl/`](idl/) match those in [pumpfun-bonkfun-bot](https://github.com/chainstacklabs/pumpfun-bonkfun-bot), and `raydium_launchlab_idl.json` is copied from it; keep them in sync when the programs change. The IDLs under-report a few account lists (PumpSwap's swaps, pump.fun's `migrate_v2`); [CLAUDE.md](CLAUDE.md) lists what they leave out. +The pump.fun IDLs under [`idl/`](idl/) match those in [pumpfun-bonkfun-bot](https://github.com/chainstacklabs/pumpfun-bonkfun-bot), and `raydium_launchlab_idl.json` is copied from it; keep them in sync when the programs change. The IDLs under-report a few account lists (PumpSwap's swaps, pump.fun's `migrate_v2`); [AGENTS.md](AGENTS.md) lists what they leave out. ## Architecture @@ -249,17 +250,14 @@ commands/ → core/ → protocol/ ## Agentic coding -This repo is configured for AI coding agents via the `.claude/` directory: - -- **`CLAUDE.md`** — project context, commands, conventions and boundaries. `AGENTS.md` is a symlink to it, so Claude Code, Codex, Cursor and Copilot read the same guide. -- **`hooks/`** — auto-lint on edit, guard against writing secrets, warn on transaction commands -- **`skills/`** — [Agent Skills](https://agentskills.io/home) for repeatable workflows: +- **[`AGENTS.md`](AGENTS.md)** — project context, commands, conventions and boundaries for any coding agent: Claude Code, Codex, Cursor, Copilot and others read it. +- **`.claude/hooks/`** — Claude Code hooks: ruff on every edited Python file, a block on edits to `.env`, wallet, key and IDL files, and a warning before commands that send transactions. +- **`.claude/skills/`** — [Agent Skills](https://agentskills.io/home) for running the tests: | Skill | Purpose | |-------|---------| -| `run-unit-and-surfpool-tests` | Run unit tests + optional Surfpool integration tests | -| `run-mainnet-e2e-tests` | Run end-to-end tests against Solana mainnet (costs real SOL) | -| `work-item` | Investigate, plan, implement (TDD), verify, and finalize work items as PRs | +| `run-unit-and-surfpool-tests` | Unit tests, plus Surfpool integration tests when Surfpool is installed | +| `run-mainnet-e2e-tests` | End-to-end tests on Solana mainnet; trading groups spend real SOL | ## Contributing diff --git a/pyproject.toml b/pyproject.toml index e94ad0a..d244b04 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pumpfun-cli" -version = "0.3.0" +version = "0.3.1" description = "CLI for pump.fun and Raydium LaunchLab on Solana — trade, launch, and browse tokens" readme = "README.md" license = {text = "Apache-2.0"} diff --git a/src/pumpfun_cli/__init__.py b/src/pumpfun_cli/__init__.py index cc61a9f..43141ed 100644 --- a/src/pumpfun_cli/__init__.py +++ b/src/pumpfun_cli/__init__.py @@ -1,3 +1,3 @@ """pumpfun-cli — CLI for pump.fun on Solana.""" -__version__ = "0.3.0" +__version__ = "0.3.1" diff --git a/uv.lock b/uv.lock index 526d489..7834044 100644 --- a/uv.lock +++ b/uv.lock @@ -571,7 +571,7 @@ wheels = [ [[package]] name = "pumpfun-cli" -version = "0.3.0" +version = "0.3.1" source = { editable = "." } dependencies = [ { name = "base58" },