@kestrelfi/lyc-sdk 1.0.1

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

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonRpcTransientError = void 0;
+exports.createMinIntervalThrottle = createMinIntervalThrottle;
+exports.jsonRpcFetchOnce = jsonRpcFetchOnce;
+exports.jsonRpcFetchWithRetries = jsonRpcFetchWithRetries;
+const general_1 = require("./general");
+const rpc_1 = require("./rpc");
+/** Thrown when the JSON-RPC error should be retried (rate limits, transient HTTP, transport). */
+class JsonRpcTransientError extends Error {
+    constructor(message, suggestedDelayMs) {
+        super(message);
+        this.suggestedDelayMs = suggestedDelayMs;
+        this.name = "JsonRpcTransientError";
+    }
+}
+exports.JsonRpcTransientError = JsonRpcTransientError;
+const RETRYABLE_HTTP = new Set([408, 429, 502, 503, 504]);
+function parseRetryAfterMs(header) {
+    if (!header)
+        return undefined;
+    const sec = Number(header.trim());
+    if (Number.isFinite(sec) && sec >= 0)
+        return Math.floor(sec * 1000);
+    return undefined;
+}
+function isRetryableJsonRpcError(err) {
+    if (!err)
+        return false;
+    if (err.code === -32429)
+        return true;
+    return /rate limit/i.test(err.message);
+}
+/**
+ * Serialize async work and enforce a minimum gap (ms) between the end of one
+ * invocation and the start of the next. Use `minIntervalMs === 0` to disable.
+ */
+function createMinIntervalThrottle(minIntervalMs) {
+    if (minIntervalMs <= 0) {
+        return async function run(fn) {
+            return fn();
+        };
+    }
+    let queue = Promise.resolve();
+    let lastEnd = 0;
+    return function run(fn) {
+        const task = queue.then(async () => {
+            const now = Date.now();
+            const wait = Math.max(0, minIntervalMs - (now - lastEnd));
+            if (wait > 0)
+                await (0, general_1.sleep)(wait);
+            try {
+                return await fn();
+            }
+            finally {
+                lastEnd = Date.now();
+            }
+        });
+        queue = task.then(() => undefined, () => undefined);
+        return task;
+    };
+}
+/**
+ * One JSON-RPC 2.0 POST. Uses raw `fetch` so response JSON matches RPC wire
+ * shape (e.g. Helius webhooks) without SDK bigint coercion.
+ */
+async function jsonRpcFetchOnce(rpcUrl, method, params) {
+    let res;
+    try {
+        res = await fetch(rpcUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        });
+    }
+    catch (e) {
+        const cause = e instanceof Error ? e.message : String(e);
+        const local = rpcUrl.includes("127.0.0.1") || rpcUrl.includes("localhost")
+            ? " No process is listening on that URL — start a local validator (e.g. surfpool/solana-test-validator) or set ENVIRONMENT + RPC_URL / HELIUS_API_KEY for a remote endpoint."
+            : "";
+        throw new JsonRpcTransientError(`RPC ${method} fetch failed (${(0, rpc_1.redactRpcUrlForLog)(rpcUrl)}): ${cause}.${local}`);
+    }
+    const retryAfterMs = parseRetryAfterMs(res.headers.get("Retry-After"));
+    if (RETRYABLE_HTTP.has(res.status)) {
+        const text = await res.text();
+        throw new JsonRpcTransientError(`RPC ${method} HTTP ${res.status}: ${text}`, retryAfterMs);
+    }
+    if (!res.ok) {
+        throw new Error(`RPC ${method} HTTP ${res.status}: ${await res.text()}`);
+    }
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        throw new JsonRpcTransientError(`RPC ${method}: invalid JSON response body`);
+    }
+    if (body.error) {
+        const dataStr = body.error.data !== undefined
+            ? ` data=${JSON.stringify(body.error.data, (_, v) => (typeof v === "bigint" ? v.toString() : v))}`
+            : "";
+        if (isRetryableJsonRpcError(body.error)) {
+            throw new JsonRpcTransientError(`RPC ${method} error ${body.error.code}: ${body.error.message}${dataStr}`, retryAfterMs);
+        }
+        throw new Error(`RPC ${method} error ${body.error.code}: ${body.error.message}${dataStr}`);
+    }
+    return body.result;
+}
+function retryDelayMs(attempt, baseDelayMs, err) {
+    const cap = 30000;
+    if (err instanceof JsonRpcTransientError && err.suggestedDelayMs != null) {
+        return Math.min(cap, err.suggestedDelayMs);
+    }
+    return Math.min(cap, baseDelayMs * 2 ** attempt);
+}
+/**
+ * JSON-RPC call with throttling + exponential backoff on {@link JsonRpcTransientError}.
+ */
+async function jsonRpcFetchWithRetries(throttle, rpcUrl, method, params, maxAttempts, baseDelayMs) {
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await throttle(() => jsonRpcFetchOnce(rpcUrl, method, params));
+        }
+        catch (e) {
+            lastErr = e;
+            const retryable = e instanceof JsonRpcTransientError;
+            if (!retryable || attempt === maxAttempts - 1)
+                break;
+            await (0, general_1.sleep)(retryDelayMs(attempt, baseDelayMs, e));
+        }
+    }
+    throw lastErr;
+}

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

@@ -0,0 +1,107 @@
+/**
+ * Metaplex Token Metadata CPI helpers for building UpdateMetadataAccountV2
+ * instruction data and CpiData for the CPI ref system.
+ */
+import { type Address } from "@solana/kit";
+import type { Connection } from "@solana/web3.js";
+import type { CpiData } from "../types";
+export interface UpdateMetadataDataV2 {
+    name: string;
+    symbol: string;
+    uri: string;
+    sellerFeeBasisPoints?: number;
+}
+export interface UpdateMetadataParams {
+    data?: UpdateMetadataDataV2;
+    newUpdateAuthority?: Address;
+    primarySaleHappened?: boolean;
+    isMutable?: boolean;
+}
+/**
+ * Serialize `UpdateMetadataAccountV2` instruction data using the Metaplex SDK.
+ *
+ * Uses `createUpdateMetadataAccountV2Instruction` from `@metaplex-foundation/mpl-token-metadata`
+ * to build a full `TransactionInstruction`, then extracts the `.data` bytes. This avoids
+ * manual Borsh serialization while keeping the result compatible with the CPI ref system.
+ */
+export declare function serializeUpdateMetadataAccountV2(metadataPda: Address, updateAuthority: Address, params: UpdateMetadataParams): Uint8Array;
+/**
+ * Display fields read out of the on-chain Metaplex metadata account, with
+ * Metaplex's right-side null padding stripped.
+ */
+export interface OnchainTokenMetadata {
+    name: string;
+    symbol: string;
+    uri: string;
+}
+/**
+ * Fetches the Metaplex Token-Metadata account for `mint` and decodes the
+ * three display fields. Returns `null` when the metadata account doesn't
+ * exist (e.g. token was created without `update_token_metadata` ever firing).
+ *
+ * Throws on RPC errors so callers can choose between retry and fallback.
+ *
+ * Token-2022 mints with the metadata extension stored on the mint itself
+ * are NOT covered here — every LYC mint goes through Metaplex via
+ * `update_token_metadata`, so there's no second source to read.
+ */
+export declare function fetchTokenMetadata(connection: Connection, mint: Address): Promise<OnchainTokenMetadata | null>;
+/**
+ * Derive the Metaplex metadata PDA for a mint.
+ *
+ * Seeds: `["metadata", METAPLEX_PROGRAM_ID, mint]`
+ */
+export declare function deriveMetadataPda(mint: Address): Promise<Address>;
+/**
+ * Build a `CpiData` for `UpdateMetadataAccountV2` that can be passed
+ * into `createCpiRefs()` and then to the `update_token_metadata` instruction.
+ *
+ * The Token PDA is the update authority and will be PDA-signed on-chain.
+ *
+ * Metaplex account order:
+ *   0. metadata (writable)
+ *   1. update_authority (Token PDA — signer set on-chain via invoke_signed)
+ *
+ * @example
+ * ```typescript
+ * const cpiData = await buildUpdateMetadataCpiData({
+ *   mint: yTokenMint,
+ *   updateAuthority: tokenPda,
+ *   data: { name: "ySOL", symbol: "ySOL", uri: "https://..." },
+ * });
+ * const { accounts, refs } = createCpiRefs([cpiData]);
+ * ```
+ */
+export declare function buildUpdateMetadataCpiData(params: {
+    mint: Address;
+    updateAuthority: Address;
+    data?: UpdateMetadataDataV2;
+    newUpdateAuthority?: Address;
+    primarySaleHappened?: boolean;
+    isMutable?: boolean;
+}): Promise<CpiData>;
+/**
+ * Build a `CpiData` for `CreateMetadataAccountV3` that can be passed
+ * into `createCpiRefs()` and then to the `update_token_metadata` instruction.
+ *
+ * Use this when no Metaplex metadata account exists yet for the mint.
+ * The Token PDA is both the mint authority (PDA-signed on-chain) and the
+ * update authority. The admin keypair is the payer and must be included in
+ * remaining_accounts.
+ *
+ * Metaplex account order:
+ *   0. metadata (writable)
+ *   1. mint (writable)
+ *   2. mint_authority / Token PDA (PDA-signed on-chain)
+ *   3. payer / admin (writable, signer)
+ *   4. update_authority / Token PDA (readonly)
+ *   5. system_program (readonly)
+ *   6. rent sysvar (readonly)
+ */
+export declare function buildCreateMetadataCpiData(params: {
+    mint: Address;
+    mintAuthority: Address;
+    payer: Address;
+    updateAuthority: Address;
+    data: UpdateMetadataDataV2;
+}): Promise<CpiData>;

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

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Metaplex Token Metadata CPI helpers for building UpdateMetadataAccountV2
+ * instruction data and CpiData for the CPI ref system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeUpdateMetadataAccountV2 = serializeUpdateMetadataAccountV2;
+exports.fetchTokenMetadata = fetchTokenMetadata;
+exports.deriveMetadataPda = deriveMetadataPda;
+exports.buildUpdateMetadataCpiData = buildUpdateMetadataCpiData;
+exports.buildCreateMetadataCpiData = buildCreateMetadataCpiData;
+const kit_1 = require("@solana/kit");
+const system_1 = require("@solana-program/system");
+const sysvars_1 = require("@solana/sysvars");
+const mpl_token_metadata_1 = require("@metaplex-foundation/mpl-token-metadata");
+const cpi_1 = require("../constants/generated/cpi");
+const general_1 = require("../constants/general");
+const compat_1 = require("./compat");
+const addressEncoder = (0, kit_1.getAddressEncoder)();
+// ---------------------------------------------------------------------------
+// Serialization (via mpl-token-metadata SDK)
+// ---------------------------------------------------------------------------
+/**
+ * Serialize `UpdateMetadataAccountV2` instruction data using the Metaplex SDK.
+ *
+ * Uses `createUpdateMetadataAccountV2Instruction` from `@metaplex-foundation/mpl-token-metadata`
+ * to build a full `TransactionInstruction`, then extracts the `.data` bytes. This avoids
+ * manual Borsh serialization while keeping the result compatible with the CPI ref system.
+ */
+function serializeUpdateMetadataAccountV2(metadataPda, updateAuthority, params) {
+    const ix = (0, mpl_token_metadata_1.createUpdateMetadataAccountV2Instruction)({
+        metadata: (0, compat_1.toWeb3Pk)(metadataPda),
+        updateAuthority: (0, compat_1.toWeb3Pk)(updateAuthority),
+    }, {
+        updateMetadataAccountArgsV2: {
+            data: params.data
+                ? {
+                    name: params.data.name,
+                    symbol: params.data.symbol,
+                    uri: params.data.uri,
+                    sellerFeeBasisPoints: params.data.sellerFeeBasisPoints ?? 0,
+                    creators: null,
+                    collection: null,
+                    uses: null,
+                }
+                : null,
+            updateAuthority: params.newUpdateAuthority ? (0, compat_1.toWeb3Pk)(params.newUpdateAuthority) : null,
+            primarySaleHappened: params.primarySaleHappened ?? null,
+            isMutable: params.isMutable ?? null,
+        },
+    });
+    return new Uint8Array(ix.data);
+}
+function trimMetadataString(s) {
+    return s.replace(/\0/g, "").trim();
+}
+/**
+ * Fetches the Metaplex Token-Metadata account for `mint` and decodes the
+ * three display fields. Returns `null` when the metadata account doesn't
+ * exist (e.g. token was created without `update_token_metadata` ever firing).
+ *
+ * Throws on RPC errors so callers can choose between retry and fallback.
+ *
+ * Token-2022 mints with the metadata extension stored on the mint itself
+ * are NOT covered here — every LYC mint goes through Metaplex via
+ * `update_token_metadata`, so there's no second source to read.
+ */
+async function fetchTokenMetadata(connection, mint) {
+    const metadataPda = await deriveMetadataPda(mint);
+    const accountInfo = await connection.getAccountInfo((0, compat_1.toWeb3Pk)(metadataPda));
+    if (!accountInfo)
+        return null;
+    const [decoded] = mpl_token_metadata_1.Metadata.fromAccountInfo(accountInfo);
+    return {
+        name: trimMetadataString(decoded.data.name),
+        symbol: trimMetadataString(decoded.data.symbol),
+        uri: trimMetadataString(decoded.data.uri),
+    };
+}
+/**
+ * Derive the Metaplex metadata PDA for a mint.
+ *
+ * Seeds: `["metadata", METAPLEX_PROGRAM_ID, mint]`
+ */
+async function deriveMetadataPda(mint) {
+    const [pda] = await (0, kit_1.getProgramDerivedAddress)({
+        programAddress: general_1.METAPLEX_TOKEN_METADATA_PROGRAM_ID,
+        seeds: [
+            Buffer.from("metadata"),
+            addressEncoder.encode(general_1.METAPLEX_TOKEN_METADATA_PROGRAM_ID),
+            addressEncoder.encode(mint),
+        ],
+    });
+    return pda;
+}
+// ---------------------------------------------------------------------------
+// CpiData Builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a `CpiData` for `UpdateMetadataAccountV2` that can be passed
+ * into `createCpiRefs()` and then to the `update_token_metadata` instruction.
+ *
+ * The Token PDA is the update authority and will be PDA-signed on-chain.
+ *
+ * Metaplex account order:
+ *   0. metadata (writable)
+ *   1. update_authority (Token PDA — signer set on-chain via invoke_signed)
+ *
+ * @example
+ * ```typescript
+ * const cpiData = await buildUpdateMetadataCpiData({
+ *   mint: yTokenMint,
+ *   updateAuthority: tokenPda,
+ *   data: { name: "ySOL", symbol: "ySOL", uri: "https://..." },
+ * });
+ * const { accounts, refs } = createCpiRefs([cpiData]);
+ * ```
+ */
+async function buildUpdateMetadataCpiData(params) {
+    const metadataPda = await deriveMetadataPda(params.mint);
+    const accounts = [
+        { address: metadataPda, role: kit_1.AccountRole.WRITABLE },
+        { address: params.updateAuthority, role: kit_1.AccountRole.READONLY },
+    ];
+    const data = serializeUpdateMetadataAccountV2(metadataPda, params.updateAuthority, {
+        data: params.data,
+        newUpdateAuthority: params.newUpdateAuthority,
+        primarySaleHappened: params.primarySaleHappened,
+        isMutable: params.isMutable,
+    });
+    return {
+        cpiType: cpi_1.CpiTypes.MPL_UPDATE_METADATA,
+        programId: general_1.METAPLEX_TOKEN_METADATA_PROGRAM_ID,
+        accounts,
+        data,
+    };
+}
+/**
+ * Build a `CpiData` for `CreateMetadataAccountV3` that can be passed
+ * into `createCpiRefs()` and then to the `update_token_metadata` instruction.
+ *
+ * Use this when no Metaplex metadata account exists yet for the mint.
+ * The Token PDA is both the mint authority (PDA-signed on-chain) and the
+ * update authority. The admin keypair is the payer and must be included in
+ * remaining_accounts.
+ *
+ * Metaplex account order:
+ *   0. metadata (writable)
+ *   1. mint (writable)
+ *   2. mint_authority / Token PDA (PDA-signed on-chain)
+ *   3. payer / admin (writable, signer)
+ *   4. update_authority / Token PDA (readonly)
+ *   5. system_program (readonly)
+ *   6. rent sysvar (readonly)
+ */
+async function buildCreateMetadataCpiData(params) {
+    const metadataPda = await deriveMetadataPda(params.mint);
+    const ix = (0, mpl_token_metadata_1.createCreateMetadataAccountV3Instruction)({
+        metadata: (0, compat_1.toWeb3Pk)(metadataPda),
+        mint: (0, compat_1.toWeb3Pk)(params.mint),
+        mintAuthority: (0, compat_1.toWeb3Pk)(params.mintAuthority),
+        payer: (0, compat_1.toWeb3Pk)(params.payer),
+        updateAuthority: (0, compat_1.toWeb3Pk)(params.updateAuthority),
+    }, {
+        createMetadataAccountArgsV3: {
+            data: {
+                name: params.data.name,
+                symbol: params.data.symbol,
+                uri: params.data.uri,
+                sellerFeeBasisPoints: params.data.sellerFeeBasisPoints ?? 0,
+                creators: null,
+                collection: null,
+                uses: null,
+            },
+            isMutable: true,
+            collectionDetails: null,
+        },
+    });
+    const accounts = [
+        { address: metadataPda, role: kit_1.AccountRole.WRITABLE },
+        { address: params.mint, role: kit_1.AccountRole.WRITABLE },
+        { address: params.mintAuthority, role: kit_1.AccountRole.READONLY },
+        { address: params.payer, role: kit_1.AccountRole.WRITABLE },
+        { address: params.updateAuthority, role: kit_1.AccountRole.READONLY },
+        { address: system_1.SYSTEM_PROGRAM_ADDRESS, role: kit_1.AccountRole.READONLY },
+        { address: sysvars_1.SYSVAR_RENT_ADDRESS, role: kit_1.AccountRole.READONLY },
+    ];
+    return {
+        cpiType: cpi_1.CpiTypes.MPL_CREATE_METADATA,
+        programId: general_1.METAPLEX_TOKEN_METADATA_PROGRAM_ID,
+        accounts,
+        data: new Uint8Array(ix.data),
+    };
+}

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

@@ -0,0 +1,72 @@
+import { BN } from "@anchor-lang/core";
+export declare const U64_MAX: bigint;
+export declare const U64_MAX_BN: BN;
+export declare function toUiAmount(amount: bigint | BN, decimals: number): number;
+export declare function fromUiAmount(amount: number, decimals: number): BN;
+/** Base-unit amount representing exactly 1 whole token for `decimals`. */
+export declare function wholeTokenAmount(decimals: number): number;
+/**
+ * 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).
+ */
+export declare function calculateTvlUsd(amount: bigint, price: bigint, decimals: number): bigint;
+/**
+ * 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`
+ */
+export declare function tvlUsdToBaseUnits(tvlUsd: bigint, price: bigint, decimals: number): bigint;
+/** `bigint` → Anchor `BN` without floating-point loss (e.g. raw lamports / token amounts). */
+export declare function bnFromBigInt(n: bigint): BN;
+/**
+ * `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.
+ */
+export declare function bigintMulNumber(a: bigint, b: number): bigint;
+/**
+ * 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.
+ */
+export declare function applyFeeCeil(principal: bigint, feeRate: number): bigint;
+export declare function getBatches<T>(items: T[], batchSize: number): T[][];
+export declare function currentUnixSeconds(): number;
+export declare function sum(numbers: number[]): number;
+export declare function toBigInt(value: BN | number | bigint): bigint;
+/** Apply a basis-points multiplier: `(value × bps) / 10_000`. */
+export declare function applyBps(value: bigint, bps: bigint | number): bigint;
+/** Compute the basis-points ratio: `(part / whole) × 10_000`. */
+export declare function toBps(part: bigint, whole: bigint): bigint;
+export declare function toSafeNumber(value: bigint | BN, field: string): number;
+export declare function numToU64Bytes(value: number | bigint | BN): Uint8Array<ArrayBufferLike>;
+export declare function numToU32Bytes(value: number | bigint | BN): Uint8Array<ArrayBufferLike>;
+export declare function numToU16Bytes(value: number | bigint | BN): Uint8Array<ArrayBufferLike>;
+/**
+ * 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.
+ */
+export declare function computeApy(priceEnd: number, priceStart: number, windowSeconds: number): number | null;