@kestrelfi/lyc-sdk 1.0.1

package/dist/shared/common/src/utils/timeSeries.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findNearestSnapshot = findNearestSnapshot;
+exports.filterDailySnapshots = filterDailySnapshots;
+const SECONDS_PER_DAY = 86400;
+/**
+ * Binary-search for the snapshot closest to (but not after) `targetTimestamp`.
+ *
+ * Assumes `snapshots` are sorted ascending by timestamp.
+ * Returns `undefined` if no snapshot exists at or before the target.
+ */
+function findNearestSnapshot(snapshots, targetTimestamp) {
+    if (snapshots.length === 0)
+        return undefined;
+    let lo = 0;
+    let hi = snapshots.length - 1;
+    if (snapshots[lo].timestamp > targetTimestamp)
+        return undefined;
+    if (snapshots[hi].timestamp <= targetTimestamp)
+        return snapshots[hi];
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (snapshots[mid].timestamp <= targetTimestamp) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return snapshots[lo];
+}
+/**
+ * Filter to only midnight-UTC snapshots (one per day).
+ *
+ * Midnight snapshots have no DynamoDB TTL and are retained forever, producing
+ * a stable daily series that survives hourly data expiry.
+ */
+function filterDailySnapshots(snapshots) {
+    return snapshots.filter((s) => s.timestamp % SECONDS_PER_DAY === 0);
+}

package/dist/shared/common/src/utils/token.d.ts

@@ -0,0 +1,33 @@
+import { Address, KeyPairSigner, Rpc, SolanaRpcApi } from "@solana/kit";
+import { BN } from "@anchor-lang/core";
+import type { MintIdentifier } from "../types";
+import { type AnchorTokenProgram } from "../types/enums";
+/** Resolve a mint registry symbol or raw base58 address to a Kit {@link Address}. */
+export declare function resolveTokenMint(token: MintIdentifier): Address;
+/** Maps an `AnchorTokenProgram` value to its on-chain program address. */
+export declare function resolveTokenProgram(tp: AnchorTokenProgram): Address;
+/**
+ * Gets the token balance of an account (decimal-adjusted)
+ *
+ * @param tokenAccount - Token account to check
+ * @returns Balance as a number (adjusted for decimals, e.g., 1000 USDC not 1000000000)
+ */
+export declare function getTokenBalanceUi(rpc: Rpc<SolanaRpcApi>, tokenAccount: Address): Promise<number>;
+/**
+ * Gets the token balance of an account
+ *
+ * @param tokenAccount - Token account to check
+ * @returns Balance as a number in base units
+ */
+export declare function getTokenBalance(rpc: Rpc<SolanaRpcApi>, tokenAccount: Address): Promise<BN>;
+/**
+ * Creates a new token mint.
+ *
+ * @param rpc - Solana RPC client
+ * @param payer - Payer for account creation rent
+ * @param mintSigner - Keypair signer for the new mint account
+ * @param authority - Mint authority address (does not need to be a signer)
+ * @param decimals - Number of decimals for the mint
+ * @param tokenProgram - Token program (defaults to SPL Token)
+ */
+export declare function createMint(rpc: Rpc<SolanaRpcApi>, payer: KeyPairSigner, mintSigner: KeyPairSigner, authority: Address, decimals: number, tokenProgram?: Address): Promise<void>;

package/dist/shared/common/src/utils/token.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTokenMint = resolveTokenMint;
+exports.resolveTokenProgram = resolveTokenProgram;
+exports.getTokenBalanceUi = getTokenBalanceUi;
+exports.getTokenBalance = getTokenBalance;
+exports.createMint = createMint;
+const kit_1 = require("@solana/kit");
+const core_1 = require("@anchor-lang/core");
+const registry_1 = require("../services/mints/registry");
+const token_1 = require("@solana-program/token");
+const token_2022_1 = require("@solana-program/token-2022");
+const system_1 = require("@solana-program/system");
+const transaction_1 = require("./transaction");
+const enums_1 = require("../types/enums");
+/** Resolve a mint registry symbol or raw base58 address to a Kit {@link Address}. */
+function resolveTokenMint(token) {
+    const known = registry_1.mints.get(token);
+    if (known) {
+        return known.address;
+    }
+    return (0, kit_1.address)(token);
+}
+/** Maps an `AnchorTokenProgram` value to its on-chain program address. */
+function resolveTokenProgram(tp) {
+    return (0, enums_1.tokenProgramToEnum)(tp) === enums_1.TokenProgram.Spl
+        ? token_1.TOKEN_PROGRAM_ADDRESS
+        : token_2022_1.TOKEN_2022_PROGRAM_ADDRESS;
+}
+/**
+ * Gets the token balance of an account (decimal-adjusted)
+ *
+ * @param tokenAccount - Token account to check
+ * @returns Balance as a number (adjusted for decimals, e.g., 1000 USDC not 1000000000)
+ */
+async function getTokenBalanceUi(rpc, tokenAccount) {
+    const response = await rpc
+        .getTokenAccountBalance(tokenAccount, { commitment: "confirmed" })
+        .send();
+    return Number(response.value.uiAmount ?? 0);
+}
+/**
+ * Gets the token balance of an account
+ *
+ * @param tokenAccount - Token account to check
+ * @returns Balance as a number in base units
+ */
+async function getTokenBalance(rpc, tokenAccount) {
+    const response = await rpc
+        .getTokenAccountBalance(tokenAccount, { commitment: "confirmed" })
+        .send();
+    return new core_1.BN(response.value.amount);
+}
+/**
+ * Creates a new token mint.
+ *
+ * @param rpc - Solana RPC client
+ * @param payer - Payer for account creation rent
+ * @param mintSigner - Keypair signer for the new mint account
+ * @param authority - Mint authority address (does not need to be a signer)
+ * @param decimals - Number of decimals for the mint
+ * @param tokenProgram - Token program (defaults to SPL Token)
+ */
+async function createMint(rpc, payer, mintSigner, authority, decimals, tokenProgram = token_1.TOKEN_PROGRAM_ADDRESS) {
+    const space = (0, token_1.getMintSize)();
+    const rent = (await rpc.getMinimumBalanceForRentExemption(BigInt(space)).send());
+    const createAccountIx = (0, system_1.getCreateAccountInstruction)({
+        payer,
+        newAccount: mintSigner,
+        lamports: rent,
+        space,
+        programAddress: tokenProgram,
+    });
+    const initMintIx = (0, token_1.getInitializeMint2Instruction)({
+        mint: mintSigner.address,
+        decimals,
+        mintAuthority: authority,
+    });
+    await (0, transaction_1.signSendAndConfirmTransaction)(rpc, payer, [createAccountIx, initMintIx], {
+        additionalSigners: [mintSigner],
+    });
+}

package/dist/shared/common/src/utils/transaction.d.ts

@@ -0,0 +1,154 @@
+import type { Address, Blockhash, CompilableTransactionMessage, Instruction, Rpc, SolanaRpcApi, TransactionSigner, Signature } from "@solana/kit";
+import { PriorityFeeSetting } from "./priorityFee";
+/** Default headroom over simulated CU usage for typical operator transactions. */
+export declare const DEFAULT_COMPUTE_UNIT_LIMIT_MULTIPLIER = 1.1;
+/**
+ * Headroom for txs with deep CPI stacks (Jupiter + external liquidity mint/deposit).
+ * Simulation often undershoots on-chain usage by more than 10%.
+ */
+export declare const HEAVY_CPI_COMPUTE_UNIT_LIMIT_MULTIPLIER = 1.2;
+export declare function computeUnitLimitFromSimulation(unitsConsumed: number, multiplier?: number): number;
+/**
+ * Error thrown when a transaction simulation or on-chain execution fails.
+ * Carries the raw Solana program logs so callers (e.g. NestJS services)
+ * can log them through their own structured logger instead of dumping
+ * to stdout via `console.error`.
+ */
+export declare class TransactionError extends Error {
+    readonly programLogs: string[];
+    constructor(message: string, programLogs?: string[]);
+}
+/**
+ * Options for signSendAndConfirmTransaction.
+ */
+export interface SendTransactionOptions {
+    /** Address lookup tables for transaction compression */
+    lookupTables?: Address[];
+    /** Additional signers beyond the fee payer (e.g., mint authority) */
+    additionalSigners?: TransactionSigner[];
+    /** Whether or not to print transaction logs after a simulation or transaction failure */
+    hideFailureInfo?: boolean;
+    /**
+     * Jito tip in lamports for bundle submissions. Default: 10,000.
+     * Set to 0 to disable bundle fallback (throws on oversize instead).
+     */
+    jitoTipLamports?: number;
+    /**
+     * Force the Jito bundle path even when the transaction fits in a single tx.
+     * Useful for smoke-testing bundle submission on mainnet. Requires
+     * `jitoTipLamports` > 0 unless {@link sendOversizedAsSequentialTransactions}
+     * is set.
+     */
+    forceJitoBundle?: boolean;
+    /**
+     * When the oversize path runs, send each split transaction with normal
+     * `sendTransaction` + confirmation instead of a Jito bundle. For Surfpool,
+     * local validators, and other RPCs that do not implement `sendBundle`.
+     *
+     * Not atomic: ledger state may change between sub-transactions. Does not
+     * add a Jito tip (`jitoTipLamports` is ignored). Uses a fresh blockhash per
+     * sub-transaction so earlier confirmations cannot expire the next send.
+     */
+    sendOversizedAsSequentialTransactions?: boolean;
+    /**
+     * Override the estimated compute-unit price (in micro-lamports). When set,
+     * skips priority-fee estimation and uses this value directly.
+     */
+    computeUnitPriceMicroLamports?: number;
+    /**
+     * Helius-compatible priority level requested through the configured RPC.
+     * Explicit `computeUnitPriceMicroLamports` takes precedence. When both
+     * options are omitted, no compute-unit-price instruction is added.
+     */
+    priorityFeeSetting?: PriorityFeeSetting;
+    /**
+     * Multiplier applied to simulated `unitsConsumed` when setting the compute
+     * unit limit. Defaults to {@link DEFAULT_COMPUTE_UNIT_LIMIT_MULTIPLIER}.
+     */
+    computeUnitLimitMultiplier?: number;
+}
+export interface TransactionPlan {
+    instructions: Instruction[];
+    lookupTables?: Address[];
+    /**
+     * Partition of `instructions` into indivisible segments when splitting for
+     * wire size (Jito bundle or sequential oversize). Lengths must be positive
+     * and sum to `instructions.length`. Omitted or undefined: each instruction
+     * is its own segment (legacy `Instruction[]` behavior).
+     *
+     * Example: [1, 2, 3] means the first 1 instruction is in the first bin, the
+     * next 2 are in the second bin, and the last 3 are in the third bin.
+     *
+     * Use this to keep an atomic group together — e.g. a Kamino flash
+     * borrow/rebalance/repay triple, where the borrow's `flash_ixs.rs` check
+     * introspects its own tx's instructions sysvar to find the matching repay.
+     */
+    segmentLengths?: number[];
+    /**
+     * Indices into the segments produced by `segmentLengths` that must
+     * always start a fresh bin. The current bin (if any) is flushed before
+     * the segment is appended, regardless of whether it would have fit.
+     *
+     * Use this when a CPI in the segment encodes a position-relative index at
+     * build time (e.g. Kamino's flash-borrow records the position of the
+     * matching repay in its data) — forcing the segment to start a new bin
+     * keeps that index stable across runs.
+     */
+    freshBinSegments?: number[];
+}
+export type SendTransactionOptionsWithPostSuccess = SendTransactionOptions & {
+    onSuccess?: () => void;
+};
+/**
+ * Build a transaction message from instructions with embedded signers.
+ *
+ * @param rpc - Solana RPC client
+ * @param feePayer - Fee payer with TransactionSigner (signer will be embedded)
+ * @param instructions - Instructions to include
+ * @param lookupTableAddresses - Optional lookup tables for compression
+ * @param additionalSigners - Optional additional signers beyond fee payer
+ * @param blockhash - Optional blockhash (fetched if not provided)
+ */
+export declare function buildTransactionMessage(rpc: Rpc<SolanaRpcApi>, feePayer: TransactionSigner, instructions: Instruction[], lookupTableAddresses?: Address[], additionalSigners?: TransactionSigner[], blockhash?: Readonly<{
+    blockhash: Blockhash;
+    lastValidBlockHeight: bigint;
+}>): Promise<CompilableTransactionMessage>;
+export interface SimulationResult {
+    err: object | null;
+    logs: string[];
+    unitsConsumed: bigint;
+}
+/**
+ * Simulate a transaction message without requiring real signatures.
+ *
+ * Compiles the message into a wire-format transaction (with placeholder
+ * signatures), sends it to `simulateTransaction` with signature verification
+ * disabled, and validates the same recent blockhash that will be signed and
+ * sent if simulation succeeds.
+ *
+ * @param rpc - Solana RPC client
+ * @param transactionMessage - A compilable transaction message (with embedded signers)
+ */
+export declare function simulateTransaction(rpc: Rpc<SolanaRpcApi>, transactionMessage: CompilableTransactionMessage): Promise<SimulationResult>;
+/**
+ * Build, sign, send, and confirm a transaction using embedded signers.
+ *
+ * Use this with instructions that have TransactionSigner objects embedded
+ * in their accounts.
+ *
+ * @param rpc - Solana RPC client
+ * @param payer - Fee payer with TransactionSigner
+ * @param instructionsOrPlan - Kit Instructions or a composed transaction plan
+ *                             (with embedded signers)
+ * @param options - Optional configuration
+ * @returns Transaction signature
+ *
+ * @example
+ * ```typescript
+ * const sig = await signSendAndConfirmTransaction(rpc, payer, [
+ *   computeBudgetIx,
+ *   transferIx,
+ * ]);
+ * ```
+ */
+export declare function signSendAndConfirmTransaction(rpc: Rpc<SolanaRpcApi>, payer: TransactionSigner, instructionsOrPlan: Instruction[] | TransactionPlan, options?: SendTransactionOptionsWithPostSuccess): Promise<Signature>;