@kestrelfi/lyc-sdk 1.0.1

package/src/utils/lookupTables.ts

@@ -0,0 +1,309 @@
+import { type Address, Rpc, SolanaRpcApi, TransactionSigner } from "@solana/kit";
+import { ADDRESS_LOOKUP_TABLE_PROGRAM_ADDRESS } from "@solana-program/address-lookup-table";
+import { COMPUTE_BUDGET_PROGRAM_ADDRESS } from "@solana-program/compute-budget";
+import { SYSTEM_PROGRAM_ADDRESS } from "@solana-program/system";
+import { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
+import { TOKEN_2022_PROGRAM_ADDRESS } from "@solana-program/token-2022";
+import {
+  DEFAULT_PUBLIC_KEY,
+  dedupeOrderedAddresses,
+  type DeployedEnv,
+  type Environment,
+  JITO_TIP_ACCOUNTS,
+  LendingPlatform,
+  type MintIdentifier,
+  fromWeb3Pk,
+  getAtaAddress,
+  getRpcUrl,
+  lendingPlatformToEnum,
+  lutManager,
+  mints,
+  resolveTokenProgram,
+} from "common";
+import { oracle } from "oracle";
+import {
+  getGeneralLookupTableAccountsForPerena,
+  PERENA_PROGRAM_ID,
+  PerenaClient,
+} from "perena-helpers";
+import { LongYieldCarryClient } from "../client/client";
+import { LYCToken } from "../models/lycToken";
+import {
+  CIRCUIT_BREAKER_CONTROLLER,
+  GENERAL_LOOKUP_TABLES,
+  MANAGER,
+  PROGRAM_ID,
+  PROTOCOL_ADMIN,
+  PROTOCOL_FEE_WALLET,
+} from "../constants/general";
+import { TOKEN_LOOKUP_TABLES } from "../constants";
+
+/**
+ * Oracle account when {@link oracle} can resolve Pyth, Switchboard, or a custom feed.
+ * Not exported — module-local helper (TypeScript has no `private` on file-level functions).
+ */
+function tryOracleAddress(mint: MintIdentifier): Address | undefined {
+  try {
+    return oracle.getOracleData(mint).oracle;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Registry stablecoins + YBAs — used for yielding-bank ATA derivation. */
+const DEBT_AND_YBA_MINT_INFOS = [...mints.stablecoins(), ...mints.yieldBearingAssets()];
+
+/** Registry Standard + LST mints — risk / collateral-style assets (oracle-only on general LUT). */
+const RISK_ASSET_MINT_INFOS = [
+  ...mints.filterAssetsByType("Standard"),
+  ...mints.filterAssetsByType("LST"),
+];
+
+/**
+ * Stablecoin + YBA mints with registry oracles for the general LUT.
+ * Risk assets (Standard + LST registry entries): oracle only — mints stay on each token's LUT via on-chain collateral.
+ * Not exported — module-local helper.
+ */
+function getMintRegistryAccountsForGeneralLut(): Address[] {
+  const out: Address[] = [];
+  for (const m of DEBT_AND_YBA_MINT_INFOS) {
+    out.push(m.address);
+    const o = tryOracleAddress(m.address);
+    if (o) {
+      out.push(o);
+    }
+  }
+  for (const m of RISK_ASSET_MINT_INFOS) {
+    const o = tryOracleAddress(m.address);
+    if (o) {
+      out.push(o);
+    }
+  }
+  return out;
+}
+
+/**
+ * Every YieldingBank PDA plus, for each bank, the ATA for each registry stablecoin and YBA mint.
+ * Not exported — module-local helper.
+ */
+async function getYieldingBankAccountsForGeneralLut(
+  client: LongYieldCarryClient
+): Promise<Address[]> {
+  const banks = await client.account.fetchAllYieldingBanks();
+  const out: Address[] = [];
+
+  for (const b of banks) {
+    out.push(b.address);
+    for (const m of DEBT_AND_YBA_MINT_INFOS) {
+      out.push(await getAtaAddress(m.address, b.address, m.tokenProgram));
+    }
+  }
+  return out;
+}
+
+/**
+ * Get the specific lookup table for the given Token PDA (if it exists).
+ *
+ * `TOKEN_LOOKUP_TABLES` is keyed by Token PDA address.
+ */
+export function getLookupTableForToken(tokenPda: Address) {
+  if (tokenPda in TOKEN_LOOKUP_TABLES) {
+    return TOKEN_LOOKUP_TABLES[tokenPda];
+  }
+}
+
+/**
+ * Assembles lookup table addresses for LYC transaction plans: the deployment
+ * general LUT (when not `local`), any registered per-token LUT for the given
+ * token PDAs, then any CPI/swap tables. Entries are omitted when missing or
+ * equal to the default (unused) public key; duplicates are removed in first-seen
+ * order.
+ */
+export function mergeLycLookupTables(
+  environment: Environment,
+  tokenPda?: Address | readonly Address[],
+  existingLookupTables?: readonly Address[]
+): Address[] {
+  const all: (Address | undefined)[] = [];
+
+  if (environment !== "local") {
+    all.push(GENERAL_LOOKUP_TABLES[environment as DeployedEnv]);
+  }
+
+  if (tokenPda !== undefined) {
+    for (const t of Array.isArray(tokenPda) ? tokenPda : [tokenPda]) {
+      all.push(getLookupTableForToken(t));
+    }
+  }
+
+  if (existingLookupTables) {
+    all.push(...existingLookupTables);
+  }
+
+  const valid = all.filter((a): a is Address => a !== undefined && a !== DEFAULT_PUBLIC_KEY);
+  return [...new Set(valid)];
+}
+
+/**
+ * Refresh per-token lookup tables for every Token account owned by the program.
+ *
+ * @param client - Initialized client (provides RPC-backed account fetch and Kamino helpers).
+ */
+export async function updateTokenLutsIfNeeded(
+  signer: TransactionSigner,
+  rpc: Rpc<SolanaRpcApi>,
+  client: LongYieldCarryClient
+) {
+  const tokens = await client.account.fetchAllTokens();
+  for (const t of tokens) {
+    await updateTokenLutIfNeeded(signer, rpc, client, t);
+  }
+}
+
+/**
+ * Extend the per-token lookup table with addresses needed for that token's
+ * instructions: mints, token/YB ATAs, registry debt-mint ATAs for the token PDA, lending protocol accounts, Kamino
+ * obligation ATAs when applicable. Lending reserve accounts live on the
+ * lending-platform LUT; price oracles for registry-listed debt/YBAs and risk
+ * assets live on the general LUT.
+ *
+ * Collateral mint is read from on-chain token state (it is not a PDA).
+ *
+ * @param client - Used for Kamino reserve metadata and reserve interaction ATAs.
+ * @param token - Fetched token model (`LYCToken`); avoids an extra fetch.
+ */
+export async function updateTokenLutIfNeeded(
+  signer: TransactionSigner,
+  rpc: Rpc<SolanaRpcApi>,
+  client: LongYieldCarryClient,
+  token: LYCToken
+) {
+  const kaminoClient = client.getLendingPlatformClientByPlatform(LendingPlatform.Kamino);
+  const allAccounts: Address[] = [];
+
+  const tokenPda = token.address;
+  const yMint = token.mint;
+  const collateralMint = token.collateralMint;
+  const collateralTp = resolveTokenProgram(token.data.collateral.tokenProgram);
+  const yTokenTp = resolveTokenProgram(token.data.config.tokenProgram);
+
+  allAccounts.push(tokenPda, yMint, collateralMint);
+  allAccounts.push(
+    await getAtaAddress(collateralMint, tokenPda, collateralTp),
+    await getAtaAddress(yMint, tokenPda, yTokenTp)
+  );
+
+  for (const m of mints.stablecoins()) {
+    allAccounts.push(await getAtaAddress(m.address, tokenPda, m.tokenProgram));
+  }
+
+  for (const position of token.data.lendingPositions) {
+    const platform = lendingPlatformToEnum(position.platform);
+    if (platform === LendingPlatform.None) {
+      continue;
+    }
+
+    allAccounts.push(fromWeb3Pk(position.protocolUserAcc));
+
+    const debtMint = fromWeb3Pk(position.accounting.debt.mint);
+    const debtTp = resolveTokenProgram(position.accounting.debt.tokenProgram);
+    allAccounts.push(await getAtaAddress(debtMint, tokenPda, debtTp));
+
+    if (platform === LendingPlatform.Kamino) {
+      const pool = fromWeb3Pk(position.pool);
+      const userAcc = fromWeb3Pk(position.protocolUserAcc);
+      for (const reserve of [
+        fromWeb3Pk(position.collateralReserve),
+        fromWeb3Pk(position.debtReserve),
+      ]) {
+        const details = await kaminoClient.accounts.reserveInteractionDetails(
+          tokenPda,
+          pool,
+          reserve,
+          userAcc
+        );
+        allAccounts.push(
+          details.userLiquidityTa.address,
+          details.userCollateralTa.address,
+          userAcc
+        );
+
+        const userFarmAddresses = await kaminoClient.accounts.getUserFarmAddresses(
+          pool,
+          reserve,
+          userAcc
+        );
+        allAccounts.push(...userFarmAddresses);
+      }
+    }
+  }
+
+  console.log("Updating token LUT for token:", tokenPda);
+  lutManager.clearCache();
+  await lutManager.updateLookupTable(signer, rpc, allAccounts, getLookupTableForToken(tokenPda));
+}
+
+/**
+ * Extend the shared general lookup table: program IDs, well-known SPL programs,
+ * stablecoin and YBA mints (plus registry oracles), Standard + LST oracle accounts,
+ * Perena program id, every on-chain YieldingBank PDA, each bank’s ATAs for
+ * all registry debt mints (stablecoins) and yield-bearing assets, the canonical
+ * Jito tip accounts (referenced by every Jito-bundle tip ix), the ComputeBudget
+ * program (referenced by every CU-limit ix), and the deployment's role wallets:
+ * manager, protocol admin, circuit-breaker controller, and protocol fee wallet.
+ *
+ * Risk asset (Standard + LST) mints are omitted here; they appear on each token LUT
+ * as collateral.
+ *
+ * Uses {@link GENERAL_LOOKUP_TABLES} for {@link LongYieldCarryClient.environment}
+ * (`test` | `prod` only) and only that tier’s program ID.
+ *
+ * @throws If `client.environment` is `local` — there is no pinned general LUT for local.
+ */
+export async function updateGeneralLutIfNeeded(
+  signer: TransactionSigner,
+  rpc: Rpc<SolanaRpcApi>,
+  client: LongYieldCarryClient
+): Promise<Address> {
+  const deployedEnv = client.environment;
+
+  if (deployedEnv === "local") {
+    throw new Error(
+      "updateGeneralLutIfNeeded requires LongYieldCarryClient built with test or prod; local has no GENERAL_LOOKUP_TABLES entry."
+    );
+  }
+
+  const registryAccounts = getMintRegistryAccountsForGeneralLut();
+  const yieldingBankAccounts = await getYieldingBankAccountsForGeneralLut(client);
+  const perenaAccounts = await getGeneralLookupTableAccountsForPerena(
+    new PerenaClient(getRpcUrl(deployedEnv))
+  );
+
+  const allAccounts: Address[] = [
+    PROGRAM_ID[deployedEnv],
+    SYSTEM_PROGRAM_ADDRESS,
+    TOKEN_PROGRAM_ADDRESS,
+    ASSOCIATED_TOKEN_PROGRAM_ADDRESS,
+    TOKEN_2022_PROGRAM_ADDRESS,
+    COMPUTE_BUDGET_PROGRAM_ADDRESS,
+    DEFAULT_PUBLIC_KEY,
+    ADDRESS_LOOKUP_TABLE_PROGRAM_ADDRESS,
+    PERENA_PROGRAM_ID,
+    MANAGER[deployedEnv],
+    PROTOCOL_ADMIN[deployedEnv],
+    CIRCUIT_BREAKER_CONTROLLER[deployedEnv],
+    PROTOCOL_FEE_WALLET[deployedEnv],
+    ...JITO_TIP_ACCOUNTS,
+    ...registryAccounts,
+    ...perenaAccounts,
+    ...yieldingBankAccounts,
+  ];
+
+  lutManager.clearCache();
+  return lutManager.updateLookupTable(
+    signer,
+    rpc,
+    dedupeOrderedAddresses(allAccounts),
+    GENERAL_LOOKUP_TABLES[deployedEnv]
+  );
+}

package/src/utils/lycData.ts

@@ -0,0 +1,321 @@
+/**
+ * Pure helpers over decoded long_yield_carry account data (`Token`, `YieldingBank`, etc.):
+ * selection logic, liquidity / holding analysis, and other algorithms that do not belong on
+ * `AccountClient` or transaction composers.
+ */
+
+import type { Address } from "@solana/kit";
+import { BN } from "@anchor-lang/core";
+import { PublicKey } from "@solana/web3.js";
+import {
+  fromWeb3Pk,
+  LendingPlatform,
+  lendingPlatformToEnum,
+  maxByNumber,
+  toUiAmount,
+} from "common";
+import type { AccountClient } from "../client/account";
+import type { LYCToken, TokenLendingPositionData } from "../models/lycToken";
+import type { BurnAmounts } from "../client/types/general";
+import { LYCYieldingBank } from "../models/yieldingBank";
+import type { LendingPlatformClientBase, LendingPlatformData } from "lending-platforms";
+import { LycLendingPositionManager } from "../services/carry";
+
+/** Any object that can resolve a lending-platform client for a given position. */
+export interface LendingPlatformResolver {
+  getForPosition(
+    position: TokenLendingPositionData
+  ): LendingPlatformClientBase<LendingPlatformData>;
+}
+
+type BurnUnwindCandidate = {
+  lendingPositionIndex: number;
+  position: TokenLendingPositionData;
+  collateralAmount: bigint;
+};
+
+export function getBurnCollateralWithdrawalAmount(tokenData: LYCToken, burnAmount: BN | number) {
+  const { collateralToUser } = tokenData.computeBurnAmounts(burnAmount);
+  const unlentAmount = BigInt(tokenData.data.collateral.unlentAmount.toString());
+  const reserved = BigInt(tokenData.data.accounting.pendingAsyncRedemptionLiability.toString());
+  const available = unlentAmount > reserved ? unlentAmount - reserved : BigInt(0);
+  return collateralToUser > available ? collateralToUser - available : BigInt(0);
+}
+
+export function getBurnCollateralWithdrawalUiAmount(
+  tokenData: LYCToken,
+  burnAmount: BN | number,
+  includeOneUnitTolerance = false
+) {
+  const withdrawalAmount = getBurnCollateralWithdrawalAmount(tokenData, burnAmount);
+  const adjustedWithdrawalAmount =
+    includeOneUnitTolerance && withdrawalAmount > BigInt(0)
+      ? withdrawalAmount + BigInt(1)
+      : withdrawalAmount;
+  return toUiAmount(adjustedWithdrawalAmount, tokenData.data.collateral.decimals);
+}
+
+export async function computeBurnAmountsForFrontendEstimate(
+  _account: AccountClient,
+  tokenData: LYCToken,
+  burnAmount: BN | number,
+  _resolver: LendingPlatformResolver
+): Promise<BurnAmounts> {
+  // TODO: For frontend redemption estimates, account for expected
+  // default-redemption swap slippage/fee.
+  return tokenData.computeBurnAmounts(burnAmount);
+}
+
+async function collectBurnUnwindCandidates(
+  tokenData: LYCToken,
+  collateralWithdrawalUiAmount: number,
+  resolver: LendingPlatformResolver
+): Promise<BurnUnwindCandidate[]> {
+  const candidates: BurnUnwindCandidate[] = [];
+
+  for (let i = 0; i < tokenData.data.lendingPositions.length; i++) {
+    const position = tokenData.data.lendingPositions[i];
+    if (lendingPlatformToEnum(position.platform) === LendingPlatform.None) {
+      continue;
+    }
+
+    const lpClient = resolver.getForPosition(position);
+    const manager = await LycLendingPositionManager.create(lpClient.data, position);
+    const eligibility = await manager.getBurnUnwindEligibility(collateralWithdrawalUiAmount);
+    if (!eligibility) {
+      continue;
+    }
+
+    candidates.push({
+      lendingPositionIndex: i,
+      position,
+      collateralAmount: BigInt(position.accounting.collateral.toString()),
+    });
+  }
+
+  return candidates;
+}
+
+/**
+ * True when at least one active lending position can supply the collateral implied by `burnAmount`
+ * for a liquidity-managed burn (same eligibility filter as {@link findPositionToUnwindForBurn}).
+ */
+export async function hasLendingPositionCoveringBurn(
+  tokenData: LYCToken,
+  burnAmount: BN | number,
+  resolver: LendingPlatformResolver
+): Promise<boolean> {
+  const collateralWithdrawalUiAmount = getBurnCollateralWithdrawalUiAmount(
+    tokenData,
+    burnAmount,
+    true
+  );
+  const candidates = await collectBurnUnwindCandidates(
+    tokenData,
+    collateralWithdrawalUiAmount,
+    resolver
+  );
+  return candidates.length > 0;
+}
+
+/**
+ * True when the best burn-candidate lending position can absorb a collateral
+ * withdrawal for `burnAmount` without pushing the LTV utilization rate above
+ * the position's upper deviation band — meaning no `decrease_carry_position`
+ * (debt repayment) is required.
+ *
+ * Should only be called after {@link hasLendingPositionCoveringBurn} returns
+ * `true`; uses the same candidate selection logic as
+ * {@link findPositionToUnwindForBurn}.
+ */
+export async function isWithdrawOnlyBurnFeasible(
+  tokenData: LYCToken,
+  burnAmount: BN | number,
+  resolver: LendingPlatformResolver
+): Promise<boolean> {
+  const collateralWithdrawalUiAmount = getBurnCollateralWithdrawalUiAmount(
+    tokenData,
+    burnAmount,
+    true
+  );
+
+  let position: TokenLendingPositionData;
+  try {
+    ({ position } = await findPositionToUnwindForBurn(
+      tokenData,
+      collateralWithdrawalUiAmount,
+      resolver
+    ));
+  } catch {
+    return false;
+  }
+
+  const lpClient = resolver.getForPosition(position);
+  const manager = await LycLendingPositionManager.create(lpClient.data, position);
+  const postWithdrawalUtilBps = await manager.calcPostWithdrawalUtilizationRateBps(
+    collateralWithdrawalUiAmount
+  );
+
+  const upperBound =
+    position.config.targetUtilizationRateBps + position.config.maxDeviationAboveTargetUtilBps;
+  return postWithdrawalUtilBps <= upperBound;
+}
+
+/**
+ * Chooses which `lendingPositions` slot to unwind for a burn liquidity-managed tx.
+ *
+ * Considers only active positions with a supported platform and collateral mint
+ * matching the token. Filters to positions that can cover `collateralWithdrawalUiAmount`
+ * (same strict less-than full-supply rule as pre-withdraw repay sizing). Among those,
+ * picks the position with the most deposited collateral (tie → lower index) so the
+ * burn unwind comes out of the deepest slot and small positions are left intact.
+ *
+ * @param getLendingPlatformClient - Resolves the Kamino (etc.) client for a position;
+ *   kept injectable so callers are not tied to transaction wiring.
+ */
+export async function findPositionToUnwindForBurn(
+  tokenData: LYCToken,
+  collateralWithdrawalUiAmount: number,
+  resolver: LendingPlatformResolver
+): Promise<{ lendingPositionIndex: number; position: TokenLendingPositionData }> {
+  const candidates = await collectBurnUnwindCandidates(
+    tokenData,
+    collateralWithdrawalUiAmount,
+    resolver
+  );
+
+  if (!candidates.length) {
+    // Fallback: the withdrawal would fully drain the position (supply <=
+    // withdrawal amount), so the eligibility filter excluded it. Pick the
+    // largest active position instead — the SDK will pass the "all" sentinel.
+    const fallback = findLargestActiveLendingPosition(tokenData);
+    if (fallback) {
+      return fallback;
+    }
+    throw new Error(
+      "No lending position can cover this burn collateral withdrawal with the token collateral mint (or platform is unsupported)"
+    );
+  }
+
+  candidates.sort((a, b) => {
+    if (a.collateralAmount === b.collateralAmount) {
+      return a.lendingPositionIndex - b.lendingPositionIndex;
+    }
+    return b.collateralAmount > a.collateralAmount ? 1 : -1;
+  });
+
+  const best = candidates[0]!;
+  return { lendingPositionIndex: best.lendingPositionIndex, position: best.position };
+}
+
+/**
+ * Finds the largest active (non-None platform) lending position by collateral
+ * amount. Used as a fallback when the standard eligibility filter excludes all
+ * positions (e.g. when the withdrawal fully drains the position).
+ */
+function findLargestActiveLendingPosition(
+  tokenData: LYCToken
+): { lendingPositionIndex: number; position: TokenLendingPositionData } | null {
+  let best: { lendingPositionIndex: number; position: TokenLendingPositionData } | null = null;
+  let bestCollateral = BigInt(0);
+
+  for (let i = 0; i < tokenData.data.lendingPositions.length; i++) {
+    const position = tokenData.data.lendingPositions[i];
+    if (lendingPlatformToEnum(position.platform) === LendingPlatform.None) {
+      continue;
+    }
+    const collateral = BigInt(position.accounting.collateral.toString());
+    if (collateral > bestCollateral) {
+      bestCollateral = collateral;
+      best = { lendingPositionIndex: i, position };
+    }
+  }
+
+  return best;
+}
+
+/**
+ * Picks the yielding bank to fund repay/swap during a burn liquidity-managed tx.
+ *
+ * Enumerates banks derived from active `debtCarry` entries on the token, fetches
+ * each account via `account.fetchYieldingBanks`, then:
+ * 1. Prefer a bank whose **debt mint** holding is at least `requiredDebtUiAmount` (debt token UI)
+ *    and is largest among those sufficient balances (headroom for the unwind repay).
+ * 2. Otherwise prefer the bank whose **default redemption mint** holding has the largest
+ *    balance in UI units (`toUiAmount` with the holding's on-chain `decimals`).
+ *
+ * Permissionless burn planning does not pass `sourceMint`; the default-redemption fallback
+ * assumes that path is viable for the chosen bank's holdings.
+ */
+export async function findBestYieldingBankForBurn(
+  account: AccountClient,
+  tokenData: LYCToken,
+  position: TokenLendingPositionData,
+  requiredDebtUiAmount: number
+): Promise<{ yieldingBank: Address }> {
+  const bankAddresses: Address[] = [];
+  const seen = new Set<string>();
+
+  for (let i = 0; i < tokenData.data.debtCarry.length; i++) {
+    const carry = tokenData.data.debtCarry[i];
+    if (carry.yieldingBaseMint.equals(PublicKey.default)) {
+      continue;
+    }
+    const bankPda = await tokenData.deriveYieldingBankAddressForDebtCarryIndex(i, account.pda);
+    const key = String(bankPda);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    bankAddresses.push(bankPda);
+  }
+
+  if (bankAddresses.length === 0) {
+    throw new Error(
+      "Token has no active yielding carry positions; cannot select a yielding bank for burn liquidity management"
+    );
+  }
+
+  const banks = await account.fetchYieldingBanks(bankAddresses);
+  const debtMint = fromWeb3Pk(position.accounting.debt.mint);
+
+  type SufficientDebt = { bank: LYCYieldingBank; debtHeldUi: number };
+  const sufficientDebt: SufficientDebt[] = [];
+  for (const bank of banks) {
+    const holding = bank.findAssetHolding(debtMint);
+    if (!holding) {
+      continue;
+    }
+    const debtHeldUi = toUiAmount(holding.amount, holding.decimals);
+    if (debtHeldUi >= requiredDebtUiAmount) {
+      sufficientDebt.push({ bank, debtHeldUi });
+    }
+  }
+
+  if (sufficientDebt.length > 0) {
+    const best = maxByNumber(sufficientDebt, (x) => x.debtHeldUi);
+    return { yieldingBank: best.bank.address };
+  }
+
+  type DefaultMintUi = { bank: LYCYieldingBank; defaultMintUiAmount: number };
+  const defaultMintUi: DefaultMintUi[] = [];
+  for (const bank of banks) {
+    const holding = bank.findAssetHolding(bank.defaultRedemptionMint);
+    if (!holding) {
+      continue;
+    }
+    defaultMintUi.push({
+      bank,
+      defaultMintUiAmount: toUiAmount(holding.amount, holding.decimals),
+    });
+  }
+
+  if (defaultMintUi.length > 0) {
+    const best = maxByNumber(defaultMintUi, (x) => x.defaultMintUiAmount);
+    return { yieldingBank: best.bank.address };
+  }
+
+  throw new Error(
+    "No yielding bank linked to this token has sufficient debt liquidity for unwind or an active default redemption holding"
+  );
+}

package/src/utils/timelock.ts

@@ -0,0 +1,63 @@
+import { BN } from "@anchor-lang/core";
+import { type Environment, toBigInt } from "common";
+
+export type TimelockKind = "touch" | "cleanup";
+
+export interface TimelockStatus {
+  enabled: boolean;
+  isTimelocked: boolean;
+  timeCreated: bigint;
+  unlockAt?: bigint;
+  remainingSecs: bigint;
+}
+
+export interface TimelockOptions {
+  enableLocalTimelocks?: boolean;
+}
+
+const TIMELOCK_COOLDOWN_SECS: Record<TimelockKind, bigint> = {
+  touch: 12n * 60n * 60n,
+  cleanup: 24n * 60n * 60n,
+};
+
+export function timelocksEnabled(environment: Environment, options: TimelockOptions = {}): boolean {
+  return (
+    environment === "prod" || (environment === "local" && options.enableLocalTimelocks === true)
+  );
+}
+
+export function getTimelockStatus(
+  environment: Environment,
+  timeCreated: bigint | number | BN,
+  kind: TimelockKind,
+  options: TimelockOptions = {}
+): TimelockStatus {
+  const createdAt = toBigInt(timeCreated);
+  const enabled = timelocksEnabled(environment, options);
+
+  if (!enabled || createdAt === 0n) {
+    return {
+      enabled,
+      isTimelocked: false,
+      timeCreated: createdAt,
+      remainingSecs: 0n,
+    };
+  }
+
+  const unlockAt = createdAt + TIMELOCK_COOLDOWN_SECS[kind];
+  const now = BigInt(Math.floor(Date.now() / 1000));
+  const remainingSecs = unlockAt > now ? unlockAt - now : 0n;
+
+  return {
+    enabled,
+    isTimelocked: remainingSecs > 0n,
+    timeCreated: createdAt,
+    unlockAt,
+    remainingSecs,
+  };
+}
+
+export type AllocationTimelockKind = TimelockKind;
+export type AllocationTimelockStatus = TimelockStatus;
+export const allocationTimelocksEnabled = timelocksEnabled;
+export const getAllocationTimelockStatus = getTimelockStatus;