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`](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=<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`](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.