@kestrelfi/lyc-sdk 1.0.1

package/dist/sdks/long-yield-carry/src/decoders/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MINT_TOKEN_REQUIRED_ACCOUNT_NAMES = exports.MINT_TOKEN_ACCOUNTS = exports.BURN_TOKEN_REQUIRED_ACCOUNT_NAMES = exports.BURN_TOKEN_ACCOUNTS = exports.listLycTopLevelInstructionNames = exports.parseLycProgramTransactionRecord = exports.decodeLycProgramTransactionWithDiagnostics = exports.decodeLycProgramTransaction = void 0;
+var decodeTransaction_1 = require("./decodeTransaction");
+Object.defineProperty(exports, "decodeLycProgramTransaction", { enumerable: true, get: function () { return decodeTransaction_1.decodeLycProgramTransaction; } });
+Object.defineProperty(exports, "decodeLycProgramTransactionWithDiagnostics", { enumerable: true, get: function () { return decodeTransaction_1.decodeLycProgramTransactionWithDiagnostics; } });
+Object.defineProperty(exports, "parseLycProgramTransactionRecord", { enumerable: true, get: function () { return decodeTransaction_1.parseLycProgramTransactionRecord; } });
+var lycInstructionNames_1 = require("./lycInstructionNames");
+Object.defineProperty(exports, "listLycTopLevelInstructionNames", { enumerable: true, get: function () { return lycInstructionNames_1.listLycTopLevelInstructionNames; } });
+var idlAccounts_1 = require("./idlAccounts");
+Object.defineProperty(exports, "BURN_TOKEN_ACCOUNTS", { enumerable: true, get: function () { return idlAccounts_1.BURN_TOKEN_ACCOUNTS; } });
+Object.defineProperty(exports, "BURN_TOKEN_REQUIRED_ACCOUNT_NAMES", { enumerable: true, get: function () { return idlAccounts_1.BURN_TOKEN_REQUIRED_ACCOUNT_NAMES; } });
+Object.defineProperty(exports, "MINT_TOKEN_ACCOUNTS", { enumerable: true, get: function () { return idlAccounts_1.MINT_TOKEN_ACCOUNTS; } });
+Object.defineProperty(exports, "MINT_TOKEN_REQUIRED_ACCOUNT_NAMES", { enumerable: true, get: function () { return idlAccounts_1.MINT_TOKEN_REQUIRED_ACCOUNT_NAMES; } });

package/dist/sdks/long-yield-carry/src/decoders/innerCpis.d.ts

@@ -0,0 +1,68 @@
+import type { InnerInstructionBlock, TokenBalanceRow, TxMeta } from "./transactionPayload";
+/** Resolve the inner-instructions block for a given top-level instruction. */
+export declare function findInnerInstructionBlock(meta: TxMeta, topLevelIndex: number): InnerInstructionBlock | undefined;
+/**
+ * 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 declare function splBurnAmountFromSource(keys: string[], block: InnerInstructionBlock, sourceAtaIndex: number): bigint | 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 declare function splMintToAmountToDest(keys: string[], block: InnerInstructionBlock, destAtaIndex: number): bigint | 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;
+}
+/**
+ * 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 declare function collectSplTransfersTo(keys: string[], block: InnerInstructionBlock, destAtaIndex: number): SplTransferSummary[];
+/**
+ * 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 declare function sumSplTransfersFromSource(keys: string[], block: InnerInstructionBlock, sourceAtaIndex: number): bigint;
+/**
+ * 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 declare function mintForAccountIndex(pre: TokenBalanceRow[] | undefined, post: TokenBalanceRow[] | undefined, accountIndex: number): string | 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 declare function aggregateCollateralTransfers(meta: TxMeta, transfers: SplTransferSummary[]): {
+    collateralMint: string;
+    amount: bigint;
+} | null;
+export {};

package/dist/sdks/long-yield-carry/src/decoders/innerCpis.js

@@ -0,0 +1,225 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findInnerInstructionBlock = findInnerInstructionBlock;
+exports.splBurnAmountFromSource = splBurnAmountFromSource;
+exports.splMintToAmountToDest = splMintToAmountToDest;
+exports.collectSplTransfersTo = collectSplTransfersTo;
+exports.sumSplTransfersFromSource = sumSplTransfersFromSource;
+exports.mintForAccountIndex = mintForAccountIndex;
+exports.aggregateCollateralTransfers = aggregateCollateralTransfers;
+const bs58_1 = __importDefault(require("bs58"));
+const token_1 = require("@solana-program/token");
+const token_2022_1 = require("@solana-program/token-2022");
+/**
+ * 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([token_1.TOKEN_PROGRAM_ADDRESS, token_2022_1.TOKEN_2022_PROGRAM_ADDRESS]);
+/**
+ * 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) {
+    let bytes;
+    try {
+        bytes = bs58_1.default.decode(ix.data);
+    }
+    catch {
+        return null;
+    }
+    if (bytes.length < 9)
+        return null;
+    const tag = bytes[0];
+    if (tag !== token_1.TokenInstruction.Transfer &&
+        tag !== token_1.TokenInstruction.TransferChecked &&
+        tag !== token_1.TokenInstruction.MintTo &&
+        tag !== token_1.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. */
+function findInnerInstructionBlock(meta, topLevelIndex) {
+    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]`.
+ */
+function splBurnAmountFromSource(keys, block, sourceAtaIndex) {
+    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 !== token_1.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]`.
+ */
+function splMintToAmountToDest(keys, block, destAtaIndex) {
+    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 !== token_1.TokenInstruction.MintTo)
+            continue;
+        if (parsed.amount <= 0n)
+            continue;
+        return parsed.amount;
+    }
+    return null;
+}
+function extractTransfer(keys, ix) {
+    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 === token_1.TokenInstruction.Transfer && ix.accounts.length >= 3) {
+        return {
+            sourceIndex: ix.accounts[0],
+            destIndex: ix.accounts[1],
+            amount: parsed.amount,
+            explicitMint: undefined,
+        };
+    }
+    if (parsed.tag === token_1.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.
+ */
+function collectSplTransfersTo(keys, block, destAtaIndex) {
+    const out = [];
+    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.
+ */
+function sumSplTransfersFromSource(keys, block, sourceAtaIndex) {
+    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.
+ */
+function mintForAccountIndex(pre, post, accountIndex) {
+    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.
+ */
+function aggregateCollateralTransfers(meta, transfers) {
+    const totals = new Map();
+    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 = 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 };
+}

package/dist/sdks/long-yield-carry/src/decoders/lycInstructionNames.d.ts

@@ -0,0 +1,6 @@
+import type { LycProgramTransactionRecord } from "./types";
+/**
+ * Top-level instructions that invoke the LYC program, in tx order.
+ * Returns `null` if the payload can't be parsed (missing meta/message).
+ */
+export declare function listLycTopLevelInstructionNames(record: LycProgramTransactionRecord): string[] | null;

package/dist/sdks/long-yield-carry/src/decoders/lycInstructionNames.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listLycTopLevelInstructionNames = listLycTopLevelInstructionNames;
+const decodeTransaction_1 = require("./decodeTransaction");
+const programIds_1 = require("./programIds");
+const solana_1 = require("./solana");
+/**
+ * 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 = {
+    "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) {
+    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).
+ */
+function listLycTopLevelInstructionNames(record) {
+    const parsed = (0, decodeTransaction_1.parseRecordPayload)(record);
+    if (!parsed)
+        return null;
+    const { keys, message } = parsed;
+    const names = [];
+    for (let i = 0; i < message.instructions.length; i++) {
+        const ix = message.instructions[i];
+        const programId = keys[ix.programIdIndex];
+        if (!programId || !programIds_1.LYC_PROGRAM_IDS.has(programId))
+            continue;
+        try {
+            names.push(lycInstructionNameFromData((0, solana_1.decodeInstructionData)(ix.data)));
+        }
+        catch {
+            names.push(`invalid_ix_data@${i}`);
+        }
+    }
+    return names;
+}

package/dist/sdks/long-yield-carry/src/decoders/programIds.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Deployed `long_yield_carry` program IDs (excludes unset prod placeholder in {@link PROGRAM_ID}).
+ */
+export declare const LYC_PROGRAM_IDS: Set<string>;

package/dist/sdks/long-yield-carry/src/decoders/programIds.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LYC_PROGRAM_IDS = void 0;
+const general_1 = require("../constants/general");
+const UNSET_PROGRAM_PLACEHOLDER = "11111111111111111111111111111111";
+/**
+ * Deployed `long_yield_carry` program IDs (excludes unset prod placeholder in {@link PROGRAM_ID}).
+ */
+exports.LYC_PROGRAM_IDS = new Set(Object.values(general_1.PROGRAM_ID)
+    .map((a) => String(a))
+    .filter((id) => id !== UNSET_PROGRAM_PLACEHOLDER));

package/dist/sdks/long-yield-carry/src/decoders/solana.d.ts

@@ -0,0 +1,7 @@
+import type { TxMessage, TxMeta } from "./transactionPayload";
+/**
+ * v0 message: static `accountKeys` + ALT-loaded writable addresses + readonly addresses.
+ */
+export declare function buildAccountKeys(message: TxMessage, meta: TxMeta): string[];
+export declare function decodeInstructionData(dataB58: string): Uint8Array;
+export declare function discriminatorMatches(data: Uint8Array, disc: Uint8Array): boolean;

package/dist/sdks/long-yield-carry/src/decoders/solana.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAccountKeys = buildAccountKeys;
+exports.decodeInstructionData = decodeInstructionData;
+exports.discriminatorMatches = discriminatorMatches;
+const bs58_1 = __importDefault(require("bs58"));
+/**
+ * v0 message: static `accountKeys` + ALT-loaded writable addresses + readonly addresses.
+ */
+function buildAccountKeys(message, meta) {
+    const staticKeys = message.accountKeys;
+    const loadedWritable = meta.loadedAddresses?.writable ?? [];
+    const loadedReadonly = meta.loadedAddresses?.readonly ?? [];
+    return [...staticKeys, ...loadedWritable, ...loadedReadonly];
+}
+function decodeInstructionData(dataB58) {
+    return bs58_1.default.decode(dataB58);
+}
+function discriminatorMatches(data, disc) {
+    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/dist/sdks/long-yield-carry/src/decoders/transactionPayload.d.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/dist/sdks/long-yield-carry/src/decoders/transactionPayload.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Wire shapes for streamed / RPC `getTransaction`-style payloads (Helius, etc.).
+ * Internal to the decoder — not part of the public queue contract ({@link LycProgramTransactionRecord}).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/sdks/long-yield-carry/src/decoders/types.d.ts

@@ -0,0 +1,58 @@
+/** 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/dist/sdks/long-yield-carry/src/decoders/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/sdks/long-yield-carry/src/errors.d.ts

@@ -0,0 +1,69 @@
+/** LYC program error when on-chain utilization guards block a carry update. */
+export declare const INVALID_UTILIZATION_RATE_CONDITION_CODE = 8020;
+/**
+ * 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 declare class NoOpTransactionError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare class NoInterestToCollectError extends NoOpTransactionError {
+    constructor(message: string);
+}
+/**
+ * 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 declare class LendingPositionBootstrapError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function lookupLycError(code: number): {
+    name: string;
+    msg: string;
+} | undefined;
+/**
+ * Parses a logged Anchor error from a simulation failure message or program log line.
+ */
+export declare function parseLoggedLycAnchorError(text: string): {
+    name: string;
+    code: number;
+    msg: string;
+} | undefined;
+/**
+ * Extracts an LYC program error code from a failed transaction, when present.
+ */
+export declare function extractLycErrorCode(err: unknown): number | undefined;
+/** True when a failed tx was rejected by an expected LYC guard (not an incident). */
+export declare function isSkippableLycTransactionError(err: unknown): boolean;
+/**
+ * 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 declare function formatTransactionError(errMessage: string): string;