@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

package/src/decoders/decodeTransaction.ts

@@ -1,319 +0,0 @@
-/**
- * Decoder: streamed Solana transaction payloads → normalized LYC user events.
- *
- * Wire shape is validator-style `getTransaction` data wrapped by the API into
- * {@link LycProgramTransactionRecord} when enqueued. Downstream consumers (the
- * indexer Lambda, backfill jobs) validate the envelope with
- * {@link parseLycProgramTransactionRecord} then call
- * {@link decodeLycProgramTransaction} to produce zero or more user-facing
- * {@link LycTransactionEvent}s.
- *
- * The set of indexed instructions is currently `mint_token` and `burn_token`.
- * Both are inlined in this module — if we ever add a third, promote back to a
- * registry/interface pattern.
- */
-
-import { BURN_TOKEN_DISCRIMINATOR, MINT_TOKEN_DISCRIMINATOR } from "./discriminators";
-import { BURN_TOKEN_ACCOUNTS, MINT_TOKEN_ACCOUNTS } from "./idlAccounts";
-import {
-  aggregateCollateralTransfers,
-  collectSplTransfersTo,
-  findInnerInstructionBlock,
-  splBurnAmountFromSource,
-  splMintToAmountToDest,
-  sumSplTransfersFromSource,
-} from "./innerCpis";
-import { LYC_PROGRAM_IDS } from "./programIds";
-import { buildAccountKeys, decodeInstructionData, discriminatorMatches } from "./solana";
-import type { TxMessage, TxMeta } from "./transactionPayload";
-import type { LycProgramTransactionRecord, LycTransactionEvent } from "./types";
-
-/**
- * Validate and narrow an arbitrary JSON body (SQS message body / API request)
- * to {@link LycProgramTransactionRecord}. Returns `null` on any shape mismatch.
- */
-export function parseLycProgramTransactionRecord(
-  input: unknown
-): LycProgramTransactionRecord | null {
-  if (!input || typeof input !== "object") return null;
-  const o = input as Record<string, unknown>;
-  if (o.source !== "lyc-program-transaction") return null;
-  if (typeof o.signature !== "string" || o.signature.length === 0) return null;
-  if (!("payload" in o)) return null;
-
-  return {
-    source: "lyc-program-transaction",
-    receivedAt: typeof o.receivedAt === "number" ? o.receivedAt : 0,
-    signature: o.signature,
-    slot: typeof o.slot === "number" ? o.slot : undefined,
-    payload: o.payload,
-  };
-}
-
-/**
- * Stable enum of why a matched-discriminator instruction produced no event.
- * All reasons are CPI-driven; none depend on balance deltas.
- */
-export type DecoderRejectionReason =
-  | "accounts_too_short"
-  | "missing_key"
-  | "no_inner_instructions_block"
-  | "no_token_burn_cpi"
-  | "no_token_mint_to_cpi"
-  | "no_collateral_out_delta"
-  | "no_collateral_in_delta";
-
-/**
- * One reason a tx produced zero events despite looking like something we index.
- *
- * - `payload_unparseable`: the envelope `payload` lacked `meta` / `transaction.message` and
- *   we couldn't even enumerate instructions.
- * - `instruction_data_invalid`: an LYC-program instruction's `data` field wasn't valid
- *   base58 so we couldn't read its discriminator.
- * - `decoder_rejected`: the discriminator matched a user-facing decoder but a guard rail
- *   returned null — `reason` identifies which guard.
- */
-export type DecodeRejection =
-  | { kind: "payload_unparseable" }
-  | { kind: "instruction_data_invalid"; instructionIndex: number }
-  | {
-      kind: "decoder_rejected";
-      name: "mint_token" | "burn_token";
-      reason: DecoderRejectionReason;
-    };
-
-export interface DecodeResult {
-  events: LycTransactionEvent[];
-  /**
-   * Non-empty only when something anomalous happened. Consumers that want to
-   * distinguish "refresh-only tx, nothing to do" from "tried and bailed" check
-   * `rejections.length === 0` for the former and `rejections.length > 0` for
-   * the latter.
-   */
-  rejections: DecodeRejection[];
-}
-
-/**
- * Decode one queued tx into zero or more user-facing events, in top-level
- * instruction order. Silently skips instructions we don't index or whose data
- * cannot be base58-decoded.
- */
-export function decodeLycProgramTransaction(
-  record: LycProgramTransactionRecord
-): LycTransactionEvent[] {
-  return decodeLycProgramTransactionWithDiagnostics(record).events;
-}
-
-/**
- * Same as {@link decodeLycProgramTransaction} but also returns structured
- * rejections for the indexer's CloudWatch log path. Use this when "zero events"
- * isn't enough information — e.g. you need to know whether a burn-shaped tx
- * bailed because its inner-instructions block was missing or because no
- * collateral transfer CPI landed in the user's ATA.
- */
-export function decodeLycProgramTransactionWithDiagnostics(
-  record: LycProgramTransactionRecord
-): DecodeResult {
-  const tx = parseRecordPayload(record);
-  if (!tx) {
-    return { events: [], rejections: [{ kind: "payload_unparseable" }] };
-  }
-
-  const events: LycTransactionEvent[] = [];
-  const rejections: DecodeRejection[] = [];
-
-  for (let i = 0; i < tx.message.instructions.length; i++) {
-    const ix = tx.message.instructions[i]!;
-    const programId = tx.keys[ix.programIdIndex];
-    if (!programId || !LYC_PROGRAM_IDS.has(programId)) continue;
-
-    let data: Uint8Array;
-    try {
-      data = decodeInstructionData(ix.data);
-    } catch {
-      rejections.push({ kind: "instruction_data_invalid", instructionIndex: i });
-      continue;
-    }
-
-    if (discriminatorMatches(data, MINT_TOKEN_DISCRIMINATOR)) {
-      const outcome = decodeMintToken(tx, ix.accounts, i);
-      if ("event" in outcome) events.push(outcome.event);
-      else
-        rejections.push({ kind: "decoder_rejected", name: "mint_token", reason: outcome.reason });
-    } else if (discriminatorMatches(data, BURN_TOKEN_DISCRIMINATOR)) {
-      const outcome = decodeBurnToken(tx, ix.accounts, i);
-      if ("event" in outcome) events.push(outcome.event);
-      else
-        rejections.push({ kind: "decoder_rejected", name: "burn_token", reason: outcome.reason });
-    }
-  }
-
-  return { events, rejections };
-}
-
-/**
- * Per-tx data shared by the mint/burn decoders and by
- * {@link listLycTopLevelInstructionNames} in the sibling module. Exported so
- * the names helper can reuse the parse work — not part of the public SDK.
- */
-export interface ParsedTx {
-  message: TxMessage;
-  meta: TxMeta;
-  signature: string;
-  slot: number;
-  blockTime: number;
-  fee: number;
-  /** Static + ALT-loaded account keys, in the index order used by instructions. */
-  keys: string[];
-}
-
-export function parseRecordPayload(record: LycProgramTransactionRecord): ParsedTx | null {
-  const payload = record.payload;
-  if (!payload || typeof payload !== "object") return null;
-
-  const p = payload as Record<string, unknown>;
-  const meta = p.meta as TxMeta | undefined;
-  const transaction = p.transaction as { message?: TxMessage } | undefined;
-  const message = transaction?.message;
-  if (!meta || !message?.accountKeys || !Array.isArray(message.instructions)) {
-    return null;
-  }
-
-  const slot =
-    typeof record.slot === "number" ? record.slot : typeof p.slot === "number" ? p.slot : 0;
-
-  return {
-    message,
-    meta,
-    signature: record.signature,
-    slot,
-    blockTime: typeof p.blockTime === "number" ? p.blockTime : 0,
-    fee: typeof meta.fee === "number" ? meta.fee : 0,
-    keys: buildAccountKeys(message, meta),
-  };
-}
-
-type DecoderOutcome = { event: LycTransactionEvent } | { reason: DecoderRejectionReason };
-
-/**
- * Authoritative reads: inner CPIs emitted by mint_token.
- *  - Token amount: SPL Token `MintTo` CPI whose `accounts[1]` (dest ATA)
- *    matches `user_token_account`. Amount is encoded in the ix data as a
- *    little-endian u64.
- *  - Collateral amount: sum of SPL Token `Transfer` / `TransferChecked`
- *    CPIs whose source matches `user_collateral_account`. The collateral
- *    mint is known structurally (`collateral_mint`), so we don't need to
- *    derive it per-transfer.
- *
- * Account positions are resolved by name from the IDL via
- * {@link MINT_TOKEN_ACCOUNTS} — resilient to account-list reordering, and
- * fail-fast at module load if a required account is renamed or removed.
- */
-function decodeMintToken(tx: ParsedTx, accounts: number[], ixIndex: number): DecoderOutcome {
-  const signerPos = MINT_TOKEN_ACCOUNTS.signer;
-  const mintPos = MINT_TOKEN_ACCOUNTS.mint;
-  const collateralMintPos = MINT_TOKEN_ACCOUNTS.collateral_mint;
-  const userCollateralAtaPos = MINT_TOKEN_ACCOUNTS.user_collateral_account;
-  const userTokenAtaPos = MINT_TOKEN_ACCOUNTS.user_token_account;
-
-  const maxPos = Math.max(
-    signerPos,
-    mintPos,
-    collateralMintPos,
-    userCollateralAtaPos,
-    userTokenAtaPos
-  );
-  if (accounts.length <= maxPos) return { reason: "accounts_too_short" };
-
-  const wallet = tx.keys[accounts[signerPos]];
-  const tokenMint = tx.keys[accounts[mintPos]];
-  const collateralMint = tx.keys[accounts[collateralMintPos]];
-  if (!wallet || !tokenMint || !collateralMint) return { reason: "missing_key" };
-
-  const block = findInnerInstructionBlock(tx.meta, ixIndex);
-  if (!block) return { reason: "no_inner_instructions_block" };
-
-  const mintedAmount = splMintToAmountToDest(tx.keys, block, accounts[userTokenAtaPos]);
-  if (mintedAmount === null) return { reason: "no_token_mint_to_cpi" };
-
-  const collateralAmount = sumSplTransfersFromSource(
-    tx.keys,
-    block,
-    accounts[userCollateralAtaPos]
-  );
-  if (collateralAmount <= 0n) return { reason: "no_collateral_in_delta" };
-
-  return {
-    event: {
-      signature: tx.signature,
-      slot: tx.slot,
-      blockTime: tx.blockTime,
-      type: "mint",
-      wallet,
-      tokenMint,
-      tokenAmountBaseUnits: mintedAmount.toString(),
-      collateralMint,
-      collateralAmountBaseUnits: collateralAmount.toString(),
-      fee: tx.fee,
-    },
-  };
-}
-
-/**
- * Authoritative reads: inner CPIs emitted by burn_token.
- *  - Token amount: SPL Token `Burn` CPI whose `accounts[0]` (source ATA)
- *    matches `user_token_account`. Amount is encoded in the ix data as a
- *    little-endian u64, not derived from a balance delta.
- *  - Collateral: SPL Token `Transfer` / `TransferChecked` CPIs whose
- *    destination matches `user_collateral_account`. Amounts are summed per
- *    mint; the dominant mint wins — in practice the Rust program emits a
- *    single transfer with a single mint, so the aggregation step is defensive
- *    (see `rust/.../burn_token.rs`).
- *
- * CPI-authoritative decoding does not depend on whether the user's collateral
- * ATA persists across the tx — created-and-closed-same-tx ATAs, pre-existing
- * ATAs closed at the end, and ATAs re-funded inside the same tx all decode
- * identically because the CPIs themselves never disappear.
- *
- * Account positions are resolved by name from the IDL via
- * {@link BURN_TOKEN_ACCOUNTS} — resilient to account-list reordering, and
- * fail-fast at module load if a required account is renamed or removed.
- */
-function decodeBurnToken(tx: ParsedTx, accounts: number[], ixIndex: number): DecoderOutcome {
-  const signerPos = BURN_TOKEN_ACCOUNTS.signer;
-  const mintPos = BURN_TOKEN_ACCOUNTS.mint;
-  const userTokenAtaPos = BURN_TOKEN_ACCOUNTS.user_token_account;
-  const userCollateralAtaPos = BURN_TOKEN_ACCOUNTS.user_collateral_account;
-
-  const maxPos = Math.max(signerPos, mintPos, userTokenAtaPos, userCollateralAtaPos);
-  if (accounts.length <= maxPos) return { reason: "accounts_too_short" };
-
-  const wallet = tx.keys[accounts[signerPos]];
-  const tokenMint = tx.keys[accounts[mintPos]];
-  if (!wallet || !tokenMint) return { reason: "missing_key" };
-
-  const block = findInnerInstructionBlock(tx.meta, ixIndex);
-  if (!block) return { reason: "no_inner_instructions_block" };
-
-  const burnedAmount = splBurnAmountFromSource(tx.keys, block, accounts[userTokenAtaPos]);
-  if (burnedAmount === null) return { reason: "no_token_burn_cpi" };
-
-  const transfers = collectSplTransfersTo(tx.keys, block, accounts[userCollateralAtaPos]);
-  const collateral = aggregateCollateralTransfers(tx.meta, transfers);
-  if (!collateral) return { reason: "no_collateral_out_delta" };
-
-  return {
-    event: {
-      signature: tx.signature,
-      slot: tx.slot,
-      blockTime: tx.blockTime,
-      type: "burn",
-      wallet,
-      tokenMint,
-      tokenAmountBaseUnits: burnedAmount.toString(),
-      collateralMint: collateral.collateralMint,
-      collateralAmountBaseUnits: collateral.amount.toString(),
-      fee: tx.fee,
-    },
-  };
-}

package/src/decoders/discriminators.ts

@@ -1,10 +0,0 @@
-/**
- * Anchor 8-byte instruction discriminators (see `idl/long_yield_carry.ts`).
- * Add new entries here when supporting additional indexed instructions.
- */
-
-/** `burn_token` */
-export const BURN_TOKEN_DISCRIMINATOR = Uint8Array.from([185, 165, 216, 246, 144, 31, 70, 74]);
-
-/** `mint_token` */
-export const MINT_TOKEN_DISCRIMINATOR = Uint8Array.from([172, 137, 183, 14, 207, 110, 234, 56]);

package/src/decoders/idlAccounts.ts

@@ -1,75 +0,0 @@
-/**
- * IDL-backed account resolution for the LYC decoder.
- *
- * The decoder reads specific accounts (wallet, mint, collateral mint, user
- * ATAs) out of each indexed instruction's account list. Rather than hardcoding
- * positional indices — which silently break if the on-chain
- * `#[derive(Accounts)]` struct is ever reordered — we resolve positions by
- * account name off the SDK's shipped IDL at module load.
- *
- * Guarantees:
- *  - **Resilient to reordering.** If the Rust program reorders accounts, the
- *    regenerated IDL updates the name→index map and the decoder follows.
- *  - **Fail-fast on rename/removal.** If an account we depend on is renamed
- *    or removed, this module throws at import time — the SDK fails to load
- *    instead of producing mislabeled events.
- *  - **Minimal surface.** Only pins the accounts the decoder actually reads
- *    (`signer`, `mint`, `collateral_mint`, `user_token_account`,
- *    `user_collateral_account`). Unused accounts can be renamed freely.
- */
-
-import { IDL } from "../idl/long_yield_carry";
-
-const MINT_TOKEN_REQUIRED_ACCOUNT_NAMES = [
-  "signer",
-  "mint",
-  "collateral_mint",
-  "user_collateral_account",
-  "user_token_account",
-] as const;
-
-const BURN_TOKEN_REQUIRED_ACCOUNT_NAMES = [
-  "signer",
-  "mint",
-  "user_token_account",
-  "user_collateral_account",
-] as const;
-
-type MintTokenAccountName = (typeof MINT_TOKEN_REQUIRED_ACCOUNT_NAMES)[number];
-type BurnTokenAccountName = (typeof BURN_TOKEN_REQUIRED_ACCOUNT_NAMES)[number];
-
-function buildAccountIndexMap<const T extends readonly string[]>(
-  instructionName: string,
-  requiredNames: T
-): Readonly<Record<T[number], number>> {
-  const ix = IDL.instructions.find((entry) => entry.name === instructionName);
-  if (!ix) {
-    throw new Error(`IDL account resolver: instruction "${instructionName}" not found`);
-  }
-  const map: Record<string, number> = {};
-  for (const name of requiredNames) {
-    const idx = ix.accounts.findIndex((a) => a.name === name);
-    if (idx < 0) {
-      throw new Error(
-        `IDL account resolver: instruction "${instructionName}" is missing account "${name}"`
-      );
-    }
-    map[name] = idx;
-  }
-  return Object.freeze(map) as Readonly<Record<T[number], number>>;
-}
-
-/** Name→index map for the accounts list of `mint_token`. */
-export const MINT_TOKEN_ACCOUNTS = buildAccountIndexMap(
-  "mint_token",
-  MINT_TOKEN_REQUIRED_ACCOUNT_NAMES
-);
-
-/** Name→index map for the accounts list of `burn_token`. */
-export const BURN_TOKEN_ACCOUNTS = buildAccountIndexMap(
-  "burn_token",
-  BURN_TOKEN_REQUIRED_ACCOUNT_NAMES
-);
-
-export { MINT_TOKEN_REQUIRED_ACCOUNT_NAMES, BURN_TOKEN_REQUIRED_ACCOUNT_NAMES };
-export type { MintTokenAccountName, BurnTokenAccountName };

package/src/decoders/index.ts

@@ -1,15 +0,0 @@
-export type { LycProgramTransactionRecord, LycTransactionEvent, LycTransactionType } from "./types";
-export {
-  decodeLycProgramTransaction,
-  decodeLycProgramTransactionWithDiagnostics,
-  parseLycProgramTransactionRecord,
-} from "./decodeTransaction";
-export type { DecodeRejection, DecodeResult, DecoderRejectionReason } from "./decodeTransaction";
-export { listLycTopLevelInstructionNames } from "./lycInstructionNames";
-export {
-  BURN_TOKEN_ACCOUNTS,
-  BURN_TOKEN_REQUIRED_ACCOUNT_NAMES,
-  MINT_TOKEN_ACCOUNTS,
-  MINT_TOKEN_REQUIRED_ACCOUNT_NAMES,
-} from "./idlAccounts";
-export type { BurnTokenAccountName, MintTokenAccountName } from "./idlAccounts";

package/src/decoders/innerCpis.ts

@@ -1,262 +0,0 @@
-import bs58 from "bs58";
-import { TOKEN_PROGRAM_ADDRESS, TokenInstruction } from "@solana-program/token";
-import { TOKEN_2022_PROGRAM_ADDRESS } from "@solana-program/token-2022";
-
-import type {
-  CompiledInstruction,
-  InnerInstructionBlock,
-  TokenBalanceRow,
-  TxMeta,
-} from "./transactionPayload";
-
-/**
- * Inner-instruction (CPI) scanning primitives for the decoder.
- *
- * The decoder reads LYC user events off the on-chain CPIs the program emits,
- * not off net balance deltas. A `burn_token` top-level ix is decoded by finding
- * the SPL Token `Burn` CPI (for the token amount) and the SPL Token
- * `Transfer` / `TransferChecked` CPIs to the user's collateral ATA (for the
- * collateral amount + mint) inside the burn ix's inner-instructions block.
- *
- * Reading CPIs is robust to ATA lifecycle quirks (created + closed in the same
- * tx, wrap + unwrap side effects, etc.) because the CPIs are the actions that
- * actually happened — balance rows are just their net effect and can be hidden
- * or confounded by other same-tx ixs.
- *
- * Program IDs come from {@link TOKEN_PROGRAM_ADDRESS} / {@link TOKEN_2022_PROGRAM_ADDRESS}
- * (kit-aligned `@solana-program/*` clients). Instruction tags use {@link TokenInstruction}
- * — Token-2022 shares the same numeric tags for Transfer / TransferChecked / MintTo / Burn.
- */
-
-const SPL_TOKEN_PROGRAM_IDS = new Set<string>([TOKEN_PROGRAM_ADDRESS, TOKEN_2022_PROGRAM_ADDRESS]);
-
-interface ParsedSplIx {
-  tag: number;
-  amount: bigint;
-}
-
-/**
- * Decode an SPL Token ix and extract its tag + u64 amount, if the tag is one
- * we care about (Transfer, TransferChecked, MintTo, Burn). Returns null for
- * any other variant (approve, close, sync native, etc.) or for malformed data.
- *
- * Layout (all little-endian):
- *  - Transfer:        `[3, amount:u64]`                       (9 bytes)
- *  - MintTo:          `[7, amount:u64]`                       (9 bytes)
- *  - Burn:            `[8, amount:u64]`                       (9 bytes)
- *  - TransferChecked: `[12, amount:u64, decimals:u8]`         (10 bytes)
- */
-function parseSplAmountIx(ix: CompiledInstruction): ParsedSplIx | null {
-  let bytes: Uint8Array;
-  try {
-    bytes = bs58.decode(ix.data);
-  } catch {
-    return null;
-  }
-  if (bytes.length < 9) return null;
-  const tag = bytes[0];
-  if (
-    tag !== TokenInstruction.Transfer &&
-    tag !== TokenInstruction.TransferChecked &&
-    tag !== TokenInstruction.MintTo &&
-    tag !== TokenInstruction.Burn
-  ) {
-    return null;
-  }
-  let amount = 0n;
-  for (let i = 0; i < 8; i++) {
-    amount |= BigInt(bytes[1 + i]) << BigInt(i * 8);
-  }
-  return { tag, amount };
-}
-
-/** Resolve the inner-instructions block for a given top-level instruction. */
-export function findInnerInstructionBlock(
-  meta: TxMeta,
-  topLevelIndex: number
-): InnerInstructionBlock | undefined {
-  return meta.innerInstructions?.find((b) => b.index === topLevelIndex);
-}
-
-/**
- * Find the SPL Token `Burn` CPI whose source token account matches
- * `sourceAtaIndex` and return its amount. Tx-level account indexes are shared
- * between outer and inner instructions, so callers resolve the source by
- * outer IDL-named account (e.g. `burn_token.user_token_account`) and we match
- * against `burn.accounts[0]` here.
- *
- * `Burn` account layout: `[source_ata, mint, authority, ...signers]`.
- */
-export function splBurnAmountFromSource(
-  keys: string[],
-  block: InnerInstructionBlock,
-  sourceAtaIndex: number
-): bigint | null {
-  for (const ix of block.instructions) {
-    if (!SPL_TOKEN_PROGRAM_IDS.has(keys[ix.programIdIndex] ?? "")) continue;
-    if (ix.accounts.length < 3 || ix.accounts[0] !== sourceAtaIndex) continue;
-    const parsed = parseSplAmountIx(ix);
-    if (parsed?.tag !== TokenInstruction.Burn) continue;
-    if (parsed.amount <= 0n) continue;
-    return parsed.amount;
-  }
-  return null;
-}
-
-/**
- * Find the SPL Token `MintTo` CPI whose destination ATA matches `destAtaIndex`
- * and return its amount. The mint slot (`MintTo.accounts[0]`) is not checked:
- * an ATA has a fixed mint, so a MintTo landing in the right ATA cannot be for
- * any other mint — the on-chain SPL program rejects mismatches.
- *
- * `MintTo` account layout: `[mint, dest_ata, authority, ...signers]`.
- */
-export function splMintToAmountToDest(
-  keys: string[],
-  block: InnerInstructionBlock,
-  destAtaIndex: number
-): bigint | null {
-  for (const ix of block.instructions) {
-    if (!SPL_TOKEN_PROGRAM_IDS.has(keys[ix.programIdIndex] ?? "")) continue;
-    if (ix.accounts.length < 3 || ix.accounts[1] !== destAtaIndex) continue;
-    const parsed = parseSplAmountIx(ix);
-    if (parsed?.tag !== TokenInstruction.MintTo) continue;
-    if (parsed.amount <= 0n) continue;
-    return parsed.amount;
-  }
-  return null;
-}
-
-interface SplTransferSummary {
-  sourceIndex: number;
-  destIndex: number;
-  amount: bigint;
-  /**
-   * For `TransferChecked` the mint sits in the ix's `accounts[1]`, so we can
-   * pin it down without consulting the balance-row table. Plain `Transfer`
-   * leaves this undefined — callers fall back to {@link mintForAccountIndex}.
-   */
-  explicitMint: string | undefined;
-}
-
-function extractTransfer(keys: string[], ix: CompiledInstruction): SplTransferSummary | null {
-  if (!SPL_TOKEN_PROGRAM_IDS.has(keys[ix.programIdIndex] ?? "")) return null;
-  const parsed = parseSplAmountIx(ix);
-  if (!parsed) return null;
-  if (parsed.amount <= 0n) return null;
-
-  if (parsed.tag === TokenInstruction.Transfer && ix.accounts.length >= 3) {
-    return {
-      sourceIndex: ix.accounts[0],
-      destIndex: ix.accounts[1],
-      amount: parsed.amount,
-      explicitMint: undefined,
-    };
-  }
-  if (parsed.tag === TokenInstruction.TransferChecked && ix.accounts.length >= 4) {
-    return {
-      sourceIndex: ix.accounts[0],
-      destIndex: ix.accounts[2],
-      amount: parsed.amount,
-      explicitMint: keys[ix.accounts[1]] ?? undefined,
-    };
-  }
-  return null;
-}
-
-/**
- * Collect every SPL Token `Transfer` / `TransferChecked` CPI in the given inner
- * block whose destination matches `destAtaIndex`. Multiple transfers (e.g. fees
- * split across two CPIs, managed-unwind returning partial then final amounts)
- * are returned as-is so callers can aggregate per mint.
- */
-export function collectSplTransfersTo(
-  keys: string[],
-  block: InnerInstructionBlock,
-  destAtaIndex: number
-): SplTransferSummary[] {
-  const out: SplTransferSummary[] = [];
-  for (const ix of block.instructions) {
-    const summary = extractTransfer(keys, ix);
-    if (summary && summary.destIndex === destAtaIndex) {
-      out.push(summary);
-    }
-  }
-  return out;
-}
-
-/**
- * Sum the amounts of every SPL Token `Transfer` / `TransferChecked` CPI in the
- * given inner block whose source matches `sourceAtaIndex`. Returns 0n if none.
- *
- * Used by `decodeMintToken` to total the collateral moved out of the user's
- * collateral ATA. The collateral mint is known structurally from the IDL
- * (`mint_token.collateral_mint`), so we don't need to track per-transfer mints.
- */
-export function sumSplTransfersFromSource(
-  keys: string[],
-  block: InnerInstructionBlock,
-  sourceAtaIndex: number
-): bigint {
-  let total = 0n;
-  for (const ix of block.instructions) {
-    const summary = extractTransfer(keys, ix);
-    if (summary && summary.sourceIndex === sourceAtaIndex) {
-      total += summary.amount;
-    }
-  }
-  return total;
-}
-
-/**
- * Look up the mint a token account was holding by finding any row in pre/post
- * balances with the matching `accountIndex`. Used when a plain `Transfer` CPI
- * doesn't carry the mint in-line — we read it off the counterparty's row.
- */
-export function mintForAccountIndex(
-  pre: TokenBalanceRow[] | undefined,
-  post: TokenBalanceRow[] | undefined,
-  accountIndex: number
-): string | null {
-  for (const row of pre ?? []) {
-    if (row.accountIndex === accountIndex) return row.mint;
-  }
-  for (const row of post ?? []) {
-    if (row.accountIndex === accountIndex) return row.mint;
-  }
-  return null;
-}
-
-/**
- * Given the inner-instruction transfers that delivered collateral to the user's
- * collateral ATA, resolve (mint, amount) per mint and return the largest.
- *
- * Multi-mint returns (dust + primary) are possible in managed-unwind paths; we
- * pick the dominant mint rather than summing across mints so the event's
- * `collateralMint` remains a single string that matches the user's intent.
- */
-export function aggregateCollateralTransfers(
-  meta: TxMeta,
-  transfers: SplTransferSummary[]
-): { collateralMint: string; amount: bigint } | null {
-  const totals = new Map<string, bigint>();
-  for (const t of transfers) {
-    const mint =
-      t.explicitMint ??
-      mintForAccountIndex(meta.preTokenBalances, meta.postTokenBalances, t.sourceIndex) ??
-      mintForAccountIndex(meta.preTokenBalances, meta.postTokenBalances, t.destIndex);
-    if (!mint) continue;
-    totals.set(mint, (totals.get(mint) ?? 0n) + t.amount);
-  }
-
-  let bestMint: string | null = null;
-  let bestAmt = 0n;
-  for (const [mint, amt] of totals) {
-    if (amt > bestAmt) {
-      bestAmt = amt;
-      bestMint = mint;
-    }
-  }
-  if (bestMint === null || bestAmt <= 0n) return null;
-  return { collateralMint: bestMint, amount: bestAmt };
-}