@kestrelfi/lyc-sdk 1.0.1

package/src/decoders/lycInstructionNames.ts

@@ -0,0 +1,73 @@
+import { parseRecordPayload } from "./decodeTransaction";
+import { LYC_PROGRAM_IDS } from "./programIds";
+import { decodeInstructionData } from "./solana";
+import type { LycProgramTransactionRecord } from "./types";
+
+/**
+ * Anchor instruction discriminators → camelCase names (from
+ * `idl/long_yield_carry.ts` instructions tuple). Update when the IDL changes
+ * (`npm run copy:idl`). Used only to populate the indexer's diagnostic
+ * `instructionNames` column for the API's transaction-history response.
+ */
+const LYC_INSTRUCTION_DISCRIMINATOR_TO_NAME: Readonly<Record<string, string>> = {
+  "185,165,216,246,144,31,70,74": "burnToken",
+  "79,126,77,51,253,163,193,248": "claimIncentives",
+  "164,152,207,99,30,186,19,182": "collectFees",
+  "238,101,253,86,160,25,16,134": "collectInterest",
+  "84,52,204,228,24,140,234,75": "createToken",
+  "32,13,223,159,125,144,219,148": "createTokenLendingPosition",
+  "123,125,211,195,102,102,90,7": "createYieldingBank",
+  "213,191,99,159,78,2,87,126": "createYieldingBankAllocation",
+  "109,115,98,62,206,179,42,145": "decreaseCarryPosition",
+  "112,210,209,249,61,231,192,207": "depositUnlentCollateral",
+  "216,191,255,166,144,169,3,187": "increaseCarryPosition",
+  "172,137,183,14,207,110,234,56": "mintToken",
+  "152,98,123,66,134,191,199,73": "rebalanceToken",
+  "181,53,252,136,138,104,145,137": "rebalanceYieldingBank",
+  "98,11,43,3,199,227,100,112": "recollateralizeLoss",
+  "229,167,209,155,223,252,150,188": "refreshTokenState",
+  "234,183,180,72,113,250,213,76": "refreshYieldingBank",
+  "152,222,104,180,163,231,152,77": "resetTokenBurnRateLimit",
+  "123,100,170,97,214,192,245,151": "setTokenCircuitBreaker",
+  "25,188,1,254,63,110,168,255": "setYieldingBankCircuitBreaker",
+  "164,56,56,248,51,167,213,96": "updateLendingPositionConfig",
+  "115,111,91,203,143,224,71,136": "updateTokenConfiguration",
+  "243,6,8,23,126,181,251,158": "updateTokenMetadata",
+  "236,3,226,53,30,160,216,24": "updateYieldingBankConfig",
+};
+
+function lycInstructionNameFromData(data: Uint8Array): string {
+  if (data.length < 8) return "truncated_instruction_data";
+  let key = "";
+  for (let i = 0; i < 8; i++) {
+    if (i > 0) key += ",";
+    key += data[i];
+  }
+  return LYC_INSTRUCTION_DISCRIMINATOR_TO_NAME[key] ?? `unknown_discriminator(${key})`;
+}
+
+/**
+ * Top-level instructions that invoke the LYC program, in tx order.
+ * Returns `null` if the payload can't be parsed (missing meta/message).
+ */
+export function listLycTopLevelInstructionNames(
+  record: LycProgramTransactionRecord
+): string[] | null {
+  const parsed = parseRecordPayload(record);
+  if (!parsed) return null;
+
+  const { keys, message } = parsed;
+  const names: string[] = [];
+  for (let i = 0; i < message.instructions.length; i++) {
+    const ix = message.instructions[i]!;
+    const programId = keys[ix.programIdIndex];
+    if (!programId || !LYC_PROGRAM_IDS.has(programId)) continue;
+
+    try {
+      names.push(lycInstructionNameFromData(decodeInstructionData(ix.data)));
+    } catch {
+      names.push(`invalid_ix_data@${i}`);
+    }
+  }
+  return names;
+}

package/src/decoders/programIds.ts

@@ -0,0 +1,12 @@
+import { PROGRAM_ID } from "../constants/general";
+
+const UNSET_PROGRAM_PLACEHOLDER = "11111111111111111111111111111111";
+
+/**
+ * Deployed `long_yield_carry` program IDs (excludes unset prod placeholder in {@link PROGRAM_ID}).
+ */
+export const LYC_PROGRAM_IDS = new Set<string>(
+  Object.values(PROGRAM_ID)
+    .map((a) => String(a))
+    .filter((id) => id !== UNSET_PROGRAM_PLACEHOLDER)
+);

package/src/decoders/solana.ts

@@ -0,0 +1,25 @@
+import bs58 from "bs58";
+
+import type { TxMessage, TxMeta } from "./transactionPayload";
+
+/**
+ * v0 message: static `accountKeys` + ALT-loaded writable addresses + readonly addresses.
+ */
+export function buildAccountKeys(message: TxMessage, meta: TxMeta): string[] {
+  const staticKeys = message.accountKeys;
+  const loadedWritable = meta.loadedAddresses?.writable ?? [];
+  const loadedReadonly = meta.loadedAddresses?.readonly ?? [];
+  return [...staticKeys, ...loadedWritable, ...loadedReadonly];
+}
+
+export function decodeInstructionData(dataB58: string): Uint8Array {
+  return bs58.decode(dataB58);
+}
+
+export function discriminatorMatches(data: Uint8Array, disc: Uint8Array): boolean {
+  if (data.length < disc.length) return false;
+  for (let i = 0; i < disc.length; i++) {
+    if (data[i] !== disc[i]) return false;
+  }
+  return true;
+}

package/src/decoders/transactionPayload.ts

@@ -0,0 +1,41 @@
+/**
+ * Wire shapes for streamed / RPC `getTransaction`-style payloads (Helius, etc.).
+ * Internal to the decoder — not part of the public queue contract ({@link LycProgramTransactionRecord}).
+ */
+
+export interface TokenBalanceRow {
+  /** Present on RPC `meta.preTokenBalances` / `postTokenBalances` — needed for per-account deltas. */
+  accountIndex?: number;
+  owner: string;
+  mint: string;
+  uiTokenAmount: { amount: string };
+}
+
+export interface CompiledInstruction {
+  accounts: number[];
+  data: string;
+  programIdIndex: number;
+}
+
+export interface TxMessage {
+  accountKeys: string[];
+  instructions: CompiledInstruction[];
+}
+
+/**
+ * RPC `meta.innerInstructions`: the CPI ixs emitted by each top-level ix,
+ * grouped by the top-level ix's position. Account indexes inside inner
+ * instructions share the same tx-level key space as outer ixs.
+ */
+export interface InnerInstructionBlock {
+  index: number;
+  instructions: CompiledInstruction[];
+}
+
+export interface TxMeta {
+  fee: number;
+  preTokenBalances?: TokenBalanceRow[];
+  postTokenBalances?: TokenBalanceRow[];
+  loadedAddresses?: { readonly?: string[]; writable?: string[] };
+  innerInstructions?: InnerInstructionBlock[];
+}

package/src/decoders/types.ts

@@ -0,0 +1,60 @@
+/** User-facing LYC transaction kinds we index. */
+export type LycTransactionType = "mint" | "burn";
+
+/**
+ * A single normalized LYC transaction event produced from a raw tx payload.
+ *
+ * A single Solana transaction can contain multiple top-level LYC instructions
+ * (e.g. `refresh_yielding_bank` + `decrease_carry_position` + `burn_token`),
+ * but only user-facing ones (`mint_token`, `burn_token`) surface here. Other
+ * LYC instructions in the same tx are infrastructure and are not indexed as
+ * user events.
+ */
+export interface LycTransactionEvent {
+  /** Solana transaction signature. */
+  signature: string;
+  /** Solana slot the tx was included in. */
+  slot: number;
+  /** Block time (unix seconds). */
+  blockTime: number;
+  /** Classified instruction kind. */
+  type: LycTransactionType;
+  /** User wallet: the tx signer for mint/burn (fee payer index 0). */
+  wallet: string;
+  /** Token mint minted into / burned from the user's token ATA. */
+  tokenMint: string;
+  /**
+   * Token base-unit amount.
+   * - `mint`: minted to the user (positive).
+   * - `burn`: burned from the user (positive).
+   */
+  tokenAmountBaseUnits: string;
+  /** Underlying collateral mint (e.g. wSOL when collateral is SOL). */
+  collateralMint: string;
+  /**
+   * Collateral base-unit amount moved to/from the user:
+   * - `mint`: collateral deposited by the user.
+   * - `burn`: collateral paid out to the user (net of fees).
+   */
+  collateralAmountBaseUnits: string;
+  /** Transaction fee in lamports paid by the signer. */
+  fee: number;
+}
+
+/**
+ * One LYC-program-related transaction we ingested and queued for indexing.
+ *
+ * `payload` is the raw Solana transaction object (slot, meta, transaction,
+ * version, etc.) — the same shape you get from `getTransaction` / streamed
+ * commitment updates. `source` discriminates this envelope from other queue
+ * producers if we add them later.
+ */
+export interface LycProgramTransactionRecord {
+  source: "lyc-program-transaction";
+  /** Unix seconds when our API accepted and wrapped the payload. */
+  receivedAt: number;
+  signature: string;
+  slot?: number;
+  /** Raw Solana tx + meta (RPC / stream shape). */
+  payload: unknown;
+}

package/src/errors.ts

@@ -0,0 +1,195 @@
+import { TransactionError } from "common";
+import { IDL } from "./idl/long_yield_carry";
+
+/** LYC program error when on-chain utilization guards block a carry update. */
+export const INVALID_UTILIZATION_RATE_CONDITION_CODE = 8020;
+
+/** LYC on-chain errors that represent expected no-ops, not operator failures. */
+const SKIPPABLE_LYC_ERROR_CODES = new Set<number>([INVALID_UTILIZATION_RATE_CONDITION_CODE]);
+
+/**
+ * Thrown when a tx builder receives inputs that make the operation a no-op
+ * (e.g. zero borrow amount, no yield to collect). Callers can catch this
+ * to distinguish "nothing to do" from genuine failures.
+ */
+export class NoOpTransactionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NoOpTransactionError";
+  }
+}
+
+/**
+ * Thrown when `collect_interest` has nothing meaningful to redeem or swap
+ * (no net carry yield, no matching carry slot, redeem rounds to zero, etc.).
+ *
+ * Extends {@link NoOpTransactionError} so batch jobs that skip no-ops via
+ * `instanceof NoOpTransactionError` continue to treat this as a skip.
+ */
+export class NoInterestToCollectError extends NoOpTransactionError {
+  constructor(message: string) {
+    super(message);
+    this.name = "NoInterestToCollectError";
+  }
+}
+
+/**
+ * Thrown when an initial lending position cannot be created because of a
+ * permanent configuration gap rather than a transient failure — e.g. the
+ * collateral mint is not listed in any lending pool, has no carry preset, or
+ * has no viable debt mint / reserve.
+ *
+ * Callers running on a tight schedule (e.g. the unlent-buffer worker) should
+ * catch this to **skip** the token instead of failing the task, which would
+ * otherwise retry every cycle and churn the DLQ until the config is fixed.
+ */
+export class LendingPositionBootstrapError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LendingPositionBootstrapError";
+  }
+}
+
+const LYC_ERROR_MAP = new Map<number, { name: string; msg: string }>();
+for (const entry of IDL.errors) {
+  LYC_ERROR_MAP.set(entry.code, { name: entry.name, msg: entry.msg });
+}
+
+/**
+ * Looks up an Anchor custom error code against the LYC program IDL.
+ * Returns the error name and message if found, or `undefined` for codes
+ * belonging to other programs (e.g. Kamino, SPL Token).
+ */
+export function lookupLycError(code: number): { name: string; msg: string } | undefined {
+  return LYC_ERROR_MAP.get(code);
+}
+
+/**
+ * Parses a logged Anchor error from a simulation failure message or program log line.
+ */
+export function parseLoggedLycAnchorError(
+  text: string
+): { name: string; code: number; msg: string } | undefined {
+  const match = text.match(
+    /Error Code:\s*([A-Za-z0-9_]+)\.\s*Error Number:\s*(\d+)\.\s*Error Message:\s*([^\n\r]*)/
+  );
+  if (!match) return undefined;
+
+  const code = parseInt(match[2], 10);
+  if (Number.isNaN(code) || !LYC_ERROR_MAP.has(code)) return undefined;
+
+  return {
+    name: match[1],
+    code,
+    msg: match[3].trim().replace(/\.$/, ""),
+  };
+}
+
+/**
+ * Extracts an LYC program error code from a failed transaction, when present.
+ */
+export function extractLycErrorCode(err: unknown): number | undefined {
+  if (err instanceof TransactionError) {
+    for (const line of err.programLogs) {
+      const parsed = parseLoggedLycAnchorError(line);
+      if (parsed) return parsed.code;
+    }
+  }
+
+  const message = err instanceof Error ? err.message : String(err);
+  const parsedFromMessage = parseLoggedLycAnchorError(message);
+  if (parsedFromMessage) return parsedFromMessage.code;
+
+  const jsonMatch = message.match(/\{.*"InstructionError".*\}/s);
+  if (!jsonMatch) return undefined;
+
+  try {
+    const parsed = JSON.parse(jsonMatch[0]);
+    const [, detail] = parsed.InstructionError;
+    if (detail?.Custom === undefined) return undefined;
+
+    const code = typeof detail.Custom === "string" ? parseInt(detail.Custom, 10) : detail.Custom;
+    return typeof code === "number" && !Number.isNaN(code) && LYC_ERROR_MAP.has(code)
+      ? code
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** True when a failed tx was rejected by an expected LYC guard (not an incident). */
+export function isSkippableLycTransactionError(err: unknown): boolean {
+  const code = extractLycErrorCode(err);
+  return code !== undefined && SKIPPABLE_LYC_ERROR_CODES.has(code);
+}
+
+/**
+ * Attempts to parse a Solana `InstructionError` from a transaction simulation
+ * failure message and returns a human-readable string.
+ *
+ * Handles formats like:
+ * - `Transaction simulation failed: {"InstructionError":["0",{"Custom":"6121"}]}`
+ * - `Transaction simulation failed: {"InstructionError":["1","ProgramFailedToComplete"]}`
+ *
+ * If the error contains a `Custom` code in the LYC IDL range, it's decoded to
+ * the program error name and message. Otherwise, the raw code or variant is
+ * included with a note that it may be from a CPI target program.
+ */
+export function formatTransactionError(errMessage: string): string {
+  const loggedAnchorError = parseLoggedAnchorError(errMessage);
+  const jsonMatch = errMessage.match(/\{.*"InstructionError".*\}/s);
+  if (!jsonMatch) {
+    return loggedAnchorError
+      ? `${loggedAnchorError.name} (${loggedAnchorError.code}) — ${loggedAnchorError.msg}`
+      : errMessage;
+  }
+
+  try {
+    const parsed = JSON.parse(jsonMatch[0]);
+    const [ixIndexRaw, detail] = parsed.InstructionError;
+    const ixIndex = typeof ixIndexRaw === "string" ? parseInt(ixIndexRaw, 10) : ixIndexRaw;
+
+    if (typeof detail === "string") {
+      return `ix[${ixIndex}]: ${detail}`;
+    }
+
+    if (detail?.Custom !== undefined) {
+      const code = typeof detail.Custom === "string" ? parseInt(detail.Custom, 10) : detail.Custom;
+      const matchingLoggedAnchorError =
+        loggedAnchorError?.code === code ? loggedAnchorError : undefined;
+      if (matchingLoggedAnchorError) {
+        return `ix[${ixIndex}]: ${matchingLoggedAnchorError.name} (${code}) — ${matchingLoggedAnchorError.msg}`;
+      }
+      const lycErr = lookupLycError(code);
+      if (lycErr) {
+        return `ix[${ixIndex}]: ${lycErr.name} (${code}) — ${lycErr.msg}`;
+      }
+      return `ix[${ixIndex}]: Custom error ${code} (from CPI target program)`;
+    }
+
+    return `ix[${ixIndex}]: ${JSON.stringify(detail)}`;
+  } catch {
+    return errMessage;
+  }
+}
+
+function parseLoggedAnchorError(
+  errMessage: string
+): { name: string; code: number; msg: string } | undefined {
+  const parsed = parseLoggedLycAnchorError(errMessage);
+  if (parsed) return parsed;
+
+  const match = errMessage.match(
+    /Error Code:\s*([A-Za-z0-9_]+)\.\s*Error Number:\s*(\d+)\.\s*Error Message:\s*([^\n\r]*)/
+  );
+  if (!match) return undefined;
+
+  const code = parseInt(match[2], 10);
+  if (Number.isNaN(code)) return undefined;
+
+  return {
+    name: match[1],
+    code,
+    msg: match[3].trim().replace(/\.$/, ""),
+  };
+}