@kestrelfi/lyc-sdk 1.0.1 → 1.0.3

package/src/services/redemption/redemptionService.ts

@@ -1,758 +0,0 @@
-import { type Address, type TransactionSigner } from "@solana/kit";
-import { toBigInt, toUiAmount } from "common";
-import type { LongYieldCarryClient } from "../../client/client";
-import type {
-  DecreaseCarryRepaySteering,
-  LongYieldCarryTransactionPlan,
-  RedemptionEpochSnapshot,
-} from "../../client/types";
-import {
-  REDEMPTION_EPOCH_STATUS_FUNDING,
-  REDEMPTION_EPOCH_STATUS_OPEN,
-  REDEMPTION_EPOCH_STATUS_PROCESSING,
-} from "../../constants/general";
-import type { IndexedLendingPosition, LYCToken } from "../../models/lycToken";
-import { LendingPositionService } from "../lendingPosition";
-
-const EPOCH_WINDOW_MS = 60_000;
-const DEFAULT_DCP_SWAP_SLIPPAGE_BPS = 100;
-// Retries after the initial attempt (3 attempts total). Each attempt
-// re-fetches a fresh swap quote.
-const DCP_MAX_RETRIES = 2;
-// Mirrors on-chain UTILIZATION_RATE_DEVIATION_THRESHOLD_BPS (150 bps relative margin).
-const UTILIZATION_RATE_DEVIATION_THRESHOLD_BPS = 150;
-// Extra fraction added to partial withdrawals so Kamino rounding never leaves
-// the epoch a few lamports short. 0.1% is well within the utilization margin.
-const WITHDRAWAL_OVERSHOOT_BPS = 10;
-
-export interface RedemptionServiceOptions {
-  /** Swap slippage tolerance for DCP transactions, in bps. Defaults to 100. */
-  dcpSwapSlippageBps?: number;
-  /** Optional structured sink for warnings (funding CPI failures, partial funding). */
-  structuredLog?: (entry: StructuredRedemptionLog) => void;
-}
-
-/** Single LP-targeted funding failure captured during epoch funding. */
-export interface RedemptionFundingFailure {
-  lpIndex: number;
-  message: string;
-}
-
-/** Aggregated non-fatal failures while funding an epoch (DCP vs withdraw phases). */
-export interface RedemptionFundingErrors {
-  dcp: RedemptionFundingFailure[];
-  withdraw: RedemptionFundingFailure[];
-}
-
-export interface StructuredRedemptionLog {
-  level: "warn" | "info";
-  event: string;
-  data?: Record<string, unknown>;
-}
-
-export interface FundRedemptionEpochResult {
-  funded: boolean;
-  fundedCollateral: bigint;
-  grossCollateralClaim: bigint;
-  realizedUnwindLoss: bigint;
-  errors: RedemptionFundingErrors;
-}
-
-export interface ProcessEpochResult {
-  requestsProcessed: number;
-}
-
-type LogFn = (msg: string) => void;
-
-function emptyFundingErrors(): RedemptionFundingErrors {
-  return { dcp: [], withdraw: [] };
-}
-
-function errorMessage(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
-
-function errorNameAndMessage(err: unknown): string {
-  if (err instanceof Error) return `${err.name}: ${err.message}`;
-  return String(err);
-}
-
-function compactStack(stack: string): string {
-  return stack
-    .split("\n")
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .slice(0, 12)
-    .join(" | ");
-}
-
-function errorCause(err: unknown): unknown {
-  return err !== null && typeof err === "object" && "cause" in err
-    ? (err as { cause?: unknown }).cause
-    : undefined;
-}
-
-function errorDiagnostics(err: unknown): string[] {
-  const diagnostics: string[] = [];
-  let current: unknown = err;
-
-  for (let depth = 0; current !== undefined && depth < 4; depth += 1) {
-    const prefix = depth === 0 ? "error" : `cause[${depth}]`;
-    diagnostics.push(`${prefix}: ${errorNameAndMessage(current)}`);
-
-    if (current instanceof Error && current.stack) {
-      diagnostics.push(`${prefix} stack: ${compactStack(current.stack)}`);
-    }
-
-    current = errorCause(current);
-  }
-
-  return diagnostics;
-}
-
-/**
- * Orchestrates the redemption epoch lifecycle: detecting open epochs, waiting
- * for their time window to elapse, funding (DCP + top-up), and processing
- * individual async burn requests.
- *
- * Holds a reference to the LYC client and caches yielding-bank PDAs per token
- * so repeated calls against the same token avoid redundant derivation.
- */
-export class RedemptionService {
-  private readonly yieldingBankCache = new Map<string, Address[]>();
-  private readonly dcpSwapSlippageBps: number;
-  private readonly lpService: LendingPositionService;
-  private readonly structuredLog?: (entry: StructuredRedemptionLog) => void;
-
-  constructor(
-    private readonly client: LongYieldCarryClient,
-    opts?: RedemptionServiceOptions
-  ) {
-    this.dcpSwapSlippageBps = opts?.dcpSwapSlippageBps ?? DEFAULT_DCP_SWAP_SLIPPAGE_BPS;
-    this.lpService = new LendingPositionService(client);
-    this.structuredLog = opts?.structuredLog;
-  }
-
-  // ── Epoch discovery ────────────────────────────────────────────────────────
-
-  /** Delegates to `client.account.fetchAllRedemptionEpochs`. */
-  async getAllEpochs(): Promise<RedemptionEpochSnapshot[]> {
-    return this.client.account.fetchAllRedemptionEpochs({ fresh: true });
-  }
-
-  /** Delegates to `client.account.fetchRedemptionEpoch`. */
-  async getEpoch(epochPda: Address): Promise<RedemptionEpochSnapshot> {
-    return this.client.account.fetchRedemptionEpoch(epochPda, { fresh: true });
-  }
-
-  /** Re-fetches an existing snapshot from on-chain state. */
-  async refreshEpoch(epoch: RedemptionEpochSnapshot): Promise<RedemptionEpochSnapshot> {
-    return this.getEpoch(epoch.pda);
-  }
-
-  // ── Epoch window ───────────────────────────────────────────────────────────
-
-  /**
-   * Returns the number of milliseconds until the epoch's acceptance window
-   * closes. Zero or negative means the window has already elapsed.
-   */
-  epochWindowRemainingMs(epoch: RedemptionEpochSnapshot): number {
-    return Number(epoch.epochId) + EPOCH_WINDOW_MS - Date.now();
-  }
-
-  /**
-   * Sleeps until the epoch's 60-second acceptance window has elapsed. Returns
-   * immediately if the window is already closed.
-   */
-  async waitForEpochWindow(epoch: RedemptionEpochSnapshot, log?: LogFn): Promise<void> {
-    const remainingMs = this.epochWindowRemainingMs(epoch);
-    if (remainingMs <= 0) {
-      log?.("Epoch window already closed.");
-      return;
-    }
-    log?.(`Waiting ${Math.ceil(remainingMs / 1000)}s for epoch window to close...`);
-    await new Promise((resolve) => setTimeout(resolve, remainingMs));
-    log?.("Window closed.");
-  }
-
-  // ── Status transitions ─────────────────────────────────────────────────────
-
-  /**
-   * Transitions an epoch from Open → Funding. Waits for the epoch window to
-   * close first so in-flight burns can still land.
-   */
-  async closeEpoch(
-    signer: TransactionSigner,
-    epoch: RedemptionEpochSnapshot,
-    log?: LogFn
-  ): Promise<void> {
-    if (epoch.status !== REDEMPTION_EPOCH_STATUS_OPEN) return;
-
-    await this.waitForEpochWindow(epoch, log);
-
-    log?.("Setting status → Funding...");
-    const plan = await this.client.tx.setRedemptionEpochStatus.getTx({
-      token: epoch.tokenPda,
-      redemptionEpoch: epoch.pda,
-      params: { status: REDEMPTION_EPOCH_STATUS_FUNDING },
-    });
-    await this.client.sendTransaction(signer, plan);
-    this.client.clearAllCache();
-  }
-
-  /** Transitions an epoch from Funding → Processing. */
-  async startProcessing(
-    signer: TransactionSigner,
-    epoch: RedemptionEpochSnapshot,
-    log?: LogFn
-  ): Promise<void> {
-    if (epoch.status > REDEMPTION_EPOCH_STATUS_FUNDING) return;
-
-    log?.("Setting status → Processing...");
-    const plan = await this.client.tx.setRedemptionEpochStatus.getTx({
-      token: epoch.tokenPda,
-      redemptionEpoch: epoch.pda,
-      params: { status: REDEMPTION_EPOCH_STATUS_PROCESSING },
-    });
-    await this.client.sendTransaction(signer, plan);
-    this.client.clearAllCache();
-  }
-
-  // ── Funding ────────────────────────────────────────────────────────────────
-
-  /**
-   * Funds a redemption epoch. Withdraws from debt-free LPs first (no DCP
-   * needed), then — if a deficit remains — runs targeted DCP + withdraw on
-   * carry-loaded LPs, prioritizing non-optimal positions.
-   */
-  async fundEpoch(
-    signer: TransactionSigner,
-    epoch: RedemptionEpochSnapshot,
-    log?: LogFn
-  ): Promise<FundRedemptionEpochResult> {
-    const fundingErrors = emptyFundingErrors();
-    const fresh = await this.refreshEpoch(epoch);
-    if (this.isFullyFunded(fresh)) {
-      log?.("Already fully funded.");
-      return this.fundResult(fresh, fundingErrors);
-    }
-
-    const token = await this.client.account.fetchToken(fresh.tokenPda, { fresh: true });
-    const decimals = token.data.collateral.decimals;
-    const deficitUi = this.deficitUi(fresh, decimals);
-    log?.(`Deficit: ${deficitUi}`);
-
-    await this.fundFromDebtFreeLps(signer, token, fresh, decimals, fundingErrors, log);
-
-    const afterDirect = await this.refreshEpoch(epoch);
-    if (this.isFullyFunded(afterDirect)) {
-      log?.("Fully funded from debt-free LPs — no DCP needed.");
-      return this.fundResult(afterDirect, fundingErrors);
-    }
-
-    await this.fundFromCarryLps(signer, fresh.tokenPda, afterDirect, decimals, fundingErrors, log);
-
-    const afterCarry = await this.refreshEpoch(epoch);
-    if (this.isFullyFunded(afterCarry)) {
-      log?.("Fully funded.");
-      return this.fundResult(afterCarry, fundingErrors);
-    }
-
-    await this.creditResidualUnlent(signer, afterCarry, decimals, log);
-
-    const afterResidual = await this.refreshEpoch(epoch);
-    if (this.isFullyFunded(afterResidual)) {
-      log?.("Fully funded from lending positions and residual unlent reserves.");
-    }
-    return this.fundResult(afterResidual, fundingErrors);
-  }
-
-  // ── Request processing ─────────────────────────────────────────────────────
-
-  /**
-   * Processes all remaining async burn requests in a redemption epoch in FIFO
-   * order.
-   */
-  async processRequests(
-    signer: TransactionSigner,
-    epoch: RedemptionEpochSnapshot,
-    log?: LogFn
-  ): Promise<ProcessEpochResult> {
-    const snap = await this.refreshEpoch(epoch);
-    let processed = 0;
-    for (let seq = snap.processedRequestCount; seq < snap.requestCount; seq++) {
-      const plan = await this.client.tx.processAsyncBurn.getTx({
-        token: snap.tokenPda,
-        params: { epochId: snap.epochId, sequence: seq },
-      });
-      const debug = plan.debug?.processAsyncBurn;
-      if (debug) {
-        const payoutTarget =
-          debug.collateralDelivery === "nativeSol"
-            ? `native SOL via request escrow ${debug.requestCollateralAccount ?? "unknown"}`
-            : `user collateral ATA ${debug.userCollateralAccount ?? "unknown"}`;
-        log?.(`Request ${seq}: user ${debug.user}, payout ${payoutTarget}`);
-      }
-      const sig = await this.client.sendTransaction(signer, plan);
-      log?.(`Request ${seq}: ${sig}`);
-      this.client.clearAllCache();
-      processed++;
-    }
-    return { requestsProcessed: processed };
-  }
-
-  // ── Full lifecycle ─────────────────────────────────────────────────────────
-
-  /**
-   * Runs the complete epoch lifecycle: close → fund → transition to
-   * processing → process all requests.
-   *
-   * Returns true if the epoch was fully processed and closed.
-   */
-  async processEpoch(
-    signer: TransactionSigner,
-    epoch: RedemptionEpochSnapshot,
-    log?: LogFn
-  ): Promise<boolean> {
-    await this.closeEpoch(signer, epoch, log);
-
-    const afterClose = await this.refreshEpoch(epoch);
-    const fundResult = await this.fundEpoch(signer, afterClose, log);
-    if (fundResult.errors.dcp.length > 0 || fundResult.errors.withdraw.length > 0) {
-      const summary = `${fundResult.errors.dcp.length} DCP failure(s), ${fundResult.errors.withdraw.length} withdraw failure(s)`;
-      log?.(`Funding phase recorded ${summary}.`);
-      this.structuredLog?.({
-        level: "warn",
-        event: "redemption_epoch_funding_failures",
-        data: {
-          epochPda: afterClose.pda,
-          tokenPda: afterClose.tokenPda,
-          dcp: fundResult.errors.dcp,
-          withdraw: fundResult.errors.withdraw,
-        },
-      });
-    }
-    if (!fundResult.funded) {
-      log?.(
-        `Epoch underfunded (${fundResult.fundedCollateral} / ${fundResult.grossCollateralClaim}; ` +
-          `realized unwind loss ${fundResult.realizedUnwindLoss}).`
-      );
-      return false;
-    }
-
-    const afterFunding = await this.refreshEpoch(afterClose);
-    await this.startProcessing(signer, afterFunding, log);
-
-    const processingEpoch = await this.refreshEpoch(afterFunding);
-    const remaining = processingEpoch.requestCount - processingEpoch.processedRequestCount;
-    log?.(`Processing ${remaining} request(s)...`);
-    await this.processRequests(signer, processingEpoch, log);
-    return true;
-  }
-
-  // ── Cache management ───────────────────────────────────────────────────────
-
-  clearYieldingBankCache(): void {
-    this.yieldingBankCache.clear();
-  }
-
-  // ── Private: funding phases ───────────────────────────────────────────────
-
-  /**
-   * Credits only the residual shortfall from collateral already sitting in the
-   * token PDA's unlent reserve. LP withdrawals run first so existing reserves
-   * are used as the tail of mixed LP/unlent funding, not the first source.
-   */
-  private async creditResidualUnlent(
-    signer: TransactionSigner,
-    epoch: RedemptionEpochSnapshot,
-    decimals: number,
-    log?: LogFn
-  ): Promise<void> {
-    const current = await this.refreshEpoch(epoch);
-    const shortfall = current.grossCollateralClaim - current.fundedCollateral;
-    if (shortfall <= 0n) return;
-
-    const token = await this.client.account.fetchToken(current.tokenPda, { fresh: true });
-    const rawUnlent = token.data.collateral.unlentAmount;
-    const unlent = rawUnlent === undefined ? 0n : toBigInt(rawUnlent);
-    const uncreditedUnlent =
-      unlent > current.fundedCollateral ? unlent - current.fundedCollateral : 0n;
-    if (uncreditedUnlent === 0n) return;
-
-    const credit = shortfall < uncreditedUnlent ? shortfall : uncreditedUnlent;
-    log?.(`Crediting residual unlent reserves (${toUiAmount(credit, decimals)}) to epoch...`);
-    const plan = await this.client.tx.creditUnlentToRedemptionEpoch.getTx({
-      token: token.address,
-      redemptionEpoch: current.pda,
-    });
-    await this.client.sendTransaction(signer, plan);
-    this.client.clearAllCache();
-  }
-
-  /** Phase 1: withdraw directly from LPs that have no debt (no DCP needed). */
-  private async fundFromDebtFreeLps(
-    signer: TransactionSigner,
-    token: LYCToken,
-    epoch: RedemptionEpochSnapshot,
-    decimals: number,
-    fundingErrors: RedemptionFundingErrors,
-    log?: LogFn
-  ): Promise<void> {
-    const debtFreeLps = token.usedLendingPositions.filter(
-      (lp) => toBigInt(lp.data.accounting.debt.amount) === 0n
-    );
-    if (debtFreeLps.length === 0) {
-      log?.("No debt-free LP collateral available for direct withdrawal.");
-      return;
-    }
-
-    log?.(`${debtFreeLps.length} debt-free LP(s) — withdrawing directly...`);
-    await this.withdrawFromLps(signer, epoch, decimals, debtFreeLps, fundingErrors, log);
-  }
-
-  /**
-   * Phase 2: DCP + withdraw from carry-loaded LPs, sorted so non-optimal
-   * positions are unwound first.
-   */
-  private async fundFromCarryLps(
-    signer: TransactionSigner,
-    tokenPda: Address,
-    epoch: RedemptionEpochSnapshot,
-    decimals: number,
-    fundingErrors: RedemptionFundingErrors,
-    log?: LogFn
-  ): Promise<void> {
-    const remainingDeficitUi = this.deficitUi(epoch, decimals);
-    log?.(`Remaining deficit after debt-free withdrawals: ${remainingDeficitUi}`);
-
-    const token = await this.client.account.fetchToken(tokenPda, { fresh: true });
-    const carryLps = token.usedLendingPositions.filter(
-      (lp) => toBigInt(lp.data.accounting.debt.amount) > 0n
-    );
-    if (carryLps.length === 0) {
-      log?.("No carry-loaded LP collateral available for DCP funding.");
-      return;
-    }
-
-    const sorted = await this.lpService.sortByOptimality(token, carryLps, log);
-    await this.dcpAcrossLps(
-      signer,
-      token,
-      epoch,
-      remainingDeficitUi,
-      decimals,
-      sorted,
-      fundingErrors,
-      log
-    );
-    await this.withdrawFromLps(signer, epoch, decimals, sorted, fundingErrors, log);
-  }
-
-  // ── Private: DCP ──────────────────────────────────────────────────────────
-
-  /**
-   * Runs a targeted DCP on each LP that needs collateral freed. Iterates `lps`
-   * in the caller-provided order (non-optimal positions first).
-   */
-  private async dcpAcrossLps(
-    signer: TransactionSigner,
-    token: LYCToken,
-    epoch: RedemptionEpochSnapshot,
-    totalDeficitUi: number,
-    decimals: number,
-    lps: IndexedLendingPosition[],
-    fundingErrors: RedemptionFundingErrors,
-    log?: LogFn
-  ): Promise<void> {
-    if (token.activeCarryPositions.length === 0) return;
-
-    const fallbackBanks = await this.resolveYieldingBanks(token);
-    const fallbackBank = fallbackBanks[0];
-    if (!fallbackBank) return;
-
-    let remainingDeficitUi = totalDeficitUi;
-
-    for (const lp of lps) {
-      if (remainingDeficitUi <= 0) break;
-
-      const lpCollateralUi = toUiAmount(toBigInt(lp.data.accounting.collateral), decimals);
-
-      // Skip DCP only when the amount this LP must supply (plus the withdrawal
-      // overshoot) can be withdrawn directly while keeping post-withdraw
-      // utilization within the on-chain threshold. Current utilization being
-      // in range is not enough: withdrawing collateral with debt outstanding
-      // raises utilization, and both Kamino's max LTV and the
-      // top_up_unlent_reserves post-withdraw check validate the resulting state.
-      const neededUi = Math.min(remainingDeficitUi, lpCollateralUi);
-      const neededWithOvershootUi = neededUi * (1 + WITHDRAWAL_OVERSHOOT_BPS / 10_000);
-      const maxDirectUi = toUiAmount(this.maxDirectWithdrawal(lp), decimals);
-      if (maxDirectUi >= neededWithOvershootUi) {
-        log?.(
-          `DCP LP[${lp.index}] skipped — needed ${neededUi} within direct-withdrawal headroom (${maxDirectUi}).`
-        );
-        remainingDeficitUi -= neededUi;
-        continue;
-      }
-
-      const fullUnwind = remainingDeficitUi >= lpCollateralUi;
-
-      const dcpSucceeded = await this.dcpSingleLp(
-        signer,
-        epoch,
-        lp,
-        fallbackBank,
-        fullUnwind,
-        neededUi,
-        fundingErrors,
-        log
-      );
-      if (dcpSucceeded) {
-        remainingDeficitUi -= neededUi;
-      }
-    }
-  }
-
-  /**
-   * Max collateral (native units) withdrawable from an LP without a prior DCP.
-   *
-   * TopUpUnlentReserves re-checks `is_utilization_rate_at_or_below_target`
-   * AFTER the withdrawal (util <= target + target * threshold / 10_000), and
-   * utilization scales as `util_after = util * collateral / (collateral - w)`
-   * when debt and prices stay constant (mirrors on-chain
-   * `simulate_utilization_rate_bps_after_collateral_withdraw`). Inverting
-   * against the upper bound gives:
-   *   w_max = collateral * (limit - util) / limit
-   */
-  private maxDirectWithdrawal(lp: IndexedLendingPosition): bigint {
-    const collateral = toBigInt(lp.data.accounting.collateral);
-    const utilBps = BigInt(lp.data.accounting.ltvUtilizationRateBps);
-    if (utilBps === 0n) return collateral;
-
-    const target = lp.data.config.targetUtilizationRateBps;
-    const margin = Math.floor((target * UTILIZATION_RATE_DEVIATION_THRESHOLD_BPS) / 10_000);
-    const limitBps = BigInt(Math.min(target + margin, 10_000));
-    if (utilBps >= limitBps) return 0n;
-    return (collateral * (limitBps - utilBps)) / limitBps;
-  }
-
-  /**
-   * Executes a single DCP on one lending position with retry logic. Uses full
-   * unwind (target utilization 0) when the deficit exceeds the LP's collateral,
-   * otherwise uses `collateralWithdrawal` steering.
-   */
-  private async dcpSingleLp(
-    signer: TransactionSigner,
-    epoch: RedemptionEpochSnapshot,
-    lp: IndexedLendingPosition,
-    yieldingBank: Address,
-    fullUnwind: boolean,
-    withdrawUi: number,
-    fundingErrors: RedemptionFundingErrors,
-    log?: LogFn
-  ): Promise<boolean> {
-    const repaySteering: DecreaseCarryRepaySteering = fullUnwind
-      ? {
-          mode: "explicitTargetUtilization",
-          targetUtilizationRateBps: 0,
-        }
-      : {
-          mode: "collateralWithdrawal",
-          collateralWithdrawalUiAmount: withdrawUi,
-          allowBelowTargetOnChain: true,
-        };
-
-    const label = fullUnwind ? "full unwind" : "collateralWithdrawal steering";
-    log?.(`DCP LP[${lp.index}] (${label})...`);
-
-    let lastError = "unknown error";
-    for (let attempt = 0; attempt <= DCP_MAX_RETRIES; attempt++) {
-      if (attempt > 0) {
-        log?.(`DCP LP[${lp.index}] retry ${attempt}/${DCP_MAX_RETRIES}...`);
-        this.client.clearAllCache();
-      }
-
-      const attemptLabel = `${attempt + 1}/${DCP_MAX_RETRIES + 1}`;
-      log?.(
-        `DCP LP[${lp.index}] attempt ${attemptLabel}: building plan ` +
-          `(token=${epoch.tokenPda}, epoch=${epoch.pda}, yieldingBank=${yieldingBank}, signer=${signer.address}).`
-      );
-
-      let plan: LongYieldCarryTransactionPlan;
-      try {
-        plan = await this.client.tx.decreaseCarryPosition.getTx({
-          signer: signer.address,
-          token: epoch.tokenPda,
-          redemptionEpoch: epoch.pda,
-          params: {
-            lendingPositionIndex: lp.index,
-            yieldingBank,
-            swapSlippageBps: this.dcpSwapSlippageBps,
-            ...(repaySteering ? { repaySteering } : {}),
-          },
-        });
-      } catch (err) {
-        lastError = errorMessage(err);
-        log?.(`DCP LP[${lp.index}] plan build failed: ${lastError}`);
-        for (const detail of errorDiagnostics(err)) {
-          log?.(`DCP LP[${lp.index}] plan build ${detail}`);
-        }
-        continue;
-      }
-
-      log?.(
-        `DCP LP[${lp.index}] attempt ${attemptLabel}: plan built ` +
-          `(${plan.instructions.length} ix, ${plan.lookupTables?.length ?? 0} LUT(s)); sending transaction.`
-      );
-
-      try {
-        await this.client.sendTransaction(signer, plan);
-        this.client.clearAllCache();
-        log?.(`DCP LP[${lp.index}] done.`);
-        return true;
-      } catch (err) {
-        lastError = errorMessage(err);
-        log?.(`DCP LP[${lp.index}] send failed: ${lastError}`);
-        for (const detail of errorDiagnostics(err)) {
-          log?.(`DCP LP[${lp.index}] send ${detail}`);
-        }
-      }
-    }
-    log?.(`DCP LP[${lp.index}] exhausted retries — continuing.`);
-    fundingErrors.dcp.push({ lpIndex: lp.index, message: lastError });
-    return false;
-  }
-
-  // ── Private: top-up withdrawals ───────────────────────────────────────────
-
-  /**
-   * Withdraws collateral from lending positions into unlent reserves, crediting
-   * the redemption epoch. Stops as soon as the epoch is fully funded.
-   */
-  private async withdrawFromLps(
-    signer: TransactionSigner,
-    epoch: RedemptionEpochSnapshot,
-    decimals: number,
-    lps: IndexedLendingPosition[],
-    fundingErrors: RedemptionFundingErrors,
-    log?: LogFn
-  ): Promise<void> {
-    for (const lp of lps) {
-      const current = await this.refreshEpoch(epoch);
-      if (this.isFullyFunded(current)) break;
-
-      // Re-fetch the LP so post-DCP debt/collateral (and thus utilization) are
-      // current — the caller's snapshot predates any DCPs run this funding pass.
-      const token = await this.client.account.fetchToken(epoch.tokenPda, { fresh: true });
-      const freshLp = token.usedLendingPositions.find((p) => p.index === lp.index);
-      if (!freshLp) continue;
-
-      const remainingDeficit = current.grossCollateralClaim - current.fundedCollateral;
-      const lpCollateral = toBigInt(freshLp.data.accounting.collateral);
-
-      // For partial withdrawals, overshoot slightly so Kamino rounding never
-      // leaves the epoch a few lamports short of fully funded.
-      const overshoot = (remainingDeficit * BigInt(WITHDRAWAL_OVERSHOOT_BPS)) / 10_000n;
-      const withOvershoot = remainingDeficit + overshoot;
-      const requested =
-        withOvershoot < lpCollateral
-          ? withOvershoot
-          : remainingDeficit < lpCollateral
-            ? remainingDeficit
-            : lpCollateral;
-
-      // Cap at what the post-withdraw utilization checks (Kamino max LTV and
-      // on-chain is_utilization_rate_at_or_below_target) allow with the LP's
-      // remaining debt.
-      const maxWithdraw = this.maxDirectWithdrawal(freshLp);
-      if (maxWithdraw === 0n) {
-        log?.(`LP[${lp.index}]: skipped — no utilization headroom for a direct withdrawal.`);
-        continue;
-      }
-      const amount = requested < maxWithdraw ? requested : maxWithdraw;
-      if (amount < requested) {
-        log?.(
-          `LP[${lp.index}]: capping withdrawal at utilization headroom (${toUiAmount(maxWithdraw, decimals)}).`
-        );
-      }
-
-      const drainAll = amount >= lpCollateral;
-      const fundsFully = amount >= remainingDeficit;
-      const uiAmount: number | "all" = drainAll ? "all" : toUiAmount(amount, decimals);
-
-      log?.(`LP[${lp.index}]: withdrawing ${drainAll ? "all" : uiAmount}...`);
-      try {
-        const plan = await this.client.tx.topUpUnlentReserves.getTx({
-          token: epoch.tokenPda,
-          params: {
-            lendingPositionIndex: lp.index,
-            uiAmount,
-            redemptionEpoch: epoch.pda,
-          },
-        });
-        if (!drainAll && fundsFully) {
-          // Bundle Funding → Processing in the same tx. On-chain the status
-          // instruction validates funded_collateral >= gross_collateral_claim,
-          // so the whole tx rolls back atomically if the withdrawal fell short.
-          const statusIx = await this.client.tx.setRedemptionEpochStatus.getIx({
-            token: epoch.tokenPda,
-            redemptionEpoch: epoch.pda,
-            params: { status: REDEMPTION_EPOCH_STATUS_PROCESSING },
-          });
-          plan.instructions.push(statusIx);
-        }
-        await this.client.sendTransaction(signer, plan);
-        this.client.clearAllCache();
-        if (fundsFully) break;
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        log?.(`LP[${lp.index}] withdraw failed: ${message}`);
-        fundingErrors.withdraw.push({ lpIndex: lp.index, message });
-      }
-    }
-  }
-
-  // ── Private: utilities ────────────────────────────────────────────────────
-
-  private isFullyFunded(epoch: RedemptionEpochSnapshot): boolean {
-    return epoch.fundedCollateral >= epoch.grossCollateralClaim;
-  }
-
-  private deficitUi(epoch: RedemptionEpochSnapshot, decimals: number): number {
-    return toUiAmount(epoch.grossCollateralClaim - epoch.fundedCollateral, decimals);
-  }
-
-  private fundResult(
-    epoch: RedemptionEpochSnapshot,
-    errors: RedemptionFundingErrors
-  ): FundRedemptionEpochResult {
-    return {
-      funded: this.isFullyFunded(epoch),
-      fundedCollateral: epoch.fundedCollateral,
-      grossCollateralClaim: epoch.grossCollateralClaim,
-      realizedUnwindLoss: epoch.realizedUnwindLoss,
-      errors,
-    };
-  }
-
-  private async resolveYieldingBanks(token: LYCToken): Promise<Address[]> {
-    const cached = this.yieldingBankCache.get(token.address);
-    if (cached) return cached;
-
-    const seen = new Set<string>();
-    const banks: Address[] = [];
-    for (const carry of token.activeCarryPositions) {
-      const bankPda = await token.deriveYieldingBankAddressForDebtCarryIndex(
-        carry.index,
-        this.client.pda
-      );
-      if (!seen.has(bankPda)) {
-        seen.add(bankPda);
-        banks.push(bankPda);
-      }
-    }
-
-    this.yieldingBankCache.set(token.address, banks);
-    return banks;
-  }
-}