@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

package/src/decoders/lycInstructionNames.ts

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

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

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

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

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

@@ -1,195 +0,0 @@
-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(/\.$/, ""),
-  };
-}