Most new tokens — incl. all Pump.fun launches — are Token-2022, so cleaning only classic SPL misses the majority of real dust. PYRE now supports Token-2022 conservatively, gating on account+mint extensions: - skip: confidential transfer, withheld transfer fees, frozen/default-frozen, and any unrecognized extension (UNSUPPORTED). "Unknown means skip" now covers unknown program OR unknown/unsafe extension. - cleanable but flagged: transfer-hook & permanent-delegate (burn/close don't fire a hook; you may always burn/close your own account); non-transferable is burnable. - rent reclaim = account's live lamports (Token-2022 size varies); CloseAccount as a top-level instruction (CPI-Guard safe). Updated PYRE_MVP_DESIGN.md (§5/§6/§7 + new §7.1 policy table + §8/§16), TOKEN_CLASSIFICATION.md (categories, safety checklist, decision flow), SECURITY.md. Researched against Solana docs + Neodyme review. Classifier CODE still skips all Token-2022 (safe subset) until the extension-aware impl lands next. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
636 lines
26 KiB
Markdown
636 lines
26 KiB
Markdown
# 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.
|