# 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 — Built / In progress / Not yet built This repo is **no longer scaffold + docs** — the burner core is implemented and live at [feedthepyre.com](https://feedthepyre.com). Keep new work aligned with the design doc; the trust rules above are non-negotiable. **Built (working):** - **Wallet scan + conservative classifier** (`@pyre/core`): EMPTY_CLOSE_ONLY / INCINERATE_ONLY / TRANSMUTABLE / PROTECTED_SKIP / UNSUPPORTED. "Unknown means skip"; never "safe". - **Token-2022** supported conservatively with account+mint **extension gating** (§7.1): confidential transfer / withheld transfer fees / frozen / unknown extensions skipped; transfer-hook & permanent-delegate mints cleanable but flagged; unverifiable mints → UNSUPPORTED. In `@pyre/core` (`extensions.ts`, `classify.ts`) + `@pyre/solana`. - **Close-empty + burn→close transactions** (`@pyre/solana`): UNSIGNED, server re-validates on-chain, value-gated, rent → user, with a transparent **5% protocol fee** (§3.1) to the treasury. Decoded + matched in the web app before signing. Live-verified on mainnet. - **Sell / transmute DETECTION** via Jupiter (read-only quotes + Shield + dust gate) in `@pyre/core` (`sell.ts`) and the API (`jupiter.ts`). Swap **execution is not built**. - **Essence ledger** (`@pyre/db`, Postgres: `rounds`, `cleanup_receipts`, `essence_contributions`): `/api/receipt` persists the receipt and records the on-chain fee as Essence; public "🔥 fed the PYRE" panel + `/api/essence`. - **Prometheus engine** (`@pyre/prometheus`): meta-mixer + name/ticker/lore/ tagline + image-prompt + safety. Provider-abstracted with real providers (Gemini/Anthropic/OpenAI text; Pollinations/fal/DeepInfra/Replicate image; OpenAI moderation) plus a deterministic stub fallback; runs on a free stack today. - **Pump.fun creator workflow** (manual / approval-gated): `spawn_records`, admin-gated generate/launch endpoints, public `/spawn` page. **In progress:** - Admin generation UI (review/approve Spawn packages). - Generation-from-receipt wiring (`/api/prometheus/generate` already pulls receipt context; full receipt → Spawn flow being finished). **Not yet built:** - Swap **execution** (TRANSMUTABLE detection only today). - On-chain claim program v1.0 (`programs/pyre-core` is still a placeholder). - Background worker jobs (`apps/worker` is a skeleton — no queues wired up). Token-2022 close/burn is in scope; confidential-transfer / fee-harvest flows and swapping hook/permanent-delegate tokens remain out of scope. --- ## 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 (SKELETON — jobs not yet wired): planned async # metadata lookup, AI generation, safety, tx-confirm, 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 test suites (real tests in core/solana/prometheus) pnpm dev # run apps in parallel (dev) ``` Production runs under **pm2** (`ecosystem.config.cjs`: `pyre-web`, `pyre-api`, `pyre-worker`). The API and worker are launched with `node --env-file-if-exists=/.env --import tsx`, so the API loads secrets from the gitignored `.env` at the repo root. --- ## 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`). --- ## Secrets Secrets live in a **gitignored `.env` at the repo root** (chmod 600), loaded via `node --env-file-if-exists`. **Never commit keys** — there is no private-key env var by design (§trust rules), and `.env.example` documents the shape only. Admin endpoints (`/api/prometheus/generate`, Spawn launch) require an `x-admin-token` header equal to `ADMIN_API_TOKEN`; when that token is unset, admin endpoints are **closed** (403), not open. --- ## 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.) --- ## Working in this repo The skeleton and burner core already exist (see "Current status" above). When extending, stay inside the design doc's scope and the trust rules. Before touching transaction-building or classification code, read the relevant section of [`docs/PYRE_MVP_DESIGN.md`](docs/PYRE_MVP_DESIGN.md) (§6, §7, §8, §16) — that document wins on any conflict. Run `pnpm -r typecheck` and `pnpm -r test` after changes.