RogueWave
c20094ab56
pnpm + TypeScript workspace per design doc §13:
- apps/{web,api,worker} skeletons (Next.js 16, Fastify 5, BullMQ)
- packages/{core,solana,prometheus,db,config} (core has real types/DTOs;
solana/prometheus are stubs)
- programs/pyre-core placeholder (future Anchor, v1.0)
- docs/: PYRE_MVP_DESIGN (canonical), ARCHITECTURE, SECURITY, TOKEN_CLASSIFICATION
- CLAUDE.md, README, .env.example (no private-key var by design)
Skeleton + docs only — no Solana/business logic yet. All workspaces typecheck clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
165 lines
6.4 KiB
Markdown
165 lines
6.4 KiB
Markdown
# 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)
|
|
- Token-2022 support
|
|
- NFT handling (incl. compressed NFTs)
|
|
- Automatic valuable-token sacrifice
|
|
- Custodial signing
|
|
- Background wallet automation
|
|
|
|
v0.1 ships: wallet connect → scan token accounts → 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.
|