@kestrelfi/lyc-sdk 1.0.1

package/dist/sdks/long-yield-carry/src/errors.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LendingPositionBootstrapError = exports.NoInterestToCollectError = exports.NoOpTransactionError = exports.INVALID_UTILIZATION_RATE_CONDITION_CODE = void 0;
+exports.lookupLycError = lookupLycError;
+exports.parseLoggedLycAnchorError = parseLoggedLycAnchorError;
+exports.extractLycErrorCode = extractLycErrorCode;
+exports.isSkippableLycTransactionError = isSkippableLycTransactionError;
+exports.formatTransactionError = formatTransactionError;
+const common_1 = require("common");
+const long_yield_carry_1 = require("./idl/long_yield_carry");
+/** LYC program error when on-chain utilization guards block a carry update. */
+exports.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([exports.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.
+ */
+class NoOpTransactionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NoOpTransactionError";
+    }
+}
+exports.NoOpTransactionError = 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.
+ */
+class NoInterestToCollectError extends NoOpTransactionError {
+    constructor(message) {
+        super(message);
+        this.name = "NoInterestToCollectError";
+    }
+}
+exports.NoInterestToCollectError = 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.
+ */
+class LendingPositionBootstrapError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LendingPositionBootstrapError";
+    }
+}
+exports.LendingPositionBootstrapError = LendingPositionBootstrapError;
+const LYC_ERROR_MAP = new Map();
+for (const entry of long_yield_carry_1.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).
+ */
+function lookupLycError(code) {
+    return LYC_ERROR_MAP.get(code);
+}
+/**
+ * Parses a logged Anchor error from a simulation failure message or program log line.
+ */
+function parseLoggedLycAnchorError(text) {
+    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.
+ */
+function extractLycErrorCode(err) {
+    if (err instanceof common_1.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). */
+function isSkippableLycTransactionError(err) {
+    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.
+ */
+function formatTransactionError(errMessage) {
+    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) {
+    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(/\.$/, ""),
+    };
+}