pyre/docs/TOKEN_CLASSIFICATION.md

# Token Classification

> Spec for the PYRE token-account classifier. Aligned with
> [`PYRE_MVP_DESIGN.md`](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](#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](#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:**
  - Token-2022 accounts (in the MVP)
  - Unknown token program
  - Bad / missing metadata
  - Unsupported account layout
  - Accounts with extension behavior not yet handled

---

## Safety rules

Reproduced from design doc §7 as a checklist. The classifier and any action
builder must enforce **all** of these. 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.

---

## 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, and
   frozen/delegated state if available.
2. **Token program check** — if not classic SPL (e.g. Token-2022, unknown
   program), classify as `UNSUPPORTED`. Stop.
3. **Account integrity check** — if metadata is bad/missing, the account layout
   is unsupported, or extension behavior is unhandled, classify as
   `UNSUPPORTED`. Stop.
4. **Protected check** — if the asset is an NFT, compressed NFT, LP token,
   receipt token, staked token, major/known-valuable asset, SOL/WSOL special
   case, suspicious token, frozen account, delegated account, or a high-value /
   over-threshold balance, classify as `PROTECTED_SKIP`. Stop.
5. **Empty check** — if the balance is zero, classify as `EMPTY_CLOSE_ONLY`.
   Stop.
6. **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.
7. **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
  ├─ not classic SPL? ───────────────────────────────► UNSUPPORTED
  ├─ bad metadata / layout / unhandled extension? ───► UNSUPPORTED
  ├─ NFT / cNFT / LP / receipt / staked / major /
  │  valuable / SOL-WSOL / suspicious / frozen /
  │  delegated / over-threshold? ────────────────────► PROTECTED_SKIP
  ├─ balance == 0? ──────────────────────────────────► EMPTY_CLOSE_ONLY
  ├─ safe swap route + passes risk checks? ──────────► TRANSMUTABLE
  └─ otherwise (burnable junk, no safe route) ───────► INCINERATE_ONLY
```

---

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