69: Add SPL-token burn support to SolanaWallet and SolanaBlockChain

openspec/specs/solana-spl-token-burning/spec.md

@@ -0,0 +1,74 @@
+# 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