@kestrelfi/lyc-sdk 1.0.1

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

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.U64_MAX_BN = exports.U64_MAX = void 0;
+exports.toUiAmount = toUiAmount;
+exports.fromUiAmount = fromUiAmount;
+exports.wholeTokenAmount = wholeTokenAmount;
+exports.calculateTvlUsd = calculateTvlUsd;
+exports.tvlUsdToBaseUnits = tvlUsdToBaseUnits;
+exports.bnFromBigInt = bnFromBigInt;
+exports.bigintMulNumber = bigintMulNumber;
+exports.applyFeeCeil = applyFeeCeil;
+exports.getBatches = getBatches;
+exports.currentUnixSeconds = currentUnixSeconds;
+exports.sum = sum;
+exports.toBigInt = toBigInt;
+exports.applyBps = applyBps;
+exports.toBps = toBps;
+exports.toSafeNumber = toSafeNumber;
+exports.numToU64Bytes = numToU64Bytes;
+exports.numToU32Bytes = numToU32Bytes;
+exports.numToU16Bytes = numToU16Bytes;
+exports.computeApy = computeApy;
+const core_1 = require("@anchor-lang/core");
+const general_1 = require("../constants/general");
+exports.U64_MAX = BigInt("18446744073709551615");
+exports.U64_MAX_BN = new core_1.BN(exports.U64_MAX.toString());
+function toUiAmount(amount, decimals) {
+    const bigintValue = typeof amount === "bigint" ? amount : BigInt(amount.toString());
+    // Treat max u64 as unlimited
+    if (bigintValue >= exports.U64_MAX) {
+        return Infinity;
+    }
+    // For values that fit in safe integer range, convert directly
+    if (bigintValue <= BigInt(Number.MAX_SAFE_INTEGER)) {
+        return Number(bigintValue) / Math.pow(10, decimals);
+    }
+    // For large values, divide first using BigInt then convert
+    // This preserves more precision for the significant digits
+    const divisor = BigInt(Math.pow(10, decimals));
+    const wholePart = bigintValue / divisor;
+    const remainder = bigintValue % divisor;
+    return Number(wholePart) + Number(remainder) / Math.pow(10, decimals);
+}
+function fromUiAmount(amount, decimals) {
+    return new core_1.BN(Math.round(amount * Math.pow(10, decimals)));
+}
+/** Base-unit amount representing exactly 1 whole token for `decimals`. */
+function wholeTokenAmount(decimals) {
+    return Math.pow(10, decimals);
+}
+/**
+ * Compute USD TVL from a raw token amount and a raw oracle price, normalized
+ * to 8-decimal USD ($1 = 100_000_000).
+ *
+ * Mirrors the on-chain `calculate_tvl_usd`:
+ *   `tvl = amount * price / (10^(2*decimals) / 10^8)`
+ *
+ * Oracle prices are scaled to `10^decimals` per dollar (e.g. $1 USDC at 6 dec
+ * = 1_000_000; $130 SOL at 9 dec = 130_000_000_000).
+ */
+function calculateTvlUsd(amount, price, decimals) {
+    const assetScale = BigInt(wholeTokenAmount(decimals));
+    const scaleFactor = (assetScale * assetScale) / general_1.TVL_USD_SCALE;
+    return (amount * price) / scaleFactor;
+}
+/**
+ * Inverse of {@link calculateTvlUsd}: convert a normalized 8-decimal USD value
+ * back to base units given a raw oracle price and decimal precision.
+ *
+ *   `amount = tvlUsd * (10^(2*decimals) / 10^8) / price`
+ */
+function tvlUsdToBaseUnits(tvlUsd, price, decimals) {
+    const assetScale = BigInt(wholeTokenAmount(decimals));
+    const scaleFactor = (assetScale * assetScale) / general_1.TVL_USD_SCALE;
+    return (tvlUsd * scaleFactor) / price;
+}
+/** `bigint` → Anchor `BN` without floating-point loss (e.g. raw lamports / token amounts). */
+function bnFromBigInt(n) {
+    return new core_1.BN(n.toString());
+}
+/**
+ * `bigint × number → bigint` with sign-preserving half-away-from-zero rounding.
+ *
+ * JS has no native `bigint * float` op; we go through `Number(a) * b` and
+ * round. Precision loss is bounded by Number's ~15 significant digits, which
+ * is well inside sub-cent tolerance for realistic token balances. Returns
+ * `0n` when either input is zero or the multiplier is non-finite.
+ *
+ * Typical use: applying a floating-point rate (NAV, APY multiplier, oracle
+ * price per UI) to an integer base-unit balance.
+ */
+function bigintMulNumber(a, b) {
+    if (a === 0n || !Number.isFinite(b) || b === 0)
+        return 0n;
+    return BigInt(Math.round(Number(a) * b));
+}
+/**
+ * Ceiling-round `principal * feeRate`, returning the result as a bigint.
+ *
+ * Use this when undershooting the fee can cause a transaction to fail (e.g.
+ * a flash-loan repay that must cover principal + fee — over-paying by at most
+ * one base unit is fine, under-paying reverts).
+ *
+ * `feeRate` is a unitless fraction (e.g. `0.003` for 0.3%). Returns `0n` for
+ * non-positive rates.
+ */
+function applyFeeCeil(principal, feeRate) {
+    if (feeRate <= 0)
+        return 0n;
+    // Scale rate to 1e9 for integer math; ceil so we over-pay by at most one unit.
+    const scale = 1000000000n;
+    const rateScaled = BigInt(Math.ceil(feeRate * Number(scale)));
+    const numerator = principal * rateScaled;
+    return (numerator + (scale - 1n)) / scale;
+}
+function getBatches(items, batchSize) {
+    const batches = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+        batches.push(items.slice(i, i + batchSize));
+    }
+    return batches;
+}
+function currentUnixSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+function sum(numbers) {
+    return numbers.reduce((prev, curr) => prev + curr, 0);
+}
+function toBigInt(value) {
+    return BigInt(value.toString());
+}
+/** Apply a basis-points multiplier: `(value × bps) / 10_000`. */
+function applyBps(value, bps) {
+    return (value * BigInt(bps)) / general_1.BPS_DENOMINATOR;
+}
+/** Compute the basis-points ratio: `(part / whole) × 10_000`. */
+function toBps(part, whole) {
+    if (whole === 0n)
+        return 0n;
+    return (part * general_1.BPS_DENOMINATOR) / whole;
+}
+function toSafeNumber(value, field) {
+    const asBigInt = typeof value === "bigint" ? value : BigInt(value.toString());
+    if (asBigInt > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error(`${field} exceeds Number.MAX_SAFE_INTEGER and cannot be quoted safely`);
+    }
+    return Number(asBigInt);
+}
+function numberToLEBytes(value, byteLength = 8) {
+    const bigintValue = typeof value === "bigint" ? value : BigInt(value.toString());
+    const buf = new ArrayBuffer(byteLength);
+    const view = new DataView(buf);
+    if (byteLength === 8) {
+        view.setBigUint64(0, bigintValue, true);
+    }
+    else {
+        // Generic little-endian encoding for other byte lengths
+        let remaining = bigintValue;
+        for (let i = 0; i < byteLength; i++) {
+            view.setUint8(i, Number(remaining & 0xffn));
+            remaining >>= 8n;
+        }
+    }
+    return new Uint8Array(buf);
+}
+function numToU64Bytes(value) {
+    return numberToLEBytes(value, 8);
+}
+function numToU32Bytes(value) {
+    return numberToLEBytes(value, 4);
+}
+function numToU16Bytes(value) {
+    return numberToLEBytes(value, 2);
+}
+/**
+ * Compute annualized percentage yield from two price snapshots.
+ *
+ * Formula:
+ *   growthRate = priceEnd / priceStart
+ *   APY = (growthRate ^ (365 / daysBetween) - 1) * 100
+ *
+ * Returns `null` if either price is missing/zero or the time delta is zero.
+ */
+function computeApy(priceEnd, priceStart, windowSeconds) {
+    const SECONDS_PER_DAY = 86400;
+    const DAYS_PER_YEAR = 365;
+    if (priceStart <= 0 || priceEnd <= 0 || windowSeconds <= 0)
+        return null;
+    const daysBetween = windowSeconds / SECONDS_PER_DAY;
+    const growthRate = priceEnd / priceStart;
+    const apy = (Math.pow(growthRate, DAYS_PER_YEAR / daysBetween) - 1) * 100;
+    return Number.isFinite(apy) ? apy : null;
+}

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

@@ -0,0 +1,18 @@
+import type { Address, Base64EncodedWireTransaction, Rpc, SolanaRpcApi } from "@solana/kit";
+/** Helius priority levels accepted by `getPriorityFeeEstimate`. */
+export declare enum PriorityFeeSetting {
+    Min = "Min",
+    Low = "Low",
+    Medium = "Medium",
+    High = "High",
+    VeryHigh = "VeryHigh"
+}
+/**
+ * Estimate a compute-unit price through the configured RPC provider's
+ * Helius-compatible `getPriorityFeeEstimate` method.
+ *
+ * Helius expects the serialized transaction in base58. If transaction-based
+ * estimation is unavailable, retry with the transaction's account keys, which
+ * preserves contention-aware pricing without silently dropping the requested fee.
+ */
+export declare function getPriorityFeeEstimate(rpc: Rpc<SolanaRpcApi>, transaction: Base64EncodedWireTransaction, accountKeys: Address[], priorityFeeSetting: PriorityFeeSetting): Promise<number>;

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

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PriorityFeeSetting = void 0;
+exports.getPriorityFeeEstimate = getPriorityFeeEstimate;
+const bs58_1 = __importDefault(require("bs58"));
+/** Helius priority levels accepted by `getPriorityFeeEstimate`. */
+var PriorityFeeSetting;
+(function (PriorityFeeSetting) {
+    PriorityFeeSetting["Min"] = "Min";
+    PriorityFeeSetting["Low"] = "Low";
+    PriorityFeeSetting["Medium"] = "Medium";
+    PriorityFeeSetting["High"] = "High";
+    PriorityFeeSetting["VeryHigh"] = "VeryHigh";
+})(PriorityFeeSetting || (exports.PriorityFeeSetting = PriorityFeeSetting = {}));
+const MAX_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS = 100000000;
+function normalizeEstimate(result) {
+    const estimate = result.priorityFeeEstimate;
+    if (typeof estimate === "bigint") {
+        if (estimate < 0n) {
+            throw new Error("Helius getPriorityFeeEstimate returned an invalid estimate");
+        }
+        return Number(estimate > BigInt(MAX_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS)
+            ? BigInt(MAX_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS)
+            : estimate);
+    }
+    if (estimate === undefined || !Number.isFinite(estimate) || estimate < 0) {
+        throw new Error("Helius getPriorityFeeEstimate returned an invalid estimate");
+    }
+    return Math.min(Math.round(estimate), MAX_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS);
+}
+/**
+ * Estimate a compute-unit price through the configured RPC provider's
+ * Helius-compatible `getPriorityFeeEstimate` method.
+ *
+ * Helius expects the serialized transaction in base58. If transaction-based
+ * estimation is unavailable, retry with the transaction's account keys, which
+ * preserves contention-aware pricing without silently dropping the requested fee.
+ */
+async function getPriorityFeeEstimate(rpc, transaction, accountKeys, priorityFeeSetting) {
+    const transactionBase58 = bs58_1.default.encode(Buffer.from(transaction, "base64"));
+    const priorityFeeRpc = rpc;
+    try {
+        const result = await priorityFeeRpc
+            .getPriorityFeeEstimate({
+            transaction: transactionBase58,
+            options: { priorityLevel: priorityFeeSetting },
+        })
+            .send();
+        return normalizeEstimate(result);
+    }
+    catch {
+        const result = await priorityFeeRpc
+            .getPriorityFeeEstimate({
+            accountKeys,
+            options: { priorityLevel: priorityFeeSetting },
+        })
+            .send();
+        return normalizeEstimate(result);
+    }
+}

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

@@ -0,0 +1,20 @@
+export declare function isTransientNetworkError(err: unknown): boolean;
+/**
+ * Retry an async function on transient network errors with exponential backoff.
+ *
+ * Only retries errors that indicate the request never reached the server
+ * (`TypeError: fetch failed`, connection resets, timeouts) plus generic
+ * internal JSON-RPC errors that local/forked Solana validators can emit
+ * transiently while warming cloned accounts. Deterministic application-level
+ * errors (HTTP 4xx/5xx, custom program errors, validation failures) are thrown
+ * immediately.
+ */
+export declare function withNetworkRetry<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;
+/**
+ * Drop-in replacement for `globalThis.fetch` that retries on transient
+ * network errors (connection resets, DNS failures, `TypeError: fetch failed`).
+ *
+ * HTTP error responses (4xx, 5xx) are NOT retried — the server received and
+ * processed the request; the caller should decide how to handle those.
+ */
+export declare function fetchWithRetry(input: string | URL, init?: RequestInit): Promise<Response>;

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

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTransientNetworkError = isTransientNetworkError;
+exports.withNetworkRetry = withNetworkRetry;
+exports.fetchWithRetry = fetchWithRetry;
+const general_1 = require("./general");
+const DEFAULT_MAX_ATTEMPTS = 4;
+const INITIAL_DELAY_MS = 200;
+const MAX_DELAY_MS = 2000;
+function isTransientNetworkError(err) {
+    if (err instanceof TypeError)
+        return true;
+    const msg = (err?.message ?? "").toLowerCase();
+    return (msg.includes("fetch failed") ||
+        msg.includes("econnreset") ||
+        msg.includes("econnrefused") ||
+        msg.includes("etimedout") ||
+        msg.includes("socket hang up") ||
+        msg.includes("network timeout") ||
+        msg.includes("all providers failed") ||
+        msg.includes("all rpc providers failed") ||
+        msg.includes("failed to get info about account") ||
+        msg.includes("429") ||
+        msg.includes("rate limit") ||
+        msg.includes("too many requests") ||
+        msg.includes("timeout") ||
+        // Local validators / forked RPCs can intermittently surface account-load
+        // issues as a generic internal JSON-RPC error before the account is warmed.
+        msg.includes("json-rpc error: internal json-rpc error") ||
+        msg.includes("json-rpc error: internal error"));
+}
+function retryDelay(attempt) {
+    return Math.min(INITIAL_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+}
+/**
+ * Retry an async function on transient network errors with exponential backoff.
+ *
+ * Only retries errors that indicate the request never reached the server
+ * (`TypeError: fetch failed`, connection resets, timeouts) plus generic
+ * internal JSON-RPC errors that local/forked Solana validators can emit
+ * transiently while warming cloned accounts. Deterministic application-level
+ * errors (HTTP 4xx/5xx, custom program errors, validation failures) are thrown
+ * immediately.
+ */
+async function withNetworkRetry(fn, maxAttempts = DEFAULT_MAX_ATTEMPTS) {
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isTransientNetworkError(err) || attempt === maxAttempts - 1)
+                break;
+            await (0, general_1.sleep)(retryDelay(attempt));
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Drop-in replacement for `globalThis.fetch` that retries on transient
+ * network errors (connection resets, DNS failures, `TypeError: fetch failed`).
+ *
+ * HTTP error responses (4xx, 5xx) are NOT retried — the server received and
+ * processed the request; the caller should decide how to handle those.
+ */
+function fetchWithRetry(input, init) {
+    return withNetworkRetry(() => fetch(input, init));
+}

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

@@ -0,0 +1,40 @@
+import { type Rpc, type SolanaRpcApi } from "@solana/kit";
+import type { Environment } from "../types";
+/**
+ * Create a Solana RPC client with automatic retry on transient network
+ * failures (connection resets, DNS timeouts, `fetch failed`).
+ *
+ * Use this instead of `createSolanaRpc(url)` for any non-local RPC endpoint.
+ */
+export declare function createRpcWithRetry(url: string): Rpc<SolanaRpcApi>;
+/**
+ * Create a Solana RPC client that retries each provider and then fails over to
+ * the next configured provider for transient read failures.
+ */
+export declare function createRpcWithFailover(urls: string[]): Rpc<SolanaRpcApi>;
+export declare function createRpc(environment: Environment): Rpc<SolanaRpcApi>;
+export declare function heliusRpcUrl(heliusApiKey: string): string;
+export declare function ironforgeRpcUrl(ironforgeApiKey: string): string;
+/**
+ * Returns the RPC URL for the given environment.
+ *
+ * Resolution order (non-local):
+ * 1. `IRONFORGE_API_KEY` env var → constructs Ironforge URL. Preferred over
+ *    `RPC_URL` so a stray `RPC_URL` (e.g. pointing at Helius) does not silently
+ *    override Ironforge when both are present.
+ * 2. `RPC_URL` env var (explicit override, if set).
+ * 3. `HELIUS_API_KEY` env var → constructs Helius URL.
+ * 4. None → throws with a clear message.
+ *
+ * Browser bundles (e.g. Next.js) do not expose arbitrary `process.env` keys to the client.
+ * The app may inject these same names at build time — see the frontend `next.config.ts`.
+ */
+export declare function getRpcUrl(environment: Environment): string;
+export declare function getRpcUrls(environment: Environment): string[];
+/**
+ * Returns the preferred mainnet RPC URL while preserving a public fallback for
+ * local tools and tests that need mainnet reads without extra env setup.
+ */
+export declare function getMainnetRpcUrl(): string;
+/** Redact API key query params for logs (Helius, Ironforge, etc.). */
+export declare function redactRpcUrlForLog(url: string): string;

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

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRpcWithRetry = createRpcWithRetry;
+exports.createRpcWithFailover = createRpcWithFailover;
+exports.createRpc = createRpc;
+exports.heliusRpcUrl = heliusRpcUrl;
+exports.ironforgeRpcUrl = ironforgeRpcUrl;
+exports.getRpcUrl = getRpcUrl;
+exports.getRpcUrls = getRpcUrls;
+exports.getMainnetRpcUrl = getMainnetRpcUrl;
+exports.redactRpcUrlForLog = redactRpcUrlForLog;
+const kit_1 = require("@solana/kit");
+const retry_1 = require("./retry");
+/**
+ * Create a Solana RPC client with automatic retry on transient network
+ * failures (connection resets, DNS timeouts, `fetch failed`).
+ *
+ * Use this instead of `createSolanaRpc(url)` for any non-local RPC endpoint.
+ */
+function createRpcWithRetry(url) {
+    const inner = (0, kit_1.createDefaultRpcTransport)({ url });
+    const retryingTransport = async (...args) => (0, retry_1.withNetworkRetry)(() => inner(...args));
+    return (0, kit_1.createSolanaRpcFromTransport)(retryingTransport);
+}
+/**
+ * Create a Solana RPC client that retries each provider and then fails over to
+ * the next configured provider for transient read failures.
+ */
+function createRpcWithFailover(urls) {
+    const uniqueUrls = uniqueRpcUrls(urls);
+    if (uniqueUrls.length === 0) {
+        throw new Error("createRpcWithFailover requires at least one RPC URL");
+    }
+    if (uniqueUrls.length === 1) {
+        return createRpcWithRetry(uniqueUrls[0]);
+    }
+    const providers = uniqueUrls.map((url) => ({
+        url,
+        transport: (0, kit_1.createDefaultRpcTransport)({ url }),
+    }));
+    const failoverTransport = async (...args) => {
+        const failures = [];
+        for (const provider of providers) {
+            try {
+                return (await (0, retry_1.withNetworkRetry)(() => provider.transport(...args)));
+            }
+            catch (err) {
+                if (!(0, retry_1.isTransientNetworkError)(err)) {
+                    throw err;
+                }
+                failures.push(`${redactRpcUrlForLog(provider.url)}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        throw new Error(`All RPC providers failed: ${failures.join(" | ")}`);
+    };
+    return (0, kit_1.createSolanaRpcFromTransport)(failoverTransport);
+}
+function createRpc(environment) {
+    const urls = getRpcUrls(environment);
+    if (environment === "local")
+        return (0, kit_1.createSolanaRpc)(urls[0]);
+    return createRpcWithFailover(urls);
+}
+function heliusRpcUrl(heliusApiKey) {
+    return `https://mainnet.helius-rpc.com/?api-key=${heliusApiKey}`;
+}
+function ironforgeRpcUrl(ironforgeApiKey) {
+    return `https://rpc.ironforge.network/mainnet?apiKey=${ironforgeApiKey}`;
+}
+const PUBLIC_MAINNET_RPC_URL = "https://api.mainnet-beta.solana.com";
+/**
+ * Returns the RPC URL for the given environment.
+ *
+ * Resolution order (non-local):
+ * 1. `IRONFORGE_API_KEY` env var → constructs Ironforge URL. Preferred over
+ *    `RPC_URL` so a stray `RPC_URL` (e.g. pointing at Helius) does not silently
+ *    override Ironforge when both are present.
+ * 2. `RPC_URL` env var (explicit override, if set).
+ * 3. `HELIUS_API_KEY` env var → constructs Helius URL.
+ * 4. None → throws with a clear message.
+ *
+ * Browser bundles (e.g. Next.js) do not expose arbitrary `process.env` keys to the client.
+ * The app may inject these same names at build time — see the frontend `next.config.ts`.
+ */
+function getRpcUrl(environment) {
+    return getRpcUrls(environment)[0];
+}
+function getRpcUrls(environment) {
+    if (environment === "local")
+        return ["http://127.0.0.1:8899"];
+    const urls = uniqueRpcUrls([
+        process.env.IRONFORGE_API_KEY ? ironforgeRpcUrl(process.env.IRONFORGE_API_KEY) : undefined,
+        process.env.RPC_URL,
+        process.env.HELIUS_API_KEY ? heliusRpcUrl(process.env.HELIUS_API_KEY) : undefined,
+    ]);
+    if (urls.length > 0)
+        return urls;
+    throw new Error("Non-local environment requires an RPC endpoint. " +
+        "Set RPC_URL, IRONFORGE_API_KEY, or HELIUS_API_KEY.");
+}
+/**
+ * Returns the preferred mainnet RPC URL while preserving a public fallback for
+ * local tools and tests that need mainnet reads without extra env setup.
+ */
+function getMainnetRpcUrl() {
+    try {
+        return getRpcUrl("prod");
+    }
+    catch {
+        return PUBLIC_MAINNET_RPC_URL;
+    }
+}
+/** Redact API key query params for logs (Helius, Ironforge, etc.). */
+function redactRpcUrlForLog(url) {
+    return url.replace(/([?&]api-key=)[^&]*/gi, "$1…").replace(/([?&]apiKey=)[^&]*/gi, "$1…");
+}
+function uniqueRpcUrls(urls) {
+    const seen = new Set();
+    const unique = [];
+    for (const url of urls) {
+        if (!url)
+            continue;
+        const normalized = url.trim();
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        unique.push(normalized);
+    }
+    return unique;
+}

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

@@ -0,0 +1,23 @@
+import { type Address, type KeyPairSigner, type Rpc, type Signature, type SolanaRpcApi, type TransactionSigner } from "@solana/kit";
+import { Keypair } from "@solana/web3.js";
+export declare function createSignerFromAddress(address: Address): TransactionSigner;
+export declare function getSlot(rpc: Rpc<SolanaRpcApi>): Promise<bigint>;
+export declare function isTransactionSigner(x: unknown): x is TransactionSigner;
+/** Raw secret key bytes from a Solana CLI JSON keypair file. */
+export declare function readLocalKeypairSecret(keypairPath: string): Uint8Array;
+/**
+ * Loads a Solana keypair signer from a JSON file on disk.
+ * @param keypairPath - Path to the JSON keypair file (e.g. ~/.config/solana/tp-id.json)
+ */
+export declare function loadLocalKeypair(keypairPath?: string): Promise<KeyPairSigner>;
+/**
+ * Same keypair file as {@link loadLocalKeypair}, returned as both a Kit signer and a
+ * `@solana/web3.js` {@link Keypair} for Anchor (`AnchorProvider` / `Wallet`).
+ *
+ * Kit's `KeyPairSigner.keyPair` is a Web Crypto `CryptoKeyPair`, not a web3.js `Keypair`.
+ */
+export declare function loadLocalKeypairWithWeb3(keypairPath?: string): Promise<{
+    signer: KeyPairSigner;
+    web3Keypair: Keypair;
+}>;
+export declare function logTxMessages(rpc: Rpc<SolanaRpcApi>, sig: Signature): Promise<void>;

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

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSignerFromAddress = createSignerFromAddress;
+exports.getSlot = getSlot;
+exports.isTransactionSigner = isTransactionSigner;
+exports.readLocalKeypairSecret = readLocalKeypairSecret;
+exports.loadLocalKeypair = loadLocalKeypair;
+exports.loadLocalKeypairWithWeb3 = loadLocalKeypairWithWeb3;
+exports.logTxMessages = logTxMessages;
+const kit_1 = require("@solana/kit");
+const web3_js_1 = require("@solana/web3.js");
+const fs_1 = __importDefault(require("fs"));
+const general_1 = require("./general");
+function createSignerFromAddress(address) {
+    return { address };
+}
+async function getSlot(rpc) {
+    return rpc.getSlot({ commitment: "confirmed" }).send();
+}
+function isTransactionSigner(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        "address" in x &&
+        typeof x.address === "string");
+}
+/** Raw secret key bytes from a Solana CLI JSON keypair file. */
+function readLocalKeypairSecret(keypairPath) {
+    const walletData = JSON.parse(fs_1.default.readFileSync((0, general_1.resolveFp)(keypairPath), "utf-8"));
+    return new Uint8Array(walletData);
+}
+/**
+ * Loads a Solana keypair signer from a JSON file on disk.
+ * @param keypairPath - Path to the JSON keypair file (e.g. ~/.config/solana/tp-id.json)
+ */
+async function loadLocalKeypair(keypairPath = "~/.config/solana/tp-id.json") {
+    return (0, kit_1.createKeyPairSignerFromBytes)(readLocalKeypairSecret(keypairPath), true);
+}
+/**
+ * Same keypair file as {@link loadLocalKeypair}, returned as both a Kit signer and a
+ * `@solana/web3.js` {@link Keypair} for Anchor (`AnchorProvider` / `Wallet`).
+ *
+ * Kit's `KeyPairSigner.keyPair` is a Web Crypto `CryptoKeyPair`, not a web3.js `Keypair`.
+ */
+async function loadLocalKeypairWithWeb3(keypairPath = "~/.config/solana/tp-id.json") {
+    const secret = readLocalKeypairSecret(keypairPath);
+    const signer = await (0, kit_1.createKeyPairSignerFromBytes)(secret, true);
+    const web3Keypair = web3_js_1.Keypair.fromSecretKey(secret);
+    return { signer, web3Keypair };
+}
+async function logTxMessages(rpc, sig) {
+    const info = await rpc
+        .getTransaction(sig, {
+        commitment: "confirmed",
+        encoding: "base64",
+    })
+        .send();
+    console.log((info?.meta?.logMessages ?? []).join("\n"));
+}

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

@@ -0,0 +1,18 @@
+export interface PriceSnapshot {
+    timestamp: number;
+    price: number;
+}
+/**
+ * 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.
+ */
+export declare function findNearestSnapshot(snapshots: PriceSnapshot[], targetTimestamp: number): PriceSnapshot | undefined;
+/**
+ * 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.
+ */
+export declare function filterDailySnapshots(snapshots: PriceSnapshot[]): PriceSnapshot[];