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

```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. 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.