@thru/programs 0.2.29 → 0.2.31

package/src/amm/index.test.ts

@@ -0,0 +1,255 @@
+import { describe, expect, it } from 'vitest';
+import { Pubkey, deriveAddress, deriveProgramAddress } from '@thru/sdk';
+import type { Thru } from '@thru/sdk/client';
+import {
+  AMM_PROGRAM_ADDRESS,
+  AMM_INSTRUCTION_ADD_LIQUIDITY,
+  AMM_INSTRUCTION_INIT_POOL,
+  AMM_INSTRUCTION_SWAP,
+  AMM_POOL_METADATA_SIZE,
+  createAddLiquidityInstruction,
+  createInitPoolInstruction,
+  createSwapInstruction,
+  deriveAmmPoolAddresses,
+  parseAmmPoolMetadata,
+  quoteAmmSwapExactIn,
+  sortAmmMints,
+} from './index';
+
+const thru = {
+  helpers: {
+    deriveAddress,
+    deriveProgramAddress,
+  },
+} as unknown as Thru;
+
+function key(id: number): Uint8Array {
+  const bytes = new Uint8Array(32);
+  bytes[0] = id;
+  return bytes;
+}
+
+function context(indexes: Record<string, number>) {
+  return {
+    getAccountIndex(pubkey: Uint8Array): number {
+      const index = indexes[bytesToHex(pubkey)];
+      if (index === undefined) throw new Error(`missing account ${bytesToHex(pubkey)}`);
+      return index;
+    },
+  };
+}
+
+function writeU64(target: Uint8Array, offset: number, value: bigint): void {
+  new DataView(target.buffer, target.byteOffset, target.byteLength)
+    .setBigUint64(offset, value, true);
+}
+
+describe('amm helpers', () => {
+  it('exports the standardized AMM program address', () => {
+    expect(AMM_PROGRAM_ADDRESS).toBe(
+      deriveProgramAddress({
+        programAddress: 'taNz_xi2ZJcAkg3nIbD0Tgy6-P4ckJGUUwLQPPqobPQbsc',
+        seed: 'amm',
+      }).address
+    );
+  });
+
+  it('sorts mint addresses lexicographically', () => {
+    const sorted = sortAmmMints(key(9), key(2));
+    expect(sorted.inputOrder).toBe('swapped');
+    expect(sorted.mintOneBytes[0]).toBe(2);
+    expect(sorted.mintTwoBytes[0]).toBe(9);
+  });
+
+  it('derives pool, LP mint, and vault addresses deterministically', () => {
+    const addresses = deriveAmmPoolAddresses(thru, {
+      ammProgramAddress: deriveProgramAddress({
+        programAddress: key(1),
+        seed: key(2),
+      }).address,
+      mintAAddress: deriveProgramAddress({
+        programAddress: key(5),
+        seed: key(6),
+      }).address,
+      mintBAddress: deriveProgramAddress({
+        programAddress: key(7),
+        seed: key(8),
+      }).address,
+      swapFeeBps: 30,
+    });
+
+    const again = deriveAmmPoolAddresses(thru, {
+      ammProgramAddress: deriveProgramAddress({
+        programAddress: key(1),
+        seed: key(2),
+      }).address,
+      mintAAddress: deriveProgramAddress({
+        programAddress: key(5),
+        seed: key(6),
+      }).address,
+      mintBAddress: deriveProgramAddress({
+        programAddress: key(7),
+        seed: key(8),
+      }).address,
+      swapFeeBps: 30,
+    });
+
+    expect(addresses.poolAddress).toBe(again.poolAddress);
+    expect(addresses.lpMintSeed).toEqual(again.lpMintSeed);
+    expect(addresses.vaultOneSeed[0]).toBe(1);
+    expect(addresses.vaultTwoSeed[0]).toBe(2);
+  });
+
+  it('packs init_pool as the C header layout', async () => {
+    const seed = new Uint8Array(32).fill(0xaa);
+    const poolProof = new Uint8Array([0x10, 0x11]);
+    const lpProof = new Uint8Array([0x20]);
+    const vaultOneProof = new Uint8Array([0x30, 0x31, 0x32]);
+    const vaultTwoProof = new Uint8Array([0x40]);
+    const accounts = {
+      payer: key(1),
+      pool: key(2),
+      lpMint: key(3),
+      vaultOne: key(4),
+      vaultTwo: key(5),
+      mintOne: key(6),
+      mintTwo: key(7),
+      tokenProgram: key(8),
+    };
+    const instruction = await createInitPoolInstruction({
+      payerAccountBytes: accounts.payer,
+      poolAccountBytes: accounts.pool,
+      lpMintAccountBytes: accounts.lpMint,
+      vaultOneAccountBytes: accounts.vaultOne,
+      vaultTwoAccountBytes: accounts.vaultTwo,
+      mintOneAccountBytes: accounts.mintOne,
+      mintTwoAccountBytes: accounts.mintTwo,
+      tokenProgramAccountBytes: accounts.tokenProgram,
+      swapFeeBps: 30,
+      lpMintSeed: seed,
+      poolStateProof: poolProof,
+      lpMintStateProof: lpProof,
+      vaultOneStateProof: vaultOneProof,
+      vaultTwoStateProof: vaultTwoProof,
+    })(context({
+      [bytesToHex(accounts.payer)]: 0,
+      [bytesToHex(accounts.pool)]: 2,
+      [bytesToHex(accounts.lpMint)]: 3,
+      [bytesToHex(accounts.vaultOne)]: 4,
+      [bytesToHex(accounts.vaultTwo)]: 5,
+      [bytesToHex(accounts.mintOne)]: 6,
+      [bytesToHex(accounts.mintTwo)]: 7,
+      [bytesToHex(accounts.tokenProgram)]: 8,
+    }));
+
+    expect(instruction.length).toBe(4 + 82 + 7);
+    expect(Array.from(instruction.slice(0, 22))).toEqual([
+      AMM_INSTRUCTION_INIT_POOL, 0, 0, 0,
+      0, 0,
+      2, 0,
+      3, 0,
+      4, 0,
+      5, 0,
+      6, 0,
+      7, 0,
+      8, 0,
+      30, 0,
+    ]);
+    expect(instruction.slice(22, 54)).toEqual(seed);
+    expect(Array.from(instruction.slice(54, 86))).toEqual([
+      2, 0, 0, 0, 0, 0, 0, 0,
+      1, 0, 0, 0, 0, 0, 0, 0,
+      3, 0, 0, 0, 0, 0, 0, 0,
+      1, 0, 0, 0, 0, 0, 0, 0,
+    ]);
+    expect(Array.from(instruction.slice(86))).toEqual([
+      ...poolProof,
+      ...lpProof,
+      ...vaultOneProof,
+      ...vaultTwoProof,
+    ]);
+  });
+
+  it('packs add_liquidity and swap instructions', async () => {
+    const accounts = Array.from({ length: 10 }, (_, idx) => key(idx + 1));
+    const indexes = Object.fromEntries(accounts.map((account, idx) => [bytesToHex(account), idx + 2]));
+    const addLiquidity = await createAddLiquidityInstruction({
+      poolAccountBytes: accounts[0],
+      depositorAccountBytes: accounts[1],
+      depositorTokenOneAccountBytes: accounts[2],
+      depositorTokenTwoAccountBytes: accounts[3],
+      depositorLpAccountBytes: accounts[4],
+      vaultOneAccountBytes: accounts[5],
+      vaultTwoAccountBytes: accounts[6],
+      lpMintAccountBytes: accounts[7],
+      tokenProgramAccountBytes: accounts[8],
+      maxAmountMintOne: 5_000_000n,
+      maxAmountMintTwo: 10_000_000n,
+    })(context(indexes));
+    const swap = await createSwapInstruction({
+      poolAccountBytes: accounts[0],
+      userTransferAuthorityBytes: accounts[1],
+      userInputAccountBytes: accounts[2],
+      userOutputAccountBytes: accounts[3],
+      vaultInputAccountBytes: accounts[4],
+      vaultOutputAccountBytes: accounts[5],
+      lpMintAccountBytes: accounts[6],
+      tokenProgramAccountBytes: accounts[7],
+      amountIn: 1_234_567n,
+    })(context(indexes));
+
+    expect(addLiquidity.length).toBe(38);
+    expect(swap.length).toBe(28);
+    expect(Array.from(addLiquidity.slice(0, 4))).toEqual([
+      AMM_INSTRUCTION_ADD_LIQUIDITY, 0, 0, 0,
+    ]);
+    expect(Array.from(swap.slice(0, 4))).toEqual([
+      AMM_INSTRUCTION_SWAP, 0, 0, 0,
+    ]);
+    expect(new DataView(addLiquidity.buffer).getBigUint64(22, true)).toBe(5_000_000n);
+    expect(new DataView(addLiquidity.buffer).getBigUint64(30, true)).toBe(10_000_000n);
+    expect(new DataView(swap.buffer).getBigUint64(20, true)).toBe(1_234_567n);
+  });
+
+  it('parses pool metadata', () => {
+    const data = new Uint8Array(AMM_POOL_METADATA_SIZE);
+    const view = new DataView(data.buffer);
+    view.setUint8(0, 1);
+    view.setBigUint64(1, 1_000_000_000n, true);
+    view.setUint16(9, 30, true);
+    data.set(key(11), 11);
+    data.set(key(12), 43);
+    data.set(key(13), 75);
+    data.set(key(14), 107);
+    data.set(key(15), 139);
+    data.set(key(16), 171);
+
+    const parsed = parseAmmPoolMetadata(data);
+    expect(parsed.isInitialized).toBe(true);
+    expect(parsed.lockedLpSupply).toBe(1_000_000_000n);
+    expect(parsed.swapFeeBps).toBe(30);
+    expect(parsed.swapPoolAuthority).toBe(encodeAddressForTest(key(11)));
+    expect(parsed.lpMint).toBe(encodeAddressForTest(key(16)));
+  });
+
+  it('quotes exact-in swaps with fee math matching the C program', () => {
+    const quote = quoteAmmSwapExactIn({
+      amountIn: 10_000_000n,
+      reserveIn: 1_000_000_000n,
+      reserveOut: 10_000_000n,
+      swapFeeBps: 30,
+    });
+
+    expect(quote.feeAmount).toBe(30_000n);
+    expect(quote.amountInAfterFee).toBe(9_970_000n);
+    expect(quote.amountOut).toBe(98_715n);
+  });
+});
+
+function encodeAddressForTest(bytes: Uint8Array): string {
+  return Pubkey.from(bytes).toThruFmt();
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}

package/src/amm/index.ts

@@ -0,0 +1,434 @@
+import { Pubkey } from '@thru/sdk';
+import { encodeAddress } from '@thru/sdk/helpers';
+import type { Account } from '@thru/sdk';
+import type { Thru } from '@thru/sdk/client';
+import { compareBytes } from '../helpers/bytes';
+import {
+  AmmAddLiquidityInstructionBuilder,
+  AmmInitPoolInstructionBuilder,
+  AmmInstructionBuilder,
+  AmmPoolMetadata as AmmPoolMetadataView,
+  AmmSwapInstructionBuilder,
+  AmmWithdrawLiquidityInstructionBuilder,
+} from './abi/thru/program/amm/types';
+
+export {
+  AmmAddLiquidityInstruction,
+  AmmAddLiquidityInstructionBuilder,
+  AmmError,
+  AmmErrorBuilder,
+  AmmEvent,
+  AmmEventBuilder,
+  AmmInitPoolInstruction,
+  AmmInitPoolInstructionBuilder,
+  AmmInstruction,
+  AmmInstructionBuilder,
+  AmmPoolMetadata as AmmPoolMetadataView,
+  AmmPoolMetadataBuilder,
+  AmmSwapInstruction,
+  AmmSwapInstructionBuilder,
+  AmmWithdrawLiquidityInstruction,
+  AmmWithdrawLiquidityInstructionBuilder,
+  BurnEventData,
+  BurnEventDataBuilder,
+  MintEventData,
+  MintEventDataBuilder,
+  PoolInitEventData,
+  PoolInitEventDataBuilder,
+  Seed32,
+  SwapEventData,
+  SwapEventDataBuilder,
+  SyncEventData,
+  SyncEventDataBuilder,
+} from './abi/thru/program/amm/types';
+
+export const AMM_INSTRUCTION_INIT_POOL = 0;
+export const AMM_INSTRUCTION_ADD_LIQUIDITY = 1;
+export const AMM_INSTRUCTION_WITHDRAW_LIQUIDITY = 2;
+export const AMM_INSTRUCTION_SWAP = 3;
+
+export const AMM_EVENT_POOL_INIT = 0;
+export const AMM_EVENT_MINT = 1;
+export const AMM_EVENT_BURN = 2;
+export const AMM_EVENT_SWAP = 3;
+export const AMM_EVENT_SYNC = 4;
+
+export const AMM_BPS_DENOMINATOR = 10_000;
+export const AMM_DEFAULT_SWAP_FEE_BPS = 30;
+export const AMM_MAX_SWAP_FEE_BPS = 500;
+export const AMM_MINIMUM_LIQUIDITY = 1_000n;
+export const AMM_LP_DECIMALS = 6;
+export const AMM_LP_SCALE = 1_000_000n;
+export const AMM_POOL_METADATA_SIZE = 203;
+export const AMM_PROGRAM_ADDRESS =
+  'taCnhMCcBZSJ8MDLGYBnTIRgmWxZx_jNjoNwOwzk1g4ST1';
+
+type AmmInstructionVariant = 'init_pool' | 'add_liquidity' | 'withdraw_liquidity' | 'swap';
+
+export const AMM_ERROR_LABELS: Record<number, string> = {
+  1: 'Invalid instruction data size',
+  2: 'Invalid instruction',
+  3: 'Account already initialized',
+  4: 'Account not initialized',
+  5: 'Invalid account index',
+  6: 'Invalid mint ordering',
+  7: 'Unauthorized operation',
+  8: 'Pool create failed',
+  9: 'LP mint create failed',
+  10: 'Vault one create failed',
+  11: 'Vault two create failed',
+  12: 'Account resize failed',
+  13: 'Account set writable failed',
+  14: 'LP mint init failed',
+  15: 'Vault one init failed',
+  16: 'Vault two init failed',
+  17: 'Liquidity bounds',
+  18: 'Vault mismatch',
+  19: 'LP mint mismatch',
+};
+
+const PUBKEY_LENGTH = 32;
+const LP_MINT_SEED_LABEL = asciiBytes('lp_mint');
+export const AMM_VAULT_ONE_SEED = oneByteSeed(0x01);
+export const AMM_VAULT_TWO_SEED = oneByteSeed(0x02);
+
+export type AccountLookupContext = {
+  getAccountIndex: (pubkey: Uint8Array) => number;
+};
+
+export type InstructionData = (context: AccountLookupContext) => Promise<Uint8Array>;
+
+export interface SortedAmmMints {
+  mintOneBytes: Uint8Array;
+  mintTwoBytes: Uint8Array;
+  mintOneAddress: string;
+  mintTwoAddress: string;
+  inputOrder: 'already-sorted' | 'swapped';
+}
+
+export interface AmmPoolAddresses {
+  mintOneAddress: string;
+  mintTwoAddress: string;
+  mintOneBytes: Uint8Array;
+  mintTwoBytes: Uint8Array;
+  poolAddress: string;
+  poolBytes: Uint8Array;
+  poolSeed: Uint8Array;
+  lpMintSeed: Uint8Array;
+  vaultOneSeed: Uint8Array;
+  vaultTwoSeed: Uint8Array;
+  swapFeeBps: number;
+  inputOrder: 'already-sorted' | 'swapped';
+}
+
+export interface AmmPoolMetadata {
+  isInitialized: boolean;
+  lockedLpSupply: bigint;
+  swapFeeBps: number;
+  swapPoolAuthority: string;
+  mintOne: string;
+  mintTwo: string;
+  vaultOne: string;
+  vaultTwo: string;
+  lpMint: string;
+}
+
+export interface AmmQuoteExactIn {
+  amountIn: bigint;
+  amountInAfterFee: bigint;
+  feeAmount: bigint;
+  amountOut: bigint;
+}
+
+export interface InitPoolArgs {
+  payerAccountBytes: Uint8Array;
+  poolAccountBytes: Uint8Array;
+  lpMintAccountBytes: Uint8Array;
+  vaultOneAccountBytes: Uint8Array;
+  vaultTwoAccountBytes: Uint8Array;
+  mintOneAccountBytes: Uint8Array;
+  mintTwoAccountBytes: Uint8Array;
+  tokenProgramAccountBytes: Uint8Array;
+  swapFeeBps: number;
+  lpMintSeed: Uint8Array;
+  poolStateProof: Uint8Array;
+  lpMintStateProof: Uint8Array;
+  vaultOneStateProof: Uint8Array;
+  vaultTwoStateProof: Uint8Array;
+}
+
+export interface AddLiquidityArgs {
+  poolAccountBytes: Uint8Array;
+  depositorAccountBytes: Uint8Array;
+  depositorTokenOneAccountBytes: Uint8Array;
+  depositorTokenTwoAccountBytes: Uint8Array;
+  depositorLpAccountBytes: Uint8Array;
+  vaultOneAccountBytes: Uint8Array;
+  vaultTwoAccountBytes: Uint8Array;
+  lpMintAccountBytes: Uint8Array;
+  tokenProgramAccountBytes: Uint8Array;
+  maxAmountMintOne: bigint;
+  maxAmountMintTwo: bigint;
+}
+
+export interface WithdrawLiquidityArgs {
+  poolAccountBytes: Uint8Array;
+  withdrawerAccountBytes: Uint8Array;
+  withdrawerTokenOneAccountBytes: Uint8Array;
+  withdrawerTokenTwoAccountBytes: Uint8Array;
+  withdrawerLpAccountBytes: Uint8Array;
+  vaultOneAccountBytes: Uint8Array;
+  vaultTwoAccountBytes: Uint8Array;
+  lpMintAccountBytes: Uint8Array;
+  tokenProgramAccountBytes: Uint8Array;
+  lpAmount: bigint;
+}
+
+export interface SwapArgs {
+  poolAccountBytes: Uint8Array;
+  userTransferAuthorityBytes: Uint8Array;
+  userInputAccountBytes: Uint8Array;
+  userOutputAccountBytes: Uint8Array;
+  vaultInputAccountBytes: Uint8Array;
+  vaultOutputAccountBytes: Uint8Array;
+  lpMintAccountBytes: Uint8Array;
+  tokenProgramAccountBytes: Uint8Array;
+  amountIn: bigint;
+}
+
+export function sortAmmMints(
+  mintA: Uint8Array | string,
+  mintB: Uint8Array | string
+): SortedAmmMints {
+  const mintABytes = toPubkeyBytes(mintA);
+  const mintBBytes = toPubkeyBytes(mintB);
+  const comparison = compareBytes(mintABytes, mintBBytes);
+  if (comparison === 0) throw new Error('AMM mints must be distinct');
+  const alreadySorted = comparison < 0;
+  const mintOneBytes = alreadySorted ? mintABytes : mintBBytes;
+  const mintTwoBytes = alreadySorted ? mintBBytes : mintABytes;
+  return {
+    mintOneBytes,
+    mintTwoBytes,
+    mintOneAddress: encodeAddress(mintOneBytes),
+    mintTwoAddress: encodeAddress(mintTwoBytes),
+    inputOrder: alreadySorted ? 'already-sorted' : 'swapped',
+  };
+}
+
+export function deriveAmmLpMintSeed(thru: Thru, poolBytes: Uint8Array | string): Uint8Array {
+  return thru.helpers.deriveAddress([
+    toPubkeyBytes(poolBytes),
+    LP_MINT_SEED_LABEL,
+  ]).bytes;
+}
+
+export function deriveAmmPoolAddresses(
+  thru: Thru,
+  args: {
+    ammProgramAddress: string;
+    mintAAddress: string;
+    mintBAddress: string;
+    swapFeeBps?: number;
+  }
+): AmmPoolAddresses {
+  const swapFeeBps = args.swapFeeBps ?? AMM_DEFAULT_SWAP_FEE_BPS;
+  assertU16(swapFeeBps, 'swapFeeBps');
+  if (swapFeeBps <= 0 || swapFeeBps > AMM_MAX_SWAP_FEE_BPS) {
+    throw new Error(`swapFeeBps must be 1-${AMM_MAX_SWAP_FEE_BPS}`);
+  }
+
+  const sorted = sortAmmMints(args.mintAAddress, args.mintBAddress);
+  const feeBytes = new Uint8Array(2);
+  new DataView(feeBytes.buffer).setUint16(0, swapFeeBps, true);
+  const poolSeed = thru.helpers.deriveAddress([
+    sorted.mintOneBytes,
+    sorted.mintTwoBytes,
+    feeBytes,
+  ]).bytes;
+  const pool = thru.helpers.deriveProgramAddress({
+    programAddress: args.ammProgramAddress,
+    seed: poolSeed,
+    ephemeral: false,
+  });
+  const lpMintSeed = deriveAmmLpMintSeed(thru, pool.bytes);
+
+  return {
+    ...sorted,
+    poolAddress: pool.address,
+    poolBytes: pool.bytes,
+    poolSeed,
+    lpMintSeed,
+    vaultOneSeed: AMM_VAULT_ONE_SEED.slice(),
+    vaultTwoSeed: AMM_VAULT_TWO_SEED.slice(),
+    swapFeeBps,
+  };
+}
+
+export function createInitPoolInstruction(args: InitPoolArgs): InstructionData {
+  assertU16(args.swapFeeBps, 'swapFeeBps');
+  const lpMintSeed = Pubkey.from(args.lpMintSeed).toBytes();
+  return async (context: AccountLookupContext): Promise<Uint8Array> => {
+    const builder = new AmmInitPoolInstructionBuilder()
+      .set_payer_account_idx(accountIndex(context, args.payerAccountBytes))
+      .set_pool_account_idx(accountIndex(context, args.poolAccountBytes))
+      .set_lp_mint_account_idx(accountIndex(context, args.lpMintAccountBytes))
+      .set_vault_one_account_idx(accountIndex(context, args.vaultOneAccountBytes))
+      .set_vault_two_account_idx(accountIndex(context, args.vaultTwoAccountBytes))
+      .set_mint_one_account_idx(accountIndex(context, args.mintOneAccountBytes))
+      .set_mint_two_account_idx(accountIndex(context, args.mintTwoAccountBytes))
+      .set_token_program_account_idx(accountIndex(context, args.tokenProgramAccountBytes))
+      .set_swap_fee_bps(args.swapFeeBps)
+      .set_lp_mint_seed(lpMintSeed);
+    builder.pool_proof().write(args.poolStateProof).finish();
+    builder.lp_mint_proof().write(args.lpMintStateProof).finish();
+    builder.vault_one_proof().write(args.vaultOneStateProof).finish();
+    builder.vault_two_proof().write(args.vaultTwoStateProof).finish();
+    return buildAmmInstruction('init_pool', builder.build());
+  };
+}
+
+export function createAddLiquidityInstruction(args: AddLiquidityArgs): InstructionData {
+  return async (context: AccountLookupContext): Promise<Uint8Array> => {
+    assertU64(args.maxAmountMintOne, 'maxAmountMintOne');
+    assertU64(args.maxAmountMintTwo, 'maxAmountMintTwo');
+    const payload = new AmmAddLiquidityInstructionBuilder()
+      .set_pool_account_idx(accountIndex(context, args.poolAccountBytes))
+      .set_depositor_account_idx(accountIndex(context, args.depositorAccountBytes))
+      .set_depositor_token_one_account_idx(accountIndex(context, args.depositorTokenOneAccountBytes))
+      .set_depositor_token_two_account_idx(accountIndex(context, args.depositorTokenTwoAccountBytes))
+      .set_depositor_lp_account_idx(accountIndex(context, args.depositorLpAccountBytes))
+      .set_vault_one_account_idx(accountIndex(context, args.vaultOneAccountBytes))
+      .set_vault_two_account_idx(accountIndex(context, args.vaultTwoAccountBytes))
+      .set_lp_mint_account_idx(accountIndex(context, args.lpMintAccountBytes))
+      .set_token_program_account_idx(accountIndex(context, args.tokenProgramAccountBytes))
+      .set_max_amount_mint_one(args.maxAmountMintOne)
+      .set_max_amount_mint_two(args.maxAmountMintTwo)
+      .build();
+    return buildAmmInstruction('add_liquidity', payload);
+  };
+}
+
+export function createWithdrawLiquidityInstruction(args: WithdrawLiquidityArgs): InstructionData {
+  return async (context: AccountLookupContext): Promise<Uint8Array> => {
+    assertU64(args.lpAmount, 'lpAmount');
+    const payload = new AmmWithdrawLiquidityInstructionBuilder()
+      .set_pool_account_idx(accountIndex(context, args.poolAccountBytes))
+      .set_withdrawer_account_idx(accountIndex(context, args.withdrawerAccountBytes))
+      .set_withdrawer_token_one_account_idx(accountIndex(context, args.withdrawerTokenOneAccountBytes))
+      .set_withdrawer_token_two_account_idx(accountIndex(context, args.withdrawerTokenTwoAccountBytes))
+      .set_withdrawer_lp_account_idx(accountIndex(context, args.withdrawerLpAccountBytes))
+      .set_vault_one_account_idx(accountIndex(context, args.vaultOneAccountBytes))
+      .set_vault_two_account_idx(accountIndex(context, args.vaultTwoAccountBytes))
+      .set_lp_mint_account_idx(accountIndex(context, args.lpMintAccountBytes))
+      .set_token_program_account_idx(accountIndex(context, args.tokenProgramAccountBytes))
+      .set_lp_amount(args.lpAmount)
+      .build();
+    return buildAmmInstruction('withdraw_liquidity', payload);
+  };
+}
+
+export function createSwapInstruction(args: SwapArgs): InstructionData {
+  return async (context: AccountLookupContext): Promise<Uint8Array> => {
+    assertU64(args.amountIn, 'amountIn');
+    const payload = new AmmSwapInstructionBuilder()
+      .set_pool_account_idx(accountIndex(context, args.poolAccountBytes))
+      .set_user_transfer_authority_idx(accountIndex(context, args.userTransferAuthorityBytes))
+      .set_user_input_account_idx(accountIndex(context, args.userInputAccountBytes))
+      .set_user_output_account_idx(accountIndex(context, args.userOutputAccountBytes))
+      .set_vault_input_account_idx(accountIndex(context, args.vaultInputAccountBytes))
+      .set_vault_output_account_idx(accountIndex(context, args.vaultOutputAccountBytes))
+      .set_lp_mint_account_idx(accountIndex(context, args.lpMintAccountBytes))
+      .set_token_program_account_idx(accountIndex(context, args.tokenProgramAccountBytes))
+      .set_amount_in(args.amountIn)
+      .build();
+    return buildAmmInstruction('swap', payload);
+  };
+}
+
+export function parseAmmPoolMetadata(accountOrData: Account | Uint8Array): AmmPoolMetadata {
+  const data = accountOrData instanceof Uint8Array ? accountOrData : accountOrData.data?.data;
+  if (!data) throw new Error('AMM pool account data is missing');
+  if (data.length < AMM_POOL_METADATA_SIZE) throw new Error('AMM pool account data is malformed');
+
+  const metadata = AmmPoolMetadataView.from_array(data);
+  if (!metadata) throw new Error('AMM pool account data is malformed');
+  return {
+    isInitialized: metadata.get_is_initialized() !== 0,
+    lockedLpSupply: metadata.get_locked_lp_supply(),
+    swapFeeBps: metadata.get_swap_fee_bps(),
+    swapPoolAuthority: pubkeyViewToAddress(metadata.get_swap_pool_authority()),
+    mintOne: pubkeyViewToAddress(metadata.get_mint_one()),
+    mintTwo: pubkeyViewToAddress(metadata.get_mint_two()),
+    vaultOne: pubkeyViewToAddress(metadata.get_vault_one()),
+    vaultTwo: pubkeyViewToAddress(metadata.get_vault_two()),
+    lpMint: pubkeyViewToAddress(metadata.get_lp_mint()),
+  };
+}
+
+export function quoteAmmSwapExactIn(args: {
+  amountIn: bigint;
+  reserveIn: bigint;
+  reserveOut: bigint;
+  swapFeeBps: number;
+}): AmmQuoteExactIn {
+  if (args.amountIn <= 0n) throw new Error('amountIn must be positive');
+  if (args.reserveIn <= 0n || args.reserveOut <= 0n) {
+    throw new Error('reserves must be positive');
+  }
+  assertU16(args.swapFeeBps, 'swapFeeBps');
+  const feeAmount = (args.amountIn * BigInt(args.swapFeeBps)) / BigInt(AMM_BPS_DENOMINATOR);
+  const amountInAfterFee = args.amountIn - feeAmount;
+  if (amountInAfterFee <= 0n) throw new Error('amountIn is fully consumed by fees');
+  const amountOut = (amountInAfterFee * args.reserveOut) / (args.reserveIn + amountInAfterFee);
+  return {
+    amountIn: args.amountIn,
+    amountInAfterFee,
+    feeAmount,
+    amountOut,
+  };
+}
+
+function toPubkeyBytes(value: Uint8Array | string): Uint8Array {
+  return Pubkey.from(value).toBytes();
+}
+
+function assertU16(value: number, label: string): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+    throw new Error(`${label} must be an integer between 0 and 65535`);
+  }
+}
+
+function assertU64(value: bigint, label: string): void {
+  if (value < 0n || value > 0xffffffffffffffffn) {
+    throw new Error(`${label} must be between 0 and 18446744073709551615`);
+  }
+}
+
+function accountIndex(context: AccountLookupContext, pubkey: Uint8Array): number {
+  const index = context.getAccountIndex(pubkey);
+  assertU16(index, 'account index');
+  return index;
+}
+
+function buildAmmInstruction(variant: AmmInstructionVariant, payload: Uint8Array): Uint8Array {
+  const builder = new AmmInstructionBuilder();
+  builder.payload().select(variant).writePayload(payload).finish();
+  return builder.build();
+}
+
+function pubkeyViewToAddress(pubkey: unknown): string {
+  const buffer = (pubkey as { buffer?: Uint8Array }).buffer;
+  if (!buffer) throw new Error('generated Pubkey view did not expose a buffer');
+  return encodeAddress(buffer);
+}
+
+function asciiBytes(value: string): Uint8Array {
+  return new TextEncoder().encode(value);
+}
+
+function oneByteSeed(value: number): Uint8Array {
+  const seed = new Uint8Array(PUBKEY_LENGTH);
+  seed[0] = value;
+  return seed;
+}