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

> **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.
>
> **Revision note — Rev 3 (2026-05-31):** The core loop is *sell sellable tokens
> → feed the PYRE (opt-in Essence) → close the emptied account*; **burning is for
> unsellable tokens only**. Selling (TRANSMUTABLE) is pulled into near-term scope
> via the **Jupiter** aggregator (§6.1) — PYRE builds no swap math and runs no
> pump.fun engine. Essence is **model 1**: net SOL stays in the user's wallet and
> is recorded as an opt-in off-chain tally; **no custody** until the v1.0 program.
>
> **Revision note — Rev 4 (2026-05-31):** Monetization locked. Recovered rent
> returns to the user **minus a transparent 5% protocol fee** (taken in the signed
> tx, shown before signing), plus an **optional user-chosen extra contribution**.
> Fees = Essence that seeds Spawn launches + the contributor claim pool — this is
> the value loop that makes PYRE more than a burn service. Swap proceeds always go
> to the user (only a ~1% swap fee). See §3.1. Fee treasury (MVP):
> `122CNV5ZLu6fqZFpEMUdUSQwDv2zs23pkYQhkNtSQk5k` (swap for a multisig before scale).

---

## 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, minus one transparent, previewed
> protocol fee.** (Rev 4 — amends the original "rent is never taxed" stance to a
> sustainable, disclosed fee; see §3.1.)

Rent must never be **silently** taxed, redirected, or pooled. The ONLY deduction
is a single, clearly-disclosed protocol fee shown in the transaction the user
signs; everything else stays with the user.

For MVP:

- recovered rent goes to the user **minus the disclosed protocol fee** (§3.1),
- the fee is shown before signing (gross reclaimed · fee · net to you) and is an
  instruction **inside the user-signed tx** — never a hidden/after-the-fact charge,
- burned junk does not count as Essence,
- swapped scraps: proceeds go to the **user** (PYRE never keeps swap output); only
  the disclosed swap fee is taken,
- any **optional extra contribution** ("feed the PYRE more") must be explicit and
  user-chosen, on top of the base fee — never defaulted on,
- all actions require wallet approval,
- **PYRE never has custody of private keys** (the treasury receives only fee SOL;
  it never holds user funds).

> **PYRE returns your rent — minus a small fee that feeds the fire.**

### 3.1 Protocol fee & Essence (the value loop)

PYRE is sustained — and the PYRE is fed — by a small, transparent fee on what it
recovers (industry-standard for Solana cleaners; e.g. Sol Incinerator ~2%). PYRE's
fee is deliberately in the fair band:

| Action | Fee | Who gets the rest |
|---|---|---|
| Close empty ATA / burn-then-close (reclaimed rent) | **5%** | 95% → user |
| NFT / Token-2022 (larger rent) burn-then-close | **5%** | 95% → user |
| Swap to SOL (transmute) | **~1%** | 100% of swap proceeds → user |
| Optional "feed the PYRE more" | user-chosen extra % | — |

- The fee is taken as an explicit transfer instruction to the **PYRE treasury** in
  the same transaction the user signs, and is shown in the preview. Non-custodial:
  the user signs; PYRE holds no keys; the treasury receives only fee SOL.
- Collected fees (+ opt-in contributions) are **Essence** — they pool to seed
  **Spawn** launches and the contributor **claim** pool (§9, §18). This is what
  makes PYRE more than a burn tool: clean = the hook, the fee = the fuel,
  Spawn+claim+rounds = the differentiation.
- Trust is the moat: always display net SOL + the exact fee before signing; never
  inject undisclosed instructions; never keep swap proceeds.
- **Ops:** the treasury must be funded to rent-exemption (~0.0009 SOL) before it
  collects fees, or the first fee transfer into a 0-balance account fails the tx
  ("insufficient funds for rent"). Verified end-to-end on mainnet 2026-05-31
  (burn→close→5% fee→Essence; tx 5ddbmLRz…).

---

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

**Selling scraps (Transmute) is now near-term scope** (Rev 3 — see §6.1): the core
loop is *sell sellable tokens for SOL → feed the PYRE (opt-in Essence) → close the
emptied account*; burning is reserved for genuinely unsellable tokens. Selling is
routed through Jupiter (third-party aggregator); PYRE never builds the swap math
itself and never takes custody (Essence is an opt-in off-chain tally — model 1).

**v0.1 must NOT include:** automatic Pump.fun launch, custom PYRE Solana program,
NFT handling, automatic valuable-token sacrifice, custodial signing, background
wallet automation, any Essence VAULT/custody (no "deposit" until the v1.0 on-chain
program), 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 (via Jupiter, §6.1) that passes the
  price-impact / slippage / dust guards. *Action:* user may swap the token into
  SOL; the net SOL stays in the user's wallet, and may be recorded as Essence
  ("feed the PYRE") **only if the user opts in** (off-chain tally, no custody).
  This is the preferred outcome for any token with real liquidity — burning is
  for unsellable tokens only.
- **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.

### 6.1 Selling scraps (Transmute) — Jupiter + the third-party-swap trust model

A non-empty token is **TRANSMUTABLE** (preferred over burning) when it has a safe
route to SOL. PYRE does **not** implement swap math or run a pump.fun engine — it
uses **Jupiter** as the aggregator:

- **Routing:** Jupiter **Ultra** (`/ultra/v1/order` → user signs → `/ultra/v1/execute`,
  keyless via `lite-api.jup.ag`) routes both **pre- and post-"graduation" pump.fun**
  tokens and **Token-2022**. If Ultra returns no route for a mint, optionally fall
  back to **PumpPortal**'s keyless local-trade API (bonding-curve sell); if neither
  routes, the token is unsellable → INCINERATE_ONLY or close-for-rent.
- **Output:** sell to wSOL with `wrapAndUnwrapSol` so the user receives **native SOL**.
- **Risk pre-screen:** call Jupiter's **Shield** API per mint; surface
  freeze/mint-authority and low-liquidity warnings.
- **Guards (a route alone is not enough):** block if `priceImpactPct` exceeds the
  threshold (warn ~2–3%, hard cap ~10%); cap slippage; and a **dust gate** — if the
  estimated NET SOL ≤ (tx fee + reclaimable rent), selling is not worth it → keep it
  INCINERATE_ONLY / suggest close-for-rent instead.

**Trust model for a third-party-built swap tx (critical).** The swap transaction is
built by Jupiter, not PYRE, and is multi-instruction with address-lookup-tables —
so it **cannot be byte-matched** the way our own close/burn tx is (§16). Before the
user signs, PYRE must instead:

1. **Simulate** the transaction and confirm the user's **SOL balance delta ≥
   `otherAmountThreshold`** (the quote's min-out) with no simulation error — this
   validates the economic effect regardless of route structure.
2. Confirm the **only required signer is the user** (no co-signer / foreign fee payer).
3. Scan instructions and **reject any `SetAuthority`, delegate `Approve` to a foreign
   address, or `CloseAccount` whose destination is not the user**.
4. Confirm proceeds credit the **user's** account.

The user always signs in their own wallet (PYRE never holds keys). **Essence
("feed the PYRE") = the net SOL is recorded as an opt-in, off-chain tally only;
proceeds stay in the user's wallet and PYRE takes no custody** until the v1.0
on-chain program. Rent and Essence are always kept separate (§3).

---

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