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

Brings the constant-product AMM example to production shape:
purpose-led naming, a configurable admin protocol-fee mechanism,
slippage protection on every state-changing handler, correctness
fixes on deposit and LP-mint math, a constant-product invariant
check on swap, and a full migration from fixed-point (I64F64) to
u128 + checked_* integer arithmetic. Drops the `fixed` crate
dependency entirely.

Correctness fixes
- deposit_liquidity used K = pool_a * pool_b as a "ratio" and then
  multiplied/divided the caller's amount by it. That's nonsense
  math, unexercised because all prior tests 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 on the current price line. Uses *effective*
  reserves (vault balance minus admin's owed fees). Adds
  AmmError::DepositAmountTooSmall for sub-base-unit deposits that
  clamp to zero.
- deposit_liquidity LP-mint formula used sqrt(a * 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)
  using effective reserves. Initial-deposit sqrt is computed with a
  u128 Newton's-method integer_sqrt helper (no more I64F64::sqrt).
- claim_admin_fees silently succeeded when both fee accumulators
  were zero. Adds AmmError::NothingToClaim so the admin gets a real
  signal and the test suite can exercise the no-op path. (Also
  fixes a litesvm gotcha where two byte-identical claim txs share a
  signature; tests now expire the 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. `PoolConfig.admin_fees_owed_a`
  and `_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,
  authorised via `has_one = admin` against `Config`.
- Slippage protection on every state-changing handler:
    swap_tokens:        min_output_amount (existing arg; error
                        renamed OutputTooSmall -> SlippageExceeded)
    deposit_liquidity:  minimum_lp_tokens_out (new)
    withdraw_liquidity: minimum_token_a_out, minimum_token_b_out (new)
  Pass 0 to opt out. Withdraw bounds are checked *before* any
  transfers. New AmmError variants DepositBelowMinimum and
  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) and compared against
  the pre-trade invariant; the trade reverts if k decreases.
  Defence-in-depth against curve-math regressions.

Renames & structural changes (purpose over implementation)
Account/struct/field renames so a first-time reader can infer
each thing's role from its name:
- Pool account fields:
    pool_account_a/b              -> pool_a / pool_b
    mint_liquidity                -> liquidity_provider_mint
    depositor_account_a/b         -> token_a / token_b
    depositor_account_liquidity   -> liquidity_provider_token
    trader_account_a/b            -> token_a / token_b
  (the `trader_`/`depositor_` prefix duplicates the signer field
   already on the Accounts struct).
- Vault terminology dropped: vault_a/b -> pool_a/b. "Vault" implies
  yield-bearing structures (Drift/Kamino/Marinade); these are just
  the pool's reserves.
- State struct Amm -> Config (program-level Config, not "the AMM").
- State struct Pool -> PoolConfig (it holds per-pool config /
  identity, not pool state).
- Error type TutorialError -> AmmError.
- Accounts derive structs: CreateAmm/CreatePool/DepositLiquidity/
  WithdrawLiquidity/SwapExactTokensForTokens ->
  CreateConfigAccounts / CreatePoolAccounts / DepositLiquidityAccounts /
  WithdrawLiquidityAccounts / SwapTokensAccounts. Structs name what
  they *are* (the bag of accounts for handler X), not a verb they
  pretend to do.
- Handler renames: create_amm -> create_config (says which account
  it creates); swap_exact_tokens_for_tokens -> swap_tokens (the
  Uniswap-style disambiguator earns no keep without a sibling).
- swap parameter swap_a: bool -> input_is_token_a: bool (purpose,
  not internal direction flag).
- Config is now a singleton: seeds = [b"config"], `id: Pubkey`
  parameter removed from create_config. Real DEXes ship one program
  per AMM; the `id` was leftover complexity.

Math discipline
- All money math is 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 formula and fee math
  rewritten as u128 numerator / u128 denominator.
- withdraw_liquidity proportional-withdraw formula rewritten in
  u128 with the same discipline.
- deposit_liquidity already uses u128 throughout.
- integer_sqrt (u128 Newton's method) replaces I64F64::sqrt for the
  initial-deposit branch.
- AmmError::MathOverflow added for the checked_* path.
- Removed `fixed = "1.27.0"` from Cargo.toml.

Documentation
- README rewritten: aligns identifiers with the code, documents the
  singleton `Config`, the admin protocol-fee design, slippage args,
  the corrected deposit / LP-mint math, and notes integer_sqrt.
- Adds an NVDAx/USDC lifecycle walkthrough with four actors (admin,
  LP, retail trader, arbitrageur) and the arithmetic for every
  handler call.

Tests
- 18/18 Rust + LiteSVM integration tests passing.
- Coverage: matching-ratio deposit, deposit clamp on either side,
  deposit-after-swap effective-ratio, sub-base-unit deposit revert,
  proportional LP-mint on subsequent deposits, LP-mint uses
  effective reserves after a swap, swap slippage revert, deposit
  slippage revert (with exact-floor sanity), withdraw slippage
  revert (both sides), invariant preservation across many swaps,
  admin-fee accrual and claim, NothingToClaim revert on empty
  claim.

Scope
- tokens/token-swap/anchor/programs/token-swap/ (source + tests)
- tokens/token-swap/quasar/ (mirror source + tests)
- tokens/token-swap/README.md

Author: Edward (Mike's bot)

tokens/token-swap/README.md

@@ -22,7 +22,9 @@ custom-panic = []
 [dependencies]
 anchor-lang = { version = "1.0.0", features = ["init-if-needed"] }
 anchor-spl = { version = "1.0.0", features = ["metadata"] }
-fixed = "1.27.0"
+# `fixed` removed: all financial math is now u128 + checked_*, matching how
+# production Solana AMMs (Orca, Raydium, Meteora, Saber) do it. Floats /
+# fixed-point types are not used for money in this program.
 
 [dev-dependencies]
 litesvm = "0.11.0"

tokens/token-swap/anchor/programs/token-swap/Cargo.toml

@@ -3,6 +3,9 @@ use anchor_lang::prelude::*;
 #[constant]
 pub const MINIMUM_LIQUIDITY: u64 = 100;
 
+#[constant]
+pub const CONFIG_SEED: &[u8] = b"config";
+
 #[constant]
 pub const AUTHORITY_SEED: &[u8] = b"authority";
 

tokens/token-swap/anchor/programs/token-swap/src/constants.rs

@@ -1,15 +1,51 @@
 use anchor_lang::prelude::*;
 
 #[error_code]
-pub enum TutorialError {
+pub enum AmmError {
     #[msg("Invalid fee value")]
     InvalidFee,
 
+    // Returned when `create_config` is called with `admin_share_bps >= 10_000`.
+    // The admin share is a basis-points fraction of the trading fee, so values
+    // at or above 10_000 are nonsensical (the admin can't take more than the
+    // whole fee).
+    #[msg("Admin share must be less than 10000 basis points")]
+    AdminShareTooHigh,
+
     #[msg("Depositing too little liquidity")]
     DepositTooSmall,
 
-    #[msg("Output is below the minimum expected")]
-    OutputTooSmall,
+    // Returned by `deposit_liquidity` when clamping the caller's amounts to the
+    // current pool ratio rounds one side down to zero. That happens when the
+    // deposit is so small (or so lopsided) that the pool can't issue meaningful
+    // LP shares without rounding one of the contributions away. We fail rather
+    // than mint zero-priced LP tokens.
+    #[msg("Deposit amount too small for current pool ratio")]
+    DepositAmountTooSmall,
+
+    // Returned by `swap_tokens` when the computed `output_amount` is strictly
+    // below the trader's `min_output_amount`. This is the trader's slippage
+    // guard: between quoting and landing, the pool can shift (other traders,
+    // sandwich attempts), so the trader passes the lowest output they're
+    // willing to accept and the program reverts if reality is worse.
+    #[msg("Swap output below minimum (slippage exceeded)")]
+    SlippageExceeded,
+
+    // Returned by `withdraw_liquidity` when either side of the proportional
+    // withdrawal falls below the LP's specified minimum. This is the LP's
+    // slippage guard: if a big swap drains one side of the pool between the
+    // LP quoting their exit and the tx landing, the LP gets a different
+    // mix than expected and can bail.
+    #[msg("Withdrawal amount below minimum (slippage exceeded)")]
+    WithdrawalBelowMinimum,
+
+    // Returned by `deposit_liquidity` when the computed LP-token amount
+    // falls below the depositor's specified minimum. This is the
+    // *lower-bound* slippage guard on what the depositor receives. The
+    // ratio clamp is the *upper-bound* guard (don't over-spend either
+    // token); both are needed for full deposit slippage protection.
+    #[msg("LP tokens minted below minimum (slippage exceeded)")]
+    DepositBelowMinimum,
 
     #[msg("Invariant does not hold")]
     InvariantViolated,
@@ -20,4 +56,19 @@ pub enum TutorialError {
     // amount used). We now fail fast so callers can react.
     #[msg("Requested amount exceeds available balance")]
     InsufficientBalance,
+
+    // Returned by `claim_admin_fees` when both accumulators are zero. Reverting
+    // (rather than silently no-op'ing) gives the admin a clear signal that the
+    // call was wasted, and avoids the litesvm gotcha where two byte-identical
+    // claim txs share a signature and the runtime rejects the second as
+    // `AlreadyProcessed`. Callers should check the accumulators off-chain
+    // before submitting a claim.
+    #[msg("No admin fees to claim")]
+    NothingToClaim,
+
+    // Returned by arithmetic helpers when a checked_* operation overflows or
+    // underflows. We treat these as hard failures rather than masking them
+    // with `.unwrap()` so the on-chain logs name the failure mode.
+    #[msg("Math overflow")]
+    MathOverflow,
 }

tokens/token-swap/anchor/programs/token-swap/src/errors.rs

@@ -0,0 +1,174 @@
+use anchor_lang::prelude::*;
+use anchor_spl::token::{self, Mint, Token, TokenAccount, TransferChecked};
+
+use crate::{
+    constants::{AUTHORITY_SEED, CONFIG_SEED},
+    errors::AmmError,
+    state::{Config, PoolConfig},
+};
+
+/// Sweep the admin's accumulated trading-fee claims for both sides of a pool
+/// into the admin's token accounts.
+///
+/// During each swap, the admin's slice of the fee accumulates as a virtual
+/// claim on the input-side reserve (`pool_config.admin_fees_owed_a` /
+/// `admin_fees_owed_b`). This handler transfers those amounts out of the
+/// pool reserves into the admin's ATAs and resets the accumulators to zero.
+///
+/// Authorisation: the `has_one = admin` constraint on `config` plus the
+/// `Signer` constraint on `admin` together mean only the address stored in
+/// `Config.admin` can call this. Any other signer will be rejected by
+/// Anchor's built-in `has_one` check.
+pub fn handle_claim_admin_fees(context: Context<ClaimAdminFeesAccounts>) -> Result<()> {
+    let owed_a = context.accounts.pool_config.admin_fees_owed_a;
+    let owed_b = context.accounts.pool_config.admin_fees_owed_b;
+
+    // Revert if there's nothing to claim. Two reasons:
+    //   1. It tells the admin off-chain that the call did nothing - silent
+    //      no-ops mask wasted txs.
+    //   2. Under litesvm, two byte-identical claim txs (same payer, same
+    //      accounts, same recent_blockhash) produce the same signature and
+    //      the runtime rejects the second as `AlreadyProcessed`. Failing
+    //      explicitly here gives callers a real error to handle.
+    if owed_a == 0 && owed_b == 0 {
+        return err!(AmmError::NothingToClaim);
+    }
+
+    let authority_bump = context.bumps.pool_authority;
+    let authority_seeds = &[
+        &context.accounts.pool_config.config.to_bytes(),
+        &context.accounts.mint_a.key().to_bytes(),
+        &context.accounts.mint_b.key().to_bytes(),
+        AUTHORITY_SEED,
+        &[authority_bump],
+    ];
+    let signer_seeds = &[&authority_seeds[..]];
+
+    // Transfer the owed token-A fees from the pool reserve to the admin.
+    if owed_a > 0 {
+        token::transfer_checked(
+            CpiContext::new_with_signer(
+                context.accounts.token_program.key(),
+                TransferChecked {
+                    from: context.accounts.pool_a.to_account_info(),
+                    mint: context.accounts.mint_a.to_account_info(),
+                    to: context.accounts.admin_token_a.to_account_info(),
+                    authority: context.accounts.pool_authority.to_account_info(),
+                },
+                signer_seeds,
+            ),
+            owed_a,
+            context.accounts.mint_a.decimals,
+        )?;
+    }
+
+    // Transfer the owed token-B fees from the pool reserve to the admin.
+    if owed_b > 0 {
+        token::transfer_checked(
+            CpiContext::new_with_signer(
+                context.accounts.token_program.key(),
+                TransferChecked {
+                    from: context.accounts.pool_b.to_account_info(),
+                    mint: context.accounts.mint_b.to_account_info(),
+                    to: context.accounts.admin_token_b.to_account_info(),
+                    authority: context.accounts.pool_authority.to_account_info(),
+                },
+                signer_seeds,
+            ),
+            owed_b,
+            context.accounts.mint_b.decimals,
+        )?;
+    }
+
+    // Reset the accumulators. Done after the transfers so a failed CPI
+    // leaves the on-chain bookkeeping intact (the admin can retry).
+    let pool_config = &mut context.accounts.pool_config;
+    pool_config.admin_fees_owed_a = 0;
+    pool_config.admin_fees_owed_b = 0;
+
+    msg!("Admin swept fees: {} of mint_a, {} of mint_b", owed_a, owed_b);
+
+    Ok(())
+}
+
+#[derive(Accounts)]
+pub struct ClaimAdminFeesAccounts<'info> {
+    #[account(
+        seeds = [CONFIG_SEED],
+        bump,
+        has_one = admin,
+    )]
+    pub config: Account<'info, Config>,
+
+    #[account(
+        mut,
+        seeds = [
+            pool_config.config.as_ref(),
+            pool_config.mint_a.key().as_ref(),
+            pool_config.mint_b.key().as_ref(),
+        ],
+        bump,
+        has_one = config,
+        has_one = mint_a,
+        has_one = mint_b,
+    )]
+    pub pool_config: Account<'info, PoolConfig>,
+
+    /// CHECK: PDA that owns the pool reserves; signs the outbound transfers.
+    #[account(
+        seeds = [
+            pool_config.config.as_ref(),
+            mint_a.key().as_ref(),
+            mint_b.key().as_ref(),
+            AUTHORITY_SEED,
+        ],
+        bump,
+    )]
+    pub pool_authority: AccountInfo<'info>,
+
+    pub mint_a: Box<Account<'info, Mint>>,
+
+    pub mint_b: Box<Account<'info, Mint>>,
+
+    /// The pool's token-A reserve. The admin's owed token-A fees are paid out
+    /// of this account.
+    #[account(
+        mut,
+        associated_token::mint = mint_a,
+        associated_token::authority = pool_authority,
+    )]
+    pub pool_a: Box<Account<'info, TokenAccount>>,
+
+    /// The pool's token-B reserve. The admin's owed token-B fees are paid out
+    /// of this account.
+    #[account(
+        mut,
+        associated_token::mint = mint_b,
+        associated_token::authority = pool_authority,
+    )]
+    pub pool_b: Box<Account<'info, TokenAccount>>,
+
+    /// Must match the address stored in `Config.admin` (enforced by
+    /// `has_one = admin` above).
+    pub admin: Signer<'info>,
+
+    /// Admin's token-A receiving account. Must already exist; the admin is
+    /// expected to create it themselves before calling. Keeps this handler
+    /// small (no `init_if_needed`).
+    #[account(
+        mut,
+        token::mint = mint_a,
+        token::authority = admin,
+    )]
+    pub admin_token_a: Box<Account<'info, TokenAccount>>,
+
+    /// Admin's token-B receiving account. Same constraints as `admin_token_a`.
+    #[account(
+        mut,
+        token::mint = mint_b,
+        token::authority = admin,
+    )]
+    pub admin_token_b: Box<Account<'info, TokenAccount>>,
+
+    pub token_program: Program<'info, Token>,
+}

tokens/token-swap/anchor/programs/token-swap/src/instructions/claim_admin_fees.rs

@@ -0,0 +1,44 @@
+use anchor_lang::prelude::*;
+
+use crate::{constants::CONFIG_SEED, errors::*, state::Config};
+
+pub fn handle_create_config(
+    mut context: Context<CreateConfigAccounts>,
+    fee: u16,
+    admin_share_bps: u16,
+) -> Result<()> {
+    let bump = context.bumps.config;
+    let config = &mut context.accounts.config;
+    config.admin = context.accounts.admin.key();
+    config.fee = fee;
+    config.admin_share_bps = admin_share_bps;
+    config.bump = bump;
+
+    Ok(())
+}
+
+#[derive(Accounts)]
+#[instruction(fee: u16, admin_share_bps: u16)]
+pub struct CreateConfigAccounts<'info> {
+    #[account(
+        init,
+        payer = payer,
+        space = Config::DISCRIMINATOR.len() + Config::INIT_SPACE,
+        seeds = [CONFIG_SEED],
+        bump,
+        constraint = fee < 10000 @ AmmError::InvalidFee,
+        constraint = admin_share_bps < 10000 @ AmmError::AdminShareTooHigh,
+    )]
+    pub config: Account<'info, Config>,
+
+    /// The admin of the AMM
+    /// CHECK: Read only, delegatable creation
+    pub admin: AccountInfo<'info>,
+
+    /// The account paying for all rents
+    #[account(mut)]
+    pub payer: Signer<'info>,
+
+    /// Solana ecosystem accounts
+    pub system_program: Program<'info, System>,
+}