com_r35157_nenjim-hubd-impl_ref/openspec/specs/solana-spl-token-burning/spec.md

solana-spl-token-burning Specification

Purpose

Defines safe construction and wallet submission of checked SPL-token burns for both supported Solana token programs.

Requirements

Requirement: Checked SPL-token burn transaction construction

The blockchain API SHALL build an unsigned transaction containing exactly one checked SPL-token burn instruction for a supplied owner, token account, mint, raw amount, decimal count, and supported token program. The owner SHALL be the fee payer, token-account authority, and sole required signer. The transaction SHALL burn from the supplied token account and mint, use a recent blockhash, and remain unsigned and unsubmitted.

Scenario: Legacy SPL Token burn construction

• WHEN valid burn inputs identify the original SPL Token Program
• THEN the returned unsigned transaction contains one BurnChecked instruction owned by that program with the supplied account, mint, amount, and decimals

Scenario: Token-2022 burn construction

• WHEN valid burn inputs identify Token-2022
• THEN the returned unsigned transaction contains one BurnChecked instruction owned by Token-2022 with the supplied account, mint, amount, and decimals

Scenario: Builder does not submit

• WHEN a checked burn transaction is built successfully
• THEN the blockchain returns the unsigned serialized transaction and recent blockhash metadata without signing or submitting it

Requirement: Low-level burn input validation

Before fetching a blockhash, the blockchain SHALL reject null, blank, malformed, or unsupported required arguments. The raw amount SHALL be a valid positive integer representable as an unsigned 64-bit value, and the decimal count SHALL be representable as an unsigned byte.

Scenario: Invalid raw amount

• WHEN the raw amount is null, non-numeric, zero, negative, or greater than unsigned 64-bit maximum
• THEN transaction construction fails with IllegalArgumentException before fetching a blockhash

Scenario: Invalid decimals

• WHEN the decimal count is less than zero or greater than 255
• THEN transaction construction fails with IllegalArgumentException before fetching a blockhash

Scenario: Invalid address or program

• WHEN the owner, token account, or mint is null, blank, malformed, or does not decode to a Solana address, or the token program is null
• THEN transaction construction fails locally before fetching a blockhash

Requirement: Wallet-owned burn validation and exact conversion

The wallet SHALL accept a mint and positive human-readable amount, load the mint account, detect whether it is owned by the original SPL Token Program or Token-2022, obtain the mint decimals, and find its own holding under that program. It SHALL require the holding decimals to equal the mint decimals and SHALL convert the requested amount exactly to positive raw units without rounding. It SHALL reject unsupported mints, missing or inconsistent state, excessive precision, and amounts exceeding the wallet balance before transaction construction or submission.

Scenario: Exact partial balance burn

• WHEN a supported mint and positive amount are exactly representable with the mint decimals and do not exceed the wallet holding
• THEN the wallet supplies the corresponding exact raw amount, its own token account, detected program, and mint decimals to checked burn construction

Scenario: Complete balance burn

• WHEN the exact raw burn amount equals the wallet's complete token balance
• THEN the wallet permits the burn without requesting token-account closure or rent recovery

Scenario: Amount has excessive precision

• WHEN the requested human-readable amount contains a non-zero fraction beyond the mint decimal precision
• THEN the wallet rejects it with IllegalArgumentException before building, signing, or submitting a transaction

Scenario: Blockchain state cannot authorize burn

• WHEN the mint is missing or unsupported, the wallet has no holding, the holding decimals differ from the mint decimals, or the amount exceeds the holding balance
• THEN the wallet rejects the operation with IllegalStateException before building, signing, or submitting a transaction

Requirement: Single submission without automatic completion handling

After successful validation, the wallet SHALL build the burn through the blockchain API, sign it through its existing signing flow, submit it exactly once through its existing submission flow, and return the resulting transaction signature. It SHALL return immediately after submission without awaiting confirmation, retrying, rebuilding, re-signing, resubmitting, or closing the token account.

Scenario: Burn is submitted successfully

• WHEN validation, construction, signing, and submission succeed
• THEN the wallet returns the transaction signature from the single submission without invoking transaction awaiting

Scenario: Burn flow is interrupted or fails

• WHEN blockchain access, signing, or submission throws an I/O error or the calling thread is interrupted
• THEN the corresponding exception propagates and no automatic retry or subsequent completion action occurs

Requirement: Cached blockchain delegates burn construction

The cached blockchain decorator SHALL delegate every burn transaction construction call directly to its underlying blockchain without caching, reuse, or deduplication.

Scenario: Repeated construction through cached decorator

• WHEN callers request burn transaction construction multiple times through the cached decorator
• THEN every invocation reaches the underlying blockchain independently