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

```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/<name>` (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.