v0.2.0 — first-class APIs for the 5 v0.1 workspace shims

Breaking release addressing 5 architectural gaps surfaced by the v0.1.1 workspace migration.

Highlights

• TokenAccountPlanConfig — replaces 4-positional-param prepare_token_accounts with a config struct. No Default impl (rent has no safe default); use TokenAccountPlanConfig::with_rent(rent) constructor.
• AtaCreateMode { Idempotent (default), Legacy } — control whether prepare_token_accounts emits idempotent or non-idempotent ATA creates.
• MintIntent::RequireTokenBalance { amount } — validate (not transfer) non-SOL token balance at plan time. Errors with InsufficientBalance instead of v0.1's silent drop.
• TokenMintMetadata — replaces TokenMintWithFee. Now includes program_id (free, from account owner) and transfer_hook_program_id (parsed from TransferHook extension).
• 2 new TokenError variants — InsufficientBalance { mint, required, actual } and RequireBalanceForSolNotSupported(Pubkey).

Migration

See CHANGELOG.md for the full migration guide with before/after code blocks.

Quick summary:

// Before (v0.1.x)
let plan = prepare_token_accounts(&state, &intent, WrapSolStrategy::Ata, rent)?;
let parsed = get_token_mint_and_transfer_fee(pk, &acc, epoch)?;

// After (v0.2.0)
let plan = prepare_token_accounts(&state, &intent, TokenAccountPlanConfig::with_rent(rent))?;
let parsed = get_token_mint_metadata(pk, &acc, epoch)?;

Verification

• cargo +nightly fmt --check — clean
• cargo clippy --all-targets -- -D warnings — clean
• cargo test — 39 pass (15 unit + 18 integration + 6 doc)
• cargo doc --no-deps — clean

Provenance

Designed and shipped via the brainstorm → spec → plan → implement → review workflow. Source documents (in the consuming workspace, not this repo):

• Spec: `docs/superpowers/specs/2026-05-03-solana-token-toolkit-v0.2-design.md`
• Plan: `docs/superpowers/plans/2026-05-03-solana-token-toolkit-v0.2.md`
• Driving review: `docs/superpowers/reviews/2026-05-03-waterpump-token-migration-review.md`

v0.1.1 - migrate to litesvm-token-extensions

Pure test-infrastructure refactor. No production code change.

What changed

Migrated `tests/integration.rs`'s Token-2022 mint construction helpers
to the newly-shipped `litesvm-token-extensions`
crate (companion lib in the same v0.1 cycle).

• Removed: `create_token2022_mint_with_transfer_fee` (~50 LOC)
• Removed: `create_token2022_mint_with_transfer_hook` (~50 LOC)
• Added: `litesvm-token-extensions = "0.1"` dev-dep
• Replaced: 4 callsites with `CreateMintWithExtensions::new(...).with_*().send()`

Net LOC: -92 (-115 deletions, +23 insertions).

Same 30 tests passing (15 unit + 9 integration + 6 doc). All extension-parsing
test coverage preserved end-to-end via the dev-dep.

No public API change

This release is dev-deps + tests only. Public API remains identical to v0.1.0.

v0.1.0 - Initial release

First publishable release of `solana-token-toolkit`.

What's in v0.1

• Tier 1 (state): `fetch_token_account_state`, `assemble_token_account_state`
• Tier 2 (mint extensions): `get_token_mint_and_transfer_fee`, `detect_transfer_hooks`, `reject_transfer_hook_mints` (Token-2022 `TransferFeeConfig` + `TransferHook` parsing)
• Tier 3 (ATA workflow): `prepare_token_accounts` with `WrapSolStrategy::{Ata, Keypair, None}` and full ephemeral-keypair wSOL wrapping path

Key design decisions

• No global mutable state — `WrapSolStrategy` is per-call
• Caller-provided rent — Tier 3 stays synchronous
• Deterministic instruction order — `prepare_token_accounts` sorts by mint pubkey
• Typed errors throughout — no `anyhow` in public API
• `WrapSolStrategy::Seed` intentionally NOT supported (protocol-specific to certain DEX implementations, not portable)

Testing

30 tests passing:

• 15 unit tests
• 9 integration tests (3 LiteSVM-backed verifying Token-2022 mint extension parsing against real on-chain bytes)
• 6 doc tests

Compatibility

• Rust 1.81+ (MSRV 1.89 in Cargo.toml due to current solana-client 3.x requirement)
• Solana SDK 3.x split crates
• `spl-token-2022-interface` 2.x

v0.2 deferred items

• Caller-controlled `Keypair` signer for `WrapSolStrategy::Keypair` (e.g. multisig)
• `TransferHookInfo.authority` field
• `close_atas` / `sync_native_only` standalone helpers (only if external feedback warrants)