@picon-finance/dlmm-sdk 1.2.0 → 1.3.0

package/src/entities/position.ts

@@ -0,0 +1,444 @@
+import {
+  decodeAccount,
+  createSolanaRpc,
+  assertAccountExists,
+  fetchEncodedAccounts,
+  type Address,
+  type Account,
+  type Instruction,
+  type TransactionSigner,
+  type FetchAccountsConfig,
+  type MaybeEncodedAccount,
+} from "@solana/kit";
+
+import { generated } from "..";
+import {
+  findPositionTokenAccount,
+  processAssociatedTokenAccountPair,
+} from "../utils/ata";
+import {
+  getBinArrayIndex,
+  getPositionBinArrayIndices,
+  type BinIdRange,
+} from "../utils/bin_location";
+import {
+  assertRangeWithinRange,
+  assertPositionBelongsToPool,
+} from "../utils/assert";
+import { isUndefined } from "../utils/type_guards";
+import { fetchInChunks } from "../utils/chunk";
+import { resolveAdminConfigAddress } from "./admin_config";
+import { MAX_ACCOUNTS_PER_RPC_BATCH } from "../utils/constants";
+
+import { Pool } from "./pool";
+import {
+  BinArray,
+  decodeAllBinArrays,
+  createAllBinArrays,
+  fetchAllBinArraysChunked,
+} from "./bin_array";
+import { type ProgramConfig } from "./types";
+
+export class Position {
+  #pool: Pool;
+  #account: Account<generated.Position>;
+  #binArrays: BinArray[];
+
+  private constructor(
+    pool: Pool,
+    account: Account<generated.Position>,
+    binArrays: BinArray[],
+  ) {
+    this.#pool = pool;
+    this.#account = account;
+    this.#binArrays = binArrays;
+  }
+
+  public get address() { return this.#account.address; }
+  public get data() { return this.#account.data; }
+  public get positionMint() { return this.data.positionMint; }
+
+  public get binArrayAddresses(): { lowerBinArray: Address, upperBinArray?: Address | undefined } {
+    const lowerBinArray = this.#binArrays[0].address;
+    const upperBinArray = this.#binArrays.length > 1 ? this.#binArrays[1].address : undefined;
+    return { lowerBinArray, upperBinArray };
+  }
+
+  public async refresh(data: [Account<generated.Position>, Account<generated.BinArray>[]]): Promise<void>;
+  public async refresh(config?: FetchAccountsConfig): Promise<void>;
+  public async refresh(arg?: [Account<generated.Position>, Account<generated.BinArray>[]] | FetchAccountsConfig) {
+    if (!Array.isArray(arg)) {
+      arg = await fetchPositionWithBinArrays(
+        this.#pool.rpc,
+        this.address,
+        this.#binArrays.map(b => b.address),
+        arg,
+      );
+    }
+    const [position, binArrays] = arg;
+    this.#account = position;
+    this.#binArrays.forEach((b, i) => b.refresh(binArrays[i]));
+  }
+
+  public async depositByWeight(owner: TransactionSigner, {
+    amountX,
+    amountY,
+    lowerBinId,
+    binWeights,
+    maxActiveBinSlippage,
+    distributionMode,
+  }: {
+    amountX: bigint,
+    amountY: bigint,
+    lowerBinId: number,
+    binWeights: number[],
+    maxActiveBinSlippage: number,
+    distributionMode: generated.DistributionMode,
+  }): Promise<Instruction[]> {
+    const upperBinId = lowerBinId + binWeights.length - 1;
+    assertRangeWithinRange({ lowerBinId, upperBinId }, this.data);
+
+    const [positionTokenAccount, {
+      ataX: tokenOwnerAccountX,
+      ataY: tokenOwnerAccountY,
+      preInstructions,
+      postInstructions
+    }] = await Promise.all([
+      findPositionTokenAccount({ owner: owner.address, positionMint: this.data.positionMint }),
+      processAssociatedTokenAccountPair({
+        owner,
+        tokenMintX: this.#pool.tokenMintX,
+        tokenMintY: this.#pool.tokenMintY,
+        tokenProgramX: this.#pool.tokenProgramX,
+        tokenProgramY: this.#pool.tokenProgramY,
+        amountX,
+        amountY,
+      }),
+    ]);
+
+    const { lowerBinArray, upperBinArray } = this.binArrayAddresses;
+    const depositByWeightIx = generated.getDepositByWeightInstruction({
+      owner,
+      pool: this.#pool.address,
+      position: this.address,
+      positionTokenAccount,
+      tokenMintX: this.#pool.tokenMintX,
+      tokenMintY: this.#pool.tokenMintY,
+      tokenOwnerAccountX,
+      tokenOwnerAccountY,
+      tokenVaultX: this.#pool.tokenVaultX,
+      tokenVaultY: this.#pool.tokenVaultY,
+      tokenProgramX: this.#pool.tokenProgramX,
+      tokenProgramY: this.#pool.tokenProgramY,
+      lowerBinArray,
+      upperBinArray,
+      amountX,
+      amountY,
+      activeBinId: this.#pool.activeBinId,
+      maxActiveBinSlippage,
+      distributionMode,
+      lowerBinId,
+      binWeights,
+    }, {
+      programAddress: this.#pool.programAddress
+    });
+
+    return [...preInstructions, depositByWeightIx, ...postInstructions];
+  }
+
+  public async claimFee(
+    owner: TransactionSigner,
+    range?: BinIdRange,
+  ): Promise<Instruction[]> {
+    const { lowerBinId, upperBinId } = range ?? this.data;
+    assertRangeWithinRange({ lowerBinId, upperBinId }, this.data);
+
+    const [positionTokenAccount, {
+      ataX: tokenOwnerAccountX,
+      ataY: tokenOwnerAccountY,
+      preInstructions,
+      postInstructions
+    }] = await Promise.all([
+      findPositionTokenAccount({ owner: owner.address, positionMint: this.data.positionMint }),
+      processAssociatedTokenAccountPair({
+        owner,
+        tokenMintX: this.#pool.tokenMintX,
+        tokenMintY: this.#pool.tokenMintY,
+        tokenProgramX: this.#pool.tokenProgramX,
+        tokenProgramY: this.#pool.tokenProgramY,
+      }),
+    ]);
+
+    const { lowerBinArray, upperBinArray } = this.binArrayAddresses;
+    const claimFeeIx = generated.getClaimFeeInstruction({
+      owner,
+      pool: this.#pool.address,
+      position: this.address,
+      positionTokenAccount,
+      tokenMintX: this.#pool.tokenMintX,
+      tokenMintY: this.#pool.tokenMintY,
+      tokenOwnerAccountX,
+      tokenOwnerAccountY,
+      tokenVaultX: this.#pool.tokenVaultX,
+      tokenVaultY: this.#pool.tokenVaultY,
+      tokenProgramX: this.#pool.tokenProgramX,
+      tokenProgramY: this.#pool.tokenProgramY,
+      lowerBinArray,
+      upperBinArray,
+      lowerBinId,
+      upperBinId,
+    }, {
+      programAddress: this.#pool.programAddress
+    });
+
+    return [...preInstructions, claimFeeIx, ...postInstructions];
+  }
+
+  public async withdraw(
+    owner: TransactionSigner,
+    bpsToRemove: number,
+    range?: BinIdRange,
+  ): Promise<Instruction[]> {
+    const { lowerBinId, upperBinId } = range ?? this.data;
+    assertRangeWithinRange({ lowerBinId, upperBinId }, this.data);
+
+    const [positionTokenAccount, {
+      ataX: tokenOwnerAccountX,
+      ataY: tokenOwnerAccountY,
+      preInstructions,
+      postInstructions
+    }] = await Promise.all([
+      findPositionTokenAccount({ owner: owner.address, positionMint: this.data.positionMint }),
+      processAssociatedTokenAccountPair({
+        owner,
+        tokenMintX: this.#pool.tokenMintX,
+        tokenMintY: this.#pool.tokenMintY,
+        tokenProgramX: this.#pool.tokenProgramX,
+        tokenProgramY: this.#pool.tokenProgramY,
+      }),
+    ]);
+
+    const { lowerBinArray, upperBinArray } = this.binArrayAddresses;
+    const withdrawIx = generated.getWithdrawInstruction({
+      owner,
+      pool: this.#pool.address,
+      position: this.address,
+      positionTokenAccount,
+      tokenMintX: this.#pool.tokenMintX,
+      tokenMintY: this.#pool.tokenMintY,
+      tokenOwnerAccountX,
+      tokenOwnerAccountY,
+      tokenVaultX: this.#pool.tokenVaultX,
+      tokenVaultY: this.#pool.tokenVaultY,
+      tokenProgramX: this.#pool.tokenProgramX,
+      tokenProgramY: this.#pool.tokenProgramY,
+      lowerBinArray,
+      upperBinArray,
+      lowerBinId,
+      upperBinId,
+      bpsToRemove,
+    }, {
+      programAddress: this.#pool.programAddress
+    });
+
+    return [...preInstructions, withdrawIx, ...postInstructions];
+  }
+
+  public async close(owner: TransactionSigner): Promise<Instruction> {
+    return await closePosition(
+      { owner, positionMint: this.data.positionMint, position: this.address },
+      { programAddress: this.#pool.programAddress },
+    );
+  }
+
+  public static async load(
+    pool: Pool,
+    address: Address,
+    config?: FetchAccountsConfig,
+  ): Promise<Position> {
+    const position = await generated.fetchPosition(pool.rpc, address, config);
+    assertPositionBelongsToPool(position.data, pool);
+
+    const { lowerBinId, upperBinId } = position.data;
+    const indices = [...new Set([
+      getBinArrayIndex(lowerBinId),
+      getBinArrayIndex(upperBinId),
+    ])];
+    const binArrays = await BinArray.loadAll(
+      pool.rpc,
+      pool.address,
+      indices,
+      pool.programAddress,
+      config,
+    );
+
+    return new Position(pool, position, binArrays);
+  }
+
+  public static async loadAll(
+    pool: Pool,
+    addresses: Address[],
+    config?: FetchAccountsConfig,
+  ): Promise<Position[]> {
+    const positions = await fetchAllPositionsChunked(pool.rpc, addresses, config);
+
+    const indicesByPosition = positions.map(position =>
+      [...new Set([getBinArrayIndex(position.data.lowerBinId), getBinArrayIndex(position.data.upperBinId)])]);
+    const binArrays = await BinArray.loadAll(
+      pool.rpc,
+      pool.address,
+      [...new Set(indicesByPosition.flat())],
+      pool.programAddress, config,
+    );
+    const binArrayByIndex = new Map(binArrays.map(binArray => [binArray.data.index, binArray]));
+
+    return positions.map((position, i) => {
+      assertPositionBelongsToPool(position.data, pool);
+      const positionBinArrays = indicesByPosition[i].map(index => binArrayByIndex.get(index)!);
+      return new Position(pool, position, positionBinArrays);
+    });
+  }
+
+  public static async refreshAll(
+    rpc: ReturnType<typeof createSolanaRpc>,
+    positions: Position[],
+    config?: FetchAccountsConfig,
+  ): Promise<void> {
+    if (positions.length === 0) {
+      return;
+    }
+
+    const addresses = positions.map(position => position.address);
+    const positionAccounts = await fetchAllPositionsChunked(rpc, addresses, config);
+
+    const binArrayAddresses = [...new Set(positions.flatMap(position =>
+      position.#binArrays.map(binArray => binArray.address)))];
+    const binArrayAccounts = await fetchAllBinArraysChunked(rpc, binArrayAddresses, config);
+    const binArrayByAddress = new Map(binArrayAccounts.map(account => [account.address, account]));
+
+    await Promise.all(positions.map((position, i) => position.refresh([
+      positionAccounts[i],
+      position.#binArrays.map(binArray => binArrayByAddress.get(binArray.address)!),
+    ])));
+  }
+}
+
+export async function findPositionAddress(
+  seeds: { positionMint: Address },
+  config: ProgramConfig,
+): Promise<Address> {
+  const [address] = await generated.findPositionPda(seeds, config);
+  return address;
+}
+
+export async function findAllPositionAddresses(
+  { positionMints }: { positionMints: Address[] },
+  config: ProgramConfig,
+): Promise<Address[]> {
+  return await Promise.all(
+    positionMints.map(positionMint => findPositionAddress({ positionMint }, config))
+  );
+}
+
+export async function openPosition(
+  rpc: ReturnType<typeof createSolanaRpc>,
+  {
+    owner,
+    positionMint,
+    pool,
+    lowerBinId,
+    upperBinId,
+  }: {
+    owner: TransactionSigner,
+    positionMint: TransactionSigner,
+    pool: Address,
+    lowerBinId: number,
+    upperBinId: number,
+  },
+  config: ProgramConfig,
+): Promise<Instruction[]> {
+  const [adminConfig, position] = await Promise.all([
+    resolveAdminConfigAddress(config.programAddress),
+    findPositionAddress({ positionMint: positionMint.address }, config),
+  ]);
+  const { metadataUpdateAuthority } = (await generated.fetchAdminConfig(rpc, adminConfig)).data;
+  const { lowerBinArrayIndex, upperBinArrayIndex } = getPositionBinArrayIndices(lowerBinId, upperBinId);
+  const indices = isUndefined(upperBinArrayIndex) ? [lowerBinArrayIndex] : [lowerBinArrayIndex, upperBinArrayIndex];
+  const createBinArraysIxs = await createAllBinArrays(
+    { payer: owner, pool, indices, idempotent: true },
+    config,
+  );
+
+  const openPositionIx = await generated.getOpenPositionInstructionAsync({
+    pool,
+    lowerBinId,
+    upperBinId,
+    owner,
+    positionMint,
+    position,
+    adminConfig,
+    metadataUpdateAuthority,
+  }, config);
+
+  return [...createBinArraysIxs, openPositionIx];
+}
+
+export async function closePosition(
+  {
+    owner,
+    positionMint,
+    position,
+  }: {
+    owner: TransactionSigner,
+    positionMint: Address,
+    position?: Address,
+  },
+  config: ProgramConfig,
+): Promise<Instruction> {
+  const [resolvedPosition, positionTokenAccount] = await Promise.all([
+    position ?? findPositionAddress({ positionMint }, config),
+    findPositionTokenAccount({ owner: owner.address, positionMint }),
+  ]);
+  return await generated.getClosePositionInstructionAsync({
+    owner,
+    position: resolvedPosition,
+    positionMint,
+    positionTokenAccount,
+  }, config);
+}
+
+async function fetchPositionWithBinArrays(
+  rpc: ReturnType<typeof createSolanaRpc>,
+  positionAddress: Address,
+  binArrayAddresses: Address[],
+  config?: FetchAccountsConfig,
+): Promise<[Account<generated.Position>, Account<generated.BinArray>[]]> {
+  const [positionAccount, ...binArrayAccounts] = await fetchEncodedAccounts(rpc, [
+    positionAddress, ...binArrayAddresses,
+  ], config);
+  return [
+    decodePosition(positionAccount),
+    decodeAllBinArrays(binArrayAccounts)
+  ];
+}
+
+async function fetchAllPositionsChunked(
+  rpc: ReturnType<typeof createSolanaRpc>,
+  addresses: Address[],
+  config?: FetchAccountsConfig,
+) {
+  return await fetchInChunks(
+    addresses,
+    MAX_ACCOUNTS_PER_RPC_BATCH,
+    chunkAddresses => generated.fetchAllPosition(rpc, chunkAddresses, config),
+  );
+}
+
+const positionDecoder = generated.getPositionDecoder();
+
+function decodePosition(
+  maybeAccount: MaybeEncodedAccount<string>,
+): Account<generated.Position> {
+  assertAccountExists(maybeAccount);
+  return decodeAccount(maybeAccount, positionDecoder);
+}

package/src/entities/position_pool.ts

@@ -0,0 +1,68 @@
+import {
+  createSolanaRpc,
+  getAddressDecoder,
+  parseBase64RpcAccount,
+  type Address,
+  type AccountInfoBase,
+  type FetchAccountsConfig,
+  type AccountInfoWithBase64EncodedData,
+} from "@solana/kit";
+import { fetchInChunks } from "../utils/chunk";
+import { MAX_ACCOUNTS_PER_RPC_BATCH } from "../utils/constants";
+
+export type PositionPoolEntry = {
+  address: Address,
+  pool: Address,
+};
+
+export async function fetchAllMaybePositionPoolsChunked(
+  rpc: ReturnType<typeof createSolanaRpc>,
+  addresses: Address[],
+  config?: FetchAccountsConfig,
+): Promise<(PositionPoolEntry | undefined)[]> {
+  return await fetchInChunks(
+    addresses,
+    MAX_ACCOUNTS_PER_RPC_BATCH,
+    chunkAddresses => fetchAllMaybePositionPools(rpc, chunkAddresses, config),
+  );
+}
+
+const POSITION_POOL_SLICE = Object.freeze({ offset: 8, length: 32 });
+
+async function fetchAllMaybePositionPools(
+  rpc: ReturnType<typeof createSolanaRpc>,
+  addresses: Address[],
+  config?: FetchAccountsConfig,
+): Promise<(PositionPoolEntry | undefined)[]> {
+  const { abortSignal, ...rpcConfig } = config ?? {};
+  const { value: accounts } = await rpc.getMultipleAccounts(addresses, {
+    ...rpcConfig,
+    dataSlice: POSITION_POOL_SLICE,
+    encoding: "base64",
+  }).send({ abortSignal });
+
+  return decodeAllMaybePositionPools(addresses, accounts);
+}
+
+const addressDecoder = getAddressDecoder();
+
+function decodeMaybePositionPool(
+  address: Address,
+  account: (AccountInfoBase & AccountInfoWithBase64EncodedData | null),
+): PositionPoolEntry | undefined {
+  if (!account) {
+    return;
+  }
+  const pool = addressDecoder.decode(parseBase64RpcAccount(address, account).data);
+  return { address, pool };
+}
+
+function decodeAllMaybePositionPools(
+  addresses: Address[],
+  accounts: (AccountInfoBase & AccountInfoWithBase64EncodedData | null)[],
+): (PositionPoolEntry | undefined)[] {
+  return accounts.map((account, i) => {
+    const address = addresses[i];
+    return decodeMaybePositionPool(address, account);
+  });
+}

package/src/entities/types.ts

@@ -0,0 +1,3 @@
+import { type Address } from "@solana/kit";
+
+export type ProgramConfig = { programAddress: Address };

package/src/events.ts

@@ -6,6 +6,8 @@
 // `generated/types/*.ts` exactly for that reason.
 import {
   type Address,
+  type Commitment,
+  type createSolanaRpcSubscriptions,
   getAddressDecoder,
   getBase64Encoder,
   getBooleanDecoder,
@@ -277,3 +279,78 @@ export function decodeEventsFromLogs(logs: readonly string[], programAddress: Ad
   }
   return events;
 }
+
+type RpcSubscriptions = ReturnType<typeof createSolanaRpcSubscriptions>;
+
+// `address` defaults to `programAddress` (every pool the program touches); pass a pool
+// address to scope it. `programAddress` also scopes CPI-log filtering (see decodeEventsFromLogs
+// above), so it should match whatever cluster's program this subscription is watching —
+// defaults to mainnet. Resolves once the subscription is active, with an unsubscribe function.
+// Errors — from the stream itself (e.g. a dropped websocket) or thrown by `handler` — are
+// reported to `onError` instead of rejecting an unheld promise; a `handler` throw only drops
+// that one event, the subscription keeps running.
+export async function onEvent(
+  rpcSubscriptions: RpcSubscriptions,
+  handler: (event: DlmmEvent) => void,
+  {
+    address,
+    programAddress = PICON_DLMM_PROGRAM_ADDRESS,
+    commitment,
+    onError,
+  }: { address?: Address, programAddress?: Address, commitment?: Commitment, onError?: (error: unknown) => void } = {},
+): Promise<() => void> {
+  const abortController = new AbortController();
+  const eventStream = await subscribeToEvents(rpcSubscriptions, {
+    address: address ?? programAddress,
+    programAddress,
+    commitment,
+    abortSignal: abortController.signal,
+  });
+
+  (async () => {
+    try {
+      for await (const event of eventStream) {
+        try {
+          handler(event);
+        } catch (error) {
+          onError?.(error);
+        }
+      }
+    } catch (error) {
+      if (!abortController.signal.aborted) {
+        onError?.(error);
+      }
+    }
+  })();
+
+  return () => abortController.abort();
+}
+
+// Resolves once the subscription is active, so callers know they won't miss anything.
+async function subscribeToEvents(
+  rpcSubscriptions: RpcSubscriptions,
+  {
+    address,
+    programAddress,
+    commitment = "confirmed",
+    abortSignal,
+  }: {
+    address: Address,
+    programAddress: Address,
+    commitment?: Commitment,
+    abortSignal: AbortSignal,
+  },
+): Promise<AsyncIterable<DlmmEvent>> {
+  const notifications = await rpcSubscriptions
+    .logsNotifications({ mentions: [address] }, { commitment })
+    .subscribe({ abortSignal });
+
+  return (async function* () {
+    for await (const notification of notifications) {
+      if (notification.value.err != null) {
+        continue;
+      }
+      yield* decodeEventsFromLogs(notification.value.logs, programAddress);
+    }
+  })();
+}

package/src/index.ts

@@ -1,7 +1,8 @@
 export * as generated from "./generated";
 export { DistributionMode } from "./generated/types/distributionMode";
 export * as events from "./events";
+export * from "./entities";
 export * from "./utils/constants";
 export { NATIVE_MINT_ADDRESS } from "./utils/ata";
-export * from "./actions";
+export type { QuoteInput, QuoteOutput, PoolState, TransferFee } from "./quote";
 export * from "./program_addresses";

package/src/program_addresses.ts

@@ -1,10 +1,4 @@
 import { type Address } from "@solana/kit";
 
-// SDK codegen always targets the mainnet IDL (see package.json's `copy-idl`), so this is the
-// same value as `generated.PICON_DLMM_PROGRAM_ADDRESS` — exported under a clearer name here
-// since it's meant to be read standalone, not discovered via the generated namespace.
 export { PICON_DLMM_PROGRAM_ADDRESS as MAINNET_PROGRAM_ADDRESS } from "./generated";
-
-// Not baked into codegen (the IDL's structure is identical across clusters — only the address
-// differs) — pass this as the `programAddress` argument on any SDK action to target devnet.
 export const DEVNET_PROGRAM_ADDRESS = "tDLMMKoxBt7UkZapYHsEgLGydmFvSQXh5mGzrRovoeM" as Address;

package/src/utils/assert.ts

@@ -0,0 +1,25 @@
+import type { Address } from "@solana/kit";
+
+import type { BinIdRange } from "./bin_location";
+
+export function assertRangeWithinRange(
+  inner: BinIdRange,
+  outer: BinIdRange,
+): void {
+  if (inner.lowerBinId < outer.lowerBinId || inner.upperBinId > outer.upperBinId) {
+    throw new RangeError(
+      `Range (${inner.lowerBinId} to ${inner.upperBinId}) must be inside range (${outer.lowerBinId} to ${outer.upperBinId})`,
+    );
+  }
+}
+
+export function assertPositionBelongsToPool(
+  position: { pool: Address },
+  pool: { address: Address },
+): void {
+  if (position.pool !== pool.address) {
+    throw new Error(
+      `Position's pool (${position.pool}) does not match expected pool (${pool.address})`,
+    );
+  }
+}

package/src/utils/bin_location.ts

@@ -1,5 +1,10 @@
 import { BINS_PER_BIN_ARRAY } from "./constants";
 
+export type BinIdRange = {
+  lowerBinId: number,
+  upperBinId: number,
+};
+
 export function getBinArrayIndex(binId: number): number {
   return Math.floor(binId / BINS_PER_BIN_ARRAY);
 }
@@ -22,10 +27,6 @@ export function getBinArrayIndexSequence(
   );
 }
 
-// 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,
@@ -37,9 +38,6 @@ export function getPositionBinArrayIndices(
     : { 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,
@@ -52,11 +50,6 @@ export function generateBinArrayIndicesForSwap(
   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,