@coffer_so/sdk 1.0.0

package/src/math/singleToken.ts

@@ -0,0 +1,251 @@
+import { ONE, assertU64, assertInteger, mulDivDown } from "./fixedPoint";
+import { calcOutGivenIn } from "./cubicMath";
+import { lpBalances, calculateSwapFee, calculateProtocolFee } from "./slippage";
+
+export interface AllocationResult {
+  /** Per-token integer amount allocations; sum = amountIn. */
+  allocations: bigint[];
+  /** Scaled W values, for inspection/debugging. */
+  wScaled: bigint[];
+  /** Sum of wScaled. */
+  sumW: bigint;
+}
+
+/**
+ * Port of stld `compute_allocations` from
+ * `contracts/programs/single-token-liquidity/src/math.rs`.
+ *
+ * W_i = weight_i * min(actual_i, virtual_i) / virtual_i.
+ * Division order matches the two integer divisions on-chain.
+ * share_i = W_i / ΣW. amount_alloc[i] = amountIn * share_i.
+ *
+ * Integer truncation of per-token amounts routes the remainder to the
+ * input-token slot so Σ allocations == amountIn exactly.
+ */
+export function computeAllocations(params: {
+  actualBalances: bigint[];
+  virtualBalances: bigint[];
+  weightsBps: number[];
+  amountIn: bigint;
+  tokenInIndex: number;
+}): AllocationResult {
+  const { actualBalances, virtualBalances, weightsBps, amountIn, tokenInIndex } = params;
+  assertU64(amountIn, "amountIn");
+  const n = actualBalances.length;
+  if (n !== virtualBalances.length || n !== weightsBps.length) {
+    throw new Error("computeAllocations: length mismatch");
+  }
+  if (!Number.isInteger(tokenInIndex) || tokenInIndex < 0 || tokenInIndex >= n) {
+    throw new Error("computeAllocations: tokenInIndex out of range");
+  }
+  const wScaled: bigint[] = [];
+  for (let i = 0; i < n; i++) {
+    if (virtualBalances[i] <= 0n) {
+      throw new Error(`computeAllocations: virtualBalance[${i}] must be positive`);
+    }
+    assertU64(actualBalances[i]); assertU64(virtualBalances[i]);
+    assertInteger(weightsBps[i], 0, 10000, "weight");
+    const effectiveActual = actualBalances[i] < virtualBalances[i] ? actualBalances[i] : virtualBalances[i];
+    const scaled = mulDivDown(effectiveActual, ONE, virtualBalances[i]);
+    const w = mulDivDown(scaled, BigInt(weightsBps[i]), 10_000n);
+    wScaled.push(w);
+  }
+  const sumW = wScaled.reduce((a, b) => a + b, 0n);
+  if (sumW === 0n) {
+    throw new Error("computeAllocations: pool not seeded (ΣW = 0)");
+  }
+  const allocations: bigint[] = wScaled.map((w) => (amountIn * w) / sumW);
+  const sumAlloc = allocations.reduce((a, b) => a + b, 0n);
+  if (sumAlloc < amountIn) {
+    allocations[tokenInIndex] += amountIn - sumAlloc;
+  }
+  return { allocations, wScaled, sumW };
+}
+
+function swapFeeAmount(amount: bigint, swapFeeRate: number): bigint {
+  return calculateSwapFee(amount, swapFeeRate);
+}
+
+function amountAfterSwapFee(amount: bigint, swapFeeRate: number): bigint {
+  const fee = swapFeeAmount(amount, swapFeeRate);
+  if (swapFeeRate > 0 && fee === 0n) {
+    throw new Error("computeTwoTokenOptimalAllocations: swap amount too small, fee rounds to zero");
+  }
+  return amount - fee;
+}
+
+function protocolFeeAmount(swapFee: bigint, protocolFeeRate: number): bigint {
+  return calculateProtocolFee(swapFee, protocolFeeRate);
+}
+
+function scoreTwoTokenSwap(params: {
+  actualBalances: [bigint, bigint];
+  virtualBalances: [bigint, bigint];
+  protocolFeesOwed: [bigint, bigint];
+  weightsBps: [number, number];
+  amountIn: bigint;
+  tokenInIndex: 0 | 1;
+  swapToOther: bigint;
+  swapFeeRate: number;
+  protocolFeeRate: number;
+}): { score: bigint; amountOut: bigint } {
+  const {
+    actualBalances,
+    virtualBalances,
+    protocolFeesOwed,
+    weightsBps,
+    amountIn,
+    tokenInIndex,
+    swapToOther,
+    swapFeeRate,
+    protocolFeeRate,
+  } = params;
+  const other = tokenInIndex === 0 ? 1 : 0;
+  const remainingInput = amountIn - swapToOther;
+  if (swapToOther <= 0n || remainingInput <= 0n) return { score: 0n, amountOut: 0n };
+
+  let afterFee: bigint;
+  try {
+    afterFee = amountAfterSwapFee(swapToOther, swapFeeRate);
+  } catch {
+    return { score: 0n, amountOut: 0n };
+  }
+  const swapFee = swapToOther - afterFee;
+  const protocolFee = protocolFeeAmount(swapFee, protocolFeeRate);
+
+  const inLp = lpBalances(
+    actualBalances[tokenInIndex],
+    virtualBalances[tokenInIndex],
+    protocolFeesOwed[tokenInIndex]
+  );
+  const outLp = lpBalances(
+    actualBalances[other],
+    virtualBalances[other],
+    protocolFeesOwed[other]
+  );
+
+  let amountOut: bigint;
+  try {
+    amountOut = calcOutGivenIn({
+      virtualBalanceIn: inLp.lpVirtual,
+      weightInBps: BigInt(weightsBps[tokenInIndex]),
+      virtualBalanceOut: outLp.lpVirtual,
+      weightOutBps: BigInt(weightsBps[other]),
+      amountIn: afterFee,
+      actualBalanceOut: outLp.lpActual,
+    });
+  } catch {
+    return { score: 0n, amountOut: 0n };
+  }
+  if (amountOut <= 0n || amountOut >= outLp.lpActual) return { score: 0n, amountOut };
+
+  const lpInAfter = inLp.lpActual + swapToOther - protocolFee;
+  const lpOutAfter = outLp.lpActual - amountOut;
+  if (lpInAfter <= 0n || lpOutAfter <= 0n) return { score: 0n, amountOut };
+
+  const ratioIn = (remainingInput * ONE) / lpInAfter;
+  const ratioOut = (amountOut * ONE) / lpOutAfter;
+  return { score: ratioIn < ratioOut ? ratioIn : ratioOut, amountOut };
+}
+
+/** @deprecated Analytical base-fee-only optimizer. The deployed helper uses computeAllocations; this does not model selloff/surge. */
+export function computeTwoTokenOptimalAllocations(params: {
+  actualBalances: [bigint, bigint];
+  virtualBalances: [bigint, bigint];
+  protocolFeesOwed: [bigint, bigint];
+  weightsBps: [number, number];
+  amountIn: bigint;
+  tokenInIndex: 0 | 1;
+  swapFeeRate: number;
+  protocolFeeRate: number;
+}): AllocationResult {
+  const { amountIn, tokenInIndex } = params;
+  if (amountIn <= 1n) {
+    throw new Error("computeTwoTokenOptimalAllocations: amountIn too small");
+  }
+
+  let low = 1n;
+  let high = amountIn - 1n;
+  for (let i = 0; i < 32 && low < high; i++) {
+    const mid = low + (high - low) / 2n;
+    const current = scoreTwoTokenSwap({ ...params, swapToOther: mid }).score;
+    const next = scoreTwoTokenSwap({
+      ...params,
+      swapToOther: mid + 1n < amountIn ? mid + 1n : amountIn - 1n,
+    }).score;
+    if (next >= current) low = mid + 1n;
+    else high = mid;
+  }
+
+  const center = low < 1n ? 1n : low >= amountIn ? amountIn - 1n : low;
+  let bestSwap = center;
+  let bestScore = 0n;
+  const start = center > 8n ? center - 8n : 1n;
+  const end = center + 8n < amountIn ? center + 8n : amountIn - 1n;
+  for (let swapToOther = start; swapToOther <= end; swapToOther++) {
+    const { score, amountOut } = scoreTwoTokenSwap({ ...params, swapToOther });
+    if (amountOut > 0n && score > bestScore) {
+      bestScore = score;
+      bestSwap = swapToOther;
+    }
+  }
+  if (bestScore === 0n) {
+    throw new Error("computeTwoTokenOptimalAllocations: amount too small");
+  }
+
+  const allocations: [bigint, bigint] = [0n, 0n];
+  const other = tokenInIndex === 0 ? 1 : 0;
+  allocations[tokenInIndex] = amountIn - bestSwap;
+  allocations[other] = bestSwap;
+  return { allocations, wScaled: [], sumW: bestScore };
+}
+
+/**
+ * Mirror of stld `cap_deposit_amounts_to_lp_ratio`.
+ *
+ * Stored actual balances already exclude protocol fees. The helper deposits
+ * the common raw-actual ratio and refunds the remaining basket.
+ */
+export function capDepositAmountsToLpRatio(params: {
+  helperBalances: bigint[];
+  actualBalances: bigint[];
+  /** Retained for compatibility; actual balances already exclude these fees. */
+  protocolFeesOwed?: bigint[];
+}): { depositAmounts: bigint[]; refundAmounts: bigint[]; lpBalancesForAdd: bigint[] } {
+  const { helperBalances, actualBalances, protocolFeesOwed } = params;
+  const n = helperBalances.length;
+  if (n !== actualBalances.length || (protocolFeesOwed && n !== protocolFeesOwed.length)) {
+    throw new Error("capDepositAmountsToLpRatio: length mismatch");
+  }
+
+  helperBalances.forEach((b) => assertU64(b));
+  const lpBalancesForAdd = actualBalances.map((actual) => assertU64(actual));
+  let ratioMin: bigint | null = null;
+
+  for (let i = 0; i < n; i++) {
+    if (lpBalancesForAdd[i] === 0n) continue;
+    if (helperBalances[i] <= 0n) {
+      throw new Error("capDepositAmountsToLpRatio: amount too small");
+    }
+    const ratio = (helperBalances[i] * ONE) / lpBalancesForAdd[i];
+    ratioMin = ratioMin === null || ratio < ratioMin ? ratio : ratioMin;
+  }
+
+  if (ratioMin === null || ratioMin === 0n) {
+    throw new Error("capDepositAmountsToLpRatio: amount too small");
+  }
+
+  const depositAmounts = lpBalancesForAdd.map((lp, i) => {
+    if (lp === 0n) return 0n;
+    const amount = (lp * ratioMin!) / ONE;
+    if (amount <= 0n) {
+      throw new Error("capDepositAmountsToLpRatio: amount too small");
+    }
+    return amount > helperBalances[i] ? helperBalances[i] : amount;
+  });
+  const refundAmounts = helperBalances.map((balance, i) =>
+    balance > depositAmounts[i] ? balance - depositAmounts[i] : 0n
+  );
+
+  return { depositAmounts, refundAmounts, lpBalancesForAdd };
+}

package/src/math/slippage.ts

@@ -0,0 +1,38 @@
+import { SLIPPAGE_PRECISION, SWAP_FEE_PRECISION, PROTOCOL_FEE_PRECISION, MAX_SWAP_FEE_RATE, MAX_PROTOCOL_FEE_RATE } from "../config";
+import { assertInteger, assertU64 } from "./fixedPoint";
+export function applySlippage(expected: bigint, slippageHbps: number): bigint {
+    assertU64(expected);
+    assertInteger(slippageHbps, 0, SLIPPAGE_PRECISION, "slippage");
+    return expected * BigInt(SLIPPAGE_PRECISION - slippageHbps) / BigInt(SLIPPAGE_PRECISION);
+}
+function ceilRatio(amount: bigint, rate: number, scale: number): bigint {
+    const numerator = amount * BigInt(rate), denominator = BigInt(scale);
+    return numerator / denominator + (numerator % denominator === 0n ? 0n : 1n);
+}
+/** Base fee rounds UP, exactly as swap.rs. Rate is in hundredths of bps. */
+export function calculateSwapFee(amount: bigint, swapFeeRate: number): bigint {
+    assertU64(amount);
+    assertInteger(swapFeeRate, 0, MAX_SWAP_FEE_RATE, "swap fee");
+    return assertU64(ceilRatio(amount, swapFeeRate, SWAP_FEE_PRECISION));
+}
+/** Protocol share of the input fee also rounds UP. Rate is in basis points. */
+export function calculateProtocolFee(fee: bigint, protocolFeeRate: number): bigint {
+    assertU64(fee);
+    assertInteger(protocolFeeRate, 0, MAX_PROTOCOL_FEE_RATE, "protocol fee");
+    return assertU64(ceilRatio(fee, protocolFeeRate, PROTOCOL_FEE_PRECISION));
+}
+export function applySwapFee(amount: bigint, swapFeeRate: number): bigint {
+    return amount - calculateSwapFee(amount, swapFeeRate);
+}
+/** Stored actual balances already exclude protocol fees. The third argument is retained for compatibility. */
+export function lpBalances(actual: bigint, virtualBal: bigint, _protocolFeesOwed?: bigint): {
+    lpActual: bigint;
+    lpVirtual: bigint;
+} {
+    return { lpActual: assertU64(actual), lpVirtual: assertU64(virtualBal) };
+}
+export function priceImpactHbps(spot: bigint, actual: bigint): number {
+    if (spot <= 0n || actual >= spot)
+        return 0;
+    return Number((spot - actual) * BigInt(SLIPPAGE_PRECISION) / spot);
+}

package/src/math/surgeFee.ts

@@ -0,0 +1,101 @@
+/** Piecewise-linear surge rate and four-segment output fee from swap.rs. */
+import { ONE, assertInteger, assertU64 } from "./fixedPoint";
+import { calcOutGivenIn } from "./cubicMath";
+import { SelloffResult } from "./maxSelloff";
+const SCALE = 10000n;
+export interface SurgeCurve {
+    thresholdPct: number;
+    slopeLowPct: number;
+    slopeMidPct: number;
+    slopeHighPct: number;
+    kinkPct: number;
+}
+function validateCurve(c: SurgeCurve): void {
+    assertInteger(c.thresholdPct, 0, 65535, "surge threshold");
+    assertInteger(c.slopeLowPct, 0, 65535, "surge low");
+    assertInteger(c.slopeMidPct, 0, 65535, "surge mid");
+    assertInteger(c.slopeHighPct, 0, 65535, "surge high");
+    assertInteger(c.kinkPct, 0, 255, "surge kink");
+}
+const sub = (a: bigint, b: bigint): bigint => a > b ? a - b : 0n;
+const min = (a: bigint, b: bigint): bigint => a < b ? a : b;
+const ceil = (a: bigint, b: bigint): bigint => a / b + (a % b === 0n ? 0n : 1n);
+function kinkT(c: SurgeCurve): bigint { const thr = BigInt(c.thresholdPct), fill = BigInt(c.kinkPct) * 100n; return c.kinkPct === 0 || thr >= SCALE || fill <= thr || fill >= SCALE ? 0n : (fill - thr) * ONE / (SCALE - thr); }
+function rateAt(t: bigint, c: SurgeCurve, k: bigint): bigint {
+    t = min(t, ONE);
+    const low = BigInt(c.slopeLowPct), mid = BigInt(c.slopeMidPct), high = BigInt(c.slopeHighPct);
+    if (k === 0n)
+        return min(low + ceil(sub(high, low) * t, ONE), SCALE);
+    if (t <= k)
+        return min(low + ceil(sub(mid, low) * t, k), SCALE);
+    return min(mid + ceil(sub(high, mid) * (t - k), ONE - k), SCALE);
+}
+function integralTo(t: bigint, c: SurgeCurve, k: bigint): bigint {
+    t = min(t, ONE);
+    const low = BigInt(c.slopeLowPct), mid = BigInt(c.slopeMidPct), high = BigInt(c.slopeHighPct);
+    // Keep Rust's division before multiplication; algebraic reordering changes rounding.
+    const ramp = (x: bigint, span: bigint, den: bigint): bigint => den === 0n || span === 0n || x === 0n ? 0n : span * (x * x / (2n * den));
+    if (k === 0n)
+        return low * t + ramp(t, sub(high, low), ONE);
+    if (t <= k)
+        return low * t + ramp(t, sub(mid, low), k);
+    const rest = t - k;
+    return k * (low + mid) / 2n + mid * rest + ramp(rest, sub(high, mid), ONE - k);
+}
+export function calcSurgeFeePct(params: SurgeCurve & {
+    before: bigint;
+    after: bigint;
+    cap: bigint;
+}): bigint {
+    validateCurve(params);
+    const { before, after, cap } = params;
+    assertU64(before);
+    assertU64(after);
+    assertU64(cap);
+    const thr = BigInt(params.thresholdPct);
+    if (cap === 0n || params.slopeHighPct === 0 || thr >= SCALE)
+        return 0n;
+    const k = kinkT(params), f0 = min(before * SCALE / cap, SCALE), f1 = min(after * SCALE / cap, SCALE);
+    if (f1 <= thr)
+        return 0n;
+    const den = SCALE - thr, t1 = (f1 - thr) * ONE / den;
+    if (f1 <= f0)
+        return rateAt(t1, params, k);
+    const f0Clamped = f0 > thr ? f0 : thr, t0 = (f0Clamped - thr) * ONE / den;
+    const integral = sub(integralTo(t1, params, k), integralTo(t0, params, k));
+    return min(ceil(den * integral, (f1 - f0Clamped) * ONE), SCALE);
+}
+export function calcSurgeFeeAmount(params: SurgeCurve & {
+    window: SelloffResult | null;
+    amountInAfterFee: bigint;
+    amountOut: bigint;
+    virtualBalanceIn: bigint;
+    weightInBps: bigint;
+    virtualBalanceOut: bigint;
+    weightOutBps: bigint;
+    actualBalanceOut: bigint;
+}): bigint {
+    const { window, amountInAfterFee, amountOut } = params;
+    assertU64(amountInAfterFee);
+    assertU64(amountOut);
+    if (!window)
+        return 0n;
+    const before = window.effectiveSelloffBefore, after = window.effectiveSelloff, cap = window.maxSelloffCap;
+    if (calcSurgeFeePct({ ...params, before, after, cap }) === 0n)
+        return 0n;
+    const thrUnits = cap * BigInt(params.thresholdPct) / SCALE;
+    const span = sub(after, before), taxedLo = before > thrUnits ? before : thrUnits;
+    if (span === 0n || after <= taxedLo)
+        return 0n;
+    const cumulative = (u: bigint): bigint => u <= before ? 0n : u >= after ? amountOut : calcOutGivenIn({ ...params, amountIn: amountInAfterFee * (u - before) / span });
+    const width = after - taxedLo;
+    let fee = 0n, prevU = taxedLo, prevY = cumulative(taxedLo);
+    for (let k = 1n; k <= 4n; k++) {
+        const u = k === 4n ? after : taxedLo + width * k / 4n, y = cumulative(u), segmentOut = sub(y, prevY);
+        if (segmentOut > 0n && u > prevU)
+            fee += ceil(segmentOut * calcSurgeFeePct({ ...params, before: prevU, after: u, cap }), SCALE);
+        prevU = u;
+        prevY = y;
+    }
+    return min(fee, amountOut);
+}

package/src/math/weightedMath.ts

@@ -0,0 +1,64 @@
+import {ONE, assertU64, assertInteger, assertU128, mulDivDown, weightToFp} from "./fixedPoint";
+import {powFp} from "./logExp";
+import { MAX_WEIGHT, MIN_WEIGHT, WEIGHT_SCALE } from "../config";
+
+/**
+ * Validate a weight vector. Must sum exactly to 10_000 (WEIGHT_SCALE) and
+ * every entry must be in [MIN_WEIGHT, MAX_WEIGHT].
+ */
+export function validateWeights(weights: number[]): void {
+  if (!Array.isArray(weights) || weights.length < 2) {
+    throw new Error("weightedMath: at least 2 weights required");
+  }
+  let sum = 0;
+  for (const w of weights) {
+    if (!Number.isInteger(w)) {
+      throw new Error("weightedMath: weights must be integers (bps)");
+    }
+    if (w < MIN_WEIGHT || w > MAX_WEIGHT) {
+      throw new Error(`weightedMath: weight ${w} out of [${MIN_WEIGHT}, ${MAX_WEIGHT}]`);
+    }
+    sum += w;
+  }
+  if (sum !== WEIGHT_SCALE) {
+    throw new Error(`weightedMath: weights sum to ${sum}, expected ${WEIGHT_SCALE}`);
+  }
+}
+
+/**
+ * Weighted spot price of token_out priced in token_in, normalised to 18
+ * decimals. Used only for display; on-chain quoting uses calcOutGivenIn.
+ */
+export function calcSpotPrice(params: {
+  balanceIn: bigint;
+  weightInBps: bigint;
+  balanceOut: bigint;
+  weightOutBps: bigint;
+  decimalsIn: number;
+  decimalsOut: number;
+}): bigint {
+  const { balanceIn, weightInBps, balanceOut, weightOutBps, decimalsIn, decimalsOut } = params;
+  const scaleIn = 10n ** BigInt(18 - decimalsIn);
+  const scaleOut = 10n ** BigInt(18 - decimalsOut);
+  const bI = balanceIn * scaleIn;
+  const bO = balanceOut * scaleOut;
+  if (bO === 0n || weightOutBps === 0n) return 0n;
+  // price = (bI / wI) / (bO / wO)
+  const numer = bI * weightOutBps * 10n ** 18n;
+  const denom = bO * weightInBps;
+  return numer / denom;
+}
+
+/** Exact seed-deposit invariant from weighted_math.rs; returns raw BPT before u64/minimum-supply checks. */
+export function calculateInvariant(balances:bigint[], normalizedWeights:number[], decimals:number[]):bigint {
+  if(balances.length!==normalizedWeights.length||balances.length!==decimals.length||balances.length<2)throw new Error("invariant: invalid vector lengths");
+  let invariant=ONE;
+  for(let i=0;i<balances.length;i++) {
+    const raw=assertU64(balances[i]);assertInteger(decimals[i],0,18,"decimals");assertInteger(normalizedWeights[i],0,10000,"weight");
+    if(raw===0n)return 0n;
+    const balance=decimals[i]>=6?raw/(10n**BigInt(decimals[i]-6)):assertU128(raw*10n**BigInt(6-decimals[i]));
+    if(balance===0n)return 0n;
+    invariant=mulDivDown(invariant,powFp(balance,weightToFp(normalizedWeights[i])),ONE);
+  }
+  return invariant;
+}

package/src/parsers/borsh.ts

@@ -0,0 +1,106 @@
+import BN from "bn.js";
+import { PublicKey } from "@solana/web3.js";
+
+/**
+ * Minimal Borsh-compatible reader. Enough to decode the Coffer contract
+ * event structs (Pubkey × N, u8/u16/u32/u64/i64, bool, Vec<u64>,
+ * Vec<Pubkey>). Avoids pulling a borsh dep into the SDK's hot path.
+ */
+export class BorshReader {
+  private offset = 0;
+  constructor(private readonly buf: Buffer) {}
+
+  remaining(): number {
+    return this.buf.length - this.offset;
+  }
+
+  /** Current read position — pair with `seek` to re-parse an ambiguous tail. */
+  pos(): number {
+    return this.offset;
+  }
+
+  seek(offset: number): void {
+    this.offset = offset;
+  }
+
+  skip(n: number): void {
+    this.requireBytes(n);
+    this.offset += n;
+  }
+
+  u8(): number {
+    this.requireBytes(1);
+    const v = this.buf.readUInt8(this.offset);
+    this.offset += 1;
+    return v;
+  }
+
+  u16(): number {
+    this.requireBytes(2);
+    const v = this.buf.readUInt16LE(this.offset);
+    this.offset += 2;
+    return v;
+  }
+
+  u32(): number {
+    this.requireBytes(4);
+    const v = this.buf.readUInt32LE(this.offset);
+    this.offset += 4;
+    return v;
+  }
+
+  u64(): BN {
+    this.requireBytes(8);
+    const slice = this.buf.slice(this.offset, this.offset + 8);
+    this.offset += 8;
+    return new BN(slice, "le");
+  }
+
+  i64(): BN {
+    this.requireBytes(8);
+    const slice = this.buf.slice(this.offset, this.offset + 8);
+    this.offset += 8;
+    // i64 is two's complement little-endian — treat as signed.
+    const bn = new BN(slice, "le");
+    if (slice[7] & 0x80) {
+      // top bit set → negative: subtract 2^64
+      return bn.sub(new BN(2).pow(new BN(64)));
+    }
+    return bn;
+  }
+
+  bool(): boolean {
+    const value = this.u8();
+    if (value > 1) throw new Error(`BorshReader: invalid bool ${value}`);
+    return value === 1;
+  }
+
+  pubkey(): PublicKey {
+    this.requireBytes(32);
+    const slice = this.buf.slice(this.offset, this.offset + 32);
+    this.offset += 32;
+    return new PublicKey(slice);
+  }
+
+  vecU64(): BN[] {
+    const len = this.u32();
+    this.requireBytes(len * 8);
+    const out: BN[] = [];
+    for (let i = 0; i < len; i++) out.push(this.u64());
+    return out;
+  }
+
+  vecPubkey(): PublicKey[] {
+    const len = this.u32();
+    this.requireBytes(len * 32);
+    const out: PublicKey[] = [];
+    for (let i = 0; i < len; i++) out.push(this.pubkey());
+    return out;
+  }
+
+  private requireBytes(length: number): void {
+    if (!Number.isSafeInteger(length) || length < 0 || length > this.remaining()) {
+      throw new Error(`BorshReader: expected ${length} bytes at offset ${this.offset}, ${this.remaining()} remain`);
+    }
+  }
+}

package/src/parsers/contracts.ts

@@ -0,0 +1,64 @@
+import { BorshAccountsCoder, BorshEventCoder, Idl } from "@coral-xyz/anchor";
+import { IDLS } from "../idl";
+import { ContractAccountMap, ContractEventMap, ContractProgram } from "../types/contracts";
+
+export type ContractEvent = {
+  [P in ContractProgram]: {
+    [E in keyof ContractEventMap[P]]: { program: P; kind: E; data: ContractEventMap[P][E] }
+  }[keyof ContractEventMap[P]]
+}[ContractProgram];
+
+const accountCoders = new Map<ContractProgram, BorshAccountsCoder>();
+const eventCoders = new Map<ContractProgram, BorshEventCoder>();
+
+/** Decode any account in the current ABI, including Config and Treasury.
+ * Fields retain IDL snake_case names; u64/i64 values remain BN without loss.
+ * The discriminator is verified. Check RPC account ownership separately.
+ */
+export function decodeContractAccount<P extends ContractProgram, A extends keyof ContractAccountMap[P] & string>(
+  program: P, account: A, data: Buffer,
+): ContractAccountMap[P][A] {
+  let coder = accountCoders.get(program);
+  if (!coder) {
+    coder = new BorshAccountsCoder(IDLS[program] as unknown as Idl);
+    accountCoders.set(program, coder);
+  }
+  const expectedSize = coder.size(account);
+  if (data.length !== expectedSize) throw new Error(`${account} has ${data.length} bytes; expected ${expectedSize} for the current ABI`);
+  return coder.decode(account, data);
+}
+
+/** Decode the payload following `Program data:` using all current event fields.
+ * Returns null for an unknown or malformed event. `program` limits decoding to
+ * one ABI when the emitting program is known from the transaction invoke stack.
+ */
+export function decodeContractEvent(base64: string, program?: ContractProgram): ContractEvent | null {
+  const programs = program ? [program] : Object.keys(IDLS) as ContractProgram[];
+  for (const candidate of programs) {
+    let coder = eventCoders.get(candidate);
+    if (!coder) {
+      coder = new BorshEventCoder(IDLS[candidate] as unknown as Idl);
+      eventCoders.set(candidate, coder);
+    }
+    try {
+      const result = coder.decode(base64);
+      if (result) return { program: candidate, kind: result.name, data: result.data } as ContractEvent;
+    } catch { /* Try the other ABI, or report an undecodable event. */ }
+  }
+  return null;
+}
+
+/** Parse all 60 known events; fields and names match the shipped contract IDLs.
+ * This is decoding, not proof of the emitting program's identity. Consumers
+ * must verify transaction success and program provenance before indexing.
+ */
+export function parseContractEvents(logs: string[], program?: ContractProgram): ContractEvent[] {
+  const events: ContractEvent[] = [];
+  for (const line of logs) {
+    const payload = /^Program data:\s+(.+)$/.exec(line)?.[1];
+    if (!payload) continue;
+    const event = decodeContractEvent(payload, program);
+    if (event) events.push(event);
+  }
+  return events;
+}