@kestrelfi/lyc-sdk 1.0.1

package/src/services/lendingPosition/lendingPositionService.ts

@@ -0,0 +1,328 @@
+import { type Address, type TransactionSigner } from "@solana/kit";
+import { fromWeb3Pk, LendingPlatform, mints, toBigInt } from "common";
+import type { LongYieldCarryClient } from "../../client/client";
+import type { LongYieldCarryTransactionPlan } from "../../client/types";
+import { LendingPositionBootstrapError } from "../../errors";
+import type { IndexedLendingPosition, LYCToken } from "../../models/lycToken";
+import {
+  getAvailableTokenLendingUserAccountId,
+  resolveDefaultPool,
+  updateTokenLutIfNeeded,
+} from "../../utils";
+import { AllocationService } from "../allocation";
+import { computeConfigForCollateral } from "../carry/carryAllocationConfig";
+
+export interface OptimalLendingPosition {
+  /** The lending position selected. */
+  lp: IndexedLendingPosition;
+  /** Debt mint of the selected position. */
+  debtMint: Address;
+  /** Human-readable symbol of the debt mint. */
+  debtSymbol: string;
+  /** Whether this position uses the optimal debt mint (true) or is the best available fallback. */
+  isOptimal: boolean;
+}
+
+type LogFn = (msg: string) => void;
+
+export interface EnsureInitialKaminoLendingPositionOptions {
+  manager: TransactionSigner;
+  /** When set, refreshes the per-token LUT after the new LP is created. */
+  lutManager?: TransactionSigner;
+  token: LYCToken;
+  sendPlan: (plan: LongYieldCarryTransactionPlan, label: string) => Promise<void>;
+  log?: LogFn;
+}
+
+/**
+ * Shared logic for choosing and interacting with a token's lending positions
+ * based on allocation optimality. Used by {@link RedemptionService} (to
+ * prioritize which positions to unwind) and by deposit scripts / backend
+ * services (to deposit into the best position).
+ */
+export class LendingPositionService {
+  constructor(private readonly client: LongYieldCarryClient) {}
+
+  /**
+   * Returns the lending position whose debt mint matches the current optimal
+   * allocation. If no position matches the optimal mint, returns the position
+   * with the most collateral as a fallback.
+   *
+   * Returns `null` only when the token has no active lending positions.
+   */
+  async findOptimalLendingPosition(
+    token: LYCToken,
+    log?: LogFn
+  ): Promise<OptimalLendingPosition | null> {
+    const usedLps = token.usedLendingPositions;
+    if (usedLps.length === 0) {
+      const activeLps = token.activeLendingPositions;
+      if (activeLps.length === 0) return null;
+      // Freshly created slots have zero collateral until the first deposit.
+      log?.("No collateral on any LP yet — using first active slot");
+      return this.toLpResult(activeLps[0], true);
+    }
+
+    if (usedLps.length === 1) {
+      return this.toLpResult(usedLps[0], true);
+    }
+
+    const optimalMint = await this.findOptimalDebtMint(token, log);
+    if (optimalMint) {
+      const match = usedLps.find(
+        (lp) => fromWeb3Pk(lp.data.accounting.debt.mint) === optimalMint.mint
+      );
+      if (match) {
+        log?.(`Using optimal LP[${match.index}] (debt: ${optimalMint.symbol})`);
+        return this.toLpResult(match, true);
+      }
+      log?.(`No LP matches optimal debt mint ${optimalMint.symbol} — using largest LP`);
+    }
+
+    const largest = this.largestLp(usedLps);
+    return this.toLpResult(largest, false);
+  }
+
+  /**
+   * Sorts lending positions so non-optimal debt mints come first. Useful for
+   * choosing which positions to unwind during redemptions — non-optimal
+   * positions are unwound first to preserve the best-yielding ones.
+   *
+   * Returns the original order if there's only one LP or the optimal mint
+   * lookup fails.
+   */
+  async sortByOptimality(
+    token: LYCToken,
+    lps: IndexedLendingPosition[],
+    log?: LogFn
+  ): Promise<IndexedLendingPosition[]> {
+    if (lps.length <= 1) return lps;
+
+    const optimalMint = await this.findOptimalDebtMint(token, log);
+    if (!optimalMint) return lps;
+
+    log?.(`Optimal debt mint: ${optimalMint.symbol} — prioritizing non-optimal LPs for unwind`);
+
+    const nonOptimal = lps.filter(
+      (lp) => fromWeb3Pk(lp.data.accounting.debt.mint) !== optimalMint.mint
+    );
+    const optimal = lps.filter(
+      (lp) => fromWeb3Pk(lp.data.accounting.debt.mint) === optimalMint.mint
+    );
+    return [...nonOptimal, ...optimal];
+  }
+
+  /**
+   * Opens the first Kamino lending position on a token that has none yet.
+   *
+   * Mirrors `scripts/createTokenLendingPosition.ts` and the create-LP branch in
+   * `TokenRebalanceWorker`: resolve pool + optimal debt mint, compute carry
+   * allocation config, send `createTokenLendingPosition`, then refetch the token.
+   *
+   * Kamino-specific: the flow resolves the default Kamino pool, fetches Kamino
+   * reserves, and uses {@link AllocationService} over Kamino reserve data. It is
+   * named accordingly until a second lending platform actually needs bootstrap
+   * support (avoid speculative platform abstraction with a single implementation).
+   *
+   * No-op when the token already has at least one active lending position slot.
+   *
+   * @throws {LendingPositionBootstrapError} when the token cannot be bootstrapped
+   *   because of a permanent configuration gap (collateral mint not in any pool,
+   *   no preset, no viable debt mint / reserve). Callers should treat this as a
+   *   skip rather than a retryable failure.
+   */
+  async ensureInitialKaminoLendingPosition(
+    options: EnsureInitialKaminoLendingPositionOptions
+  ): Promise<LYCToken> {
+    const { manager, lutManager, token, sendPlan, log } = options;
+
+    if (token.activeLendingPositions.length > 0) {
+      return token;
+    }
+
+    log?.("No lending positions — creating initial LP");
+
+    let pool: Address;
+    try {
+      pool = resolveDefaultPool(token.collateralMint);
+    } catch (err) {
+      throw new LendingPositionBootstrapError(
+        `Cannot resolve a default pool for ${token.label} (${token.collateralMint}): ${
+          err instanceof Error ? err.message : String(err)
+        }`
+      );
+    }
+
+    const kamino = this.client.getLendingPlatformClientByPlatform(LendingPlatform.Kamino);
+    const collateralReserve = await kamino.data.fetchReserveByMint(pool, token.collateralMint);
+    if (!collateralReserve) {
+      throw new LendingPositionBootstrapError(
+        `No Kamino reserve found for collateral ${token.label} (${token.collateralMint}) in pool ${pool}`
+      );
+    }
+
+    const yieldingBanks = await this.client.account.fetchAllYieldingBanks();
+    const allocationService = new AllocationService(kamino.data, { logger: log, yieldingBanks });
+    const optimalDebt = await allocationService.findOptimalDebtMint(pool, collateralReserve, token);
+    if (!optimalDebt) {
+      throw new LendingPositionBootstrapError(
+        `No viable debt mint found for ${token.label} on pool ${pool}`
+      );
+    }
+
+    log?.(
+      `Selected debt mint ${optimalDebt.symbol} (borrow APY ${(optimalDebt.borrowApy * 100).toFixed(3)}%)`
+    );
+
+    const debtReserve = await kamino.data.fetchReserveByMint(pool, optimalDebt.mint);
+    if (!debtReserve) {
+      throw new LendingPositionBootstrapError(
+        `No Kamino reserve found for debt mint ${optimalDebt.symbol} (${optimalDebt.mint})`
+      );
+    }
+
+    let config: ReturnType<typeof computeConfigForCollateral>;
+    try {
+      config = computeConfigForCollateral({
+        collateralMint: token.collateralMint,
+        collateralReserve,
+        debtReserve,
+      });
+    } catch (err) {
+      throw new LendingPositionBootstrapError(
+        `No carry allocation config for ${token.label} (${token.collateralMint}): ${
+          err instanceof Error ? err.message : String(err)
+        }`
+      );
+    }
+
+    const userAccountId = await getAvailableTokenLendingUserAccountId({
+      lendingClient: kamino,
+      token,
+      pool,
+    });
+
+    const label = `create-initial-lp-${token.label}-${optimalDebt.symbol}`;
+    const plan = await this.client.tx.createTokenLendingPosition.getTx({
+      token: token.address,
+      debtMint: optimalDebt.mint,
+      userAccountId,
+      pool,
+      ...config,
+    });
+    await sendPlan(plan, label);
+    log?.(`Sent createTokenLendingPosition (${plan.instructions.length} ix)`);
+
+    this.client.clearAllCache();
+    const freshToken = await this.client.account.fetchToken(token.address, { fresh: true });
+
+    if (lutManager) {
+      try {
+        await updateTokenLutIfNeeded(lutManager, this.client.rpc, this.client, freshToken);
+        log?.("Updated per-token LUT after initial lending position");
+      } catch (err) {
+        log?.(`updateTokenLutIfNeeded failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    if (freshToken.activeLendingPositions.length === 0) {
+      throw new Error(
+        `Initial lending position creation completed but ${token.label} still has no active LPs`
+      );
+    }
+
+    return freshToken;
+  }
+
+  /**
+   * Deposits unlent collateral into the optimal lending position. Refreshes
+   * the token state first, then deposits all unlent collateral into the
+   * position returned by {@link findOptimalLendingPosition}.
+   */
+  async depositToOptimalPosition(
+    signer: TransactionSigner,
+    token: LYCToken,
+    log?: LogFn
+  ): Promise<{ signature: string; lendingPositionIndex: number; debtSymbol: string }> {
+    const optimal = await this.findOptimalLendingPosition(token, log);
+    if (!optimal) {
+      throw new Error(`Token ${token.address} has no used lending positions to deposit into`);
+    }
+
+    log?.(
+      `Depositing unlent collateral into LP[${optimal.lp.index}] (debt: ${optimal.debtSymbol})...`
+    );
+
+    const refreshPlan = await this.client.tx.refreshTokens.getTx({
+      signer: signer.address,
+      params: { tokens: [token.address] },
+    });
+    await this.client.sendTransaction(signer, refreshPlan);
+    this.client.clearAllCache();
+
+    const depositPlan = await this.client.tx.depositUnlentCollateral.getTx({
+      manager: signer.address,
+      token: token.address,
+      params: {
+        lendingPositionIndex: optimal.lp.index,
+        depositAll: true,
+      },
+    });
+    const sig = await this.client.sendTransaction(signer, depositPlan);
+    this.client.clearAllCache();
+    log?.(`Deposit done: ${sig}`);
+
+    return {
+      signature: sig,
+      lendingPositionIndex: optimal.lp.index,
+      debtSymbol: optimal.debtSymbol,
+    };
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────
+
+  /**
+   * Queries `AllocationService.findOptimalDebtMint` for the token's
+   * pool + collateral pair. Returns null on any failure (missing reserve, etc.).
+   */
+  private async findOptimalDebtMint(
+    token: LYCToken,
+    log?: LogFn
+  ): Promise<{ mint: Address; symbol: string } | null> {
+    try {
+      const firstLp = token.usedLendingPositions[0]?.data;
+      if (!firstLp) return null;
+
+      const pool = fromWeb3Pk(firstLp.pool);
+      const kaminoData = this.client.getLendingPlatformClientByPlatform(
+        LendingPlatform.Kamino
+      ).data;
+      const collateralReserve = await kaminoData.fetchReserve(
+        pool,
+        fromWeb3Pk(firstLp.collateralReserve)
+      );
+      if (!collateralReserve) return null;
+
+      const yieldingBanks = await this.client.account.fetchAllYieldingBanks();
+      const allocationService = new AllocationService(kaminoData, { yieldingBanks });
+      return await allocationService.findOptimalDebtMint(pool, collateralReserve, token);
+    } catch (err) {
+      log?.(`Optimal debt mint lookup failed: ${err instanceof Error ? err.message : err}`);
+      return null;
+    }
+  }
+
+  private largestLp(lps: IndexedLendingPosition[]): IndexedLendingPosition {
+    return lps.reduce((best, lp) =>
+      toBigInt(lp.data.accounting.collateral) > toBigInt(best.data.accounting.collateral)
+        ? lp
+        : best
+    );
+  }
+
+  private toLpResult(lp: IndexedLendingPosition, isOptimal: boolean): OptimalLendingPosition {
+    const debtMint = fromWeb3Pk(lp.data.accounting.debt.mint);
+    const debtSymbol = mints.get(debtMint)?.symbol ?? debtMint.slice(0, 6);
+    return { lp, debtMint, debtSymbol, isOptimal };
+  }
+}

package/src/services/rebalance/index.ts

@@ -0,0 +1,2 @@
+export * from "./token";
+export * from "./yieldingBank";

package/src/services/rebalance/token/index.ts

@@ -0,0 +1 @@
+export * from "./tokenRebalanceService";

package/src/services/rebalance/token/tokenRebalanceService.ts

@@ -0,0 +1,142 @@
+import type { Address } from "@solana/kit";
+import { ExactInQuoteExceedsMaxInputError } from "jupiter-helpers";
+import { FlashRebalanceSwapCostExceededError } from "lending-platforms";
+import { NoOpTransactionError } from "../../../errors";
+import type { LYCToken } from "../../../models/lycToken";
+import type { LongYieldCarryTransactionPlan } from "../../../client/types";
+import type { DebtAllocationTarget, DebtReallocation } from "../../allocation/types";
+import type { LongYieldCarryClient } from "../../../client/client";
+import { REBALANCE_TOKEN_RATE_LIMIT_SECS } from "../../../constants/general";
+import { mints } from "common";
+
+export type RebalancePlanResult =
+  | { outcome: "skipped"; reason: string }
+  | { outcome: "plan"; plan: LongYieldCarryTransactionPlan; label: string };
+
+/**
+ * Shared logic for building a token rebalance plan from a {@link DebtReallocation}.
+ * Callers are responsible for sending the returned plan (and any post-send steps such as
+ * excess-rent reclaim).
+ */
+export interface TokenRebalanceServiceOptions {
+  /**
+   * Maximum acceptable execution cost (route fees + price impact) of the
+   * rebalance swap quote vs the oracle-fair cross rate, in bps. Candidates
+   * quoting worse are skipped — that cost is permanently lost value.
+   * Unset = no limit.
+   */
+  maxSwapCostBps?: number;
+  /**
+   * Maximum acceptable market basis between the two debt stables, in bps
+   * either direction. Bounds how much mark-to-market difference the $1-pinned
+   * books absorb per conversion, and blocks rebalancing through a depegging
+   * stable. Unset = no limit.
+   */
+  maxMarketBasisBps?: number;
+}
+
+export class TokenRebalanceService {
+  constructor(
+    private readonly client: LongYieldCarryClient,
+    private readonly options: TokenRebalanceServiceOptions = {}
+  ) {}
+
+  /**
+   * Validates a reallocation and builds the rebalance transaction plan.
+   * If the primary targets fail due to insufficient borrow/swap capacity
+   * ({@link ExactInQuoteExceedsMaxInputError}), retries with each fallback
+   * option in order before giving up.
+   *
+   * Returns `{ outcome: "skipped" }` for benign no-ops (inactive token, no active LP for the
+   * reallocation index, no targets). Throws on unexpected errors from the builder.
+   */
+  async buildPlan(token: LYCToken, realloc: DebtReallocation): Promise<RebalancePlanResult> {
+    if (!token.isActive) {
+      return { outcome: "skipped", reason: "token inactive (circuit breaker)" };
+    }
+
+    const lpIndex = realloc.lendingPositionIndex;
+    const lp = token.activeLendingPositions.find((p) => p.index === lpIndex);
+    if (!lp) {
+      return { outcome: "skipped", reason: `no active lending position at index ${lpIndex}` };
+    }
+
+    // Rate limit: the program rejects a rebalance on a position touched within
+    // REBALANCE_TOKEN_RATE_LIMIT_SECS (RebalanceRateLimited). Skip client-side
+    // so we don't build a transaction that would revert on-chain.
+    const lastUpdatedTs = Number(lp.data.lastUpdatedTs.toString());
+    const nowSecs = Math.floor(Date.now() / 1000);
+    const elapsed = nowSecs - lastUpdatedTs;
+    if (lastUpdatedTs > 0 && elapsed < REBALANCE_TOKEN_RATE_LIMIT_SECS) {
+      const hoursLeft = ((REBALANCE_TOKEN_RATE_LIMIT_SECS - elapsed) / 3600).toFixed(1);
+      const reason =
+        `lp${lpIndex} rebalanced ${(elapsed / 3600).toFixed(1)}h ago; ` +
+        `rate limit is ${REBALANCE_TOKEN_RATE_LIMIT_SECS / 3600}h (${hoursLeft}h remaining)`;
+      console.log(`Skip token ${token.address.slice(0, 8)}…: ${reason}`);
+      return { outcome: "skipped", reason };
+    }
+
+    const label = `rebalance-token-${token.address.slice(0, 8)}-lp${lpIndex}`;
+    const allOptions = [realloc.targets, ...(realloc.fallbackTargets ?? [])];
+
+    for (const targets of allOptions) {
+      const targetMint = targets[0]?.mint;
+      if (!targetMint) continue;
+
+      try {
+        const plan = await this.client.tx.rebalanceToken.getTx({
+          token: token.address,
+          params: {
+            lpIndex,
+            destinationDebtMint: targetMint,
+            uiAmount: "all",
+            maxSwapCostBps: this.options.maxSwapCostBps,
+            maxMarketBasisBps: this.options.maxMarketBasisBps,
+          },
+        });
+        return { outcome: "plan", plan, label };
+      } catch (err) {
+        if (err instanceof NoOpTransactionError) {
+          return { outcome: "skipped", reason: err.message };
+        }
+        if (err instanceof FlashRebalanceSwapCostExceededError) {
+          const symbol = mints.get(targetMint)?.symbol ?? targetMint.slice(0, 6);
+          console.log(
+            `Skip ${symbol}: swap ${err.reason} over ${err.limitBps} bps limit ` +
+              `(execution cost ${err.executionCostBps.toFixed(2)} bps, ` +
+              `market basis ${err.marketBasisBps.toFixed(2)} bps); trying next candidate`
+          );
+          continue;
+        }
+        if (err instanceof ExactInQuoteExceedsMaxInputError) {
+          const symbol = mints.get(targetMint)?.symbol ?? targetMint.slice(0, 6);
+          console.log(
+            `Skip ${symbol}: borrow capacity (${err.maxInputAmount}) < swap input (${err.inputAmount}); trying next candidate`
+          );
+          continue;
+        }
+        if (err instanceof Error && err.message.includes("no available borrow capacity")) {
+          const symbol = mints.get(targetMint)?.symbol ?? targetMint.slice(0, 6);
+          console.log(`Skip ${symbol}: no available borrow capacity; trying next candidate`);
+          continue;
+        }
+        throw err;
+      }
+    }
+
+    return {
+      outcome: "skipped",
+      reason:
+        "all candidates exhausted — insufficient borrow/swap capacity or swap cost above limit for each",
+    };
+  }
+
+  /** Convenience: fetch a fresh token then call {@link buildPlan}. */
+  async fetchAndBuildPlan(
+    tokenAddress: Address,
+    realloc: DebtReallocation
+  ): Promise<RebalancePlanResult> {
+    const token = await this.client.account.fetchToken(tokenAddress, { fresh: true });
+    return this.buildPlan(token, realloc);
+  }
+}

package/src/services/rebalance/yieldingBank/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./strategy";
+export { RebalancePlanner } from "./planner";

package/src/services/rebalance/yieldingBank/planner.ts

@@ -0,0 +1,215 @@
+import type { Address } from "@solana/kit";
+import { PublicKey } from "@solana/web3.js";
+import { applyBps, fromWeb3Pk, toBigInt } from "common";
+import type { RebalanceSwapSpec, YieldingBankAllocationConfig } from "../../../client/types";
+import type { LYCYieldingBank } from "../../../models";
+import type { AllocationStrategy } from "./strategy";
+import type { AllocationTarget, YieldingBankRebalancePlan } from "./types";
+
+/** Minimum 6-decimal stablecoin amount worth swapping: 0.01 token (~$0.01). */
+const MIN_STABLE_SWAP_AMOUNT = 10_000;
+
+interface HoldingSnapshot {
+  mint: Address;
+  amount: bigint;
+}
+
+/**
+ * Computes the swaps needed to move a yielding bank from its current
+ * asset distribution to a target allocation.
+ *
+ * The planner is stateless and performs no RPC — it operates entirely on
+ * the in-memory bank model and the strategy's target. This makes it
+ * straightforward to unit-test.
+ *
+ * ## How it works
+ *
+ * 1. The {@link AllocationStrategy} produces a {@link TargetAllocation}
+ *    (e.g. 25% USD*, 75% USD*-J).
+ * 2. The planner classifies every bank holding as either a **target**
+ *    (a mint the strategy manages) or an **idle source** (everything
+ *    else — the base asset, plus any non-target stablecoins that
+ *    arrived from borrows in other denominations).
+ * 3. Each idle source with a non-trivial balance gets its own
+ *    {@link YieldingBankRebalancePlan} that deploys its capital
+ *    proportionally across the targets according to their weights.
+ * 4. If existing target holdings are imbalanced relative to their
+ *    weights (overweight / underweight), a separate rebalance plan
+ *    routes through the base mint. The resulting swaps are sorted
+ *    sells-first so freed base-mint liquidity is available for
+ *    subsequent buy swaps.
+ *
+ * All swaps route through the bank's base mint as the common
+ * intermediate, matching how the on-chain `rebalance_yielding_bank`
+ * instruction processes CPI swaps.
+ */
+export class RebalancePlanner {
+  constructor(private readonly strategy: AllocationStrategy) {}
+
+  /**
+   * Plan the rebalance for a single yielding bank.
+   * Returns an empty array if no action is needed.
+   *
+   * Each element is an independent plan that can be sent as its own
+   * transaction. Separate plans are produced for:
+   * - Each idle source (base asset, or non-target stablecoins)
+   * - Target-to-target rebalancing (selling overweight, buying underweight)
+   */
+  plan(bank: LYCYieldingBank): YieldingBankRebalancePlan[] {
+    const targets = this.strategy.computeTarget(bank);
+    const targetMints = new Set(targets.map((t) => t.mint));
+
+    const idleSources = this.discoverIdleSources(bank, targetMints);
+    const targetHoldings = this.snapshotTargetHoldings(bank, targetMints);
+
+    const plans: YieldingBankRebalancePlan[] = [];
+
+    for (const source of idleSources) {
+      const plan = this.buildDeploymentPlan(bank, targets, source);
+      if (plan) plans.push(plan);
+    }
+
+    const rebalancePlan = this.buildTargetRebalancePlan(bank, targets, targetHoldings);
+    if (rebalancePlan) plans.push(rebalancePlan);
+
+    return plans;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Idle source discovery
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns every holding on the bank that is NOT a strategy target.
+   * This includes the base asset and any non-target asset slots with
+   * a positive balance (e.g. a stablecoin that arrived from a
+   * non-base-mint borrow).
+   */
+  private discoverIdleSources(bank: LYCYieldingBank, targetMints: Set<string>): HoldingSnapshot[] {
+    const sources: HoldingSnapshot[] = [];
+
+    const baseAmount = toBigInt(bank.data.baseAsset.amount);
+    if (baseAmount > 0n) {
+      sources.push({ mint: bank.baseMint, amount: baseAmount });
+    }
+
+    for (const asset of bank.data.assets) {
+      if (asset.mint.equals(PublicKey.default)) continue;
+      const mint = fromWeb3Pk(asset.mint);
+      if (targetMints.has(mint)) continue;
+      const amount = toBigInt(asset.amount);
+      if (amount > 0n) {
+        sources.push({ mint, amount });
+      }
+    }
+
+    return sources;
+  }
+
+  /** Snapshot only the holdings that ARE strategy targets. */
+  private snapshotTargetHoldings(
+    bank: LYCYieldingBank,
+    targetMints: Set<string>
+  ): HoldingSnapshot[] {
+    const result: HoldingSnapshot[] = [];
+
+    for (const asset of bank.data.assets) {
+      if (asset.mint.equals(PublicKey.default)) continue;
+      const mint = fromWeb3Pk(asset.mint);
+      if (!targetMints.has(mint)) continue;
+      result.push({ mint, amount: toBigInt(asset.amount) });
+    }
+
+    return result;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Plan builders
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Build a plan that deploys a single idle source proportionally
+   * across the strategy's targets according to their weights.
+   */
+  private buildDeploymentPlan(
+    bank: LYCYieldingBank,
+    targets: AllocationTarget[],
+    source: HoldingSnapshot
+  ): YieldingBankRebalancePlan | null {
+    if (source.amount < BigInt(MIN_STABLE_SWAP_AMOUNT)) return null;
+
+    const swaps: RebalanceSwapSpec[] = [];
+    let newAllocation: { config: YieldingBankAllocationConfig } | undefined;
+
+    for (const alloc of targets) {
+      const share = applyBps(source.amount, alloc.weightBps);
+      if (Number(share) < MIN_STABLE_SWAP_AMOUNT) continue;
+
+      swaps.push({
+        inputMint: source.mint,
+        outputMint: alloc.mint,
+        amount: Number(share),
+        slippageBps: alloc.slippageBps,
+      });
+
+      if (!newAllocation && bank.findAssetHolding(alloc.mint) === null) {
+        newAllocation = { config: alloc.allocationConfig };
+      }
+    }
+
+    if (swaps.length === 0 && !newAllocation) return null;
+    return { swaps, newAllocation };
+  }
+
+  /**
+   * Build a plan that rebalances between existing target holdings when
+   * they've drifted from the strategy's desired weights. Overweight
+   * targets are sold back to the base mint; underweight targets are
+   * bought with the freed base.
+   */
+  private buildTargetRebalancePlan(
+    bank: LYCYieldingBank,
+    targets: AllocationTarget[],
+    targetHoldings: HoldingSnapshot[]
+  ): YieldingBankRebalancePlan | null {
+    const totalTargetValue = targetHoldings.reduce((sum, h) => sum + h.amount, 0n);
+    if (totalTargetValue <= 0n) return null;
+
+    const swaps: RebalanceSwapSpec[] = [];
+
+    for (const alloc of targets) {
+      const desired = applyBps(totalTargetValue, alloc.weightBps);
+      const current = this.findCurrentAmount(targetHoldings, alloc.mint);
+      const delta = desired - current;
+      const absDelta = delta < 0n ? -delta : delta;
+
+      if (Number(absDelta) < MIN_STABLE_SWAP_AMOUNT) continue;
+
+      if (delta < 0n) {
+        swaps.push({
+          inputMint: alloc.mint,
+          outputMint: bank.baseMint,
+          amount: Number(absDelta),
+          slippageBps: alloc.slippageBps,
+        });
+      } else {
+        swaps.push({
+          inputMint: bank.baseMint,
+          outputMint: alloc.mint,
+          amount: Number(delta),
+          slippageBps: alloc.slippageBps,
+        });
+      }
+    }
+
+    if (swaps.length === 0) return null;
+    swaps.sort(
+      (a, b) => (a.inputMint === bank.baseMint ? 1 : 0) - (b.inputMint === bank.baseMint ? 1 : 0)
+    );
+    return { swaps };
+  }
+
+  private findCurrentAmount(holdings: HoldingSnapshot[], mint: string): bigint {
+    return holdings.find((h) => h.mint === mint)?.amount ?? 0n;
+  }
+}