@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

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

@@ -1,134 +0,0 @@
-"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

@@ -1,107 +0,0 @@
-/**
- * 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

@@ -1,194 +0,0 @@
-"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

@@ -1,72 +0,0 @@
-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;