@coffer_so/sdk 1.0.0

package/src/parsers/events.ts

@@ -0,0 +1,275 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import { BorshReader } from "./borsh";
+import { decodeContractEvent, ContractEvent } from "./contracts";
+import { CubicPoolEvent, AdditionalContractEvent } from "../types/events";
+
+/**
+ * Anchor event log format (base64-encoded after `Program data:`):
+ *   [ 8-byte discriminator | borsh-encoded event struct ]
+ *
+ * Discriminators for cubic-pool and single-token-liquidity are hard-coded
+ * here from the generated IDL. Never guess from event name — the Anchor
+ * macro actually uses `sha256("event:<Name>")[0..8]`, but for robustness
+ * we pin the bytes.
+ */
+
+// Cubic-pool event discriminators (from target/idl/cubic_pool.json):
+const DISC = {
+  PoolInitialized:          Buffer.from([100, 118, 173, 87, 12, 198, 254, 229]),
+  Swap:                     Buffer.from([81, 108, 227, 190, 205, 208, 10, 196]),
+  LiquidityAdded:           Buffer.from([154, 26, 221, 108, 238, 64, 217, 161]),
+  LiquidityRemoved:         Buffer.from([225, 105, 216, 39, 124, 116, 169, 189]),
+  ProtocolFeesCollected:    Buffer.from([165, 34, 125, 155, 15, 86, 99, 191]),
+  SwapFeeRateUpdated:       Buffer.from([101, 132, 24, 255, 91, 253, 227, 101]),
+  ProtocolFeeRateUpdated:   Buffer.from([189, 56, 7, 65, 0, 95, 192, 6]),
+  PoolEnabledUpdated:       Buffer.from([101, 47, 3, 240, 197, 181, 236, 142]),
+  SwapsEnabledUpdated:      Buffer.from([55, 116, 118, 138, 102, 26, 227, 223]),
+  DebugLiquidityWithdrawn:  Buffer.from([174, 59, 149, 22, 135, 129, 129, 83]),
+  PoolStateLog:             Buffer.from([59, 254, 237, 111, 163, 10, 140, 224]),
+  PoolInfo:                 Buffer.from([207, 20, 87, 97, 251, 212, 234, 45]),
+  BannedExtensionsUpdated:  Buffer.from([107, 126, 13, 149, 182, 108, 139, 202]),
+  MaxSelloffWindowAdvanced: Buffer.from([229, 227, 163, 30, 22, 183, 78, 57]),
+  // Stld:
+  SingleTokenDeposit:       Buffer.from([215, 54, 137, 104, 219, 39, 164, 235]),
+};
+
+type DiscName = keyof typeof DISC;
+
+export function parseCubicPoolEvents(logs: string[]): CubicPoolEvent[] {
+  const out: CubicPoolEvent[] = [];
+  for (const line of logs) {
+    const m = line.match(/^Program data:\s+(.+)$/);
+    if (!m) continue;
+    const buf = Buffer.from(m[1], "base64");
+    if (buf.length < 8) continue;
+    const disc = buf.slice(0, 8);
+    const payload = buf.slice(8);
+    const name = matchDiscriminator(disc);
+    if (!name) {
+      const current = decodeContractEvent(m[1]);
+      if (current) {
+        try { out.push(camelEvent(current)); }
+        catch (error) { out.push({ kind: "Unknown", name: current.kind, data: { error: String(error), payload: payload.toString("base64") } }); }
+        continue;
+      }
+      out.push({ kind: "Unknown", name: "unknown", data: { disc: disc.toString("base64"), payload: payload.toString("base64") } });
+      continue;
+    }
+    try {
+      const ev = decodeEvent(name, payload);
+      if (ev) out.push(ev);
+    } catch (e) {
+      out.push({
+        kind: "Unknown",
+        name,
+        data: { error: String(e), payload: payload.toString("base64") },
+      });
+    }
+  }
+  return out;
+}
+
+function matchDiscriminator(d: Buffer): DiscName | null {
+  for (const [name, bytes] of Object.entries(DISC)) {
+    if (bytes.equals(d)) return name as DiscName;
+  }
+  return null;
+}
+
+function decodeEvent(name: DiscName, buf: Buffer): CubicPoolEvent | null {
+  const r = new BorshReader(buf);
+  switch (name) {
+    case "Swap": {
+      // The deployed without-SF event ends with timestamp, surge_fee_amount.
+      // Optional trailing transfer-fee fields are retained only for decoding
+      // logs from other historical builds; they do not imply mint support.
+      const pool = r.pubkey();
+      const user = r.pubkey();
+      const tokenIn = r.pubkey();
+      const tokenOut = r.pubkey();
+      const amountIn = r.u64();
+      const amountOut = r.u64();
+      const feeAmount = r.u64();
+      const protocolFeeAmount = r.u64();
+      const timestamp = r.i64().toNumber();
+      const surgeFeeAmount = r.u64();
+      // Absent in the deployed without-SF ABI: expose zero for compatibility.
+      const transferFeeIn = r.remaining() >= 8 ? r.u64() : new BN(0);
+      const transferFeeOut = r.remaining() >= 8 ? r.u64() : new BN(0);
+      return {
+        kind: "Swap",
+        pool,
+        user,
+        tokenIn,
+        tokenOut,
+        amountIn,
+        amountOut,
+        feeAmount,
+        protocolFeeAmount,
+        surgeFeeAmount,
+        timestamp,
+        transferFeeIn,
+        transferFeeOut,
+      };
+    }
+    case "LiquidityAdded": {
+      const pool = r.pubkey();
+      const user = r.pubkey();
+      const tokenAmounts = r.vecU64();
+      const bptAmount = r.u64();
+      const timestamp = r.i64().toNumber();
+      return { kind: "LiquidityAdded", pool, user, tokenAmounts, bptAmount, timestamp };
+    }
+    case "LiquidityRemoved": {
+      const pool = r.pubkey();
+      const user = r.pubkey();
+      const bptAmount = r.u64();
+      const tokenAmounts = r.vecU64();
+      const timestamp = r.i64().toNumber();
+      return { kind: "LiquidityRemoved", pool, user, bptAmount, tokenAmounts, timestamp };
+    }
+    case "ProtocolFeesCollected": {
+      const pool = r.pubkey();
+      const authority = r.pubkey();
+      const tokenAmounts = r.vecU64();
+      const timestamp = r.i64().toNumber();
+      return { kind: "ProtocolFeesCollected", pool, authority, tokenAmounts, timestamp };
+    }
+    case "PoolInitialized": {
+      const pool = r.pubkey();
+      const config = r.pubkey();
+      const tokenCount = r.u8();
+      const bptMint = r.pubkey();
+      const timestamp = r.i64().toNumber();
+      // Appended: the effective banned-extensions bitmap the pool's tokens
+      // were vetted against at creation. Guarded for older logs.
+      const bannedExtensions = r.remaining() >= 8 ? r.u64() : new BN(0);
+      return { kind: "PoolInitialized", pool, config, tokenCount, bptMint, timestamp, bannedExtensions };
+    }
+    case "PoolEnabledUpdated": {
+      const pool = r.pubkey();
+      const authority = r.pubkey();
+      const oldValue = r.bool();
+      const newValue = r.bool();
+      const timestamp = r.i64().toNumber();
+      return { kind: "PoolEnabledUpdated", pool, authority, oldValue, newValue, timestamp };
+    }
+    case "SwapsEnabledUpdated": {
+      const pool = r.pubkey();
+      const authority = r.pubkey();
+      const oldValue = r.bool();
+      const newValue = r.bool();
+      const timestamp = r.i64().toNumber();
+      return { kind: "SwapsEnabledUpdated", pool, authority, oldValue, newValue, timestamp };
+    }
+    case "SingleTokenDeposit": {
+      // Verified against `SingleTokenDeposit` in
+      // src/idl/single_token_liquidity.json:
+      //   helper, pool, user, token_in_index, amount_in, allocations,
+      //   deposited_amounts, bpt_received, dust_refunded, timestamp
+      //
+      // Two fixes vs. the previous decoder:
+      //  1. There is NO `slippage_hundredths_bps: u32` field. The per-call
+      //     slippage argument was removed from `deposit_single_token` (the
+      //     single `minimum_bpt_amount` guard replaced it) and the event
+      //     field went with it. Reading a phantom u32 here shifted every
+      //     later field by 4 bytes.
+      //  2. `dust_refunded` is `Vec<u64>` (index-aligned with the pool's
+      //     tokens), not a scalar `u64`.
+      const helper = r.pubkey();
+      const pool = r.pubkey();
+      const user = r.pubkey();
+      const tokenInIndex = r.u8();
+      const amountIn = r.u64();
+      const allocations = r.vecU64();
+      const depositedAmounts = r.vecU64();
+      const bptReceived = r.u64();
+      const dustRefunded = r.vecU64();
+      const timestamp = r.i64().toNumber();
+      return {
+        kind: "SingleTokenDeposit",
+        helper,
+        pool,
+        user,
+        tokenInIndex,
+        amountIn,
+        allocations,
+        depositedAmounts,
+        bptReceived,
+        dustRefunded,
+        timestamp,
+      };
+    }
+    case "PoolStateLog": {
+      const pool = r.pubkey();
+      const virtualBalances = r.vecU64();
+      const actualBalances = r.vecU64();
+      const protocolFeesOwed = r.vecU64();
+      const timestamp = r.i64().toNumber();
+      return { kind: "PoolStateLog", pool, virtualBalances, actualBalances, protocolFeesOwed, timestamp };
+    }
+    case "MaxSelloffWindowAdvanced": {
+      const pool = r.pubkey();
+      const tokenIndex = r.u8();
+      const effectiveSelloff = r.u64();
+      const maxSelloffCap = r.u64();
+      const vbSnapshot = r.u64();
+      const previousSelloff = r.u64();
+      const currentSelloff = r.u64();
+      const windowStartTimestamp = r.i64().toNumber();
+      const timestamp = r.i64().toNumber();
+      return {
+        kind: "MaxSelloffWindowAdvanced",
+        pool,
+        tokenIndex,
+        effectiveSelloff,
+        maxSelloffCap,
+        vbSnapshot,
+        previousSelloff,
+        currentSelloff,
+        windowStartTimestamp,
+        timestamp,
+      };
+    }
+    case "BannedExtensionsUpdated": {
+      const config = r.pubkey();
+      const authority = r.pubkey();
+      const oldValue = r.u64();
+      const newValue = r.u64();
+      const timestamp = r.i64().toNumber();
+      // Appended in v5.1 alongside `set_banned_extensions`' new
+      // `hard_banned_extensions` argument. Guarded for older logs.
+      const oldHardValue = r.remaining() >= 8 ? r.u64() : new BN(0);
+      const newHardValue = r.remaining() >= 8 ? r.u64() : new BN(0);
+      return {
+        kind: "BannedExtensionsUpdated",
+        config,
+        authority,
+        oldValue,
+        newValue,
+        timestamp,
+        oldHardValue,
+        newHardValue,
+      };
+    }
+    // Decode the remaining current events through the complete shipped ABI.
+    case "SwapFeeRateUpdated":
+    case "ProtocolFeeRateUpdated":
+    case "DebugLiquidityWithdrawn":
+    case "PoolInfo":
+      const current = decodeContractEvent(Buffer.concat([DISC[name], buf]).toString("base64"));
+      return current ? camelEvent(current) : { kind: "Unknown", name, data: { raw: buf.toString("base64") } };
+  }
+}
+
+void PublicKey; // keep import used by types above via type inference
+
+function camelEvent(event: ContractEvent): AdditionalContractEvent {
+  const fields: Record<string, unknown> = { kind: event.kind };
+  for (const [key, value] of Object.entries(event.data)) {
+    const name = key.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    fields[name] = key === "timestamp" && BN.isBN(value) ? value.toNumber() : value;
+  }
+  return fields as AdditionalContractEvent;
+}

package/src/parsers/index.ts

@@ -0,0 +1,5 @@
+export * from "./poolAccount";
+export * from "./mintAccount";
+export * from "./events";
+export * from "./borsh";
+export * from "./contracts";

package/src/parsers/mintAccount.ts

@@ -0,0 +1,44 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import { parseMintExtensions } from "../utils/extensions";
+
+/**
+ * SPL Token (or Token-2022) Mint parser. Reads the 82-byte base layout and,
+ * for Token-2022 mints, the TLV extension list (discriminants only).
+ *
+ * Layout:
+ *   0..36  COption<Pubkey>  mintAuthority  (4 bytes tag + 32 bytes pubkey)
+ *   36..44 u64              supply
+ *   44..45 u8               decimals
+ *   45..46 u8               isInitialized
+ *   46..82 COption<Pubkey>  freezeAuthority
+ */
+export interface RawMintAccount {
+  mintAuthority: PublicKey | null;
+  supply: BN;
+  decimals: number;
+  isInitialized: boolean;
+  freezeAuthority: PublicKey | null;
+  /** Token-2022 extension discriminants; `[]` for classic SPL mints. */
+  extensions: number[];
+}
+
+export function decodeMintAccount(data: Buffer): RawMintAccount {
+  const extensions = parseMintExtensions(data);
+  const mintAuthTag = data.readUInt32LE(0);
+  if (mintAuthTag !== 0 && mintAuthTag !== 1) {
+    throw new Error(`decodeMintAccount: invalid mint-authority option ${mintAuthTag}`);
+  }
+  const mintAuthority =
+    mintAuthTag === 0 ? null : new PublicKey(data.slice(4, 36));
+  const supply = new BN(data.slice(36, 44), "le");
+  const decimals = data.readUInt8(44);
+  const isInitialized = data.readUInt8(45) === 1;
+  const freezeTag = data.readUInt32LE(46);
+  if (freezeTag !== 0 && freezeTag !== 1) {
+    throw new Error(`decodeMintAccount: invalid freeze-authority option ${freezeTag}`);
+  }
+  const freezeAuthority =
+    freezeTag === 0 ? null : new PublicKey(data.slice(50, 82));
+  return { mintAuthority, supply, decimals, isInitialized, freezeAuthority, extensions };
+}

package/src/parsers/poolAccount.ts

@@ -0,0 +1,372 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+
+/**
+ * Raw binary layout of CubicPool **v5** (see
+ * `contracts/programs/cubic-pool/src/state/cubic_pool.rs`).
+ *
+ * v4 reorganised per-token data from six parallel arrays into a single
+ * `tokens: [TokenSlot; 10]` array (each slot = `AssetConfig` +
+ * `AssetDynamics`). For backwards compatibility with downstream
+ * consumers (`CubicPoolClient.sync()` and similar), this decoder still
+ * exposes the parallel-array shape, plus the new max-selloff and admin
+ * fields.
+ *
+ * v5.1 layout deltas (all carved out of `reserved`, total size unchanged
+ * at 1683 — every pre-existing field keeps its byte offset):
+ *   - `AssetConfig.reserved[3]` → `variable_fee_slope_mid_pct: u16` +
+ *     `variable_fee_kink_pct: u8`. Slot stays 88 bytes.
+ *   - `CubicPool`: `range_manager_max_leverage_bps: u32` and
+ *     `range_manager_min_leverage_bps: u32` appended after
+ *     `banned_extensions`; trailing `reserved` shrank [u8;24] → [u8;16].
+ *
+ * Pools written by the pre-v5.1 program decode these new fields as `0`,
+ * which is the back-compatible reading (curve has no kink, leverage band
+ * disabled).
+ *
+ * We decode manually to avoid bundling an Anchor `Program` instance into
+ * the SDK — both frontend and backend consume the SDK, and pulling the
+ * full Anchor runtime is heavy.
+ */
+export interface RawPoolAccount {
+  config: PublicKey;
+  bump: number;
+  tokenCount: number;
+  poolId: BN;
+  swapFeeRate: number;
+  protocolFeeRate: number;
+  createdAt: BN;
+  poolEnabled: boolean;
+  swapsEnabled: boolean;
+  poolAdmin: PublicKey;
+  pendingPoolAdmin: PublicKey;
+
+  rangeManager: PublicKey;
+  rangeManagerEnabled: boolean;
+  /** Percent-of-current-value cap, `PERCENT_SCALE` units (10_000 = 100%). */
+  rangeManagerMaxVbChangePct: number;
+  rangeManagerMaxWeightChangePct: number;
+  rangeManagerMinUpdateIntervalSecs: number;
+  rangeManagerLastUpdated: BN;
+  /**
+   * Absolute UPPER bound on `virtual_balance / actual_balance` the range
+   * manager may leave a token at, in basis points (10_000 = 1.0×).
+   * `0` ⇒ band disabled. Pools written before v5.1 read `0`.
+   *
+   * The per-update percentage caps *velocity*; this caps *distance*.
+   * Breaching it reverts with `RangeManagerLeverageBandExceeded` (6062).
+   */
+  rangeManagerMaxLeverageBps: number;
+  /**
+   * Absolute LOWER bound on `virtual_balance / actual_balance`, same units.
+   * `0` ⇒ floor disabled. Pools written before v5.1 read `0`.
+   */
+  rangeManagerMinLeverageBps: number;
+
+  // Per-token (length 10 each; values past `tokenCount` are zeroed).
+  tokenMints: PublicKey[];
+  tokenPrograms: PublicKey[];
+  normalizedWeights: BN[];
+  /**
+   * Max cumulative sell volume per window, as a percent of the token's
+   * virtual balance (`PERCENT_SCALE` units; 10_000 = 100%). `0` disables.
+   */
+  maxSelloffPct: number[];
+  maxSelloffPeriodLength: number[];
+  /** Variable surge-fee curve, per token (`PERCENT_SCALE` units). */
+  variableFeeThresholdPct: number[];
+  variableFeeSlopeLowPct: number[];
+  variableFeeSlopeHighPct: number[];
+  /**
+   * Surge fee at the KINK — the middle control point of the three-point
+   * curve (`PERCENT_SCALE` units). Between `variableFeeThresholdPct` and
+   * the kink the fee runs linearly from `variableFeeSlopeLowPct` to this
+   * value; beyond it, from this value to `variableFeeSlopeHighPct` at full
+   * window fill. Contract enforces `low <= mid <= high`.
+   *
+   * New in v5.1 (carved out of `AssetConfig.reserved`). Pools written by
+   * the older program read `0`.
+   */
+  variableFeeSlopeMidPct: number[];
+  /**
+   * Window fill at which the surge curve kinks, in WHOLE PERCENT (0..=100)
+   * — NOT `PERCENT_SCALE` units. `0` ⇒ no kink: the curve degenerates to a
+   * single straight line from `low` at the threshold to `high` at full fill,
+   * which is exactly how every pre-v5.1 pool decodes.
+   *
+   * New in v5.1 (carved out of `AssetConfig.reserved`).
+   */
+  variableFeeKinkPct: number[];
+  /**
+   * Per-token input kill switch. `false` ⇒ swaps with this token as INPUT
+   * revert (`TokenInactive`). Defaults to `true`.
+   */
+  isActive: boolean[];
+
+  virtualBalances: BN[];
+  actualBalances: BN[];
+  protocolFeesOwed: BN[];
+  previousSelloff: BN[];
+  currentSelloff: BN[];
+  windowStartTimestamp: BN[];
+  /** Virtual-balance snapshot taken when the max-selloff window opened. */
+  selloffVbSnapshot: BN[];
+
+  /**
+   * Per-pool Address Lookup Table. `PublicKey.default` means the pool's
+   * ALT has not been provisioned yet (`initialize_pool_alt` not called).
+   * SDK uses this to choose between v0 (with ALT) and legacy tx-building
+   * paths.
+   */
+  lookupTable: PublicKey;
+
+  /**
+   * Effective Token-2022 banned-extensions bitmap this pool's tokens were
+   * vetted against at creation (creator override, or the config default).
+   * `0` ⇒ no extensions banned. Pre-upgrade pools read `0`. A permissive
+   * value is a rug-risk — surface it before depositing.
+   */
+  bannedExtensions: BN;
+  /** The exact trailing ABI padding, preserved for complete state inspection. */
+  reserved: Buffer;
+}
+
+/** 8-byte anchor discriminator for CubicPool. */
+export const POOL_DISCRIMINATOR_LEN = 8;
+const POOL_DISCRIMINATOR = Buffer.from([137, 210, 42, 22, 209, 156, 43, 78]);
+const MAX_TOKENS = 10;
+/**
+ * Total on-chain size of a v4/v5 CubicPool (includes the 8-byte
+ * discriminator). v5.1 carved its new fields out of `reserved`, so the
+ * size is deliberately identical to v4 — size alone cannot tell the two
+ * apart. Decoding interprets the current layout; it does not prove an older
+ * account has been migrated.
+ */
+export const POOL_V4_LEN = 1683;
+/** Alias for {@link POOL_V4_LEN}; the layout is shared by v4 and v5. */
+export const POOL_LEN = POOL_V4_LEN;
+/** Per-token `TokenSlot` = `AssetConfig` (88) + `AssetDynamics` (56). */
+const ASSET_CONFIG_LEN = 88;
+const ASSET_DYNAMICS_LEN = 56;
+const TOKEN_SLOT_LEN = ASSET_CONFIG_LEN + ASSET_DYNAMICS_LEN;
+/** Pre-v4 size — legacy accounts are unsupported by the current v4-to-v5 migration. */
+export const POOL_V3_LEN = 1154;
+
+export function decodePoolAccount(data: Buffer): RawPoolAccount {
+  if (data.length === POOL_V3_LEN) {
+    throw new Error(
+      `decodePoolAccount: account is at v3 size (${POOL_V3_LEN}). ` +
+        `Legacy v3 accounts require a separate migration; migrate_to_v5 supports only 1683-byte v4 accounts.`,
+    );
+  }
+  if (data.length !== POOL_V4_LEN) {
+    throw new Error(
+      `decodePoolAccount: unexpected data length ${data.length} ` +
+        `(expected ${POOL_V4_LEN} for v4).`,
+    );
+  }
+  if (!data.subarray(0, POOL_DISCRIMINATOR_LEN).equals(POOL_DISCRIMINATOR)) {
+    throw new Error("decodePoolAccount: invalid CubicPool discriminator");
+  }
+
+  let off = POOL_DISCRIMINATOR_LEN;
+
+  const config = readPubkey(data, off);
+  off += 32;
+  const bump = data.readUInt8(off);
+  off += 1;
+  const tokenCount = data.readUInt8(off);
+  off += 1;
+  if (tokenCount > MAX_TOKENS) {
+    throw new Error(`decodePoolAccount: token_count ${tokenCount} exceeds ${MAX_TOKENS}`);
+  }
+  const poolId = readU64LE(data, off);
+  off += 8;
+  const swapFeeRate = data.readUInt32LE(off);
+  off += 4;
+  const protocolFeeRate = data.readUInt16LE(off);
+  off += 2;
+  const createdAt = readI64LE(data, off);
+  off += 8;
+  const poolEnabled = readBool(data, off);
+  off += 1;
+  const swapsEnabled = readBool(data, off);
+  off += 1;
+  const poolAdmin = readPubkey(data, off);
+  off += 32;
+  const pendingPoolAdmin = readPubkey(data, off);
+  off += 32;
+
+  const rangeManager = readPubkey(data, off);
+  off += 32;
+  const rangeManagerEnabled = readBool(data, off);
+  off += 1;
+  const rangeManagerMaxVbChangePct = data.readUInt16LE(off);
+  off += 2;
+  const rangeManagerMaxWeightChangePct = data.readUInt16LE(off);
+  off += 2;
+  const rangeManagerMinUpdateIntervalSecs = data.readUInt32LE(off);
+  off += 4;
+  const rangeManagerLastUpdated = readI64LE(data, off);
+  off += 8;
+
+  // Per-token AoS — 10 slots, each 144 bytes.
+  const tokenMints: PublicKey[] = [];
+  const tokenPrograms: PublicKey[] = [];
+  const normalizedWeights: BN[] = [];
+  const maxSelloffPct: number[] = [];
+  const maxSelloffPeriodLength: number[] = [];
+  const variableFeeThresholdPct: number[] = [];
+  const variableFeeSlopeLowPct: number[] = [];
+  const variableFeeSlopeHighPct: number[] = [];
+  const variableFeeSlopeMidPct: number[] = [];
+  const variableFeeKinkPct: number[] = [];
+  const isActive: boolean[] = [];
+  const virtualBalances: BN[] = [];
+  const actualBalances: BN[] = [];
+  const protocolFeesOwed: BN[] = [];
+  const previousSelloff: BN[] = [];
+  const currentSelloff: BN[] = [];
+  const windowStartTimestamp: BN[] = [];
+  const selloffVbSnapshot: BN[] = [];
+
+  for (let i = 0; i < MAX_TOKENS; i++) {
+    const slotStart = off;
+
+    // AssetConfig — 88 bytes
+    tokenMints.push(readPubkey(data, off));
+    off += 32;
+    tokenPrograms.push(readPubkey(data, off));
+    off += 32;
+    normalizedWeights.push(readU64LE(data, off));
+    off += 8;
+    maxSelloffPct.push(data.readUInt16LE(off));
+    off += 2;
+    maxSelloffPeriodLength.push(data.readUInt32LE(off));
+    off += 4;
+    variableFeeThresholdPct.push(data.readUInt16LE(off));
+    off += 2;
+    variableFeeSlopeLowPct.push(data.readUInt16LE(off));
+    off += 2;
+    variableFeeSlopeHighPct.push(data.readUInt16LE(off));
+    off += 2;
+    isActive.push(readBool(data, off));
+    off += 1;
+    // v5.1: the trailing `AssetConfig.reserved[3]` became these two fields.
+    // Byte-for-byte replacement — the slot is still 88 bytes and every
+    // preceding field keeps its offset, so a v4 account decodes as 0/0.
+    variableFeeSlopeMidPct.push(data.readUInt16LE(off));
+    off += 2;
+    variableFeeKinkPct.push(data.readUInt8(off));
+    off += 1;
+
+    // AssetDynamics — 56 bytes
+    virtualBalances.push(readU64LE(data, off));
+    off += 8;
+    actualBalances.push(readU64LE(data, off));
+    off += 8;
+    protocolFeesOwed.push(readU64LE(data, off));
+    off += 8;
+    previousSelloff.push(readU64LE(data, off));
+    off += 8;
+    currentSelloff.push(readU64LE(data, off));
+    off += 8;
+    windowStartTimestamp.push(readI64LE(data, off));
+    off += 8;
+    selloffVbSnapshot.push(readU64LE(data, off));
+    off += 8; // AssetDynamics.selloff_vb_snapshot
+
+    // Fail loudly rather than silently sliding every later field if the
+    // slot layout ever drifts again.
+    if (off - slotStart !== TOKEN_SLOT_LEN) {
+      throw new Error(
+        `decodePoolAccount: TokenSlot ${i} consumed ${off - slotStart} bytes, expected ${TOKEN_SLOT_LEN}`,
+      );
+    }
+  }
+
+  const lookupTable = readPubkey(data, off);
+  off += 32;
+
+  // Effective per-pool Token-2022 banned-extensions bitmap (carved out of
+  // the old reserved[32]; pre-upgrade pools read 0).
+  const bannedExtensions = readU64LE(data, off);
+  off += 8;
+
+  // v5.1: two u32s carved out of the trailing reserved blob, which shrank
+  // [u8;24] → [u8;16]. Pre-v5.1 pools read 0 (band disabled).
+  const rangeManagerMaxLeverageBps = data.readUInt32LE(off);
+  off += 4;
+  const rangeManagerMinLeverageBps = data.readUInt32LE(off);
+  off += 4;
+
+  // Preserve the trailing ABI padding after checking its exact offset.
+  if (off + 16 !== POOL_V4_LEN) {
+    throw new Error(
+      `decodePoolAccount: consumed ${off} bytes before reserved[16], ` +
+        `expected ${POOL_V4_LEN - 16}. Layout drift — regenerate this decoder.`,
+    );
+  }
+  const reserved = Buffer.from(data.subarray(off, off + 16));
+
+  return {
+    config,
+    bump,
+    tokenCount,
+    poolId,
+    swapFeeRate,
+    protocolFeeRate,
+    createdAt,
+    poolEnabled,
+    swapsEnabled,
+    poolAdmin,
+    pendingPoolAdmin,
+    rangeManager,
+    rangeManagerEnabled,
+    rangeManagerMaxVbChangePct,
+    rangeManagerMaxWeightChangePct,
+    rangeManagerMinUpdateIntervalSecs,
+    rangeManagerLastUpdated,
+    rangeManagerMaxLeverageBps,
+    rangeManagerMinLeverageBps,
+    tokenMints,
+    tokenPrograms,
+    normalizedWeights,
+    maxSelloffPct,
+    maxSelloffPeriodLength,
+    variableFeeThresholdPct,
+    variableFeeSlopeLowPct,
+    variableFeeSlopeHighPct,
+    variableFeeSlopeMidPct,
+    variableFeeKinkPct,
+    isActive,
+    virtualBalances,
+    actualBalances,
+    protocolFeesOwed,
+    previousSelloff,
+    currentSelloff,
+    windowStartTimestamp,
+    selloffVbSnapshot,
+    lookupTable,
+    bannedExtensions,
+    reserved,
+  };
+}
+
+function readPubkey(data: Buffer, off: number): PublicKey {
+  return new PublicKey(data.slice(off, off + 32));
+}
+
+function readU64LE(data: Buffer, off: number): BN {
+  return new BN(data.slice(off, off + 8), "le");
+}
+
+function readI64LE(data: Buffer, off: number): BN {
+  return new BN(data.subarray(off, off + 8), "le").fromTwos(64);
+}
+
+function readBool(data: Buffer, off: number): boolean {
+  const value = data.readUInt8(off);
+  if (value > 1) throw new Error(`decodePoolAccount: invalid Borsh bool ${value} at offset ${off}`);
+  return value === 1;
+}