pyre/docs/TOKEN_CLASSIFICATION.md

Token Classification

Spec for the PYRE token-account classifier. Aligned with PYRE_MVP_DESIGN.md §6 and §7 — when in doubt, the design doc wins.

PYRE scans a wallet's SPL token accounts and assigns each one a single conservative category. The category determines what action (if any) the user is allowed to take and how recovered rent / Essence are handled.

---

Philosophy: conservative by default

The classifier exists to protect the user from accidentally destroying value. It is intentionally cautious. It never optimizes for "more accounts cleaned" at the cost of safety. When two readings of an account are possible, it picks the safer (less destructive) one.

Default rule: Unknown means skip.

Anything the system cannot fully and safely reason about — an unknown token program, bad or missing metadata, an unsupported account layout, unfamiliar extension behavior — is classified into a non-destructive category (PROTECTED_SKIP or UNSUPPORTED) and is never acted on by default. The user must manually opt in to anything risky.

The classifier must never say "this token is safe." It may only say "this token appears eligible based on current checks." See Wording rule.

---

Classification categories

Each token account is assigned exactly one of the following categories. The canonical enum lives in packages/core (see Canonical enum).

EMPTY_CLOSE_ONLY

• Enum identifier: EMPTY_CLOSE_ONLY
• Meaning: A zero-balance token account that can be closed.
• Allowed action(s): Close the associated token account (ATA).
• Rent / Essence rules: Recovered ATA rent is sent to the user's wallet. Nothing is counted as Essence.

INCINERATE_ONLY

• Enum identifier: INCINERATE_ONLY
• Meaning: An account with a balance that has no safe swap route but may be burnable junk.
• Allowed action(s): The user may burn the balance to zero; if the account becomes empty after the burn, it may then be closed.
• Rent / Essence rules: Recovered rent (from closing the emptied account) returns to the user's wallet. Burned junk does not count as Essence.

TRANSMUTABLE

• Enum identifier: TRANSMUTABLE
• Meaning: An account holding a token that has a safe swap route and passes the risk checks.
• Allowed action(s): The user may swap the token into SOL.
• Rent / Essence rules: The net swapped SOL may become Essence only if the user explicitly opts in. Without opt-in, proceeds go to the user. Recovered rent from any subsequently closed account returns to the user.

PROTECTED_SKIP

• Enum identifier: PROTECTED_SKIP
• Meaning: An account PYRE recognizes but will not touch by default because acting on it could destroy or mishandle value.
• Allowed action(s): None by default. Acting on these requires an explicit, manual advanced override by the user.
• Rent / Essence rules: No rent recovery and no Essence by default.
• Example asset types:
  • SOL / WSOL special cases
  • USDC / USDT / other major assets
  • Valuable meme tokens
  • NFTs
  • LP tokens
  • Receipt tokens
  • Staked tokens
  • Suspicious tokens
  • Frozen accounts
  • Delegated accounts
  • High-value balances

UNSUPPORTED

• Enum identifier: UNSUPPORTED
• Meaning: An account the system cannot safely reason about in the MVP.
• Allowed action(s): None. These are skipped.
• Rent / Essence rules: No rent recovery and no Essence.
• Example asset types:
  • Unknown token program
  • Bad / missing metadata
  • Unsupported account layout
  • Token-2022 accounts/mints with extensions not yet safely handled — confidential transfer, withheld transfer fees, or any unrecognized extension (see design doc §7.1). Token-2022 with benign/no extensions is classified like classic SPL.

---

Safety rules

Reproduced from design doc §7 as a checklist. The classifier and any action builder must enforce all of these. MVP rules:

• Support classic SPL and Token-2022; gate Token-2022 on account+mint extensions per design doc §7.1 (skip confidential transfer, withheld transfer fees, frozen, and any unknown extension). Use the correct token program per account; CloseAccount as a top-level instruction.
• Reclaimable rent = the account's live lamports (not a 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.

---

Wording rule

The system must never state that a token is safe.

• Forbidden: "This token is safe."
• Required: "This token appears eligible based on current checks."

This wording is load-bearing: it communicates that eligibility is a snapshot of current automated checks, not a guarantee about the asset.

---

Decision flow

How a single account flows from scan to a final category:

1. Scan — fetch the token account: owner, ATA address, mint, token program, raw/UI balance, decimals, metadata if available, token program type, frozen/delegated state, and (Token-2022) the account and mint extension list.
2. Token program check — classic SPL and Token-2022 are both supported. An unknown/other token program ⇒ UNSUPPORTED. Stop.
3. Extension check (Token-2022) — if the account/mint carries an extension PYRE does not safely handle (confidential transfer, withheld transfer fees, or any unrecognized extension), classify as UNSUPPORTED. Stop. Transfer-hook / permanent-delegate mints continue but are flagged (see design doc §7.1).
4. Account integrity check — bad/missing metadata or unsupported layout ⇒ UNSUPPORTED. Stop.
5. Lock check — frozen or delegated accounts are skipped regardless of balance: classify as PROTECTED_SKIP. Stop.
6. Empty check — if the balance is zero (and classic-SPL/Token-2022 with safe extensions, not frozen/delegated), classify as EMPTY_CLOSE_ONLY. Stop. (Empty accounts hold no value, so they close regardless of mint identity.)
7. Protected check — for a NON-empty balance: if the asset is an NFT, compressed NFT, LP token, receipt token, staked token, major/known-valuable asset, SOL/WSOL special case, suspicious token, or a high-value / over-threshold balance, classify as PROTECTED_SKIP. Stop.
8. Route check — evaluate a swap route. If a safe route exists and passes all risk checks (no high price impact, no stale quote, no weird liquidity path, simulation passes), classify as TRANSMUTABLE. Stop. (No swap routing in MVP v0.1, so this never fires yet.)
9. Fallback — otherwise the account has a balance with no safe route but may be burnable junk: classify as INCINERATE_ONLY.

At any step where the system cannot safely decide, it falls back to a non-destructive category — Unknown means skip.

scan account
  ├─ unknown/other token program (not SPL or Token-2022)? ─► UNSUPPORTED
  ├─ Token-2022 unsafe/unknown extension
  │  (confidential transfer / withheld fee / unrecognized)? ► UNSUPPORTED
  ├─ bad metadata / unsupported layout? ───────────────────► UNSUPPORTED
  ├─ frozen or delegated?  (regardless of balance) ────────► PROTECTED_SKIP
  ├─ balance == 0?  (closes regardless of mint identity) ──► EMPTY_CLOSE_ONLY
  ├─ NON-empty & NFT / cNFT / LP / receipt / staked / major /
  │  valuable / SOL-WSOL / suspicious / over-threshold? ───► PROTECTED_SKIP
  ├─ NON-empty & safe swap route + passes risk checks? ────► TRANSMUTABLE
  └─ otherwise (burnable junk, no safe route) ─────────────► INCINERATE_ONLY

(Transfer-hook & permanent-delegate Token-2022 mints pass the program/extension gates — they are cleanable — but are flagged and excluded from swap. See design doc §7.1.)

---

Canonical enum

The canonical classification enum and the risk rules live in packages/core (shared types and business logic). Apps and the worker import the enum from there; they must not redefine it.

The server must recompute classification. Client-submitted classifications are never trusted — the backend recomputes classification server-side before building any transaction (design doc §16). A category arriving from the client is treated as a hint at most, never as authority for a destructive action.