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

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 the 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 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.
- Slippage protection on every state-changing instruction.
- Constant-product invariant check on every swap as defence-in-depth.
- Singleton Config at seeds [b"config"]; unique PoolConfig per
  (config, mint_a, mint_b) with mint_a < mint_b.
- LP positions as SPL tokens for composability.

## 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.

https://claude.ai/code/session_01DFHVK3tVoPfz6MJMwEAGBf

Author: claude

.gitignore

@@ -22,4 +22,5 @@ node_modules/
 
 /target
 deploy
-.claude
+.claude/*
+!.claude/skills/

tokens/token-swap/README.md

@@ -21,8 +21,10 @@ 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"
+anchor-spl = { version = "1.0.0", features = ["metadata", "spl-token-interface"] }
+# `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,16 @@ use anchor_lang::prelude::*;
 #[constant]
 pub const MINIMUM_LIQUIDITY: u64 = 100;
 
+/// Basis-points denominator. Fees and the admin's fee share are stored in
+/// basis points (1 bp = 1/10_000), so dividing by this converts a bp value to
+/// a fraction. Using the named constant keeps the 10_000 out of the math as a
+/// bare literal.
+#[constant]
+pub const BASIS_POINTS_DIVISOR: u64 = 10_000;
+
+#[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,26 @@ 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 offchain
+    // 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 onchain logs name the failure mode.
+    #[msg("Math overflow")]
+    MathOverflow,
+
+    // Returned by `create_pool` when `mint_a >= mint_b`. Requiring a strict
+    // ascending order ensures each (mint_a, mint_b) pair has exactly one
+    // canonical pool PDA — without it, a (X, Y) pool and a (Y, X) pool would
+    // both be valid, fragmenting liquidity.
+    #[msg("mint_a must be less than mint_b for canonical pool ordering")]
+    InvalidMintOrder,
 }

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

@@ -0,0 +1,184 @@
+use anchor_lang::prelude::*;
+use anchor_spl::token_interface::{self, Mint, TokenAccount, TokenInterface, 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<ClaimAdminFeesAccountConstraints>) -> 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 offchain 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);
+    }
+
+    // Pre-copy seed bytes before the mutable borrow of pool_config.
+    let authority_bump = context.bumps.pool_authority;
+    let config_bytes = context.accounts.pool_config.config.to_bytes();
+    let mint_a_bytes = context.accounts.mint_a.key().to_bytes();
+    let mint_b_bytes = context.accounts.mint_b.key().to_bytes();
+
+    // Effects: zero the accumulators before the CPIs (Checks-Effects-Interactions).
+    // If a CPI fails the whole transaction reverts, so the state reset is safe.
+    {
+        let pool_config = &mut context.accounts.pool_config;
+        pool_config.admin_fees_owed_a = 0;
+        pool_config.admin_fees_owed_b = 0;
+    }
+
+    // Interactions: transfer the owed fees out of the pool reserves.
+    let authority_seeds = &[
+        config_bytes.as_ref(),
+        mint_a_bytes.as_ref(),
+        mint_b_bytes.as_ref(),
+        AUTHORITY_SEED,
+        &[authority_bump],
+    ];
+    let signer_seeds = &[&authority_seeds[..]];
+
+    if owed_a > 0 {
+        token_interface::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,
+        )?;
+    }
+
+    if owed_b > 0 {
+        token_interface::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,
+        )?;
+    }
+
+    msg!("Admin swept fees: {} of mint_a, {} of mint_b", owed_a, owed_b);
+
+    Ok(())
+}
+
+#[derive(Accounts)]
+pub struct ClaimAdminFeesAccountConstraints<'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: UncheckedAccount<'info>,
+
+    pub mint_a: Box<InterfaceAccount<'info, Mint>>,
+
+    pub mint_b: Box<InterfaceAccount<'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,
+        associated_token::token_program = token_program,
+    )]
+    pub pool_a: Box<InterfaceAccount<'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,
+        associated_token::token_program = token_program,
+    )]
+    pub pool_b: Box<InterfaceAccount<'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,
+        token::token_program = token_program,
+    )]
+    pub admin_token_a: Box<InterfaceAccount<'info, TokenAccount>>,
+
+    /// Admin's token-B receiving account. Same constraints as `admin_token_a`.
+    #[account(
+        mut,
+        token::mint = mint_b,
+        token::authority = admin,
+        token::token_program = token_program,
+    )]
+    pub admin_token_b: Box<InterfaceAccount<'info, TokenAccount>>,
+
+    pub token_program: Interface<'info, TokenInterface>,
+}

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

@@ -0,0 +1,3 @@
+mod claim_admin_fees;
+
+pub use claim_admin_fees::*;

tokens/token-swap/anchor/programs/token-swap/src/instructions/admin/mod.rs

@@ -0,0 +1,48 @@
+use anchor_lang::prelude::*;
+
+use crate::{
+    constants::{BASIS_POINTS_DIVISOR, CONFIG_SEED},
+    errors::*,
+    state::Config,
+};
+
+pub fn handle_create_config(
+    context: Context<CreateConfigAccountConstraints>,
+    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 CreateConfigAccountConstraints<'info> {
+    #[account(
+        init,
+        payer = payer,
+        space = Config::DISCRIMINATOR.len() + Config::INIT_SPACE,
+        seeds = [CONFIG_SEED],
+        bump,
+        constraint = (fee as u64) < BASIS_POINTS_DIVISOR @ AmmError::InvalidFee,
+        constraint = (admin_share_bps as u64) < BASIS_POINTS_DIVISOR @ AmmError::AdminShareTooHigh,
+    )]
+    pub config: Account<'info, Config>,
+
+    /// The admin of the AMM
+    /// CHECK: Read only, delegatable creation
+    pub admin: UncheckedAccount<'info>,
+
+    /// The account paying for all rents
+    #[account(mut)]
+    pub payer: Signer<'info>,
+
+    /// Solana ecosystem accounts
+    pub system_program: Program<'info, System>,
+}