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 — Built / In progress / Not yet built

This repo is no longer scaffold + docs — the burner core is implemented and live at 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.

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=<repo>/.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/<name> (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 — 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.)

---

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 (§6, §7, §8, §16) — that document wins on any conflict. Run pnpm -r typecheck and pnpm -r test after changes.