RogueWave/pyre
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
28064c513166018143de575a532d6fdc1451dd01
pyre/CLAUDE.md
RogueWave 00f9a96286 feat(phase2): close-empty-ATA flow — build/decode/preview/sign/confirm/receipt 
- @pyre/solana: buildCloseEmptyAccountsTx (UNSIGNED v0 tx; re-validates each
  account on-chain — owner==wallet, balance==0, correct program, not
  frozen/delegated, Token-2022 EMPTY_CLOSE_ONLY via §7.1; rejects whole build on
  any ineligible account), simulateTransaction, decodeTransaction. Rent
  destination + close authority + fee payer all pinned to the wallet.
- @pyre/api: POST /api/build/close-empty (server re-validates, 400 on ineligible)
  and POST /api/receipt (on-chain verified: meta.err==null, signer==wallet, rent
  from balance delta; lists only closes whose destination==wallet).
- @pyre/web: select empty accounts → build → CLIENT-SIDE decode+match (7 checks:
  feePayer/all-closeAccount/dest==wallet/closed-set==selected==preview) gates
  signing → sign in wallet → send → confirm → on-chain receipt w/ explorer link.

Built by 3 agents, reviewed by 2 audits (security: SOUND — no critical/high;
integration: SHIP). Applied audit fixes: receipt destination check, doc/lint
cleanup. typecheck 8/8, core 85, solana 19, web build green. Live-verified: the
API refuses to build a close tx for a non-empty account (400). buildBurnTx
remains a Phase-3 stub.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-05-31 04:49:30 +00:00

175 lines
7.0 KiB
Markdown
Raw Blame History

# 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. Implemented in
`@pyre/core` (`extensions.ts` + `classify.ts`) and `@pyre/solana` (account+mint
extension reads); unverifiable mints → UNSUPPORTED.
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.
Reference in New Issue View Git Blame Copy Permalink