pyre/docs/PYRE_MVP_DESIGN.md

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.

---

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 must NOT include: automatic Pump.fun launch, user-contributed Essence vault, custom PYRE Solana program, Token-2022 support, NFT handling, automatic valuable-token sacrifice, custodial signing, background wallet automation.

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: Token-2022 in MVP, unknown token program, bad metadata, unsupported account layout, accounts with extension behavior not yet handled.

Default rule: Unknown means skip.

---

7. Token Safety Rules

The classifier must be conservative. MVP rules:

• Classic SPL only.
• Skip Token-2022 by default.
• 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."

---

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, metadata if available, token program type, frozen/delegated state if available.
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

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. Token-2022 default skip for MVP. 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.