@kestrelfi/lyc-sdk 1.0.1

package/src/decoders/decodeTransaction.ts

@@ -0,0 +1,319 @@
+/**
+ * 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

@@ -0,0 +1,10 @@
+/**
+ * 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

@@ -0,0 +1,75 @@
+/**
+ * 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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,262 @@
+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 };
+}