feat(token-swap): production-shape AMM example - protocol fees, slippage, correctness fixes, u128 math

[mikemaccana-edwardbot]

What this PR does

Brings the constant-product AMM example in tokens/token-swap/ to production shape: purpose-led naming throughout, a configurable admin protocol-fee mechanism, slippage protection on every state-changing handler, correctness fixes on deposit_liquidity and the LP-mint formula, a constant-product invariant check on swap, and a full migration from fixed-point (I64F64) to u128 + checked_* integer arithmetic. The fixed crate dependency is removed entirely.

Correctness fixes

• deposit_liquidity ratio bug. The non-empty-pool branch was using K = pool_a * pool_b as a "ratio" and then multiplying or dividing the caller's amount by it — nonsense math, unexercised because every prior test deposited into an empty pool. Replaced with Uniswap V2's mint() ratio-clamp pattern in u128 integer math: caller amounts are upper bounds, the contract picks the largest pair that lies on the current price line. Uses effective reserves (vault balance minus the admin's owed fees) so accumulated admin fees don't distort the LP price. Adds AmmError::DepositAmountTooSmall for sub-base-unit deposits that clamp to zero.

• LP-mint formula bug. deposit_liquidity was using sqrt(amount_a * amount_b) for every deposit, breaking proportionality on subsequent deposits. Now matches Uniswap V2:

  • initial: liquidity = sqrt(a*b) - MINIMUM_LIQUIDITY
  • subsequent: liquidity = min(a * supply / pool_a, b * supply / pool_b) against effective reserves.

  The initial-deposit sqrt is computed with a u128 Newton's-method integer_sqrt helper (no more I64F64::sqrt).

• claim_admin_fees no-signal bug. Used to silently succeed when both fee accumulators were zero. Now reverts with AmmError::NothingToClaim. (Also unblocks tests: two byte-identical claim transactions share a signature; tests expire_blockhash between repeat claims.)

New features

• Admin protocol-fee mechanism (Uniswap V2 / Raydium accumulator pattern). Config.admin_share_bps splits each swap's trading fee between LPs and a configurable admin slice. PoolConfig.admin_fees_owed_a / _b accumulate the admin's per-side claim virtually inside the existing pool_a / pool_b vaults — no extra CPI per swap. New claim_admin_fees handler lets the admin sweep accrued fees from both sides, authorised via has_one = admin against Config. deposit_liquidity and withdraw_liquidity use effective reserves so the admin's owed slice doesn't drag LP shares.
• Slippage protection on every state-changing handler. Pass 0 to opt out. Withdraw bounds are checked before any transfers.
  • swap_tokens: existing min_output_amount kept; error renamed OutputTooSmall → SlippageExceeded.
  • deposit_liquidity: new minimum_lp_tokens_out. Pairs with the ratio-clamp upper bound for full slippage protection (clamp protects against over-spending either token; floor protects against under-receiving LP tokens). Reverts with AmmError::DepositBelowMinimum.
  • withdraw_liquidity: new minimum_token_a_out and minimum_token_b_out. Reverts with AmmError::WithdrawalBelowMinimum.
• Constant-product invariant check on swap. Post-trade k = effective_a * effective_b is recomputed in u128 (raw u64 multiplication overflows at large reserves, ~1.8e19 base units) and compared against the pre-trade invariant; the trade reverts if k decreases. Defence-in-depth against curve-math regressions.

Renames & structural changes

Rule applied throughout: purpose over implementation, clarity over convention. A first-time reader should be able to infer the role of each account, struct, field, and parameter from its name.

Account fields:

• pool_account_a / pool_account_b → pool_a / pool_b (the reserves are "the pool" in natural English; vault_* imported yield-bearing-vault DeFi vocabulary that doesn't apply).
• mint_liquidity → liquidity_provider_mint (the mint that issues LP tokens; "LP" expanded for first-time readers).
• depositor_account_* / trader_account_* → token_a / token_b / liquidity_provider_token (the redundant owner prefix duplicates the signer field already on the Accounts struct).

Types:

• State struct Amm → Config (it holds program-level config — admin, fee, bump — not "the AMM").
• State struct Pool → PoolConfig (it holds per-pool config / identity — config, mint_a, mint_b, bump — not pool state).
• Error type TutorialError → AmmError.
• Accounts derive structs renamed to <HandlerName>Accounts (e.g. CreateAmm → CreateConfigAccounts). Structs name what they are (the bag of accounts for handler X), not a verb they pretend to do.

Handlers:

• create_amm → create_config (names the account it creates, matching CreateConfigAccounts).
• swap_exact_tokens_for_tokens → swap_tokens (the Uniswap-style disambiguator earns no keep without a swap_tokens_for_exact_tokens sibling).
• swap parameter swap_a: bool → input_is_token_a: bool (purpose, not internal direction flag).

Config singleton:

• Config is now a singleton with seeds [b"config"]. The id: Pubkey parameter is removed from create_config. Real DEXes ship one program per AMM (Phoenix, Raydium) — the id was leftover complexity. Calling create_config twice fails because the account already exists.
• CONFIG_SEED: &[u8] = b"config" added to anchor constants.rs; quasar's AmmPda renamed to ConfigPda with #[seeds(b"config")]; amm: Address generics in PoolPda / PoolAuthorityPda / LiquidityMintPda renamed to config: Address.
• Pool seeds [config, mint_a, mint_b] are unchanged.

Math discipline

• All money math is now u128 + checked_mul / checked_div / try_into, multiply-before-divide, floor rounding in the pool's favour (Uniswap V2 convention).
• swap_tokens constant-product output and fee formula rewritten in u128.
• withdraw_liquidity proportional-withdraw formula rewritten in u128.
• deposit_liquidity already used u128.
• integer_sqrt (u128 Newton's method) replaces I64F64::sqrt for the initial-deposit branch.
• AmmError::MathOverflow added for the checked_* path.
• fixed = "1.27.0" removed from Cargo.toml.

Documentation

• README.md rewritten to match the code: identifiers, singleton Config, admin protocol-fee design, slippage args, corrected deposit / LP-mint math.
• New NVDAx/USDC lifecycle walkthrough with four actors (admin, LP, retail trader, arbitrageur), spelling out every handler call (Accounts struct, fields, args) and the arithmetic for each swap / deposit / withdraw / claim. All identifiers grep-checked against src/.

Tests

18/18 Rust + LiteSVM integration tests passing. Coverage:

• matching-ratio deposit uses both amounts in full;
• deposit clamps excess on either side (A or B);
• deposit after a swap honours the shifted effective ratio (not the raw vault ratio);
• sub-base-unit deposit reverts with DepositAmountTooSmall;
• subsequent-deposit LP-mint is proportional to share of pool;
• post-swap deposit LP-mint uses effective reserves (admin fees excluded);
• swap slippage revert (and zero-min still succeeds);
• deposit slippage revert (with exact-floor sanity check);
• withdraw slippage revert on both sides;
• constant-product invariant preservation across swaps;
• admin-fee accrual and claim across multiple swaps;
• NothingToClaim revert on a no-op claim.

Run with: cargo test --manifest-path tokens/token-swap/anchor/programs/token-swap/Cargo.toml --tests.

Scope

• tokens/token-swap/anchor/programs/token-swap/ — source + tests
• tokens/token-swap/quasar/ — mirror source + tests
• tokens/token-swap/README.md