@kestrelfi/lyc-sdk 1.0.1

package/src/constants/configs/allocations.ts

@@ -0,0 +1,30 @@
+import {
+  enumToExternalLiquidityType,
+  enumToOracleType,
+  ExternalLiquidityType,
+  mints,
+  OracleType,
+} from "common";
+import { YieldingBankAllocationConfig } from "../../client";
+import { oracle } from "oracle";
+
+const USD_STAR = mints.get("USD*")!;
+const USD_STAR_JUNIOR = mints.get("USD*-J")!;
+
+export const usdStarAllocationConfig: YieldingBankAllocationConfig = {
+  assetHolding: {
+    mint: USD_STAR.address,
+    oracle: oracle.getOracleData("USD*").oracle,
+    oracleType: enumToOracleType(OracleType.PerenaBank),
+    externalLiquidityType: enumToExternalLiquidityType(ExternalLiquidityType.None),
+  },
+};
+
+export const usdStarJuniorAllocationConfig: YieldingBankAllocationConfig = {
+  assetHolding: {
+    mint: USD_STAR_JUNIOR.address,
+    oracle: oracle.getOracleData("USD*-J").oracle,
+    oracleType: enumToOracleType(OracleType.PerenaTranche),
+    externalLiquidityType: enumToExternalLiquidityType(ExternalLiquidityType.PerenaWithdrawalQueue),
+  },
+};

package/src/constants/configs/carryTradePresets.ts

@@ -0,0 +1,164 @@
+/**
+ * Per-asset carry trade price-band presets, split by volatility regime.
+ *
+ * Each preset defines three drawdown / rally buffers that control how aggressively a
+ * lending position is utilized relative to its liquidation line:
+ *
+ * - `drawdownPctFromTargetToLiq` — collateral drawdown (%) that separates the **target**
+ *    utilization from the liquidation line. Larger = more conservative target.
+ * - `drawdownPctFromUnwindToLiq` — collateral drawdown (%) that separates the **unwind
+ *    trigger** from the liquidation line. Smaller than target (closer to liquidation).
+ * - `maxPriceChangeUpPercent` — max collateral **rally** (%) before the boost trigger fires,
+ *    prompting the position to borrow more and return to target.
+ *
+ * ## Usage
+ *
+ * Select the appropriate asset preset and volatility regime, then pass it to
+ * `LycLendingPositionManager.getLendingAllocationConfigFromPriceBands(preset)`, which combines
+ * the price-band params with pair-specific `maxLtv` and `liquidationThreshold` to produce
+ * a `CarryLendingAllocationConfig` (target utilization + deviation bands in bps). The
+ * resulting config is used to update the on-chain `LendingPositionConfig`, adapting the
+ * position's risk envelope to the current market regime.
+ *
+ * ## Asset tiers (tightest → widest buffers)
+ *
+ * BTC → ETH → SOL → large-cap alts → small-cap alts
+ *
+ * Higher-volatility assets use wider buffers to avoid unnecessary unwinds during normal
+ * price swings, while lower-volatility assets can afford tighter bands for better capital
+ * efficiency.
+ */
+import type { CarryPriceBandPreset } from "../../services/carry/carryAllocationConfig";
+
+export const VOLATILITY_REGIMES = ["lowVol", "highVol"] as const;
+export type VolatilityRegime = (typeof VOLATILITY_REGIMES)[number];
+
+export function isVolatilityRegime(s: string): s is VolatilityRegime {
+  return VOLATILITY_REGIMES.includes(s as VolatilityRegime);
+}
+
+export type CarryVolatilityPresets = {
+  lowVol: CarryPriceBandPreset;
+  highVol: CarryPriceBandPreset;
+};
+
+export interface AssetPresetEntry {
+  presets: CarryVolatilityPresets;
+  defaultRegime: VolatilityRegime;
+}
+
+export const STOCK_INDEX_PRESETS: CarryVolatilityPresets = {
+  lowVol: {
+    drawdownPctFromTargetToLiq: 8,
+    drawdownPctFromUnwindToLiq: 5,
+    maxPriceChangeUpPercent: 2,
+  },
+  highVol: {
+    drawdownPctFromTargetToLiq: 11,
+    drawdownPctFromUnwindToLiq: 7,
+    maxPriceChangeUpPercent: 3,
+  },
+};
+
+export const BTC_CARRY_PRESETS: CarryVolatilityPresets = {
+  lowVol: {
+    drawdownPctFromTargetToLiq: 12,
+    drawdownPctFromUnwindToLiq: 8,
+    maxPriceChangeUpPercent: 6,
+  },
+  highVol: {
+    drawdownPctFromTargetToLiq: 14,
+    drawdownPctFromUnwindToLiq: 10,
+    maxPriceChangeUpPercent: 8,
+  },
+};
+
+export const ETH_CARRY_PRESETS: CarryVolatilityPresets = {
+  lowVol: {
+    drawdownPctFromTargetToLiq: 14,
+    drawdownPctFromUnwindToLiq: 10,
+    maxPriceChangeUpPercent: 7,
+  },
+  highVol: {
+    drawdownPctFromTargetToLiq: 17,
+    drawdownPctFromUnwindToLiq: 12,
+    maxPriceChangeUpPercent: 10,
+  },
+};
+
+export const SOL_CARRY_PRESETS: CarryVolatilityPresets = {
+  lowVol: {
+    drawdownPctFromTargetToLiq: 16,
+    drawdownPctFromUnwindToLiq: 12,
+    maxPriceChangeUpPercent: 8,
+  },
+  highVol: {
+    drawdownPctFromTargetToLiq: 19,
+    drawdownPctFromUnwindToLiq: 14,
+    maxPriceChangeUpPercent: 11,
+  },
+};
+
+export const LST_CARRY_PRESETS: CarryVolatilityPresets = {
+  lowVol: {
+    drawdownPctFromTargetToLiq: 19,
+    drawdownPctFromUnwindToLiq: 10,
+    maxPriceChangeUpPercent: 8,
+  },
+  highVol: {
+    drawdownPctFromTargetToLiq: 22,
+    drawdownPctFromUnwindToLiq: 12,
+    maxPriceChangeUpPercent: 11,
+  },
+};
+
+export const LARGE_CAP_ALT_CARRY_PRESETS: CarryVolatilityPresets = {
+  lowVol: {
+    drawdownPctFromTargetToLiq: 22,
+    drawdownPctFromUnwindToLiq: 16,
+    maxPriceChangeUpPercent: 8,
+  },
+  highVol: {
+    drawdownPctFromTargetToLiq: 25,
+    drawdownPctFromUnwindToLiq: 18,
+    maxPriceChangeUpPercent: 10,
+  },
+};
+
+export const SMALL_CAP_ALT_CARRY_PRESETS: CarryVolatilityPresets = {
+  lowVol: {
+    drawdownPctFromTargetToLiq: 26,
+    drawdownPctFromUnwindToLiq: 22,
+    maxPriceChangeUpPercent: 10,
+  },
+  highVol: {
+    drawdownPctFromTargetToLiq: 29,
+    drawdownPctFromUnwindToLiq: 24,
+    maxPriceChangeUpPercent: 12,
+  },
+};
+
+/**
+ * Maps collateral symbol (upper-cased) to its carry trade preset tier and
+ * default volatility regime. Used by scripts and backend services to resolve
+ * the correct price-band parameters when creating or reconfiguring lending
+ * positions.
+ */
+export const ASSET_PRESETS: Record<string, AssetPresetEntry> = {
+  WBTC: { presets: BTC_CARRY_PRESETS, defaultRegime: "lowVol" },
+  CBBTC: { presets: BTC_CARRY_PRESETS, defaultRegime: "lowVol" },
+  WETH: { presets: ETH_CARRY_PRESETS, defaultRegime: "lowVol" },
+  SOL: { presets: SOL_CARRY_PRESETS, defaultRegime: "lowVol" },
+  JUPSOL: { presets: LST_CARRY_PRESETS, defaultRegime: "lowVol" },
+  JITOSOL: { presets: LST_CARRY_PRESETS, defaultRegime: "lowVol" },
+  DFDVSOL: { presets: LST_CARRY_PRESETS, defaultRegime: "lowVol" },
+  SPYX: { presets: STOCK_INDEX_PRESETS, defaultRegime: "lowVol" },
+  QQQX: { presets: STOCK_INDEX_PRESETS, defaultRegime: "lowVol" },
+  LARGE_CAP: { presets: LARGE_CAP_ALT_CARRY_PRESETS, defaultRegime: "lowVol" },
+  SMALL_CAP: { presets: SMALL_CAP_ALT_CARRY_PRESETS, defaultRegime: "highVol" },
+};
+
+/** Looks up the carry preset entry for a collateral symbol (case-insensitive). */
+export function resolvePresets(collateralSymbol: string): AssetPresetEntry | undefined {
+  return ASSET_PRESETS[collateralSymbol.toUpperCase()];
+}

package/src/constants/configs/index.ts

@@ -0,0 +1,2 @@
+export * from "./allocations";
+export * from "./carryTradePresets";

package/src/constants/general.ts

@@ -0,0 +1,141 @@
+import { BN } from "@anchor-lang/core";
+import { Address, address } from "@solana/kit";
+import {
+  DEPLOYED_ADMIN_KEYPAIR_FP,
+  PROTOCOL_ADMIN,
+  type DeployedEnv,
+  type Environment,
+} from "common";
+
+/** Program ID per environment */
+export const PROGRAM_ID: Record<Environment, Address> = {
+  local: address("7YPAKESPJ7zJAvBuk45ZVziu6tXGKoNzg3p9YpvrH6pX"),
+  test: address("7C39GeKrqLygmgV9D4bicUaiyFhKrX6Eevk6PDACwuj7"),
+  prod: address("LYC8YiiSzQfPpxUW2tpxfuPKGZwywAJhXKUfDP2B66f"),
+};
+
+/** Manager authority for manager-gated instruction accounts */
+export const MANAGER: Record<Environment, Address> = {
+  local: address("4g1CzxGL2hopch95Aeww9RrQjx3NPq7NgN9QFK7jx8X1"),
+  test: address("AqB478KVcoBwV39QjftJQ6qvV9xTh8CYB9jEnc2XSNLu"),
+  prod: address("4g1CzxGL2hopch95Aeww9RrQjx3NPq7NgN9QFK7jx8X1"), // TODO
+};
+
+/** Circuit breaker controller for circuit-breaker-gated instruction accounts */
+export const CIRCUIT_BREAKER_CONTROLLER: Record<Environment, Address> = {
+  local: address("CAcAFXBQBbr5xpESdbd9L1tEijPq1o2bdxju56qMZssj"),
+  test: address("Wrj4caR4RJcmPgrRBE3HyFVMRKEmd2Y1ZuChbcjdeQu"),
+  prod: address("7PxS1VMxKbzUTF4sxeAw4LqBfnGMaeQH2KwabmUcVxYC"), // TODO
+};
+
+/** Re-exported from `common` — see {@link PROTOCOL_ADMIN} there. */
+export { PROTOCOL_ADMIN };
+
+/**
+ * Protocol fee wallet — receives the protocol share of mint/burn + perf fees
+ * and serves as the on-chain fallback for a token's `roles.fees` when unset
+ * (`TokenRoles::curator_fee_wallet()` delegates to `protocol_fee_wallet()`).
+ */
+export const PROTOCOL_FEE_WALLET: Record<Environment, Address> = {
+  local: address("Fo6ihiHavRRnFG7k24JgwxNqVt6j7FWAWxDwoGoKd2MY"),
+  test: address("8L2dWQqs6oQW6GCwp3fuosFTi5uCRJcbhhCKkjtyFG2e"),
+  prod: address("Fo6ihiHavRRnFG7k24JgwxNqVt6j7FWAWxDwoGoKd2MY"), // TODO
+};
+
+/** Redemption epoch status: accepting new async burn requests. */
+export const REDEMPTION_EPOCH_STATUS_OPEN = 0;
+/** Redemption epoch status: closed to new requests, collateral being funded. */
+export const REDEMPTION_EPOCH_STATUS_FUNDING = 1;
+/** Redemption epoch status: funded, individual burn requests being processed. */
+export const REDEMPTION_EPOCH_STATUS_PROCESSING = 2;
+
+/**
+ * On-chain `TokenAccounting::MAX_FRESHNESS_SECS` = ONE_HOUR (3600s).
+ * We use a 120s buffer so the refresh lands before on-chain staleness kicks in.
+ */
+export const TOKEN_STALENESS_THRESHOLD_SECS = 3600 - 120;
+
+/** Maximum heap-frame size requested by composed multi-CPI transactions. */
+export const MAX_HEAP_FRAME_BYTES = 256 * 1024;
+
+/**
+ * Mirror of the on-chain `REBALANCE_TOKEN_RATE_LIMIT_SECS` (24 hours). The
+ * program rejects a `rebalance_token` on a lending position that was already
+ * rebalanced within this window (`RebalanceRateLimited`); the SDK skips such
+ * candidates client-side so we never build a transaction that would revert.
+ */
+export const REBALANCE_TOKEN_RATE_LIMIT_SECS = 24 * 60 * 60;
+
+/** Default recollateralize-loss swap slippage, capped by the on-chain 150 bps check. */
+export const DEFAULT_RECOLLATERALIZE_LOSS_SLIPPAGE_BPS = 150;
+
+/**
+ * Minimum claimable reward (in the reward token's UI units) for an incentive to
+ * be worth harvesting. Below this, the on-chain `HarvestReward` moves only dust
+ * while still costing a transaction fee, so `getOutstandingIncentives` omits it.
+ */
+export const DEFAULT_MIN_INCENTIVE_UI_AMOUNT = 0.01;
+
+/**
+ * Sentinel value (u64::MAX) that callers can pass as an amount to `mint_token`
+ * or `burn_token` to indicate "use the entire balance".
+ * - mint_token: deposits the full collateral ATA balance.
+ * - burn_token: burns the full yToken ATA balance.
+ */
+export const AMOUNT_ALL_SENTINEL = new BN("18446744073709551615");
+
+/** Re-exported from `common` — see {@link DEPLOYED_ADMIN_KEYPAIR_FP} there. */
+export const LYC_ADMIN_KEYPAIR_FP = DEPLOYED_ADMIN_KEYPAIR_FP;
+
+/**
+ * Filesystem paths to the manager keypair for future manager CLI scripts,
+ * fixed per deployment tier (no env overrides).
+ */
+export const LYC_MANAGER_KEYPAIR_FP: Record<DeployedEnv, string> = {
+  test: "~/.config/solana/tp-lyc-manager-test.json",
+  prod: "~/.config/solana/tp-lyc-manager-prod.json",
+};
+
+/**
+ * Filesystem paths to the circuit breaker controller keypair.
+ * Used by emergency scripts (trigger circuit breaker, reset burn rate limit).
+ */
+export const LYC_CB_KEYPAIR_FP: Record<DeployedEnv, string> = {
+  test: "~/.config/solana/tp-lyc-cb-test.json",
+  prod: "~/.config/solana/tp-lyc-cb-prod.json",
+};
+
+/**
+ * Shared general LUT per remote deployment tier (`test` | `prod`), same split as
+ * {@link LYC_ADMIN_KEYPAIR_FP}. Populate via `pnpm run update-general-lut -- test|prod`.
+ */
+export const GENERAL_LOOKUP_TABLES: Record<DeployedEnv, Address> = {
+  test: address("GbiTxgWknTyRD2qwCvtytPXa1KnCwJWqakH4mJRpU3mF"),
+  prod: address("11111111111111111111111111111111"), // TODO
+};
+
+export const TOKEN_LOOKUP_TABLES: Record<Address, Address> = {
+  // TEST
+  [address("7fEA5HTsveMn5HfnXN82nmTniXeWDs6YJuvLyk7qFcNG")]: address(
+    "HTBxsGsKgfMmPVuxdia1PQkdATUrFofmbJAtC7he6qEK"
+  ),
+  [address("2BGSs7s5mSJgSCMcppAaQj5Ppp1kHmQNQ9ESoGWK2Hmx")]: address(
+    "5UmqM2LE4RwpF91aXiXNVB5tSJKsLoVfxLA3gc6Qrj35"
+  ),
+  [address("6qtzJnVn6nTZXJhcAUgmofKsTYuaSp8ag1BcxcE9EEz7")]: address(
+    "DJstSjLyA4KwhgRh3s1Bd28eSoke8st6nAXTDNVtckqj"
+  ),
+  [address("3m9Nx5ZCghjsMPmBpJm1ZWb27SUHLzdUJdwb2mquo3Kb")]: address(
+    "3bZYrhiqee6zPCvnXqMjNjtN5M7aPa4rebvmEtVUvGwG"
+  ),
+  [address("HbhfU6ihxuzzpwmdgpWP5QC6HpemnMGZANCQEDQ7V92L")]: address(
+    "EJSQZD9qzqaBacntUgouM9dmo9dgeBechNvASZ3V4NRr"
+  ),
+  [address("GphwC2jwG3mcM8FYFFm5j8A4jNw3i7Hhic4poLbnoKpu")]: address(
+    "6x8fiZxU6f82a3grAECC8nLuwkFoBPjFwAYhfpbeqw18"
+  ),
+  [address("975Zp2WbD7WQfG6mTDPVUjc4mbEALMBXeyn4Pwr45f7p")]: address(
+    "9ERF9KcYvehmMku9mqAvzhduDHpJu36pcvZ3xr2NJJ9o"
+  ),
+  // PROD
+};

package/src/constants/index.ts

@@ -0,0 +1,3 @@
+export * from "./general";
+export * from "./configs";
+export * from "./lycTokenMetadata";

package/src/constants/lycTokenMetadata.ts

@@ -0,0 +1,52 @@
+import type { Environment } from "common";
+
+/**
+ * Display fields used as the fallback when on-chain Metaplex Token-Metadata
+ * is missing or empty. Mirrors {@link OnchainTokenMetadata} on the read path
+ * so the consumer can treat both sources uniformly.
+ */
+export interface LycTokenMetadataEntry {
+  /** Brand-cased symbol shown as the primary label (e.g. "ksBTC", "primeBTC"). */
+  symbol: string;
+  /** Human-readable name (e.g. "Kestrel BTC", "Prime BTC"). */
+  name: string;
+}
+
+/**
+ * Curated fallback registry of LYC token display metadata, keyed by the
+ * token's mint address. Only used when on-chain Metaplex Token-Metadata
+ * isn't set yet — the on-chain value always wins.
+ *
+ * This exists because:
+ *   1. Multiple LYC tokens can share the same underlying collateral
+ *      (e.g. ksBTC and primeBTC both built on cbBTC), so the LYC token's
+ *      symbol cannot be synthesized from the collateral's symbol alone.
+ *   2. Metaplex `update_token_metadata` requires an admin transaction we
+ *      don't always run before a token starts surfacing in the UI.
+ *
+ * Keyed by environment because LYC mints are unique per program deployment.
+ *
+ * To populate, add the LYC token mint address as the key. Once metadata is
+ * set on-chain via:
+ *
+ *   pnpm --filter @kestrelfi/lyc-sdk run \
+ *     update-token-metadata -- test|prod <TOKEN_PDA|COLLATERAL_SYMBOL> \
+ *     --name "<Display Name>" --symbol "<ksXXX>" --uri "<json uri>"
+ *
+ * the entry here can be removed.
+ */
+export const LYC_TOKEN_METADATA: Record<Environment, Record<string, LycTokenMetadataEntry>> = {
+  local: {},
+  test: {
+    EsMqszfbgHtVgh5N2q1wKSEQQAP4HqojRVjDgDo6MB4U: { symbol: "ksBTC", name: "Kestrel BTC" },
+    JD9axkbp23WabWcVJJQfBvJ9z7Qn4A2zayHhRED8ynZq: { symbol: "ksETH", name: "Kestrel ETH" },
+    GFMBAKop6cdzBTqW9PP2eKddowDgXZSK1P6Bp8rCuFFm: { symbol: "ksSOL", name: "Kestrel SOL" },
+    "2z8P6DvqPzii6vuNu8JGPFBrGHQ94Fjgi9hHQQ7JcS34": {
+      symbol: "ksDFDVSOL",
+      name: "Kestrel dfdvSOL",
+    },
+    "8k3eDWZ6wZkJcBWYS4tzmtHfk2HjqxmwkLzr8wixXAcj": { symbol: "ksQQQX", name: "Kestrel QQQx" },
+    "9tPaWdEkjBYW3FbEBMt38wYAGdSWFj6wGXvzPrYwC4Bp": { symbol: "ksSPYX", name: "Kestrel SPYx" },
+  },
+  prod: {},
+};