@kestrelfi/lyc-sdk 1.0.1

package/scripts/updateTokenLuts.ts

@@ -0,0 +1,36 @@
+import "./env";
+import {
+  createRpc,
+  loadLocalKeypairWithWeb3,
+  TP_LUT_MANAGER_KP_FP,
+  createDefaultAnchorProvider,
+} from "common";
+import { LongYieldCarryClient } from "../src/client/client";
+import { updateTokenLutsIfNeeded } from "../src/utils/lookupTables";
+import { extractKeypairFlag, parseCliEnvironmentAndRest } from "./localUtils";
+
+async function main() {
+  const { env, rest } = parseCliEnvironmentAndRest("update-token-luts");
+  const { rest: args, keypairPath: keypairFlagPath } = extractKeypairFlag(rest);
+  if (args.length > 0) {
+    console.error("Usage: pnpm run update-token-luts -- [test|prod] [--keypair KEYPAIR_JSON]");
+    process.exit(1);
+  }
+
+  const { signer, web3Keypair } = await loadLocalKeypairWithWeb3(
+    keypairFlagPath ?? TP_LUT_MANAGER_KP_FP
+  );
+  const rpc = createRpc(env);
+  const provider = createDefaultAnchorProvider(env, web3Keypair);
+  const client = new LongYieldCarryClient(provider, env);
+
+  await updateTokenLutsIfNeeded(signer, rpc, client);
+  console.log("Per-token LUT updates finished (see TOKEN_LOOKUP_TABLES in constants).");
+}
+
+main()
+  .then(() => console.log("Finished"))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/scripts/updateTokenMetadata.ts

@@ -0,0 +1,199 @@
+import "./env";
+import * as fs from "fs";
+import * as path from "path";
+import {
+  buildUpdateMetadataCpiData,
+  buildCreateMetadataCpiData,
+  createCpiRefs,
+  deriveMetadataPda,
+  fetchTokenMetadata,
+  loadLocalKeypairWithWeb3,
+  createDefaultAnchorProvider,
+} from "common";
+import { LongYieldCarryClient } from "../src/client/client";
+import { LYC_ADMIN_KEYPAIR_FP } from "../src/constants/general";
+import { extractKeypairFlag, parseCliEnvironmentAndRest, resolveTokenPda } from "./localUtils";
+
+/**
+ * Updates on-chain Metaplex metadata (name, symbol, URI) for a token's mint.
+ *
+ * Usage:
+ *   pnpm run update-token-metadata -- test|prod <TOKEN_PDA|COLLATERAL_SYMBOL> [--name NAME] [--symbol SYMBOL] [--uri URI] [--json PATH] [KEYPAIR_JSON]
+ *
+ * At least one of --name, --symbol, --uri, or --json must be provided.
+ * Omitted fields retain their current on-chain values.
+ * When --json is provided, its fields (name, symbol, uri) override individual flags.
+ *
+ * Examples:
+ *   pnpm run update-token-metadata -- test SOL --name "ySOL" --symbol "ySOL" --uri "https://example.com/ysol.json"
+ *   pnpm run update-token-metadata -- test SOL --name "Long Yield SOL"
+ *   pnpm run update-token-metadata -- prod 7fEA5HTsveMn5HfnXN82nmTniXeWDs6YJuvLyk7qFcNG --uri "https://example.com/new-metadata.json"
+ *   pnpm run update-token-metadata -- prod SOL --json ./docs/example-metadata.json
+ */
+async function main() {
+  const { env, rest } = parseCliEnvironmentAndRest("update-token-metadata");
+  const { rest: args, keypairPath: keypairFlagPath } = extractKeypairFlag(rest);
+
+  const { tokenArg, flags, keypairArg } = parseArgs(args);
+
+  const keypairPath = keypairFlagPath ?? keypairArg ?? LYC_ADMIN_KEYPAIR_FP[env];
+
+  const { signer: adminSigner, web3Keypair } = await loadLocalKeypairWithWeb3(keypairPath);
+  const provider = createDefaultAnchorProvider(env, web3Keypair);
+  const client = new LongYieldCarryClient(provider, env);
+
+  const { tokenPda, collateralSymbol } = await resolveTokenPda(client, tokenArg);
+  const token = await client.account.fetchToken(tokenPda, { fresh: true });
+  const mint = token.mint;
+
+  const metadataPda = await deriveMetadataPda(mint);
+  const connection = provider.connection;
+  const currentMetadata = await fetchTokenMetadata(connection, mint);
+  const isCreate = currentMetadata === null;
+
+  const currentName = currentMetadata?.name ?? "";
+  const currentSymbol = currentMetadata?.symbol ?? "";
+  const currentUri = currentMetadata?.uri ?? "";
+
+  const newName = flags.name ?? currentName;
+  const newSymbol = flags.symbol ?? currentSymbol;
+  const newUri = flags.uri ?? currentUri;
+
+  console.log(`Token PDA:  ${tokenPda} (collateral: ${collateralSymbol ?? "unknown"})`);
+  console.log(`Mint:       ${mint}`);
+  console.log(`Metadata:   ${metadataPda}`);
+  console.log(`Action:     ${isCreate ? "CREATE (no metadata account exists)" : "UPDATE"}`);
+  console.log("");
+  if (!isCreate) {
+    console.log("Current metadata:");
+    console.log(`  name:   "${currentName}"`);
+    console.log(`  symbol: "${currentSymbol}"`);
+    console.log(`  uri:    "${currentUri}"`);
+    console.log("");
+  }
+  console.log("New metadata:");
+  console.log(`  name:   "${newName}"${flags.name || isCreate ? "" : " (unchanged)"}`);
+  console.log(`  symbol: "${newSymbol}"${flags.symbol || isCreate ? "" : " (unchanged)"}`);
+  console.log(`  uri:    "${newUri}"${flags.uri || isCreate ? "" : " (unchanged)"}`);
+
+  if (
+    !isCreate &&
+    newName === currentName &&
+    newSymbol === currentSymbol &&
+    newUri === currentUri
+  ) {
+    console.log("\nNo changes detected — skipping transaction.");
+    return;
+  }
+
+  const cpiData = isCreate
+    ? await buildCreateMetadataCpiData({
+        mint,
+        mintAuthority: tokenPda,
+        payer: adminSigner.address,
+        updateAuthority: tokenPda,
+        data: { name: newName, symbol: newSymbol, uri: newUri },
+      })
+    : await buildUpdateMetadataCpiData({
+        mint,
+        updateAuthority: tokenPda,
+        data: { name: newName, symbol: newSymbol, uri: newUri },
+      });
+
+  const { accounts, refs } = createCpiRefs([cpiData]);
+
+  const plan = await client.tx.updateTokenMetadata.getTx({
+    token: tokenPda,
+    mint,
+    params: {
+      ixRefs: refs,
+      remainingAccounts: accounts,
+    },
+  });
+
+  const sig = await client.sendTransaction(adminSigner, plan);
+
+  console.log("");
+  console.log("update_token_metadata succeeded.");
+  console.log("  environment:", env);
+  console.log("  admin:", adminSigner.address);
+  console.log("  signature:", sig);
+}
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+interface ParsedFlags {
+  name?: string;
+  symbol?: string;
+  uri?: string;
+}
+
+function parseArgs(rest: string[]): {
+  tokenArg: string;
+  flags: ParsedFlags;
+  keypairArg?: string;
+} {
+  if (rest.length < 1) {
+    printUsageAndExit();
+  }
+
+  const tokenArg = rest[0];
+  const flags: ParsedFlags = {};
+  let keypairArg: string | undefined;
+
+  let i = 1;
+  while (i < rest.length) {
+    const arg = rest[i];
+    if (arg === "--name" && i + 1 < rest.length) {
+      flags.name = rest[++i];
+    } else if (arg === "--symbol" && i + 1 < rest.length) {
+      flags.symbol = rest[++i];
+    } else if (arg === "--uri" && i + 1 < rest.length) {
+      flags.uri = rest[++i];
+    } else if (arg === "--json" && i + 1 < rest.length) {
+      const jsonPath = path.resolve(process.env.INIT_CWD ?? process.cwd(), rest[++i]);
+      const raw = JSON.parse(fs.readFileSync(jsonPath, "utf-8"));
+      if (raw.name) flags.name = raw.name;
+      if (raw.symbol) flags.symbol = raw.symbol;
+      if (raw.uri) flags.uri = raw.uri;
+    } else if (!arg.startsWith("--") && !keypairArg) {
+      keypairArg = arg;
+    } else {
+      console.error(`Unknown or incomplete argument: ${arg}`);
+      printUsageAndExit();
+    }
+    i++;
+  }
+
+  if (!flags.name && !flags.symbol && !flags.uri) {
+    console.error("Error: At least one of --name, --symbol, --uri, or --json must be provided.\n");
+    printUsageAndExit();
+  }
+
+  return { tokenArg, flags, keypairArg };
+}
+
+function printUsageAndExit(): never {
+  console.error(
+    "Usage: pnpm run update-token-metadata -- [test|prod] <TOKEN_PDA|COLLATERAL_SYMBOL> [--name NAME] [--symbol SYMBOL] [--uri URI] [--json PATH] [KEYPAIR_JSON]\n\n" +
+      "Arguments:\n" +
+      "  TOKEN_PDA|COLLATERAL_SYMBOL  Token PDA address or collateral symbol (e.g. SOL)\n" +
+      "  --name NAME                  New token name\n" +
+      "  --symbol SYMBOL              New token symbol\n" +
+      "  --uri URI                    New metadata URI\n" +
+      "  --json PATH                  Path to a JSON file with name/symbol/uri fields\n" +
+      "  KEYPAIR_JSON                 Optional path to admin keypair JSON\n\n" +
+      "At least one of --name, --symbol, --uri, or --json must be provided.\n" +
+      "Omitted fields retain their current on-chain values."
+  );
+  process.exit(1);
+}
+
+main()
+  .then(() => console.log("Finished"))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/scripts/updateYieldingBankConfig.ts

@@ -0,0 +1,100 @@
+import "./env";
+import { address, type Address } from "@solana/kit";
+import { loadLocalKeypairWithWeb3, mints, createDefaultAnchorProvider } from "common";
+import { LongYieldCarryClient } from "../src/client/client";
+import { PROTOCOL_ADMIN, LYC_ADMIN_KEYPAIR_FP } from "../src/constants/general";
+import { extractKeypairFlag, isValidPubkeyString, parseCliEnvironmentAndRest } from "./localUtils";
+
+const USAGE = `Usage:
+
+  pnpm run update-yb-config -- [test|prod] <YIELDING_BANK> <REDEMPTION_MINT>
+
+  YIELDING_BANK:  yielding bank PDA address
+  REDEMPTION_MINT: new default redemption mint (common registry symbol like USD* or a mint address)
+
+  Examples:
+    pnpm run update-yb-config -- test 7fEA5HTs... USD*`;
+
+function resolveMint(arg: string): { mint: Address; label: string } {
+  const trimmed = arg.trim();
+  const symbol = trimmed.toUpperCase();
+  const mintInfo = mints.get(symbol);
+  if (mintInfo) {
+    return { mint: mintInfo.address, label: symbol };
+  }
+
+  if (!isValidPubkeyString(trimmed)) {
+    throw new Error(
+      `Unknown mint "${arg}". Use a common mint symbol (for example USD*) or a mint address.`
+    );
+  }
+
+  return { mint: address(trimmed), label: trimmed };
+}
+
+async function main() {
+  const { env, rest } = parseCliEnvironmentAndRest("update-yb-config");
+  const { rest: args, keypairPath: keypairFlagPath } = extractKeypairFlag(rest);
+
+  const yieldingBankArg = args[0];
+  const redemptionMintArg = args[1];
+
+  if (yieldingBankArg === undefined || redemptionMintArg === undefined) {
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  if (!isValidPubkeyString(yieldingBankArg)) {
+    console.error(`Invalid yielding bank address "${yieldingBankArg}".`);
+    process.exit(1);
+  }
+
+  let redemptionMint: Address;
+  let redemptionLabel: string;
+  try {
+    ({ mint: redemptionMint, label: redemptionLabel } = resolveMint(redemptionMintArg));
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+
+  const yieldingBank = address(yieldingBankArg);
+  const { signer: adminSigner, web3Keypair } = await loadLocalKeypairWithWeb3(
+    keypairFlagPath ?? LYC_ADMIN_KEYPAIR_FP[env]
+  );
+  const provider = createDefaultAnchorProvider(env, web3Keypair);
+  const client = new LongYieldCarryClient(provider, env);
+
+  const bank = await client.account.fetchYieldingBank(yieldingBank);
+  const currentRedemptionMint = bank.data.config.defaultRedemptionMint;
+
+  console.log("Yielding bank:", yieldingBank);
+  console.log("  base mint:", bank.baseMint);
+  console.log("");
+  console.log("Current config:");
+  console.log("  defaultRedemptionMint:", currentRedemptionMint);
+  console.log("");
+  console.log("New config:");
+  console.log("  defaultRedemptionMint:", redemptionMint, `(${redemptionLabel})`);
+
+  const plan = await client.tx.updateYieldingBankConfig.getTx({
+    yieldingBank,
+    params: {
+      defaultRedemptionMint: redemptionMint,
+    },
+  });
+  const sig = await client.sendTransaction(adminSigner, plan);
+
+  console.log("");
+  console.log("update_yielding_bank_config succeeded.");
+  console.log("  environment:", env);
+  console.log("  admin (must match on-chain):", PROTOCOL_ADMIN[env]);
+  console.log("  signature:", sig);
+}
+
+main()
+  .then(() => console.log("Finished"))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/scripts/withdrawUnlentCollateral.ts

@@ -0,0 +1,178 @@
+import "./env";
+import {
+  fromWeb3Pk,
+  loadLocalKeypairWithWeb3,
+  mints,
+  toBigInt,
+  toUiAmount,
+  createDefaultAnchorProvider,
+} from "common";
+import { LongYieldCarryClient } from "../src/client/client";
+import { LYC_MANAGER_KEYPAIR_FP } from "../src/constants/general";
+import { LycLendingPositionManager } from "../src/services/carry/lycLendingPositionManager";
+import {
+  extractKeypairFlag,
+  parseCliEnvironmentAndRest,
+  resolveLendingPositionIndex,
+  resolveTokenPda,
+} from "./localUtils";
+
+/** Mirrors on-chain `UTILIZATION_RATE_DEVIATION_THRESHOLD_BPS` (150 = 1.5%). */
+const UTILIZATION_RATE_DEVIATION_THRESHOLD_BPS = 150;
+
+const USAGE = `Withdraw collateral from a lending position into the token PDA's unlent reserves.
+
+Requires the **manager** keypair. Withdraws the maximum collateral allowed without
+pushing utilization above the position's target band (same constraint as
+top_up_unlent_reserves on-chain). Debt-free positions withdraw all supply.
+
+Usage:
+  pnpm run withdraw-unlent -- [test|prod] <TOKEN> <LP_INDEX|DEBT_SYMBOL> [KEYPAIR_JSON]
+  From repo root: pnpm run lyc:withdraw-unlent -- [test|prod] <TOKEN> <LP_INDEX|DEBT_SYMBOL] [KEYPAIR_JSON]
+
+Examples:
+  pnpm run withdraw-unlent -- test SOL USDC
+  pnpm run withdraw-unlent -- test SOL 0 --keypair ~/.config/solana/tp-lyc-manager-test.json
+
+Keypair defaults to ~/.config/solana/tp-lyc-manager-{env}.json`;
+
+async function main() {
+  const { env, rest } = parseCliEnvironmentAndRest("withdraw-unlent");
+  const { rest: args, keypairPath: keypairFlagPath } = extractKeypairFlag(rest);
+
+  const tokenArg = args[0];
+  const positionIdentifier = args[1];
+  if (tokenArg === undefined || positionIdentifier === undefined) {
+    console.error(USAGE);
+    process.exit(1);
+  }
+  if (args.length > 3) {
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  const keypairPath = keypairFlagPath ?? args[2] ?? LYC_MANAGER_KEYPAIR_FP[env];
+
+  const { signer: managerSigner, web3Keypair } = await loadLocalKeypairWithWeb3(keypairPath);
+  const provider = createDefaultAnchorProvider(env, web3Keypair);
+  const client = new LongYieldCarryClient(provider, env);
+
+  const { tokenPda, collateralSymbol } = await resolveTokenPda(client, tokenArg);
+  let token = await client.account.fetchToken(tokenPda, { fresh: true });
+  const lendingPositionIndex = resolveLendingPositionIndex(token, positionIdentifier, tokenPda);
+  const position = token.data.lendingPositions[lendingPositionIndex]!;
+  const debtMint = fromWeb3Pk(position.accounting.debt.mint);
+  const debtLabel = mints.get(debtMint)?.symbol ?? debtMint;
+
+  console.log("Withdraw unlent collateral");
+  console.log("  environment:", env);
+  console.log("  manager:", managerSigner.address);
+  console.log("  token:", tokenPda, collateralSymbol ? `(${collateralSymbol})` : "");
+  console.log("  lending position index:", lendingPositionIndex);
+  console.log("  debt mint:", debtLabel);
+
+  const collateralRaw = toBigInt(position.accounting.collateral);
+  if (collateralRaw === BigInt(0)) {
+    console.error("Lending position has no supplied collateral to withdraw.");
+    process.exit(1);
+  }
+
+  const collateralUiBefore = toUiAmount(collateralRaw, token.data.collateral.decimals);
+  console.log(`  supplied collateral: ${collateralUiBefore}`);
+
+  console.log("\nRefreshing token state...");
+  const refreshPlan = await client.tx.refreshTokens.getTx({
+    signer: managerSigner.address,
+    params: { tokens: [tokenPda] },
+  });
+  await client.sendTransaction(managerSigner, refreshPlan);
+  client.clearAllCache();
+  token = await client.account.fetchToken(tokenPda, { fresh: true });
+
+  const withdrawUiAmount = await computeMaxWithdrawUiAmount(client, token, lendingPositionIndex);
+  if (withdrawUiAmount === 0) {
+    console.error(
+      "No collateral can be withdrawn without exceeding the position utilization target. " +
+        "Run decrease-carry or deleverage-all first to free headroom."
+    );
+    process.exit(1);
+  }
+
+  const withdrawLabel = withdrawUiAmount === "all" ? "all" : withdrawUiAmount.toFixed(9);
+  console.log(`\nWithdrawing ${withdrawLabel} collateral to unlent reserves...`);
+
+  const topUpPlan = await client.tx.topUpUnlentReserves.getTx({
+    token: tokenPda,
+    params: {
+      lendingPositionIndex,
+      uiAmount: withdrawUiAmount,
+    },
+  });
+  const sig = await client.sendTransaction(managerSigner, topUpPlan);
+
+  console.log("\ntop_up_unlent_reserves succeeded.");
+  console.log("  signature:", sig);
+  console.log("  withdrawn:", withdrawLabel);
+}
+
+/**
+ * Maximum withdraw allowed by `top_up_unlent_reserves`: all collateral when
+ * debt-free; otherwise the largest partial withdraw that keeps post-withdraw
+ * utilization at or below target + deviation margin.
+ */
+async function computeMaxWithdrawUiAmount(
+  client: LongYieldCarryClient,
+  token: Awaited<ReturnType<LongYieldCarryClient["account"]["fetchToken"]>>,
+  lendingPositionIndex: number
+): Promise<number | "all"> {
+  const position = token.data.lendingPositions[lendingPositionIndex]!;
+  const decimals = token.data.collateral.decimals;
+  const collateralUi = toUiAmount(position.accounting.collateral, decimals);
+
+  if (toBigInt(position.accounting.debt.amount) === BigInt(0)) {
+    return "all";
+  }
+
+  const manager = await LycLendingPositionManager.create(
+    client.getLendingPlatformClient(position).data,
+    position
+  );
+  const target = position.config.targetUtilizationRateBps;
+  const margin = Math.floor((target * UTILIZATION_RATE_DEVIATION_THRESHOLD_BPS) / 10_000);
+  const upperBoundBps = Math.min(target + margin, 10_000);
+
+  const minWithdrawUi = 1 / 10 ** decimals;
+  try {
+    const postUtilAtMin = await manager.calcPostWithdrawalUtilizationRateBps(minWithdrawUi);
+    if (postUtilAtMin > upperBoundBps) {
+      return 0;
+    }
+  } catch {
+    return 0;
+  }
+
+  let lo = minWithdrawUi;
+  let hi = collateralUi * (1 - 1 / 10 ** decimals);
+  for (let i = 0; i < 50; i += 1) {
+    const mid = (lo + hi) / 2;
+    try {
+      const postUtil = await manager.calcPostWithdrawalUtilizationRateBps(mid);
+      if (postUtil <= upperBoundBps) {
+        lo = mid;
+      } else {
+        hi = mid;
+      }
+    } catch {
+      hi = mid;
+    }
+  }
+
+  return lo >= minWithdrawUi ? lo : 0;
+}
+
+main()
+  .then(() => console.log("Finished"))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });