# PYRE / Prometheus Protocol — MVP Design Document > Canonical source of truth for the PYRE MVP. This document is reproduced from > the original design brief. When in doubt, this file wins. **Tagline:** *Burn the dead. Feed the PYRE. Claim the Spawn.* > **Revision note — Rev 2 (2026-05-31):** Token-2022 (Token Extensions) is now > **in MVP scope**. Most new tokens — including everything launched on Pump.fun — > are Token-2022, so cleaning only classic SPL would miss the majority of real > dust. PYRE supports Token-2022 conservatively, gating on account/mint > **extensions** (see §7.1). The original brief's "skip Token-2022" stance is > superseded by this revision. --- ## 1. Project Summary PYRE is a Solana wallet-cleanup and ritual meme rebirth protocol. Users connect a Solana wallet. PYRE scans SPL token accounts for empty accounts, abandoned balances, dust tokens, scam tokens, illiquid remnants, and unsupported assets. The system classifies each token account and helps the user safely perform cleanup actions. The initial MVP focuses on **wallet cleanup and trust**: 1. Scan the user wallet. 2. Identify token accounts. 3. Classify assets as safe-to-close, burnable, transmutable, or protected. 4. Let the user close empty associated token accounts. 5. Return recovered ATA rent to the user. 6. Generate a clear PYRE receipt. The later ritual layer uses **Prometheus**, an AI firebringer engine, to generate a new meme token identity (a **Spawn**) from burned/transmuted token remnants. The first launch flow is semi-manual through Pump.fun before full protocol automation is attempted. > The MVP should **not** start as a fully automated on-chain launch protocol. It > should start as a safe burner/cleaner with a beautiful receipt experience. --- ## 2. Core Product Positioning PYRE is **not** an investment product, yield mechanism, trading bot, guaranteed-profit system, or protected launch mechanism. PYRE **is**: wallet cleanup, token scrap transmutation, recovered rent return, transparent contribution accounting, AI-generated meme rebirth, and ritual entertainment. > PYRE cleans dead Solana remnants from your wallet, returns recovered rent to > you, and optionally lets safely swapped scraps feed a ritual round that > Prometheus uses to birth a new AI-generated Spawn. --- ## 3. Core Trust Rule > **Recovered ATA rent returns to the user by default.** Rent must not be silently taxed, redirected, pooled, or used as Essence unless a future version creates an explicit opt-in donation mode. For MVP: - recovered rent goes to the user, - burned junk does not count as Essence, - swapped scraps may become Essence **only if the user explicitly approves**, - optional SOL contribution must be separate and explicit, - all actions require wallet approval, - **PYRE never has custody of private keys.** > **PYRE returns your rent. The scraps feed the fire.** --- ## 4. MVP Philosophy Narrow, practical, and trust-building. Do **not** build the full ritual launch protocol first. Build this first: ``` Connect wallet → scan token accounts → classify accounts → close eligible empty ATAs → optionally burn obvious junk → return rent to user → show receipt ``` Then add: ``` Burned/transmuted token metadata → Prometheus AI generation → manual Pump.fun launch package ``` Then later add: ``` Essence ledger → contribution proofs → round state machine → Spawn distribution → claim logic ``` The first emotional win: *"PYRE cleaned my wallet and returned SOL I forgot was trapped in token accounts."* That trust moment makes the later ritual layer believable. --- ## 5. MVP Feature Scope ### MVP v0.1 — Burner / Cleaner **Required:** - Solana wallet connect - Read token accounts - Detect empty associated token accounts - Estimate reclaimable rent - Classify obvious protected assets - Build close-account transactions - User signs locally - Send rent back to user wallet - Display transaction result - Generate PYRE receipt **Optional but desirable:** detect burnable junk tokens; allow user to burn selected junk to zero; close emptied accounts after burn; show skipped/protected tokens; export/share receipt image. **v0.1 token-program support:** classic **SPL Token** AND **Token-2022** token accounts are scanned, classified, closed, and burned — Token-2022 only when its account/mint extensions are safe to act on (see §7.1). Token-2022 accounts with unhandled extensions (confidential transfer, withheld transfer fees, unknown extensions) and all frozen accounts are skipped. **v0.1 must NOT include:** automatic Pump.fun launch, user-contributed Essence vault, custom PYRE Solana program, NFT handling, automatic valuable-token sacrifice, custodial signing, background wallet automation, on-chain swap routing (TRANSMUTABLE), or any Token-2022 confidential-transfer / fee-harvest flows. ### MVP v0.2 — Prometheus Meta Mixer AI generation from burned/cleaned token context. **Input:** token names, symbols, metadata, categories, burned count, transmutable count, source archetypes, optional theme seed, chaos factor. **Output:** spawn name, ticker, lore, tagline, image prompt, metadata description, Pump.fun launch description, risk/safety warnings, forbidden-term check, duplicate ticker/name check. Prometheus must **not** directly launch tokens — it generates a candidate package for human review. ### MVP v0.3 — Manual Pump.fun Creator Workflow ``` Burner receipt → Prometheus generates Spawn package → human reviews package → human manually creates Pump.fun token → PYRE records mint, launch URL, metadata, tx → public Spawn record page ``` Validates metadata/art/ticker quality, the Pump.fun creation process, user understanding, and social reaction without dangerous automation. ### MVP v0.4 — Essence Ledger ``` safe scrap swap output → net SOL value → record as Essence → associate with wallet and round → show round progress ``` Can start in a database before moving on-chain. **Important:** do not call it a deposit until an on-chain custody model exists; do not promise claims until claim logic exists; keep it experimental if not on-chain. ### MVP v1.0 — PYRE Core Program Custom Solana program for trust-critical accounting: create round, accept Essence, hold Essence vault, record contribution receipts, lock round, register Spawn mint, open claims, distribute Spawn pro rata, support refunds for failed rounds, prevent double claims. This is where PYRE becomes a true protocol. --- ## 6. Token Classification Token accounts are classified into conservative categories. - **EMPTY_CLOSE_ONLY** — zero balance, can be closed. *Action:* close ATA, send rent to user wallet. - **INCINERATE_ONLY** — no safe swap route but may be burnable. *Action:* user may burn balance to zero; if account becomes empty, close it; recovered rent returns to user. - **TRANSMUTABLE** — has a safe swap route and passes risk checks. *Action:* user may swap token into SOL; net swapped SOL may become Essence **only if the user opts in**. - **PROTECTED_SKIP** — not touched by default. Examples: SOL/WSOL special cases, USDC/USDT/major assets, valuable meme tokens, NFTs, LP tokens, receipt tokens, staked tokens, suspicious tokens, frozen accounts, delegated accounts, high-value balances. - **UNSUPPORTED** — system cannot safely reason about it. Examples: unknown token program, bad metadata, unsupported account layout, and **Token-2022 accounts or mints carrying extensions PYRE does not yet safely handle** — confidential transfer, accounts with withheld transfer fees, or any unrecognized extension (see §7.1). Token-2022 accounts with only benign/no extensions are classified exactly like classic SPL (EMPTY_CLOSE_ONLY / INCINERATE_ONLY / PROTECTED_SKIP), using the Token-2022 program for the close/burn instructions. Transfer-hook and permanent-delegate mints are still cleanable (burn/close don't trigger a transfer hook, and you may always burn/close your own account) but are **flagged** and excluded from any future swap. > **Default rule: Unknown means skip** — unknown token program *or* unknown/unsafe > Token-2022 extension. --- ## 7. Token Safety Rules The classifier must be conservative. MVP rules: - Support classic **SPL Token** and **Token-2022**; gate Token-2022 on its account *and* mint extensions per §7.1 (skip confidential transfer, withheld transfer fees, and any unknown extension). - Use the correct token program per account for every instruction (classic vs Token-2022); perform `CloseAccount` as a **top-level** instruction (CPI-Guard safe). - Reclaimable rent is the account's **live lamport balance** (Token-2022 rent varies with extensions) — never a fixed constant. - Skip NFTs. - Skip compressed NFTs. - Skip LP tokens. - Skip frozen accounts. - Skip delegated accounts. - Skip known valuable assets. - Skip tokens above a user-safe USD threshold. - Skip routes with high price impact. - Skip routes with stale quotes. - Skip unsafe or weird liquidity paths. - Simulate all transactions before final signing. > The system should never say *"This token is safe."* > It should say *"This token appears eligible based on current checks."* ### 7.1 Token-2022 (Token Extensions) Support Token-2022 accounts and mints can carry **extensions** that change what is safe to close, burn, or swap. The scanner reads extensions from `jsonParsed` RPC data on **both** the token account and its mint (transfer hook, permanent delegate, and confidential-transfer config live on the *mint*). Closing requires a zero-balance, non-frozen account; burning is owner-authorized and does **not** invoke a transfer hook. Program IDs: - Classic SPL Token — `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA` - Token-2022 — `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` Conservative per-extension policy (default for any **unknown extension → skip**): | Extension | close-empty | burn-then-close | swap (future) | |---|---|---|---| | None / Immutable-Owner / Memo / Metadata / Interest-Bearing | allow | allow | allow | | Non-Transferable (soulbound) | allow | allow (owner may burn) | block | | Transfer Hook (mint) | allow (no hook on close) | allow (no hook on burn) | **skip** + flag | | Permanent Delegate (mint) | allow | allow + **scam flag** | **skip** + flag | | Transfer Fee | allow only if **no** withheld balance | allow (harvest withheld before close) | allow, fee disclosed | | Default-Frozen / account `state == frozen` | **skip** | **skip** | **skip** | | Confidential Transfer | **skip** (needs drain + ZK-proof close) | **skip** | **skip** | | CPI Guard | allow (close as top-level ix) | allow | review | | Unknown / unrecognized | **skip** | **skip** | **skip** | Per-account preflight (server-side, never trust the client): 1. Read `info.state` — skip if `frozen`. 2. Read `tokenAmount.amount` — `0` ⇒ close path; non-zero ⇒ burn-then-close. 3. Read the token-account extensions — `confidentialTransferAccount` ⇒ skip; `transferFeeAmount.withheldAmount > 0` ⇒ skip (harvest-first is out of MVP scope). 4. Read the **mint** extensions — transfer hook / permanent delegate ⇒ flag (cleanable, but warn and exclude from swap). 5. Any unrecognized extension ⇒ UNSUPPORTED. 6. Reclaim = the account's live lamports; sign with the account owner / its `CloseAuthority`. Out of MVP scope (later phases): confidential-transfer close (drain + ZK proof), transfer-fee withheld-balance harvesting, and swapping hook/permanent-delegate tokens. --- ## 8. Burner Transaction Flow 1. **Wallet Connect** — user connects via Solana Wallet Adapter. 2. **Account Scan** — query token accounts. For each: owner, ATA address, mint, token program, balance, decimals, rent estimate (live lamports), metadata if available, token program type, frozen/delegated state, and — for Token-2022 — the account **and mint** extension list (§7.1). 3. **Classification** — each account classified; UI groups into: closeable empty accounts, burnable junk, potentially transmutable scraps, protected/skipped, unsupported. 4. **Preview** — before signing the user sees: accounts to close, tokens to burn, accounts skipped, estimated rent returned, transaction fees, warnings, destination wallet for recovered rent. 5. **Build Transaction** — backend/frontend builds an unsigned Solana transaction. It must be decoded and compared against the preview. 6. **User Signs** — locally, with the wallet. PYRE must never ask for private keys. 7. **Confirmation** — system waits for transaction confirmation. 8. **Receipt** — shows tx signature, accounts closed, tokens burned, rent returned, accounts skipped, warnings, timestamp, optional share image. --- ## 9. Prometheus AI Meta Mixer Prometheus is the creative engine. It generates Spawn identity, **not** control of funds. **Input:** `burned_tokens[]`, `transmuted_tokens[]`, `token_symbols[]`, `token_names[]`, `metadata_descriptions[]`, `dominant_archetypes[]`, `chaos_factor`, `manual_theme_seed_optional`. **Output:** `spawn_name`, `spawn_ticker`, `spawn_lore`, `spawn_tagline`, `spawn_description`, `image_prompt`, `metadata_json`, `launch_copy`, `risk_flags`. **Meta influence** (probabilistic, not deterministic) — example model: ``` 40% burned token archetypes 25% Essence-weighted token themes 20% Prometheus mutation / chaos 15% manual operator seed ``` Do not allow users to force exact copyrighted or existing meme identities. - Bad: *"Create a Pepe token."* - Better: *"Frog archetype influence increased."* Prometheus should create inspired mutations, not direct clones. --- ## 10. Pump.fun Creator Workflow The first Pump.fun integration is manual / approval-gated. **Manual MVP flow:** Prometheus generates token package → operator reviews → operator creates token on Pump.fun → operator records mint and launch link → PYRE shows Spawn record. **Semi-automated future:** generates package → backend uploads metadata → backend builds create transaction → creator/multisig signs → token launches → PYRE records launch. **Fully automated future** (NOT MVP): round locks → Prometheus generates Spawn → metadata uploaded → launch tx built → Essence used for initial acquisition → Spawn distributor receives tokens → contributors claim pro rata. --- ## 11. Architecture **Frontend** — Next.js, TypeScript, Tailwind, Solana Wallet Adapter, React Query or Zustand, transaction preview UI, receipt UI, admin/generation UI. *Responsibilities:* wallet connect, token account display, classification grouping, user confirmations, transaction signing, receipt rendering, Spawn package review, public round/spawn pages. **Backend API** — Node.js, Fastify or Express, TypeScript, PostgreSQL, Redis, BullMQ. *Responsibilities:* token scan coordination, classification helpers, route evaluation, AI generation orchestration, metadata preparation, receipt storage, Spawn record storage, public API, admin API. **Worker** — Node.js worker process, BullMQ queue, Redis, AI API clients. *Responsibilities:* slow token metadata enrichment, AI generation jobs, image prompt generation, safety checks, ticker/name collision checks, background confirmation tracking, receipt enrichment. **Database** — PostgreSQL. *Initial tables:* `wallet_scans`, `token_accounts`, `token_classifications`, `cleanup_receipts`, `burn_events`, `close_account_events`, `prometheus_generations`, `spawn_candidates`, `spawn_records`, `system_events`. *Future tables:* `pyre_rounds`, `essence_contributions`, `claim_records`, `refund_records`, `influence_fields`. **Redis** — job queue, scan cache, rate limiting, temporary quote cache, generation status. **Solana RPC** — external provider. Do **not** run a validator/RPC node on the MVP VPS. Required: get token accounts by owner, get account info, simulate transactions, send transactions, confirm transactions, parse token account state. **AI Services** — API-based first (text generation, image generation, moderation/safety, custom prompt templates). Do **not** run local LLMs or image models on the MVP server. --- ## 12. Server / Infrastructure Setup An 8GB VPS is enough for the MVP. Run: `pyre-web`, `pyre-api`, `pyre-worker`, postgres, redis, nginx, pm2 or systemd, logs, admin dashboard. Do **not** run: a Solana validator, a Solana RPC node, a large local LLM, local image generation, or heavy indexing at scale. **Server base setup — already completed:** new user `pyre`, root disabled, SSH key auth, UFW configured, Fail2ban installed, basic security hardening. **Next setup:** Node.js 22, pnpm, Git, nginx, PostgreSQL, Redis, PM2, Claude Code, project repo, environment files, backup script, log rotation. --- ## 13. Recommended Repo Structure ``` pyre/ apps/ web/ api/ worker/ packages/ core/ solana/ prometheus/ db/ config/ programs/ pyre-core/ docs/ PYRE_MVP_DESIGN.md ARCHITECTURE.md SECURITY.md TOKEN_CLASSIFICATION.md scripts/ infra/ preview.html CLAUDE.md package.json pnpm-workspace.yaml ``` - **apps/web** — user-facing app: landing, wallet connect, scanner UI, cleanup preview, receipt page, Prometheus generation preview, admin review page. - **apps/api** — backend HTTP API: scan, classify, build transaction, receipt, generation, admin endpoints. - **apps/worker** — background workers: async metadata lookup, AI generation, safety checks, tx confirmation watcher, receipt enrichment. - **packages/core** — shared types and business logic: classification enums, risk rules, shared DTOs, receipt schema, Prometheus input/output schema. - **packages/solana** — Solana transaction helpers: token account parsing, close-account tx builder, burn tx builder, simulation helpers, tx decoder. - **packages/prometheus** — AI generation logic: prompt templates, meta mixer, output parser, safety checks, image prompt generator. - **packages/db** — database schema, migrations, table definitions. - **packages/config** — shared config and environment loading. - **programs/pyre-core** — future Anchor program (NOT needed for the first burner MVP). --- ## 14. API Design ```http POST /api/scan # in: { "wallet": "wallet_pubkey" } # out: { scanId, wallet, summary: { totalAccounts, emptyCloseOnly, # incinerateOnly, transmutable, protectedSkip, unsupported, # estimatedRentLamports }, accounts: [] } POST /api/build/close-empty # in: { "wallet": "...", "accountAddresses": ["ata1","ata2"] } # out: { transactionBase64, preview: { accountsToClose, # estimatedRentReturnedLamports, rentDestination } } POST /api/build/burn # in: { "wallet": "...", "items": [{ tokenAccount, mint, amount }] } # out: { transactionBase64, preview: { tokensToBurn, accountsPotentiallyClosable } } POST /api/receipt # in: { "wallet": "...", "txSignature": "...", "scanId": "uuid" } # out: { receiptId, txSignature, rentReturnedLamports, closedAccounts, # burnedTokens, skippedTokens } POST /api/prometheus/generate # in: { "receiptId": "uuid", "chaos": 0.25, "operatorSeed": "optional" } # out: { generationId, spawnName, ticker, lore, imagePrompt, metadata, riskFlags } ``` --- ## 15. MVP Database Schema ``` wallet_scans: id, wallet, status, created_at, completed_at, summary_json token_accounts: id, scan_id, wallet, ata, mint, token_program, raw_balance, ui_balance, decimals, symbol, name, classification, warnings_json, estimated_rent_lamports, created_at cleanup_receipts: id, wallet, scan_id, tx_signature, rent_returned_lamports, closed_accounts_count, burned_tokens_count, status, created_at, receipt_json prometheus_generations: id, receipt_id, input_json, output_json, status, risk_flags_json, created_at, approved_at, rejected_at spawn_records: id, generation_id, spawn_name, ticker, mint, metadata_uri, pumpfun_url, launch_tx, status, created_at ``` (Also: `token_classifications`, `burn_events`, `close_account_events`, `spawn_candidates`, `system_events`.) --- ## 16. Security Requirements **Wallet Security:** Never request private keys. Never run custodial signing. Never auto-execute without user signing. Always show transaction preview. Decode transaction before signing. Match decoded transaction against preview. **Token Safety:** Unknown assets default to skip — unknown token program *or* unknown/unsafe Token-2022 extension (§7.1). Token-2022 is supported only when its account/mint extensions are safe to act on; confidential-transfer, withheld-fee, and frozen accounts are skipped. NFTs default skip. Valuable assets default skip. User must manually select anything risky. High-value actions require stronger confirmation. **Backend Security:** Rate-limit scan endpoints. Validate wallet pubkeys. Validate token account ownership. Do not trust client-submitted classifications; recompute server-side where needed. Log all transaction build requests. Protect admin endpoints. Use environment secrets only. Rotate API keys if leaked. **AI Safety:** Filter generated names, tickers, lore. Avoid hate, explicit, extremist, copyrighted, impersonation, and scam-like outputs. Require human approval before first launches. --- ## 17. Abuse Scenarios - **Misclassification of valuable asset** → user loses valuable token. *Defense:* protected token registry, USD value threshold, major-token skip list, manual advanced override only. - **Fake dust farming** → user creates many fake tokens to influence status. *Defense:* no allocation by token count, no reward by account count, Essence weighting only in future versions. - **Rent confusion** → people claim PYRE steals rent. *Defense:* receipt clearly shows rent returned, transaction preview clearly shows destination, do not pool rent by default. - **AI output abuse** → Prometheus generates offensive/copyrighted token. *Defense:* safety filters, blocked terms, ticker collision checks, human approval in MVP. - **Pump.fun launch abuse** → Spawn launches look like team-rug launches. *Defense:* manual review, public launch record, no profit promises, clear entertainment framing, disclose launch wallet / creator. --- ## 18. MVP Development Phases - **Phase 0 — Server and Repo Setup:** VPS configured, Claude Code installed, repo initialized, pnpm workspace created, web/api/worker skeleton, Postgres + Redis running, nginx configured, environment templates. - **Phase 1 — Wallet Scanner:** wallet connect frontend, scan endpoint, token account fetch, basic classification, scan results UI, protected/skipped UI. - **Phase 2 — Close Empty ATAs:** identify empty token accounts, build close-account tx, decode tx preview, wallet signing, confirmation tracking, receipt page. - **Phase 3 — Burn Junk:** incinerate-only classification, burn transaction builder, burn-then-close flow, stronger confirmations, receipt update. - **Phase 4 — Prometheus Generator:** generation input from receipt, meta mixer, Spawn name/ticker/lore generation, image prompt generation, safety checks, admin approval UI. - **Phase 5 — Manual Pump.fun Launch Workflow:** approved Spawn package, metadata JSON, operator launch checklist, mint/url/tx record input, public Spawn record page. - **Phase 6 — Essence / Round Prototype:** safe swap candidate detection, route quote preview, net Essence estimate, round dashboard, contribution database record, no claim promises until on-chain logic exists. - **Phase 7 — PYRE Core Program:** Anchor program — create round, contribute Essence, contribution receipt PDA, lock round, register Spawn, claim Spawn, refund failed round, tests. --- ## 19. What We Need Set Up Now **Server — already done:** pyre user, SSH auth key, root disabled, UFW, Fail2ban. **Server — next:** Node.js 22, pnpm, Git, nginx, PostgreSQL, Redis, PM2, Claude Code, repo directory, .env files, backup script, logrotate config. **External accounts / services:** Solana RPC provider, OpenAI/Anthropic API key, image generation provider, domain name, GitHub repo, Pump.fun creator wallet, optional IPFS/Arweave metadata service. **Local / dev tools:** VS Code or SSH workflow, Claude Code, Git, Node.js, pnpm, Postgres client, Redis CLI, Solana CLI (later), Anchor (later). **Project files to create:** `CLAUDE.md`, `README.md`, `docs/PYRE_MVP_DESIGN.md`, `docs/SECURITY.md`, `docs/TOKEN_CLASSIFICATION.md`, `.env.example`, `pnpm-workspace.yaml`. --- ## 20. First Claude Code Prompts After repo + CLAUDE.md exist, **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. --- ## 21. MVP Definition of Done The MVP is complete when a user can: connect wallet, scan token accounts, see clear classifications, select empty ATAs, preview the close-account transaction, sign it, recover rent to their wallet, see a receipt, generate a Prometheus Spawn concept from the receipt, manually record a Pump.fun launch, and view a public Spawn record page. > The MVP is **not** complete if it requires users to trust hidden backend logic. The MVP succeeds if users say: *"This cleaned my wallet, returned SOL, and the receipt/generation was cool."* That is the foundation for the full PYRE protocol.