@kestrelfi/lyc-sdk 1.0.1

package/dist/shared/common/src/utils/cpi/args.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * CPI args buffer utilities.
+ *
+ * # Wire format (per CPI slot)
+ *
+ * ```text
+ * [u16 LE length]
+ *   • 0xFFFF → skip (program must compute args)
+ *   • 0      → no instruction args (invoke with empty data)
+ *   • N > 0  → N bytes of client-provided data follow
+ * ```
+ *
+ * Protocol-specific getter functions (e.g. `getPerenaMintArgs`) return raw
+ * serialized bytes (no prefix). Wrap them with `serializeArgs()` to add
+ * the u16 length prefix before packing into the CPI args buffer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CpiArgsBuilder = exports.SKIP_SENTINEL = void 0;
+exports.serializeArgs = serializeArgs;
+/** Sentinel u16 value meaning "program must provide args." */
+exports.SKIP_SENTINEL = 0xffff;
+/**
+ * Serialize CPI args with a u16 LE length prefix.
+ *
+ * - Called with data    → `[u16_len, ...data]`  (client provides args; len may be 0)
+ * - Called without data → `[0xFF, 0xFF]`         (skip — program provides args)
+ *
+ * @example
+ * ```typescript
+ * serializeArgs(getPerenaMintArgs({ ... })) // [16, 0, ...16 bytes]
+ * serializeArgs(jupiterSwapData)            // [N, 0, ...N bytes]
+ * serializeArgs(Buffer.alloc(0))            // [0, 0] — no-args instruction
+ * serializeArgs()                           // [0xFF, 0xFF] — skip
+ * ```
+ */
+function serializeArgs(data) {
+    if (data === undefined) {
+        const buf = Buffer.alloc(2);
+        buf.writeUInt16LE(exports.SKIP_SENTINEL);
+        return buf;
+    }
+    const len = data.length;
+    const buf = Buffer.alloc(2 + len);
+    buf.writeUInt16LE(len);
+    if (len > 0) {
+        Buffer.from(data).copy(buf, 2);
+    }
+    return buf;
+}
+/**
+ * Fluent builder for packing CPI args into a single buffer.
+ *
+ * Each `.add()` call wraps the provided data with a u16 length prefix
+ * via `serializeArgs`, then appends it.
+ *
+ * @example
+ * ```typescript
+ * const cpiArgs = new CpiArgsBuilder()
+ *   .add(getPerenaMintArgs({ amountYieldingDeposit: 1e6, minBankMintMinted: 9e5 }))
+ *   .add(jupiterSwapData)
+ *   .noArgs()            // no-args instruction (len = 0)
+ *   .skip()              // program provides args (0xFFFF)
+ *   .build();
+ * ```
+ */
+class CpiArgsBuilder {
+    constructor() {
+        this.parts = [];
+    }
+    /**
+     * Add client-provided args for the next CPI slot.
+     * Automatically wraps with a u16 LE length prefix.
+     */
+    add(data) {
+        this.parts.push(serializeArgs(data));
+        return this;
+    }
+    /**
+     * Mark the next CPI slot as a no-args instruction (length = 0).
+     * The Rust side will invoke the CPI with empty instruction data.
+     */
+    noArgs() {
+        this.parts.push(serializeArgs(Buffer.alloc(0)));
+        return this;
+    }
+    /**
+     * Mark the next CPI slot as program-provided (sentinel 0xFFFF).
+     * The Rust handler must compute args and call `invoke_cpi` directly.
+     */
+    skip() {
+        this.parts.push(serializeArgs());
+        return this;
+    }
+    /** Build the final packed buffer. */
+    build() {
+        return Buffer.concat(this.parts);
+    }
+}
+exports.CpiArgsBuilder = CpiArgsBuilder;

package/dist/shared/common/src/utils/cpi/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./args";
+export * from "./refs";

package/dist/shared/common/src/utils/cpi/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./args"), exports);
+__exportStar(require("./refs"), exports);

package/dist/shared/common/src/utils/cpi/refs.d.ts

@@ -0,0 +1,122 @@
+/**
+ * CPI account mapping utilities for multi-CPI transactions.
+ */
+import { type Address } from "@solana/kit";
+import { CpiData, CustomAccountMeta, InstructionRefs } from "../../types";
+/**
+ * Mapping for extracting accounts from `remainingAccounts` across multiple CPIs.
+ *
+ * @example
+ * For 2 CPIs where CPI 0 needs 10 accounts and CPI 1 needs 8 accounts:
+ * ```
+ * indices: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 2, 5, 7, 10, 11, 12, 13, 14]
+ * lengths: [10, 8]
+ *
+ * CPI 0 uses indices[0..10]
+ * CPI 1 uses indices[10..18]
+ * ```
+ *
+ * Matches Rust `CpiMapping` struct.
+ */
+export interface CpiMapping {
+    /** All indices into the account pool, flattened across all CPIs */
+    indices: Buffer;
+    /** Number of accounts per CPI - used to slice indices */
+    lengths: Buffer;
+}
+/**
+ * Input for a single CPI in deduplication.
+ *
+ * Any object with `cpiType` and `accounts` can be used, including `CpiData`.
+ *
+ * @property cpiType - Index into CPI_REGISTRY
+ * @property accounts - Accounts for this CPI (PROGRAM MUST BE FIRST!)
+ */
+export interface CpiInput {
+    /** Index into CPI_REGISTRY (e.g., CpiTypes.PERENA_MINT) */
+    cpiType: number;
+    /** Accounts for this CPI - PROGRAM MUST BE FIRST ACCOUNT */
+    accounts: CustomAccountMeta[];
+}
+/**
+ * Options for deduplicating CPI accounts.
+ */
+export interface DeduplicateOptions {
+    /**
+     * Accounts to pre-populate the pool with before processing CPIs.
+     *
+     * These accounts are inserted at the beginning of the pool (positions 0..N-1)
+     * so that CPI account indices correctly reference them.  Any CPI account
+     * whose address matches an initial account reuses that slot (deduplication).
+     *
+     * Use this to merge oracle accounts with CPI accounts in a single pass.
+     */
+    initialAccounts?: CustomAccountMeta[];
+    /** Addresses to track - returns their indices in the pool */
+    trackAddresses?: Address[];
+}
+/**
+ * Result of creating CPI refs from multiple CPI account lists.
+ */
+export interface CreateCpiRefsResult {
+    /** The deduplicated pool of unique accounts (pass as remainingAccounts) */
+    accounts: CustomAccountMeta[];
+    /** Anchor-serializable instruction refs (pass to Rust) */
+    refs: InstructionRefs;
+    lookupTables: Address[];
+}
+/**
+ * Result of creating multiple separate CPI ref groups from a shared account pool.
+ */
+export interface CreateMultiCpiRefsResult {
+    /** The single deduplicated pool of unique accounts (pass as remainingAccounts) */
+    accounts: CustomAccountMeta[];
+    /** One InstructionRefs per input group, all indexing into the shared pool */
+    refsGroups: InstructionRefs[];
+    lookupTables: Address[];
+}
+/**
+ * Deduplicate multiple groups of CPI data into a single shared account pool,
+ * returning separate `InstructionRefs` for each group.
+ *
+ * Use this when an instruction accepts multiple independent refs arguments
+ * (e.g. `ybIxRefs` + `tokenIxRefs`) that must index into the same
+ * `remainingAccounts` pool.
+ *
+ * @param cpiGroups - Array of CPI data groups; each group produces one InstructionRefs
+ * @param options   - Optional initial accounts and tracked addresses
+ *
+ * @example
+ * ```typescript
+ * const swapCpis = [jupiterSwapCpiData];
+ * const repayCpis = [kaminoRepayCpiData];
+ *
+ * const { accounts, refsGroups } = createMultiCpiRefs(
+ *   [swapCpis, repayCpis],
+ *   { initialAccounts: carryTradeAccounts }
+ * );
+ * const [ybIxRefs, tokenIxRefs] = refsGroups;
+ * ```
+ */
+export declare function createMultiCpiRefs(cpiGroups: CpiData[][], options?: DeduplicateOptions): CreateMultiCpiRefsResult;
+/**
+ * Deduplicate multiple CPI account lists into a single pool with CPI refs.
+ *
+ * Accepts any array of objects with `cpiType` and `accounts`, including `CpiData[]`.
+ *
+ * @param cpis - Array of CPI inputs (each with cpiType and accounts)
+ * @param options - Optional configuration (e.g., addresses to track)
+ * @returns Deduplicated pool and CPI refs
+ *
+ * @example
+ * ```typescript
+ * // CpiData includes cpiType, so pass it directly
+ * const perenaIx = await perenaClient.getSwapCpiData(quote, pda);
+ * const jupiterIx = await jupiterClient.getSwapCpiData(quote, pda);
+ *
+ * const { accounts, refs } = createCpiRefs([perenaIx, jupiterIx]);
+ *
+ * // Use accounts as remainingAccounts, refs as instruction arg
+ * ```
+ */
+export declare function createCpiRefs(cpis: CpiData[], options?: DeduplicateOptions): CreateCpiRefsResult;

package/dist/shared/common/src/utils/cpi/refs.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * CPI account mapping utilities for multi-CPI transactions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMultiCpiRefs = createMultiCpiRefs;
+exports.createCpiRefs = createCpiRefs;
+const kit_1 = require("@solana/kit");
+const roles_1 = require("../accounts/roles");
+const args_1 = require("./args");
+const accounts_1 = require("../accounts");
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Build indices for a single account list against a pool.
+ */
+function buildIndicesForCpi(accounts, poolIndex) {
+    return accounts.map((acc) => {
+        const idx = poolIndex.get(acc.address);
+        if (idx === undefined) {
+            throw new Error(`Account ${acc.address} not found in pool`);
+        }
+        return idx;
+    });
+}
+/**
+ * Build deduplicated pool from multiple account lists.
+ */
+function buildDeduplicatedPool(accountLists) {
+    const poolMap = new Map();
+    for (const accounts of accountLists) {
+        for (const acc of accounts) {
+            const existing = poolMap.get(acc.address);
+            if (!existing) {
+                poolMap.set(acc.address, { ...acc });
+            }
+            else {
+                // Upgrade role if needed (most permissive wins)
+                if ((0, roles_1.isRoleWritable)(acc.role) && !(0, roles_1.isRoleWritable)(existing.role)) {
+                    existing.role = (0, kit_1.upgradeRoleToWritable)(existing.role);
+                }
+                if ((0, roles_1.isRoleSigner)(acc.role) && !(0, roles_1.isRoleSigner)(existing.role)) {
+                    existing.role = (0, kit_1.upgradeRoleToSigner)(existing.role);
+                }
+            }
+        }
+    }
+    return poolMap;
+}
+/**
+ * Build a pool that preserves the exact sequential order of `initialAccounts`
+ * (no deduplication within them) and then appends CPI accounts deduplicated
+ * against the pool's first-occurrence index.
+ *
+ * This is required for instructions like `refresh_yielding_bank` that read
+ * remaining_accounts **positionally** — deduplicating the initial accounts
+ * would shift indices and break the sequential read order.
+ */
+function buildPoolWithOrderedInitial(initialAccounts, accountLists) {
+    // Preserve every initial account entry in order (duplicates allowed).
+    const pool = initialAccounts.map((acc) => ({ ...acc }));
+    // Index maps each address to its FIRST occurrence for CPI dedup lookups.
+    const poolIndex = new Map();
+    pool.forEach((acc, i) => {
+        if (!poolIndex.has(acc.address)) {
+            poolIndex.set(acc.address, i);
+        }
+    });
+    // Append CPI accounts, deduplicating against the pool.
+    for (const accounts of accountLists) {
+        for (const acc of accounts) {
+            const existingIdx = poolIndex.get(acc.address);
+            if (existingIdx === undefined) {
+                const idx = pool.length;
+                poolIndex.set(acc.address, idx);
+                pool.push({ ...acc });
+            }
+            else {
+                // Upgrade role on the first-occurrence entry (most permissive wins).
+                const existing = pool[existingIdx];
+                if ((0, roles_1.isRoleWritable)(acc.role) && !(0, roles_1.isRoleWritable)(existing.role)) {
+                    existing.role = (0, kit_1.upgradeRoleToWritable)(existing.role);
+                }
+                if ((0, roles_1.isRoleSigner)(acc.role) && !(0, roles_1.isRoleSigner)(existing.role)) {
+                    existing.role = (0, kit_1.upgradeRoleToSigner)(existing.role);
+                }
+            }
+        }
+    }
+    return { pool, poolIndex };
+}
+// ============================================================================
+// Shared Internal Helpers
+// ============================================================================
+/**
+ * Build a deduplicated account pool from CPI account lists, respecting
+ * optional `initialAccounts` ordering.
+ */
+function buildPool(accountLists, options) {
+    if (options?.initialAccounts) {
+        return buildPoolWithOrderedInitial(options.initialAccounts, accountLists);
+    }
+    const poolMap = buildDeduplicatedPool(accountLists);
+    const pool = Array.from(poolMap.values());
+    const poolIndex = new Map();
+    pool.forEach((acc, i) => poolIndex.set(acc.address, i));
+    return { pool, poolIndex };
+}
+/**
+ * Resolve tracked addresses to their indices in the pool.
+ */
+function resolveTrackedIndices(poolIndex, trackAddresses) {
+    if (!trackAddresses)
+        return [];
+    return trackAddresses.map((addr) => {
+        const idx = poolIndex.get(addr);
+        if (idx === undefined) {
+            throw new Error(`Tracked address ${addr} not found in pool`);
+        }
+        return idx;
+    });
+}
+/**
+ * Build a single `InstructionRefs` from a flat list of CPIs and their
+ * pre-built account lists, all indexing into a shared pool.
+ */
+function buildInstructionRefs(cpis, accountLists, poolIndex, trackedIndices) {
+    const allIndices = [];
+    const lengths = [];
+    const cpiTypes = [];
+    const cpiArgs = new args_1.CpiArgsBuilder();
+    for (let i = 0; i < cpis.length; i++) {
+        const indices = buildIndicesForCpi(accountLists[i], poolIndex);
+        allIndices.push(...indices);
+        lengths.push(indices.length);
+        cpiTypes.push(cpis[i].cpiType);
+        if (cpis[i].data !== undefined) {
+            cpiArgs.add(cpis[i].data);
+        }
+        else {
+            cpiArgs.skip();
+        }
+    }
+    return {
+        cpi: {
+            accounts: {
+                indices: Buffer.from(allIndices),
+                lengths: Buffer.from(lengths),
+            },
+            types: Buffer.from(cpiTypes),
+            args: cpiArgs.build(),
+        },
+        tracked: Buffer.from(trackedIndices),
+    };
+}
+/** Prepend the program account to each CPI's account list. */
+function toCpiAccountLists(cpis) {
+    return cpis.map((cpi) => [(0, accounts_1.toCustomAccountMeta)(cpi.programId), ...cpi.accounts]);
+}
+/** Collect all lookup tables from a flat list of CPIs. */
+function collectLookupTables(cpis) {
+    return cpis.flatMap((x) => x.lookupTables ?? []);
+}
+/**
+ * Deduplicate multiple groups of CPI data into a single shared account pool,
+ * returning separate `InstructionRefs` for each group.
+ *
+ * Use this when an instruction accepts multiple independent refs arguments
+ * (e.g. `ybIxRefs` + `tokenIxRefs`) that must index into the same
+ * `remainingAccounts` pool.
+ *
+ * @param cpiGroups - Array of CPI data groups; each group produces one InstructionRefs
+ * @param options   - Optional initial accounts and tracked addresses
+ *
+ * @example
+ * ```typescript
+ * const swapCpis = [jupiterSwapCpiData];
+ * const repayCpis = [kaminoRepayCpiData];
+ *
+ * const { accounts, refsGroups } = createMultiCpiRefs(
+ *   [swapCpis, repayCpis],
+ *   { initialAccounts: carryTradeAccounts }
+ * );
+ * const [ybIxRefs, tokenIxRefs] = refsGroups;
+ * ```
+ */
+function createMultiCpiRefs(cpiGroups, options) {
+    const allCpis = cpiGroups.flat();
+    const allAccountLists = toCpiAccountLists(allCpis);
+    const { pool, poolIndex } = buildPool(allAccountLists, options);
+    const trackedIndices = resolveTrackedIndices(poolIndex, options?.trackAddresses);
+    let flatIdx = 0;
+    const refsGroups = cpiGroups.map((group) => {
+        const groupAccountLists = allAccountLists.slice(flatIdx, flatIdx + group.length);
+        flatIdx += group.length;
+        return buildInstructionRefs(group, groupAccountLists, poolIndex, trackedIndices);
+    });
+    return {
+        accounts: (0, roles_1.stripSignerFromAccounts)(pool),
+        refsGroups,
+        lookupTables: collectLookupTables(allCpis),
+    };
+}
+/**
+ * Deduplicate multiple CPI account lists into a single pool with CPI refs.
+ *
+ * Accepts any array of objects with `cpiType` and `accounts`, including `CpiData[]`.
+ *
+ * @param cpis - Array of CPI inputs (each with cpiType and accounts)
+ * @param options - Optional configuration (e.g., addresses to track)
+ * @returns Deduplicated pool and CPI refs
+ *
+ * @example
+ * ```typescript
+ * // CpiData includes cpiType, so pass it directly
+ * const perenaIx = await perenaClient.getSwapCpiData(quote, pda);
+ * const jupiterIx = await jupiterClient.getSwapCpiData(quote, pda);
+ *
+ * const { accounts, refs } = createCpiRefs([perenaIx, jupiterIx]);
+ *
+ * // Use accounts as remainingAccounts, refs as instruction arg
+ * ```
+ */
+function createCpiRefs(cpis, options) {
+    const accountLists = toCpiAccountLists(cpis);
+    const { pool, poolIndex } = buildPool(accountLists, options);
+    const trackedIndices = resolveTrackedIndices(poolIndex, options?.trackAddresses);
+    return {
+        accounts: (0, roles_1.stripSignerFromAccounts)(pool),
+        refs: buildInstructionRefs(cpis, accountLists, poolIndex, trackedIndices),
+        lookupTables: collectLookupTables(cpis),
+    };
+}

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

@@ -0,0 +1,20 @@
+import type { TransactionCacheInvalidation } from "../types/general";
+import type { DataCache } from "../services/dataCache";
+export interface ApplyDataCacheTransactionInvalidationsOptions {
+    /**
+     * `DataCache` category used for `lycToken` invalidations (program-specific; e.g. LYC uses `"token"`).
+     */
+    tokenPdaCategory: string;
+    /**
+     * `DataCache` category used for `lycYieldingBank` invalidations.
+     */
+    yieldingBankPdaCategory: string;
+}
+/**
+ * Clears {@link DataCache} entries described by post-success invalidations.
+ *
+ * Handles `lycToken`, `lycYieldingBank`, `splAta`, and `perena` branches of
+ * {@link TransactionCacheInvalidation}. Ignores `kamino` entries (those are
+ * applied by lending-platform clients).
+ */
+export declare function applyDataCacheTransactionInvalidations(dataCache: DataCache, invalidations: TransactionCacheInvalidation[], options: ApplyDataCacheTransactionInvalidationsOptions): void;

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

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyDataCacheTransactionInvalidations = applyDataCacheTransactionInvalidations;
+const baseAccountClient_1 = require("../services/baseAccountClient");
+/**
+ * Clears {@link DataCache} entries described by post-success invalidations.
+ *
+ * Handles `lycToken`, `lycYieldingBank`, `splAta`, and `perena` branches of
+ * {@link TransactionCacheInvalidation}. Ignores `kamino` entries (those are
+ * applied by lending-platform clients).
+ */
+function applyDataCacheTransactionInvalidations(dataCache, invalidations, options) {
+    for (const inv of invalidations) {
+        if (inv.client === "lycToken") {
+            dataCache.clearCacheEntry(options.tokenPdaCategory, inv.tokenPda);
+        }
+        else if (inv.client === "lycYieldingBank") {
+            dataCache.clearCacheEntry(options.yieldingBankPdaCategory, inv.yieldingBankPda);
+        }
+        else if (inv.client === "splAta") {
+            dataCache.clearCacheEntry(baseAccountClient_1.SPL_ATA_CACHE_CATEGORY, inv.ata);
+        }
+        else if (inv.client === "perena") {
+            inv.dataCache.clearCacheEntry(inv.category, inv.id);
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+import { Address } from "@solana/kit";
+export declare function resolveFp(keypairFp: string): string;
+export declare function deduplicateAccounts(addresses: Address[]): Address[];
+/**
+ * Returns items in encounter order; later entries with the same `key(item)` are skipped.
+ */
+export declare function dedupeOrdered<T>(items: readonly T[], key: (item: T) => string): T[];
+/**
+ * {@link dedupeOrdered} for Solana Kit `Address` values (compares base58 strings).
+ */
+export declare function dedupeOrderedAddresses(addresses: readonly Address[]): Address[];
+/** Return `addresses` excluding any address present in `excluded`. */
+export declare function filterSpecificAccounts(addresses: readonly Address[], excluded: readonly Address[]): Address[];
+export declare function zip<T, U>(list1: T[], list2: U[]): [T, U][];
+/**
+ * Returns the element with the highest numeric score. Throws if `items` is empty.
+ */
+export declare function maxByNumber<T>(items: T[], score: (item: T) => number): T;
+export declare function createRecord<T>(keys: string[], values: T[]): Record<string, T>;
+/**
+ * Case-insensitive key lookup on a record. Returns the first matching key, or undefined.
+ */
+export declare function findKeyIgnoreCase(record: Record<string, unknown>, key: string): string | undefined;
+export declare function sleep(ms: number): Promise<void>;

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

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFp = resolveFp;
+exports.deduplicateAccounts = deduplicateAccounts;
+exports.dedupeOrdered = dedupeOrdered;
+exports.dedupeOrderedAddresses = dedupeOrderedAddresses;
+exports.filterSpecificAccounts = filterSpecificAccounts;
+exports.zip = zip;
+exports.maxByNumber = maxByNumber;
+exports.createRecord = createRecord;
+exports.findKeyIgnoreCase = findKeyIgnoreCase;
+exports.sleep = sleep;
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+function resolveFp(keypairFp) {
+    // Expand ~ to home dir
+    if (keypairFp.startsWith("~")) {
+        keypairFp = path_1.default.join(os_1.default.homedir(), keypairFp.slice(1));
+    }
+    // Resolve relative paths to absolute ones
+    keypairFp = path_1.default.resolve(keypairFp);
+    return keypairFp;
+}
+function deduplicateAccounts(addresses) {
+    return Array.from(new Set(addresses).values());
+}
+/**
+ * Returns items in encounter order; later entries with the same `key(item)` are skipped.
+ */
+function dedupeOrdered(items, key) {
+    const ordered = [];
+    const seen = new Set();
+    for (const item of items) {
+        const k = key(item);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        ordered.push(item);
+    }
+    return ordered;
+}
+/**
+ * {@link dedupeOrdered} for Solana Kit `Address` values (compares base58 strings).
+ */
+function dedupeOrderedAddresses(addresses) {
+    return dedupeOrdered(addresses, (a) => a);
+}
+/** Return `addresses` excluding any address present in `excluded`. */
+function filterSpecificAccounts(addresses, excluded) {
+    const excludedSet = new Set(excluded);
+    return addresses.filter((address) => !excludedSet.has(address));
+}
+function zip(list1, list2) {
+    const minLength = Math.min(list1.length, list2.length);
+    const result = [];
+    for (let i = 0; i < minLength; i++) {
+        result.push([list1[i], list2[i]]);
+    }
+    return result;
+}
+/**
+ * Returns the element with the highest numeric score. Throws if `items` is empty.
+ */
+function maxByNumber(items, score) {
+    if (items.length === 0) {
+        throw new Error("maxByNumber: empty items");
+    }
+    let best = items[0];
+    let bestScore = score(best);
+    for (let i = 1; i < items.length; i++) {
+        const item = items[i];
+        const s = score(item);
+        if (s > bestScore) {
+            best = item;
+            bestScore = s;
+        }
+    }
+    return best;
+}
+function createRecord(keys, values) {
+    return Object.fromEntries(zip(keys, values).map(([k, v]) => [k.toString(), v]));
+}
+/**
+ * Case-insensitive key lookup on a record. Returns the first matching key, or undefined.
+ */
+function findKeyIgnoreCase(record, key) {
+    const lower = key.toLowerCase();
+    return Object.keys(record).find((k) => k.toLowerCase() === lower);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,22 @@
+export * from "./accounts";
+export * from "./data";
+export * from "./compat";
+export * from "./cpi";
+export * from "./instruction";
+export * from "./numbers";
+export * from "./rpc";
+export * from "./jsonRpcFetch";
+export * from "./asyncConcurrency";
+export * from "./anchor";
+export * from "./solana";
+export * from "./transaction";
+export * from "./transactionSplitter";
+export * from "./txAccountCoverage";
+export * from "./jito";
+export * from "./general";
+export * from "./retry";
+export * from "./token";
+export * from "./timeSeries";
+export * from "./metadata";
+export * from "./json";
+export * from "./priorityFee";