@kestrelfi/lyc-sdk 1.0.1

package/src/utils/tokenFeeMath.ts

@@ -0,0 +1,25 @@
+/**
+ * Collectable net yield in 8-decimal normalized USD: any carry surplus above
+ * debt. Returns `0n` when carry TVL does not exceed debt TVL.
+ *
+ * Used by SDK planning and metrics to size collect-interest attempts.
+ *
+ * @param totalCarryTvlUsd Aggregate carry-position TVL (8-dec USD).
+ * @param totalDebtUsd Aggregate lending-position debt TVL (8-dec USD).
+ */
+export function collectableNetYieldUsd(totalCarryTvlUsd: bigint, totalDebtUsd: bigint): bigint {
+  return totalCarryTvlUsd > totalDebtUsd ? totalCarryTvlUsd - totalDebtUsd : 0n;
+}
+
+export function splitFeeProportionally(
+  totalFee: bigint,
+  protocolBps: bigint,
+  curatorBps: bigint
+): [bigint, bigint] {
+  const splitBps = protocolBps + curatorBps;
+  if (splitBps === 0n) return [totalFee, 0n];
+
+  const curatorFee = (totalFee * curatorBps) / splitBps;
+  const protocolFee = totalFee - curatorFee;
+  return [protocolFee, curatorFee];
+}

package/src/utils/transactions.ts

@@ -0,0 +1,109 @@
+import {
+  type Address,
+  type KeyPairSigner,
+  type Signature,
+  generateKeyPairSigner,
+} from "@solana/kit";
+import { TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
+import { createMint } from "common";
+import type { LongYieldCarryClient } from "../client/client";
+import type { LongYieldCarryTransactionPlan } from "../client/types";
+import { findFreeTokenId } from "./data";
+
+/**
+ * Compose ordered phases into one bundle-ready plan without making an entire
+ * phase indivisible. Existing atomic segments are preserved, and each phase
+ * after the first is forced to start in a new transaction.
+ */
+export function composePhasedTransactionPlan(
+  phases: LongYieldCarryTransactionPlan[]
+): LongYieldCarryTransactionPlan {
+  if (phases.length === 0) {
+    throw new Error("Cannot compose an empty transaction phase list.");
+  }
+  if (phases.length === 1) {
+    return phases[0];
+  }
+
+  const segmentLengths: number[] = [];
+  const freshBinSegments = new Set<number>();
+  let segmentOffset = 0;
+
+  for (const [phaseIndex, phase] of phases.entries()) {
+    const phaseSegmentLengths =
+      phase.segmentLengths?.length === 0 || phase.segmentLengths === undefined
+        ? phase.instructions.map(() => 1)
+        : phase.segmentLengths;
+
+    if (phaseIndex > 0) {
+      freshBinSegments.add(segmentOffset);
+    }
+    for (const segmentIndex of phase.freshBinSegments ?? []) {
+      freshBinSegments.add(segmentOffset + segmentIndex);
+    }
+
+    segmentLengths.push(...phaseSegmentLengths);
+    segmentOffset += phaseSegmentLengths.length;
+  }
+
+  return {
+    instructions: phases.flatMap((phase) => phase.instructions),
+    lookupTables: [...new Set(phases.flatMap((phase) => phase.lookupTables ?? []))],
+    segmentLengths,
+    freshBinSegments: [...freshBinSegments].sort((a, b) => a - b),
+    postSuccessCacheInvalidations: phases.flatMap(
+      (phase) => phase.postSuccessCacheInvalidations ?? []
+    ),
+  };
+}
+
+export async function setTokenCircuitBreaker(
+  client: LongYieldCarryClient,
+  signer: KeyPairSigner,
+  token: Address,
+  active: boolean
+): Promise<Signature> {
+  const plan = await client.tx.setTokenCircuitBreaker.getTx({
+    authority: signer.address,
+    token,
+    active,
+  });
+  return client.sendTransaction(signer, plan);
+}
+
+export async function setYieldingBankCircuitBreaker(
+  client: LongYieldCarryClient,
+  signer: KeyPairSigner,
+  yieldingBank: Address,
+  active: boolean
+): Promise<Signature> {
+  const plan = await client.tx.setYieldingBankCircuitBreaker.getTx({
+    authority: signer.address,
+    yieldingBank,
+    active,
+  });
+  return client.sendTransaction(signer, plan);
+}
+
+/**
+ * Creates a new yToken SPL mint with mint authority = token PDA, using the next free token ID.
+ */
+export async function createYTokenMint(
+  client: LongYieldCarryClient,
+  payer: KeyPairSigner,
+  decimals: number = 6,
+  tokenProgram: Address = TOKEN_PROGRAM_ADDRESS
+): Promise<{
+  mintSigner: KeyPairSigner;
+  tokenPda: Address;
+  tokenPdaBump: number;
+  id: number;
+}> {
+  const mintSigner = await generateKeyPairSigner();
+  const id = await findFreeTokenId(client, mintSigner.address);
+  const [tokenPda, tokenPdaBump] = await client.pda.deriveTokenPda(mintSigner.address, id);
+
+  await createMint(client.rpc, payer, mintSigner, tokenPda, decimals, tokenProgram);
+
+  return { mintSigner, tokenPda, tokenPdaBump, id };
+}

package/src/utils/yieldingBank.ts

@@ -0,0 +1,38 @@
+import type { Address } from "@solana/kit";
+import { lendingPlatformToEnum, type LendingPlatform } from "common";
+import type { LYCToken } from "../models/lycToken";
+import type { LYCYieldingBank } from "../models/yieldingBank";
+
+/**
+ * Returns the first active yielding bank (circuit breaker off, lowest id).
+ *
+ * TODO: This naively returns the first active bank regardless of what the
+ * lending position actually borrows. It works today because there is one
+ * yielding bank (USDC) and all debt is denominated in USDC. When a second
+ * yielding bank exists (e.g. SOL-denominated) or a lending position borrows
+ * a non-USDC asset, the carry-manager would route that debt into the wrong
+ * bank. At that point this function needs to accept the lending position's
+ * debt mint and match it to the correct bank — either via the token's
+ * existing `debtCarry` entries or an explicit per-token bank configuration.
+ *
+ * @returns The yielding bank address, or `null` if no active bank exists.
+ */
+export function resolveYieldingBankForPosition(allBanks: LYCYieldingBank[]): Address | null {
+  const candidates = allBanks.filter((b) => b.circuitBreaker === 0).sort((a, b) => a.id - b.id);
+
+  return candidates[0]?.address ?? null;
+}
+
+/**
+ * Returns the index of the first active lending position for the given
+ * platform, or `null` if the token has no positions on that platform.
+ */
+export function firstActiveLendingIndex(token: LYCToken, platform: LendingPlatform): number | null {
+  const positions = token.data.lendingPositions;
+  for (let i = 0; i < positions.length; i++) {
+    if (lendingPlatformToEnum(positions[i].platform) === platform) {
+      return i;
+    }
+  }
+  return null;
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["es2020"],
+    "target": "es2020",
+    "strict": true,
+    "declaration": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*", "scripts/**/*"]
+}