# CLAUDE.md — PYRE / Prometheus Protocol Operating guide for Claude Code sessions in this repo. Keep changes aligned with the canonical design at [`docs/PYRE_MVP_DESIGN.md`](docs/PYRE_MVP_DESIGN.md) — when in doubt, that document wins. PYRE is a Solana wallet-cleanup and ritual meme-rebirth protocol. Users connect a wallet; PYRE scans SPL token accounts, classifies them conservatively, and helps the user safely close empty associated token accounts (ATAs) and burn obvious junk — returning recovered rent to the user and producing a clear receipt. A later layer (Prometheus) uses API-based AI to generate a meme-token "Spawn" from burned remnants for manual, human-reviewed launch. > **Burn the dead. Feed the PYRE. Claim the Spawn.** --- ## Non-negotiable trust rules These are load-bearing. Do not weaken, work around, or "optimize" them. See §3, §7, and §16 of the design doc. - **PYRE never holds private keys.** There is no key/mnemonic env var and there never will be. All signing happens client-side in the user's wallet. - **No custodial signing, ever.** Never auto-execute a transaction without the user signing it locally in their wallet. - **Recovered ATA rent returns to the user by default.** Rent must not be silently taxed, redirected, pooled, or counted as Essence. (Donation modes, if ever added, must be explicit opt-in.) - **Always preview before signing.** Build the unsigned transaction, **decode** it, and **match** the decoded contents against the preview shown to the user (accounts to close, tokens to burn, rent amount, rent destination, fees, warnings) before any signature is requested. Simulate transactions first. - **Unknown means skip.** Anything the system cannot safely reason about defaults to `PROTECTED_SKIP` / `UNSUPPORTED`. The user must manually opt in to anything risky. - **Never claim a token is safe.** The classifier must never say "this token is safe." It may only say "this token **appears eligible** based on current checks." --- ## Current status & scope guardrail **MVP v0.1 is a burner/cleaner only.** This repo is currently **scaffold + docs**: **Solana transaction logic and business logic are NOT yet implemented.** Do not add application/business logic unless explicitly asked. **Explicitly OUT of scope for v0.1** (per §5): - Automatic Pump.fun launch - User-contributed Essence vault - Custom PYRE Solana program (Anchor) - Token-2022 support - NFT handling (incl. compressed NFTs) - Automatic valuable-token sacrifice - Custodial signing - Background wallet automation v0.1 ships: wallet connect → scan token accounts → classify → close eligible empty ATAs (optionally burn obvious junk) → return rent to user → show receipt. --- ## Repo layout ``` pyre/ apps/ web/ # Next.js user app: landing, wallet connect, scanner UI, # cleanup preview, receipt page, Prometheus preview, admin review api/ # Fastify HTTP API: scan, classify, build tx, receipt, # generation, admin endpoints worker/ # BullMQ worker: async metadata lookup, AI generation, # safety checks, tx-confirmation watcher, receipt enrichment packages/ core/ # shared types & logic: classification enums, risk rules, # DTOs, receipt schema, Prometheus I/O schema solana/ # Solana tx helpers: token-account parsing, close-account & # burn tx builders, simulation helpers, tx decoder prometheus/ # AI generation: prompt templates, meta mixer, output parser, # safety checks, image-prompt generator db/ # database schema, migrations, table definitions config/ # shared config & environment loading programs/ pyre-core/ # FUTURE Anchor program (v1.0). NOT needed for the burner MVP. docs/ # design + architecture + security + classification docs scripts/ infra/ ``` See §13 for full responsibilities. --- ## Tech stack - **web** — Next.js, TypeScript, Tailwind, Solana Wallet Adapter, React Query or Zustand. - **api** — Node.js, Fastify, TypeScript, PostgreSQL, Redis, BullMQ. - **worker** — Node.js worker process, BullMQ, Redis, AI API clients. - **Database** — PostgreSQL. - **Solana RPC** — external provider only (Helius/Triton/QuickNode/etc.). Do **not** run a validator or RPC node on the MVP VPS. - **AI** — API-based only (text + image + moderation). Do **not** run local LLMs or image models on the server. --- ## Dev commands `pnpm` is installed at `~/.local/share/pnpm/bin` — if `pnpm` is not found, add that to `PATH` (e.g. `export PATH="$HOME/.local/share/pnpm/bin:$PATH"`). Node 22 is required. ```bash pnpm install # install workspace deps pnpm -r build # build all packages/apps pnpm -r typecheck # type-check all pnpm -r test # run all tests pnpm dev # run apps in parallel (dev) ``` > **Nothing is installed yet.** These commands are not runnable until the > skeleton's `package.json` files and dependencies exist. --- ## Conventions - **TypeScript strict** — every package extends `tsconfig.base.json`. - **ESM** — `"type": "module"` throughout. - **Workspace deps** — reference internal packages via `workspace:*`. - **Package names** — `@pyre/` (e.g. `@pyre/core`, `@pyre/solana`). --- ## Docs - [`docs/PYRE_MVP_DESIGN.md`](docs/PYRE_MVP_DESIGN.md) — canonical design (source of truth) - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — system architecture - [`docs/SECURITY.md`](docs/SECURITY.md) — security requirements - [`docs/TOKEN_CLASSIFICATION.md`](docs/TOKEN_CLASSIFICATION.md) — classification rules (Sibling docs are being authored in parallel.) --- ## Bootstrap prompts (§20) Use these in order. **Plan first — no code:** > Read CLAUDE.md and docs/PYRE_MVP_DESIGN.md. Do not write code yet. Produce an > implementation plan for PYRE MVP v0.1 focused only on wallet scanning, token > account classification, close-empty-ATA transaction building, transaction > preview, and receipt generation. Identify the exact packages, APIs, database > tables, and test cases needed. Then, after plan review — **skeleton only:** > Create the monorepo skeleton with pnpm workspaces. Add apps/web, apps/api, > apps/worker, packages/core, packages/solana, packages/prometheus, packages/db, > and docs. Add TypeScript configs, package.json files, README files, and > .env.example files. Do not implement Solana transaction logic yet.