pyre/CLAUDE.md

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 — 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)
• NFT handling (incl. compressed NFTs)
• Automatic valuable-token sacrifice
• Custodial signing
• Background wallet automation
• On-chain swap routing (TRANSMUTABLE) and Token-2022 confidential-transfer / fee-harvest flows

Token-2022 IS in v0.1 scope (Rev 2 — most new/pump.fun tokens are Token-2022), supported conservatively with account+mint extension gating: confidential transfer / withheld transfer fees / frozen / unknown extensions are skipped; transfer-hook & permanent-delegate mints are cleanable but flagged. See docs/PYRE_MVP_DESIGN.md §7.1. (Note: the classifier code currently still skips all Token-2022 as a safe subset until the extension-aware implementation lands.)

v0.1 ships: wallet connect → scan token accounts (classic SPL + Token-2022) → 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.

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/<name> (e.g. @pyre/core, @pyre/solana).

---

Docs

• docs/PYRE_MVP_DESIGN.md — canonical design (source of truth)
• docs/ARCHITECTURE.md — system architecture
• docs/SECURITY.md — security requirements
• 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.