@picon-finance/dlmm-sdk 1.0.0

package/src/utils/ata.ts

@@ -0,0 +1,213 @@
+import {
+  address,
+  type Address,
+  type Instruction,
+  type TransactionSigner,
+} from "@solana/kit";
+import {
+  findAssociatedTokenPda,
+  getCloseAccountInstruction,
+  getCreateAssociatedTokenIdempotentInstruction,
+  getSyncNativeInstruction,
+  TOKEN_PROGRAM_ADDRESS,
+} from "@solana-program/token";
+import {
+  findAssociatedTokenPda as findAssociatedToken2022Pda,
+  getCreateAssociatedTokenIdempotentInstruction as getCreateAssociatedToken2022IdempotentInstruction,
+  TOKEN_2022_PROGRAM_ADDRESS
+} from "@solana-program/token-2022";
+import { getTransferSolInstruction } from "@solana-program/system";
+
+export const NATIVE_MINT_ADDRESS = address("So11111111111111111111111111111111111111112");
+
+export async function findAssociatedTokenPdaByTokenProgram(params: {
+  owner: Address,
+  mint: Address,
+  tokenProgram: Address,
+}) {
+  const findAssociatedTokenPda = chooseFindAssociatedTokenPda(params.tokenProgram);
+  const [ata] = await findAssociatedTokenPda(params);
+  return ata;
+}
+
+// Position NFTs are always Token2022 — shared by every position-scoped instruction
+// (open_position, close_position, withdraw, claim_fee, claim_multiple_fees, deposit_by_weight).
+export function findPositionTokenAccount({
+  owner,
+  positionMint,
+}: {
+  owner: Address,
+  positionMint: Address,
+}): Promise<Address> {
+  return findAssociatedTokenPdaByTokenProgram({ owner, mint: positionMint, tokenProgram: TOKEN_2022_PROGRAM_ADDRESS });
+}
+
+// A pool's X/Y vaults — shared by every instruction that moves tokens through a pool
+// (withdraw, claim_fee, claim_multiple_fees, claim_protocol_fee, deposit_by_weight, swap).
+export async function findPoolTokenVaults({
+  pool,
+  tokenMintX,
+  tokenMintY,
+  tokenProgramX,
+  tokenProgramY,
+}: {
+  pool: Address,
+  tokenMintX: Address,
+  tokenMintY: Address,
+  tokenProgramX: Address,
+  tokenProgramY: Address,
+}): Promise<{ tokenVaultX: Address; tokenVaultY: Address }> {
+  const [tokenVaultX, tokenVaultY] = await Promise.all([
+    findAssociatedTokenPdaByTokenProgram({ owner: pool, mint: tokenMintX, tokenProgram: tokenProgramX }),
+    findAssociatedTokenPdaByTokenProgram({ owner: pool, mint: tokenMintY, tokenProgram: tokenProgramY }),
+  ]);
+  return { tokenVaultX, tokenVaultY };
+}
+
+interface ProcessAssociatedTokenAccountParams {
+  owner: TransactionSigner,
+  mint: Address,
+  amount?: bigint,
+  tokenProgram: Address,
+}
+
+interface ProcessAssociatedTokenAccountResult {
+  ata: Address,
+  preInstructions: Instruction[],
+  postInstructions: Instruction[],
+}
+
+export function processAssociatedTokenAccount(params: ProcessAssociatedTokenAccountParams): Promise<ProcessAssociatedTokenAccountResult> {
+  if (params.mint === NATIVE_MINT_ADDRESS) {
+    return processWsolAssociatedTokenAccount(params);
+  } else {
+    return processRegularAssociatedTokenAccount(params);
+  }
+}
+
+// Shared by every instruction that moves both X and Y through a single owner's ATAs
+// (swap, withdraw, claim_fee, claim_protocol_fee, deposit_by_weight, claim_multiple_fees) —
+// processes both sides and flattens their pre/post instructions in X-then-Y order.
+export async function processAssociatedTokenAccountPair({
+  owner,
+  tokenMintX,
+  tokenMintY,
+  tokenProgramX,
+  tokenProgramY,
+  amountX,
+  amountY,
+}: {
+  owner: TransactionSigner,
+  tokenMintX: Address,
+  tokenMintY: Address,
+  tokenProgramX: Address,
+  tokenProgramY: Address,
+  amountX?: bigint,
+  amountY?: bigint,
+}): Promise<{
+  ataX: Address,
+  ataY: Address,
+  preInstructions: Instruction[],
+  postInstructions: Instruction[],
+}> {
+  const [x, y] = await Promise.all([
+    processAssociatedTokenAccount({ owner, mint: tokenMintX, amount: amountX, tokenProgram: tokenProgramX }),
+    processAssociatedTokenAccount({ owner, mint: tokenMintY, amount: amountY, tokenProgram: tokenProgramY }),
+  ]);
+  return {
+    ataX: x.ata,
+    ataY: y.ata,
+    preInstructions: [...x.preInstructions, ...y.preInstructions],
+    postInstructions: [...x.postInstructions, ...y.postInstructions],
+  };
+}
+
+async function processWsolAssociatedTokenAccount({
+  owner,
+  amount,
+  tokenProgram,
+}: ProcessAssociatedTokenAccountParams): Promise<ProcessAssociatedTokenAccountResult> {
+  if (tokenProgram !== TOKEN_PROGRAM_ADDRESS) {
+    throw new Error("Invalid program for wSOL");
+  }
+  const { ata, instructions: wrapIxs } = await getWrapWsolInstructions(owner, amount);
+  const unwrapIx = getUnwrapWsolInstruction(owner, ata);
+  return {
+    ata,
+    preInstructions: wrapIxs,
+    postInstructions: [unwrapIx],
+  };
+}
+
+async function processRegularAssociatedTokenAccount({
+  owner,
+  mint,
+  tokenProgram,
+}: ProcessAssociatedTokenAccountParams): Promise<ProcessAssociatedTokenAccountResult> {
+  const [findAssociatedTokenPda, getCreateAssociatedTokenIdempotentInstruction] = choosePdaFunctions(tokenProgram);
+  const [ata] = await findAssociatedTokenPda({ mint, owner: owner.address, tokenProgram });
+  const createAtaIx = getCreateAssociatedTokenIdempotentInstruction({ ata, mint, owner: owner.address, payer: owner, tokenProgram });
+  return {
+    ata,
+    preInstructions: [createAtaIx],
+    postInstructions: [],
+  };
+}
+
+function choosePdaFunctions(tokenProgram: Address):
+  [typeof findAssociatedTokenPda, typeof getCreateAssociatedTokenIdempotentInstruction] |
+  [typeof findAssociatedToken2022Pda, typeof getCreateAssociatedToken2022IdempotentInstruction] {
+  switch (tokenProgram) {
+    case TOKEN_PROGRAM_ADDRESS: return [findAssociatedTokenPda, getCreateAssociatedTokenIdempotentInstruction];
+    case TOKEN_2022_PROGRAM_ADDRESS: return [findAssociatedToken2022Pda, getCreateAssociatedToken2022IdempotentInstruction];
+    default: throw new Error(`Unsupported token program: ${tokenProgram}`);
+  }
+}
+
+function chooseFindAssociatedTokenPda(tokenProgram: Address) {
+  return choosePdaFunctions(tokenProgram)[0];
+}
+
+async function getWrapWsolInstructions(
+  owner: TransactionSigner,
+  amount?: bigint,
+): Promise<{ ata: Address; instructions: Instruction[] }> {
+  const [ata] = await findAssociatedTokenPda({
+    mint: NATIVE_MINT_ADDRESS,
+    owner: owner.address,
+    tokenProgram: TOKEN_PROGRAM_ADDRESS,
+  });
+
+  const instructions = [
+    getCreateAssociatedTokenIdempotentInstruction({
+      ata,
+      mint: NATIVE_MINT_ADDRESS,
+      owner: owner.address,
+      payer: owner,
+      tokenProgram: TOKEN_PROGRAM_ADDRESS,
+    }),
+    ...(amount
+      ? [
+        getTransferSolInstruction({
+          source: owner,
+          destination: ata,
+          amount,
+        }),
+        getSyncNativeInstruction({ account: ata }),
+      ]
+      : []),
+  ];
+
+  return { ata, instructions };
+}
+
+function getUnwrapWsolInstruction(
+  owner: TransactionSigner,
+  ata: Address,
+) {
+  return getCloseAccountInstruction({
+    account: ata,
+    destination: owner.address,
+    owner,
+  });
+}

package/src/utils/bin_array.ts

@@ -0,0 +1,45 @@
+import { type Address } from "@solana/kit";
+import { findBinArrayPda } from "../generated";
+import { generateBinArrayIndicesForSwap, getPositionBinArrayIndices } from "./bin_location";
+import { MAX_BIN_ARRAYS_PER_SWAP } from "./constants";
+import { isUndefined } from "./type_guards";
+
+// Shared by every instruction that enumerates an arbitrary span of bin arrays as Anchor
+// `remaining_accounts` (swap, sync_pool), as opposed to the fixed lower/upper pair a
+// position-scoped instruction uses.
+export async function findBinArrayAddresses(pool: Address, indices: number[], programAddress: Address): Promise<Address[]> {
+  return Promise.all(indices.map(async index => (await findBinArrayPda({ pool, index }, { programAddress }))[0]));
+}
+
+// Pure local PDA derivation — no RPC. Shared by `swap` (which only needs the addresses for
+// remaining accounts) and `quote` (which additionally fetches each account's data).
+export function findSwapBinArrayAddresses(
+  pool: Address,
+  activeBinId: number,
+  xToY: boolean,
+  programAddress: Address,
+): Promise<Address[]> {
+  const binArrayIndices = generateBinArrayIndicesForSwap(activeBinId, xToY, MAX_BIN_ARRAYS_PER_SWAP);
+  return findBinArrayAddresses(pool, binArrayIndices, programAddress);
+}
+
+// Shared by every position-scoped instruction (open_position, deposit_by_weight, withdraw,
+// claim_fee) — derives the lower and (optionally) upper bin array covering the position's
+// range, matching the program's own `lowerBinArray` + `upperBinArray: Option<UncheckedAccount>`
+// account pair. `upperBinArray` is omitted when both ends fall in the same bin array.
+export async function findPositionBinArrayAddresses(
+  pool: Address,
+  lowerBinId: number,
+  upperBinId: number,
+  programAddress: Address,
+): Promise<{ lowerBinArray: Address; upperBinArray?: Address }> {
+  const { lowerBinArrayIndex, upperBinArrayIndex } = getPositionBinArrayIndices(lowerBinId, upperBinId);
+
+  const [lowerBinArray] = await findBinArrayPda({ pool, index: lowerBinArrayIndex }, { programAddress });
+  if (isUndefined(upperBinArrayIndex)) {
+    return { lowerBinArray };
+  }
+
+  const [upperBinArray] = await findBinArrayPda({ pool, index: upperBinArrayIndex }, { programAddress });
+  return { lowerBinArray, upperBinArray };
+}

package/src/utils/bin_location.ts

@@ -0,0 +1,79 @@
+import { BINS_PER_BIN_ARRAY } from "./constants";
+
+export function getBinArrayIndex(binId: number): number {
+  return Math.floor(binId / BINS_PER_BIN_ARRAY);
+}
+
+export function getBinIndex(binId: number): number {
+  return ((binId % BINS_PER_BIN_ARRAY) + BINS_PER_BIN_ARRAY) % BINS_PER_BIN_ARRAY;
+}
+
+export function getBinId(binArrayIndex: number, binIndex: number): number {
+  return binArrayIndex * BINS_PER_BIN_ARRAY + binIndex;
+}
+
+export function getBinArrayIndexSequence(
+  lowerBinArrayIndex: number,
+  upperBinArrayIndex: number,
+): number[] {
+  return Array.from(
+    { length: upperBinArrayIndex - lowerBinArrayIndex + 1 },
+    (_, i) => lowerBinArrayIndex + i
+  );
+}
+
+// A position spans at most MAX_BIN_ARRAYS_PER_POSITION (2) bin arrays — the lower and
+// (only if distinct) upper one covering its range. Shared by every position-scoped
+// instruction that needs to enumerate exactly those arrays (open_position's bin-array
+// bootstrap, withdraw/claim_fee's account derivation).
+export function getPositionBinArrayIndices(
+  lowerBinId: number,
+  upperBinId: number,
+): { lowerBinArrayIndex: number, upperBinArrayIndex?: number } {
+  const lowerBinArrayIndex = getBinArrayIndex(lowerBinId);
+  const upperBinArrayIndex = getBinArrayIndex(upperBinId);
+  return lowerBinArrayIndex === upperBinArrayIndex
+    ? { lowerBinArrayIndex }
+    : { lowerBinArrayIndex, upperBinArrayIndex };
+}
+
+// One bin array of margin is kept on the opposite side of travel: if the live active bin
+// drifts one array against the expected direction between quote time and execution (e.g. a
+// competing swap lands first), it's still covered by this range instead of reverting.
+export function generateBinArrayIndicesForSwap(
+  activeBinId: number,
+  xToY: boolean,
+  maxBinArrays: number,
+): number[] {
+  const activeBinArrayIndex = getBinArrayIndex(activeBinId);
+  const [lowerBinArrayIndex, upperBinArrayIndex] = xToY
+    ? [activeBinArrayIndex - (maxBinArrays - 2), activeBinArrayIndex + 1]
+    : [activeBinArrayIndex - 1, activeBinArrayIndex + (maxBinArrays - 2)];
+  return getBinArrayIndexSequence(lowerBinArrayIndex, upperBinArrayIndex);
+}
+
+// Spans from the live `activeBinId` to the caller's exact `desiredBinId` target, plus one
+// bin array of margin beyond the active end (the side subject to drift — `desiredBinId` is
+// a fixed target, but the live active bin could move further away from it before this tx
+// lands). Capped at `maxBinArrays`, trimming from the `desiredBinId` end so the active+margin
+// anchor stays intact — a sync toward a distant target simply converges partially in that case.
+export function generateBinArrayIndicesForSync(
+  activeBinId: number,
+  desiredBinId: number,
+  maxBinArrays: number,
+): number[] {
+  const activeBinArrayIndex = getBinArrayIndex(activeBinId);
+  const desiredBinArrayIndex = getBinArrayIndex(desiredBinId);
+  const xToY = desiredBinId <= activeBinId;
+
+  let lowerBinArrayIndex: number;
+  let upperBinArrayIndex: number;
+  if (xToY) {
+    upperBinArrayIndex = activeBinArrayIndex + 1;
+    lowerBinArrayIndex = Math.max(desiredBinArrayIndex, upperBinArrayIndex - maxBinArrays + 1);
+  } else {
+    lowerBinArrayIndex = activeBinArrayIndex - 1;
+    upperBinArrayIndex = Math.min(desiredBinArrayIndex, lowerBinArrayIndex + maxBinArrays - 1);
+  }
+  return getBinArrayIndexSequence(lowerBinArrayIndex, upperBinArrayIndex);
+}

package/src/utils/chunk.ts

@@ -0,0 +1,7 @@
+export function chunk<T>(items: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    chunks.push(items.slice(i, i + size));
+  }
+  return chunks;
+}

package/src/utils/compute_budget.ts

@@ -0,0 +1,58 @@
+import {
+  getSetComputeUnitLimitInstruction,
+  getSetComputeUnitPriceInstruction,
+} from "@solana-program/compute-budget";
+import {
+  createSolanaRpc,
+  estimateComputeUnitLimitFactory,
+  prependTransactionMessageInstructions,
+  type TransactionMessage,
+  type TransactionMessageWithFeePayer,
+} from "@solana/kit";
+import { isUndefined } from "./type_guards";
+
+export function withComputeBudget<TTransactionMessage extends TransactionMessage>(
+  message: TTransactionMessage,
+  {
+    computeUnitLimit,
+    computeUnitPrice,
+  }: {
+    computeUnitLimit?: number,
+    computeUnitPrice?: bigint,
+  } = {},
+): TTransactionMessage {
+  const ixs = [
+    ...(isUndefined(computeUnitLimit) ? [] : [getSetComputeUnitLimitInstruction({ units: computeUnitLimit })]),
+    ...(isUndefined(computeUnitPrice) ? [] : [getSetComputeUnitPriceInstruction({ microLamports: computeUnitPrice })]),
+  ];
+  return prependTransactionMessageInstructions(ixs, message) as TTransactionMessage;
+}
+
+export async function withEstimatedComputeBudget<
+  TTransactionMessage extends TransactionMessage & TransactionMessageWithFeePayer
+>(
+  rpc: ReturnType<typeof createSolanaRpc>,
+  message: TTransactionMessage,
+  {
+    estimateComputeUnitPrice,
+    estimateComputeUnitLimit,
+    bufferFactor = 1.1,
+  }: {
+    estimateComputeUnitPrice?: bigint | ((computeUnitLimit: number) => bigint),
+    estimateComputeUnitLimit?: ReturnType<typeof estimateComputeUnitLimitFactory>,
+    bufferFactor?: number,
+  } = {},
+): Promise<TTransactionMessage> {
+  estimateComputeUnitLimit = estimateComputeUnitLimit ?? estimateComputeUnitLimitFactory({ rpc });
+
+  const computeUnitBase = await estimateComputeUnitLimit(message);
+  const computeUnitLimit = Math.ceil(computeUnitBase * bufferFactor);
+  const computeUnitPrice = estimateComputeUnitPrice instanceof Function
+    ? estimateComputeUnitPrice(computeUnitLimit)
+    : estimateComputeUnitPrice;
+
+  return withComputeBudget(message, {
+    computeUnitLimit: computeUnitLimit,
+    computeUnitPrice,
+  });
+}

package/src/utils/constants.ts

@@ -0,0 +1,24 @@
+import IDL from "./../picon_dlmm.json";
+import { isUndefined } from "./type_guards";
+
+function getIdlConstant(name: string): number {
+  const constant = IDL.constants.find(c => c.name === name);
+  if (isUndefined(constant)) throw new Error(`${name} constant not found in IDL`);
+  return Number.parseInt(constant.value);
+}
+
+export const BINS_PER_BIN_ARRAY = getIdlConstant("BINS_PER_BIN_ARRAY");
+export const MAX_BIN_ARRAYS_PER_POSITION = getIdlConstant("MAX_BIN_ARRAYS_PER_POSITION");
+export const MAX_BIN_ARRAYS_PER_SWAP = getIdlConstant("MAX_BIN_ARRAYS_PER_SWAP");
+export const MAX_BIN_ARRAYS_PER_SYNC = getIdlConstant("MAX_BIN_ARRAYS_PER_SYNC");
+
+export const FEE_PRECISION = getIdlConstant("FEE_PRECISION");
+export const ONE_BPS_FEE_RATE = getIdlConstant("ONE_BPS_FEE_RATE");
+export const MAX_FEE_RATE = getIdlConstant("MAX_FEE_RATE");
+export const MAX_PROTOCOL_SHARE = getIdlConstant("MAX_PROTOCOL_SHARE");
+export const MAX_BASIS_POINTS = getIdlConstant("MAX_BASIS_POINTS");
+
+export const MAX_POSITIONS_PER_CLAIM = 3;
+
+// Solana RPC's own hard cap on addresses per getMultipleAccounts request.
+export const MAX_ACCOUNTS_PER_RPC_BATCH = 100;

package/src/utils/transfer_fee.ts

@@ -0,0 +1,29 @@
+import { unwrapOption } from "@solana/kit";
+import { type Mint, type Extension } from "@solana-program/token-2022";
+import type { TransferFee } from "../quote";
+
+function isTransferFeeConfig(
+  extension: Extension,
+): extension is Extract<Extension, { __kind: "TransferFeeConfig" }> {
+  return extension.__kind === "TransferFeeConfig";
+}
+
+// TransferFeeConfig carries two rates — olderTransferFee/newerTransferFee — so the
+// program can phase in a fee change without retroactively affecting in-flight swaps.
+// newerTransferFee takes effect once the current epoch reaches its `epoch` field.
+export function resolveTransferFee(mint: Mint, epoch: bigint): TransferFee | undefined {
+  const extensions = unwrapOption(mint.extensions) ?? [];
+  const transferFeeConfig = extensions.find(isTransferFeeConfig);
+  if (!transferFeeConfig) {
+    return undefined;
+  }
+
+  const activeTransferFee = epoch >= transferFeeConfig.newerTransferFee.epoch
+    ? transferFeeConfig.newerTransferFee
+    : transferFeeConfig.olderTransferFee;
+
+  return {
+    feeBps: activeTransferFee.transferFeeBasisPoints,
+    maxFee: activeTransferFee.maximumFee,
+  };
+}

package/src/utils/type_guards.ts

@@ -0,0 +1,3 @@
+export function isUndefined<T>(value: T | undefined): value is undefined {
+  return value === undefined;
+}