chore: scaffold PYRE MVP monorepo (structure + docs)
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>
This commit is contained in:
164
CLAUDE.md
Normal file
164
CLAUDE.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user