feat(token-swap): constant-product AMM with protocol fees, slippage protection, and u128 math

[mikemaccana]

Adds a production-shape constant-product AMM (CPAMM) example for both the Anchor and Quasar frameworks, covering the complete lifecycle of a DEX: deployment, pool creation, liquidity provision, token swaps, and admin fee management.

Instruction handlers

• create_config — initialises the singleton Config PDA with trading fee and admin-share parameters (both in basis points). One per deployed program.
• create_pool — initialises a PoolConfig PDA, an LP-token mint, and two pool reserve token accounts for a given (mint_a, mint_b) pair.
• deposit_liquidity — transfers tokens from the depositor to the pool and mints LP tokens. Amounts are clamped to the current pool ratio (Uniswap V2 mint() pattern); supports a minimum-LP-tokens slippage floor.
• withdraw_liquidity — burns LP tokens and returns a proportional share of the effective reserves (vault balance minus admin's owed slice) to the LP. Per-side slippage floors supported.
• swap_tokens — constant-product swap with a configurable trading fee split between LPs and the admin. Supports a minimum-output slippage floor and re-verifies the x*y=k invariant after every trade as defence-in-depth.
• claim_admin_fees — lets the Config.admin sweep their accumulated fee claim from both sides of a pool. Resets accumulators to zero.

Key design properties

• Admin protocol-fee mechanism: Config.admin_share_bps splits each swap's trading fee between LPs and the program operator. Admin fees accrue as virtual claims on the existing pool reserves (no extra CPI per swap) and are swept on demand via claim_admin_fees.
• Effective-reserve accounting: all LP math (deposits, withdrawals, swap curve) operates on pool_X.amount - admin_fees_owed_X so the admin's owed slice does not distort LP pricing or yield.
• u128 checked arithmetic throughout: no floating-point, multiply-before-divide, floor rounding in the pool's favour — matching how production Solana AMMs (Orca, Raydium, Meteora) handle money math.
• Slippage protection on every state-changing instruction: each handler accepts a caller-supplied floor and reverts if the output falls below it.
• Constant-product invariant check on swap: post-trade k is recomputed and compared against pre-trade k; reverts with InvariantViolated if it decreases.
• Singleton Config: one Config per deployed program, at seeds [b"config"]. Unique PoolConfig per (config, mint_a, mint_b) with mint_a < mint_b.
• LP positions as SPL tokens: composable with any wallet or downstream program.

Tests

• Anchor: 18 LiteSVM integration tests
• Quasar: 14 QuasarSvm integration tests

Documentation

README covers the CPAMM formula, design rationale, full state and instruction reference, and an end-to-end program-flow walkthrough (Alice/Bob/Carol/Dave, NVDAx/TSLAx/USDC pools) with financial terms linked to Investopedia and Solana terminology on first use.