@kestrelfi/lyc-sdk 1.0.1

package/dist/shared/common/src/types/index.js

@@ -0,0 +1,20 @@
+"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("./solana"), exports);
+__exportStar(require("./general"), exports);
+__exportStar(require("./cpi"), exports);
+__exportStar(require("./enums"), exports);

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

@@ -0,0 +1,24 @@
+import { AssociatedTokenSeeds } from "@solana-program/token";
+import { AccountRole, Address, Instruction } from "@solana/kit";
+import type { TransactionCacheInvalidation } from "./general";
+export type CustomAccountMeta = {
+    address: Address;
+    role: AccountRole;
+    isRequiredAta?: AssociatedTokenSeeds;
+};
+export interface CpiData {
+    cpiType: number;
+    programId: Address;
+    accounts: CustomAccountMeta[];
+    /** Instruction data for the given CPI. if not provided, it implies the program should provide it internally. Can pass new UInt8Array() if no data is expected */
+    data?: Uint8Array;
+    lookupTables?: Address[];
+    postSuccessCacheInvalidations?: TransactionCacheInvalidation[];
+    /**
+     * Top-level instructions that must run before the host transaction's CPI
+     * dispatcher (e.g. createATA for intermediate-mint accounts a multi-hop
+     * Jupiter route will write into). The host bundler is responsible for
+     * placing these before the CPI but after lending-platform pre-instructions.
+     */
+    preInstructions?: Instruction[];
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,5 @@
+export * from "./meta";
+export * from "./roles";
+export * from "./rpc";
+export * from "./pda";
+export * from "./splBalances";

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

@@ -0,0 +1,21 @@
+"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("./meta"), exports);
+__exportStar(require("./roles"), exports);
+__exportStar(require("./rpc"), exports);
+__exportStar(require("./pda"), exports);
+__exportStar(require("./splBalances"), exports);

package/dist/shared/common/src/utils/accounts/meta.d.ts

@@ -0,0 +1,21 @@
+import { Address } from "@solana/kit";
+import { CustomAccountMeta } from "../../types";
+import { AccountMeta } from "@solana/web3.js";
+import { AssociatedTokenSeeds } from "@solana-program/token";
+/**
+ * Create a CustomAccountMeta from individual parameters.
+ *
+ * @param address - The account's public key
+ * @param isWritable - Whether the account is writable (default: false)
+ * @param requiredAtaDetails - Optional ATA details if this account needs to be created
+ * @param isSigner - Whether the account is a signer (default: false)
+ * @returns A CustomAccountMeta object
+ */
+export declare function toCustomAccountMeta(address: Address, isWritable?: boolean, requiredAtaDetails?: AssociatedTokenSeeds, isSigner?: boolean): CustomAccountMeta;
+/**
+ * Convert a web3.js AccountMeta to a CustomAccountMeta.
+ *
+ * @param web3AccountMeta - The web3.js AccountMeta
+ * @returns A CustomAccountMeta object
+ */
+export declare function toCustomAccountMetaFromWeb3AccountMeta(web3AccountMeta: AccountMeta): CustomAccountMeta;

package/dist/shared/common/src/utils/accounts/meta.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCustomAccountMeta = toCustomAccountMeta;
+exports.toCustomAccountMetaFromWeb3AccountMeta = toCustomAccountMetaFromWeb3AccountMeta;
+const roles_1 = require("./roles");
+/**
+ * Create a CustomAccountMeta from individual parameters.
+ *
+ * @param address - The account's public key
+ * @param isWritable - Whether the account is writable (default: false)
+ * @param requiredAtaDetails - Optional ATA details if this account needs to be created
+ * @param isSigner - Whether the account is a signer (default: false)
+ * @returns A CustomAccountMeta object
+ */
+function toCustomAccountMeta(address, isWritable, requiredAtaDetails, isSigner) {
+    const role = (0, roles_1.getAccountRole)(isWritable ?? false, isSigner ?? false);
+    return { address, role, isRequiredAta: requiredAtaDetails };
+}
+/**
+ * Convert a web3.js AccountMeta to a CustomAccountMeta.
+ *
+ * @param web3AccountMeta - The web3.js AccountMeta
+ * @returns A CustomAccountMeta object
+ */
+function toCustomAccountMetaFromWeb3AccountMeta(web3AccountMeta) {
+    return toCustomAccountMeta(web3AccountMeta.pubkey.toBase58(), web3AccountMeta.isWritable, undefined, web3AccountMeta.isSigner);
+}

package/dist/shared/common/src/utils/accounts/pda.d.ts

@@ -0,0 +1,2 @@
+import { Address } from "@solana/kit";
+export declare function getAtaAddress(mint: Address, owner: Address, tokenProgram?: Address): Promise<Address>;

package/dist/shared/common/src/utils/accounts/pda.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAtaAddress = getAtaAddress;
+const token_1 = require("@solana-program/token");
+const web3_js_1 = require("@solana/web3.js");
+const compat_1 = require("../compat");
+/**
+ * SPL associated token account (ATA) for mint + owner + token program (same PDA as
+ * `@solana-program/token`’s `findAssociatedTokenPda`).
+ */
+function deriveAssociatedTokenAddress(mint, owner, tokenProgram) {
+    const [ata] = web3_js_1.PublicKey.findProgramAddressSync([(0, compat_1.toWeb3Pk)(owner).toBuffer(), (0, compat_1.toWeb3Pk)(tokenProgram).toBuffer(), (0, compat_1.toWeb3Pk)(mint).toBuffer()], new web3_js_1.PublicKey(token_1.ASSOCIATED_TOKEN_PROGRAM_ADDRESS));
+    return (0, compat_1.fromWeb3Pk)(ata);
+}
+async function getAtaAddress(mint, owner, tokenProgram = token_1.TOKEN_PROGRAM_ADDRESS) {
+    return deriveAssociatedTokenAddress(mint, owner, tokenProgram);
+}

package/dist/shared/common/src/utils/accounts/roles.d.ts

@@ -0,0 +1,26 @@
+import { AccountRole } from "@solana/kit";
+import { CustomAccountMeta } from "../../types";
+export declare function isRoleWritable(role: AccountRole): boolean;
+export declare function isRoleSigner(role: AccountRole): boolean;
+export declare function getAccountRole(isWritable: boolean, isSigner: boolean): AccountRole;
+/**
+ * Downgrade a role from signer to non-signer, preserving writability.
+ *
+ * This is useful when preparing accounts for CPI patterns where a PDA
+ * signs via `invoke_signed` on-chain, not externally.
+ *
+ * @param role - The account role to downgrade
+ * @returns The role without signer status
+ */
+export declare function downgradeRoleFromSigner(role: AccountRole): AccountRole;
+/**
+ * Strip signer status from all accounts in a list.
+ *
+ * Use this when passing accounts as remainingAccounts for CPI patterns
+ * where a PDA signs via `invoke_signed`. The on-chain program handles
+ * PDA signing, so remainingAccounts should not have signer flags.
+ *
+ * @param accounts - Array of accounts to strip signer status from
+ * @returns New array with signer status removed
+ */
+export declare function stripSignerFromAccounts(accounts: CustomAccountMeta[]): CustomAccountMeta[];

package/dist/shared/common/src/utils/accounts/roles.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRoleWritable = isRoleWritable;
+exports.isRoleSigner = isRoleSigner;
+exports.getAccountRole = getAccountRole;
+exports.downgradeRoleFromSigner = downgradeRoleFromSigner;
+exports.stripSignerFromAccounts = stripSignerFromAccounts;
+const kit_1 = require("@solana/kit");
+function isRoleWritable(role) {
+    return role === kit_1.AccountRole.WRITABLE || role === kit_1.AccountRole.WRITABLE_SIGNER;
+}
+function isRoleSigner(role) {
+    return role === kit_1.AccountRole.READONLY_SIGNER || role === kit_1.AccountRole.WRITABLE_SIGNER;
+}
+function getAccountRole(isWritable, isSigner) {
+    let role = kit_1.AccountRole.READONLY;
+    if (isWritable)
+        role = (0, kit_1.upgradeRoleToWritable)(role);
+    if (isSigner)
+        role = (0, kit_1.upgradeRoleToSigner)(role);
+    return role;
+}
+/**
+ * Downgrade a role from signer to non-signer, preserving writability.
+ *
+ * This is useful when preparing accounts for CPI patterns where a PDA
+ * signs via `invoke_signed` on-chain, not externally.
+ *
+ * @param role - The account role to downgrade
+ * @returns The role without signer status
+ */
+function downgradeRoleFromSigner(role) {
+    if (role === kit_1.AccountRole.READONLY_SIGNER)
+        return kit_1.AccountRole.READONLY;
+    if (role === kit_1.AccountRole.WRITABLE_SIGNER)
+        return kit_1.AccountRole.WRITABLE;
+    return role;
+}
+/**
+ * Strip signer status from all accounts in a list.
+ *
+ * Use this when passing accounts as remainingAccounts for CPI patterns
+ * where a PDA signs via `invoke_signed`. The on-chain program handles
+ * PDA signing, so remainingAccounts should not have signer flags.
+ *
+ * @param accounts - Array of accounts to strip signer status from
+ * @returns New array with signer status removed
+ */
+function stripSignerFromAccounts(accounts) {
+    return accounts.map((acc) => ({
+        ...acc,
+        role: downgradeRoleFromSigner(acc.role),
+    }));
+}

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

@@ -0,0 +1,8 @@
+import { Address, Rpc, SolanaRpcApi } from "@solana/kit";
+export interface AllAccountsExistResult {
+    existingAddresses: Address[];
+    missingAddresses: Address[];
+    existsByAddress: Map<Address, boolean>;
+}
+export declare function allAccountsExist(rpc: Rpc<SolanaRpcApi>, addresses: Address[]): Promise<AllAccountsExistResult>;
+export declare function accountExists(rpc: Rpc<SolanaRpcApi>, address: Address): Promise<boolean>;

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

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allAccountsExist = allAccountsExist;
+exports.accountExists = accountExists;
+async function allAccountsExist(rpc, addresses) {
+    if (!addresses.length) {
+        return {
+            existingAddresses: [],
+            missingAddresses: [],
+            existsByAddress: new Map(),
+        };
+    }
+    const uniqueAddresses = [...new Set(addresses)];
+    const response = await rpc
+        .getMultipleAccounts(uniqueAddresses, { encoding: "base64" })
+        .send();
+    const existsByAddress = new Map();
+    for (let i = 0; i < uniqueAddresses.length; i += 1) {
+        existsByAddress.set(uniqueAddresses[i], response.value[i] !== null);
+    }
+    return {
+        existingAddresses: uniqueAddresses.filter((address) => existsByAddress.get(address)),
+        missingAddresses: uniqueAddresses.filter((address) => !existsByAddress.get(address)),
+        existsByAddress,
+    };
+}
+async function accountExists(rpc, address) {
+    const accountInfo = await rpc.getAccountInfo(address, { encoding: "base64" }).send();
+    return accountInfo.value !== null;
+}

package/dist/shared/common/src/utils/accounts/splBalances.d.ts

@@ -0,0 +1,15 @@
+import { Address, Rpc, SolanaRpcApi } from "@solana/kit";
+/**
+ * Fetch SPL token account `amount` values for a list of token accounts in one
+ * (or a small number of) RPC calls.
+ *
+ * Keyed by token account address rather than mint so the caller can derive
+ * whatever mapping they need. Closed or non-existent accounts are simply
+ * absent from the returned map (callers should treat them as `0`).
+ *
+ * Works for both SPL Token and Token-2022 accounts — the base layout through
+ * byte 72 is identical. Use this instead of `getTokenAccountsByOwner` when
+ * the set of accounts to read is known in advance; it scales with the query
+ * set size rather than with the wallet's total token-account count.
+ */
+export declare function fetchSplTokenAccountAmounts(rpc: Rpc<SolanaRpcApi>, tokenAccounts: Address[]): Promise<Map<Address, bigint>>;

package/dist/shared/common/src/utils/accounts/splBalances.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchSplTokenAccountAmounts = fetchSplTokenAccountAmounts;
+/**
+ * Byte offset of the `amount` field in an SPL token account's serialized layout:
+ *
+ *   [0..32)  mint
+ *   [32..64) owner
+ *   [64..72) amount: u64 little-endian
+ *
+ * Token-2022 preserves the same base layout at these offsets; account
+ * extensions (if any) live after byte 165, so reading the base `amount` at 64
+ * is correct for both token programs.
+ */
+const SPL_TOKEN_ACCOUNT_AMOUNT_OFFSET = 64;
+/** `getMultipleAccounts` is capped at this many keys per request. */
+const GET_MULTIPLE_ACCOUNTS_MAX_KEYS = 100;
+/**
+ * Fetch SPL token account `amount` values for a list of token accounts in one
+ * (or a small number of) RPC calls.
+ *
+ * Keyed by token account address rather than mint so the caller can derive
+ * whatever mapping they need. Closed or non-existent accounts are simply
+ * absent from the returned map (callers should treat them as `0`).
+ *
+ * Works for both SPL Token and Token-2022 accounts — the base layout through
+ * byte 72 is identical. Use this instead of `getTokenAccountsByOwner` when
+ * the set of accounts to read is known in advance; it scales with the query
+ * set size rather than with the wallet's total token-account count.
+ */
+async function fetchSplTokenAccountAmounts(rpc, tokenAccounts) {
+    if (tokenAccounts.length === 0)
+        return new Map();
+    const chunks = [];
+    for (let i = 0; i < tokenAccounts.length; i += GET_MULTIPLE_ACCOUNTS_MAX_KEYS) {
+        chunks.push(tokenAccounts.slice(i, i + GET_MULTIPLE_ACCOUNTS_MAX_KEYS));
+    }
+    const balances = new Map();
+    await Promise.all(chunks.map(async (chunk) => {
+        const response = await rpc
+            .getMultipleAccounts(chunk, { encoding: "base64" })
+            .send();
+        for (let i = 0; i < chunk.length; i++) {
+            const entry = response.value[i];
+            if (!entry)
+                continue;
+            const buf = Buffer.from(entry.data[0], "base64");
+            balances.set(chunk[i], buf.readBigUInt64LE(SPL_TOKEN_ACCOUNT_AMOUNT_OFFSET));
+        }
+    }));
+    return balances;
+}

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

@@ -0,0 +1,17 @@
+import { AnchorProvider, Wallet } from "@anchor-lang/core";
+import { type ConfirmOptions, Keypair } from "@solana/web3.js";
+import type { Environment } from "../types";
+/**
+ * Builds an {@link AnchorProvider} for the given cluster with the standard script defaults
+ * (`Connection` + `opts` use the same commitment, default `"confirmed"`).
+ *
+ * @param walletOrKeypair - Anchor `Wallet`, or a `@solana/web3.js` `Keypair` (wrapped as `Wallet`).
+ */
+export declare function createDefaultAnchorProvider(env: Environment, walletOrKeypair: Wallet | Keypair, confirmOptions?: ConfirmOptions): AnchorProvider;
+/**
+ * Builds a read-only {@link AnchorProvider} with a throwaway keypair.
+ *
+ * Use this for services that only need to read on-chain state (e.g. the
+ * price ingestion Lambda) and never sign transactions.
+ */
+export declare function createReadOnlyAnchorProvider(env: Environment): AnchorProvider;

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

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultAnchorProvider = createDefaultAnchorProvider;
+exports.createReadOnlyAnchorProvider = createReadOnlyAnchorProvider;
+const core_1 = require("@anchor-lang/core");
+const web3_js_1 = require("@solana/web3.js");
+const rpc_1 = require("./rpc");
+const DEFAULT_COMMITMENT = "confirmed";
+/**
+ * Builds an {@link AnchorProvider} for the given cluster with the standard script defaults
+ * (`Connection` + `opts` use the same commitment, default `"confirmed"`).
+ *
+ * @param walletOrKeypair - Anchor `Wallet`, or a `@solana/web3.js` `Keypair` (wrapped as `Wallet`).
+ */
+function createDefaultAnchorProvider(env, walletOrKeypair, confirmOptions) {
+    const commitment = confirmOptions?.commitment ?? DEFAULT_COMMITMENT;
+    const wallet = walletOrKeypair instanceof web3_js_1.Keypair ? new core_1.Wallet(walletOrKeypair) : walletOrKeypair;
+    const opts = { commitment, ...confirmOptions };
+    return new core_1.AnchorProvider(new web3_js_1.Connection((0, rpc_1.getRpcUrl)(env), commitment), wallet, opts);
+}
+/**
+ * Builds a read-only {@link AnchorProvider} with a throwaway keypair.
+ *
+ * Use this for services that only need to read on-chain state (e.g. the
+ * price ingestion Lambda) and never sign transactions.
+ */
+function createReadOnlyAnchorProvider(env) {
+    return createDefaultAnchorProvider(env, web3_js_1.Keypair.generate());
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Process items from an async iterable with at most `concurrency` parallel workers.
+ * The source iterator is advanced serially; workers run in parallel up to the limit.
+ */
+export declare function runWithConcurrency<T>(source: AsyncIterable<T>, concurrency: number, worker: (item: T) => Promise<void>, onWorkerError?: (error: unknown) => void): Promise<void>;

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

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithConcurrency = runWithConcurrency;
+/**
+ * Process items from an async iterable with at most `concurrency` parallel workers.
+ * The source iterator is advanced serially; workers run in parallel up to the limit.
+ */
+async function runWithConcurrency(source, concurrency, worker, onWorkerError) {
+    const pending = new Set();
+    const logError = onWorkerError ??
+        ((e) => {
+            console.error("runWithConcurrency worker error", JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
+        });
+    for await (const item of source) {
+        if (pending.size >= concurrency) {
+            await Promise.race(pending);
+        }
+        const p = worker(item)
+            .catch((e) => {
+            logError(e);
+        })
+            .finally(() => {
+            pending.delete(p);
+        });
+        pending.add(p);
+    }
+    await Promise.all(pending);
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Kit <-> Web3.js compatibility helpers.
+ *
+ * These helpers bridge between Kit v2 types and web3.js v1 types,
+ * which is needed when using Kit with Anchor (which still uses web3.js v1).
+ */
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import { Address, AccountMeta, Instruction } from "@solana/kit";
+import { CustomAccountMeta } from "../types";
+/**
+ * Convert a Kit Address to a web3.js PublicKey.
+ *
+ * @param addr - Kit Address (base58 string branded type)
+ * @returns web3.js PublicKey
+ */
+export declare function toWeb3Pk(addr: Address): PublicKey;
+/**
+ * Convert a web3.js PublicKey to a Kit Address
+ *
+ * @param addr - web3.js PublicKey
+ * @returns Kit Address
+ */
+export declare function fromWeb3Pk(addr: PublicKey): Address;
+/**
+ * Convert a Kit AccountMeta to web3.js AccountMeta format.
+ *
+ * Kit uses an AccountRole enum, while web3.js uses isSigner/isWritable booleans.
+ * This is useful for Anchor's remainingAccounts which expects web3.js format.
+ *
+ * @param account - Kit AccountMeta
+ * @returns web3.js compatible AccountMeta
+ */
+export declare function toWeb3AccountMeta(account: AccountMeta | CustomAccountMeta): {
+    pubkey: PublicKey;
+    isSigner: boolean;
+    isWritable: boolean;
+};
+/**
+ * Convert a web3.js TransactionInstruction to Kit Instruction.
+ *
+ * This allows using Anchor-generated instructions with Kit's transaction building.
+ *
+ * @param ix - web3.js TransactionInstruction (from Anchor's .instruction())
+ * @returns Kit Instruction
+ */
+export declare function toKitInstruction(ix: TransactionInstruction): Instruction;

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

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Kit <-> Web3.js compatibility helpers.
+ *
+ * These helpers bridge between Kit v2 types and web3.js v1 types,
+ * which is needed when using Kit with Anchor (which still uses web3.js v1).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toWeb3Pk = toWeb3Pk;
+exports.fromWeb3Pk = fromWeb3Pk;
+exports.toWeb3AccountMeta = toWeb3AccountMeta;
+exports.toKitInstruction = toKitInstruction;
+const web3_js_1 = require("@solana/web3.js");
+const kit_1 = require("@solana/kit");
+/**
+ * Convert a Kit Address to a web3.js PublicKey.
+ *
+ * @param addr - Kit Address (base58 string branded type)
+ * @returns web3.js PublicKey
+ */
+function toWeb3Pk(addr) {
+    return new web3_js_1.PublicKey(addr);
+}
+/**
+ * Convert a web3.js PublicKey to a Kit Address
+ *
+ * @param addr - web3.js PublicKey
+ * @returns Kit Address
+ */
+function fromWeb3Pk(addr) {
+    return (0, kit_1.address)(addr.toString());
+}
+/**
+ * Convert a Kit AccountMeta to web3.js AccountMeta format.
+ *
+ * Kit uses an AccountRole enum, while web3.js uses isSigner/isWritable booleans.
+ * This is useful for Anchor's remainingAccounts which expects web3.js format.
+ *
+ * @param account - Kit AccountMeta
+ * @returns web3.js compatible AccountMeta
+ */
+function toWeb3AccountMeta(account) {
+    return {
+        pubkey: new web3_js_1.PublicKey(account.address),
+        isSigner: account.role === kit_1.AccountRole.READONLY_SIGNER || account.role === kit_1.AccountRole.WRITABLE_SIGNER,
+        isWritable: account.role === kit_1.AccountRole.WRITABLE || account.role === kit_1.AccountRole.WRITABLE_SIGNER,
+    };
+}
+/**
+ * Convert a web3.js TransactionInstruction to Kit Instruction.
+ *
+ * This allows using Anchor-generated instructions with Kit's transaction building.
+ *
+ * @param ix - web3.js TransactionInstruction (from Anchor's .instruction())
+ * @returns Kit Instruction
+ */
+function toKitInstruction(ix) {
+    return {
+        programAddress: ix.programId.toBase58(),
+        data: new Uint8Array(ix.data),
+        accounts: ix.keys.map((key) => ({
+            address: key.pubkey.toBase58(),
+            role: key.isWritable
+                ? key.isSigner
+                    ? kit_1.AccountRole.WRITABLE_SIGNER
+                    : kit_1.AccountRole.WRITABLE
+                : key.isSigner
+                    ? kit_1.AccountRole.READONLY_SIGNER
+                    : kit_1.AccountRole.READONLY,
+        })),
+    };
+}

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

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+/** Sentinel u16 value meaning "program must provide args." */
+export declare const SKIP_SENTINEL = 65535;
+/**
+ * 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
+ * ```
+ */
+export declare function serializeArgs(data?: Buffer | Uint8Array): Buffer;
+/**
+ * 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();
+ * ```
+ */
+export declare class CpiArgsBuilder {
+    private parts;
+    /**
+     * Add client-provided args for the next CPI slot.
+     * Automatically wraps with a u16 LE length prefix.
+     */
+    add(data: Buffer | Uint8Array): 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;
+    /**
+     * Mark the next CPI slot as program-provided (sentinel 0xFFFF).
+     * The Rust handler must compute args and call `invoke_cpi` directly.
+     */
+    skip(): this;
+    /** Build the final packed buffer. */
+    build(): Buffer;
+}