@kestrelfi/lyc-sdk 1.0.1

package/scripts/inspect.ts

@@ -0,0 +1,147 @@
+import "./env";
+import { Keypair } from "@solana/web3.js";
+import { fetchMaybeToken } from "@solana-program/token";
+import { createSolanaRpc, type Address } from "@solana/kit";
+import { LendingPlatform, mints, getAtaAddress, createDefaultAnchorProvider } from "common";
+import { LongYieldCarryClient } from "../src/client/client";
+import { PROTOCOL_FEE_WALLET } from "../src/constants/general";
+import type { LYCToken } from "../src/models/lycToken";
+import type { LYCYieldingBank } from "../src/models/yieldingBank";
+import {
+  buildTokenInspectSnapshot,
+  buildYieldingBankInspectSnapshot,
+} from "../src/utils/enrichment";
+import { parseCliEnvironmentAndRest, resolveTokenPda } from "./localUtils";
+import {
+  formatTokenSnapshot,
+  formatYieldingBankSnapshot,
+  formatFeeWallet,
+  formatFooter,
+  formatHeader,
+  type FeeWalletBalance,
+} from "./inspect/format";
+
+/**
+ * CLI inspect tool — prints a human-readable summary of all on-chain LYC state.
+ *
+ * Usage:
+ *   pnpm run inspect -- test|prod [TOKEN_PDA|COLLATERAL_SYMBOL]
+ *
+ * From root:
+ *   pnpm lyc:inspect -- test [SOL]
+ *
+ * If a token argument is provided, only that token (and its associated yielding
+ * banks) are shown. Otherwise all tokens and banks are printed.
+ */
+async function main() {
+  const { env, rest } = parseCliEnvironmentAndRest("inspect");
+  if (rest.length > 1) {
+    console.error("Usage: pnpm run inspect -- [test|prod] [TOKEN_PDA|COLLATERAL_SYMBOL]");
+    process.exit(1);
+  }
+
+  const provider = createDefaultAnchorProvider(env, Keypair.generate());
+  const client = new LongYieldCarryClient(provider, env);
+  const rpc = createSolanaRpc(provider.connection.rpcEndpoint);
+
+  let tokens: LYCToken[];
+  let banks: LYCYieldingBank[];
+  const tokenArg = rest[0];
+
+  if (tokenArg !== undefined) {
+    const resolved = await resolveTokenPda(client, tokenArg);
+    tokens = [await client.account.fetchToken(resolved.tokenPda)];
+    banks = await client.account.fetchAllYieldingBanks();
+  } else {
+    ({ tokens, yieldingBanks: banks } = await client.account.fetchAllTokensAndYieldingBanks());
+  }
+
+  const enrichedTokens = await Promise.all(
+    tokens.map((token) =>
+      buildTokenInspectSnapshot(token, {
+        environment: env,
+        mintRegistry: mints,
+        yieldingBanks: banks,
+        kaminoData: client.getLendingPlatformClientByPlatform(LendingPlatform.Kamino).data,
+      })
+    )
+  );
+  const banksToPrint =
+    tokenArg === undefined
+      ? banks
+      : filterBanksForTokens(
+          banks,
+          enrichedTokens.flatMap((t) => t.carryPositions)
+        );
+  const enrichedBanks = banksToPrint.map((bank) =>
+    buildYieldingBankInspectSnapshot(bank, { environment: env, mintRegistry: mints })
+  );
+
+  console.log(formatHeader(env, tokens.length, banksToPrint.length));
+
+  for (const bank of enrichedBanks) {
+    console.log(formatYieldingBankSnapshot(bank, enrichedTokens));
+  }
+
+  for (const token of enrichedTokens) {
+    console.log(formatTokenSnapshot(token, enrichedBanks));
+  }
+
+  // -- Fee wallet balances --
+  const feeWallet = PROTOCOL_FEE_WALLET[env];
+  const feeBalances: FeeWalletBalance[] = [];
+  for (const token of tokens) {
+    const collMint = token.collateralMint;
+    const collSymbol = mints.get(collMint)?.symbol ?? collMint.toString().slice(0, 8);
+    const collDecimals = token.data.collateral.decimals;
+
+    const ata = await getAtaAddress(collMint, feeWallet);
+    const account = await fetchMaybeToken(rpc, ata);
+    const balance = account.exists ? account.data.amount : 0n;
+
+    feeBalances.push({ symbol: collSymbol, decimals: collDecimals, balance });
+
+    const yTokenAta = await getAtaAddress(token.mint, feeWallet);
+    const yTokenAccount = await fetchMaybeToken(rpc, yTokenAta);
+    const yTokenBalance = yTokenAccount.exists ? yTokenAccount.data.amount : 0n;
+    if (yTokenBalance > 0n) {
+      feeBalances.push({
+        symbol: `y${collSymbol}`,
+        decimals: token.decimals,
+        balance: yTokenBalance,
+      });
+    }
+  }
+
+  console.log(formatFeeWallet(feeWallet, feeBalances));
+
+  const totalTvlUsd = enrichedTokens.reduce((sum, token) => sum + token.tvlUsd, 0);
+  console.log(formatFooter(totalTvlUsd));
+}
+
+function filterBanksForTokens(
+  banks: LYCYieldingBank[],
+  carryPositions: Awaited<ReturnType<typeof buildTokenInspectSnapshot>>["carryPositions"]
+): LYCYieldingBank[] {
+  const bankAddresses = new Set(
+    carryPositions
+      .map((carryPosition) => carryPosition.yieldingBankAddress)
+      .filter((address): address is Address => address !== undefined)
+  );
+  return banks.filter((bank) => bankAddresses.has(bank.address));
+}
+
+main().catch((err) => {
+  console.error("");
+  console.error("========================================================================");
+  console.error("Inspect failed");
+  if (err instanceof Error) {
+    console.error(err.message);
+    if (err.stack) {
+      console.error(err.stack);
+    }
+  } else {
+    console.error(String(err));
+  }
+  process.exit(1);
+});

package/scripts/localUtils.ts

@@ -0,0 +1,249 @@
+import "./env";
+import { address, type Address } from "@solana/kit";
+import { PublicKey } from "@solana/web3.js";
+import { type DeployedEnv, type Environment, ENVIRONMENT, mints } from "common";
+import { LongYieldCarryClient } from "../src/client/client";
+import type { LYCToken } from "../src/models/lycToken";
+import {
+  ASSET_PRESETS,
+  VOLATILITY_REGIMES,
+  isVolatilityRegime,
+  resolvePresets,
+  type AssetPresetEntry,
+  type CarryVolatilityPresets,
+  type VolatilityRegime,
+} from "../src/constants/configs/carryTradePresets";
+
+function deployedEnvOrExit(packageScriptName: string, env: Environment): DeployedEnv {
+  if (env === "local") {
+    console.error(
+      `Usage: pnpm run ${packageScriptName} -- test|prod\n` +
+        `(ENVIRONMENT is "local" or you passed "local"; this entrypoint only targets deployed test/prod.)`
+    );
+    process.exit(1);
+  }
+  return env;
+}
+
+/**
+ * Reads `test` | `prod` from argv. Strips pnpm’s `--` separator
+ * (`pnpm run … -- prod` → argv contains `--` then `prod`).
+ *
+ * Does not accept `local`; use integration tests or other tooling for Surfpool/local validator.
+ *
+ * If the first argument is omitted, uses `ENVIRONMENT` from `common`
+ * (`process.env.ENVIRONMENT` ?? `"local"`) — must be `test` or `prod`, not `local`.
+ *
+ * @param packageScriptName - npm script name for the usage line (e.g. `update-token-luts`)
+ */
+export function parseCliEnvironmentAndRest(packageScriptName: string): {
+  env: DeployedEnv;
+  rest: string[];
+} {
+  const args = process.argv.slice(2).filter((a) => a !== "--");
+  const arg = args[0];
+  if (arg === "test" || arg === "prod") {
+    return { env: arg, rest: args.slice(1) };
+  }
+  if (arg === "local") {
+    console.error(
+      `Usage: pnpm run ${packageScriptName} -- [test|prod] [extra-args...]\n` +
+        `("local" is not supported; use integration tests for local validator workflows.)`
+    );
+    process.exit(1);
+  }
+  return { env: deployedEnvOrExit(packageScriptName, ENVIRONMENT), rest: args };
+}
+
+/**
+ * Same as {@link parseCliEnvironmentAndRest} but ignores positional args after the environment.
+ */
+export function parseCliEnvironment(packageScriptName: string): DeployedEnv {
+  return parseCliEnvironmentAndRest(packageScriptName).env;
+}
+
+// =============================================================================
+// CLI argument helpers
+// =============================================================================
+
+/** True when `s` looks like a filesystem path to a keypair (vs a token PDA/symbol). */
+export function isLikelyKeypairPath(s: string): boolean {
+  const t = s.trim();
+  return t.endsWith(".json") || t.includes("/") || t.startsWith("~");
+}
+
+export function extractKeypairFlag(rest: string[]): { rest: string[]; keypairPath?: string } {
+  const filtered: string[] = [];
+  let keypairPath: string | undefined;
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i]!;
+    if (arg === "--keypair" || arg === "-k") {
+      keypairPath = rest[i + 1];
+      if (!keypairPath || keypairPath.startsWith("--")) {
+        console.error(`${arg} requires a path argument.`);
+        process.exit(1);
+      }
+      i += 1;
+    } else if (arg.startsWith("--keypair=")) {
+      keypairPath = arg.slice("--keypair=".length);
+      if (!keypairPath) {
+        console.error("--keypair requires a path argument.");
+        process.exit(1);
+      }
+    } else {
+      filtered.push(arg);
+    }
+  }
+
+  return { rest: filtered, keypairPath };
+}
+
+// =============================================================================
+// Token PDA resolution
+// =============================================================================
+
+/**
+ * Returns true if `s` decodes as a valid Ed25519 public key (use as Token PDA input).
+ * Short symbols like `SOL` are rejected by {@link PublicKey}.
+ */
+export function isValidPubkeyString(s: string): boolean {
+  try {
+    new PublicKey(s);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface ResolvedToken {
+  tokenPda: Address;
+  collateralSymbol?: string;
+  collateralDecimals: number;
+}
+
+/**
+ * Resolve a CLI token argument: either a Token PDA address, or a collateral
+ * mint symbol (e.g. SOL or SOL:0) by scanning on-chain Token accounts for one
+ * whose `collateral.mint` matches.
+ */
+export async function resolveTokenPda(
+  client: LongYieldCarryClient,
+  arg: string
+): Promise<ResolvedToken> {
+  const trimmed = arg.trim();
+
+  if (isValidPubkeyString(trimmed)) {
+    const tokenPda = address(trimmed);
+    const lyct = await client.account.fetchToken(tokenPda);
+    return {
+      tokenPda,
+      collateralSymbol: mints.get(lyct.collateralMint)?.symbol,
+      collateralDecimals: lyct.data.collateral.decimals,
+    };
+  }
+
+  const parsedSymbol = parseCollateralSymbolSelector(trimmed);
+  const symbol = parsedSymbol.symbol;
+  const tokenId = parsedSymbol.tokenId;
+  const collateralInfo = mints.get(symbol);
+  if (!collateralInfo) {
+    console.error(
+      `Unknown mint identifier "${symbol}". Use a registry symbol (e.g. SOL, SOL:0) or pass the Token PDA base58 address.`
+    );
+    process.exit(1);
+  }
+
+  const tokens = await client.account.fetchAllTokens();
+  const want = collateralInfo.address;
+  const matches = tokens.filter(
+    (t) => t.collateralMint === want && (tokenId === undefined || t.id === tokenId)
+  );
+
+  if (matches.length === 0) {
+    const idSuffix = tokenId === undefined ? "" : ` and token id ${tokenId}`;
+    console.error(`No Token account found with collateral mint ${want} (${symbol})${idSuffix}.`);
+    process.exit(1);
+  }
+
+  if (matches.length > 1) {
+    console.error(
+      `Multiple Tokens use collateral ${symbol} (${want}). Pass SYMBOL:ID or the Token PDA explicitly:\n` +
+        matches.map((t) => `  ${symbol}:${t.id}  ${t.address}`).join("\n")
+    );
+    process.exit(1);
+  }
+
+  const t = matches[0]!;
+  return {
+    tokenPda: t.address,
+    collateralSymbol: symbol,
+    collateralDecimals: t.data.collateral.decimals,
+  };
+}
+
+function parseCollateralSymbolSelector(arg: string): { symbol: string; tokenId?: number } {
+  const match = arg.match(/^([A-Za-z0-9]+)(?::|#)(\d+)$/);
+  if (!match) {
+    return { symbol: arg.toUpperCase() };
+  }
+
+  const tokenId = Number(match[2]);
+  if (!Number.isInteger(tokenId) || tokenId < 0 || tokenId > 255) {
+    console.error(`Invalid token id "${match[2]}" in "${arg}". Token id must be a u8 (0-255).`);
+    process.exit(1);
+  }
+
+  return { symbol: match[1]!.toUpperCase(), tokenId };
+}
+
+/**
+ * Resolves a lending position by numeric index or debt mint symbol.
+ * Exits the process with a usage error when the position is invalid.
+ */
+export function resolveLendingPositionIndex(
+  token: LYCToken,
+  positionIdentifier: string,
+  tokenPda: Address
+): number {
+  const parsedIndex = parseInt(positionIdentifier, 10);
+  if (Number.isFinite(parsedIndex) && parsedIndex >= 0) {
+    const positions = token.data.lendingPositions;
+    if (parsedIndex >= positions.length || "none" in positions[parsedIndex]!.platform) {
+      console.error(
+        `Lending position ${parsedIndex} is inactive or out of bounds ` +
+          `(token has ${positions.length} slots).`
+      );
+      process.exit(1);
+    }
+    return parsedIndex;
+  }
+
+  const debtSymbol = positionIdentifier.toUpperCase();
+  const debtMintInfo = mints.get(debtSymbol);
+  if (!debtMintInfo) {
+    console.error(
+      `Unknown debt mint symbol "${debtSymbol}". Known symbols use the common mint registry.`
+    );
+    process.exit(1);
+  }
+
+  const lendingPositionIndex = token.findLendingPositionByDebtMint(debtMintInfo.address);
+  if (lendingPositionIndex === -1) {
+    console.error(
+      `No active lending position found with debt ${debtSymbol} (${debtMintInfo.address}) on token ${tokenPda}.`
+    );
+    process.exit(1);
+  }
+  return lendingPositionIndex;
+}
+
+export {
+  ASSET_PRESETS,
+  VOLATILITY_REGIMES,
+  isVolatilityRegime,
+  resolvePresets,
+  type AssetPresetEntry,
+  type CarryVolatilityPresets,
+  type VolatilityRegime,
+};

package/scripts/mintToken.ts

@@ -0,0 +1,126 @@
+import "./env";
+import { BN } from "@anchor-lang/core";
+import {
+  fromUiAmount,
+  loadLocalKeypairWithWeb3,
+  TP_ID_KEYPAIR_FP,
+  createDefaultAnchorProvider,
+} from "common";
+import { LongYieldCarryClient } from "../src/client/client";
+import { extractKeypairFlag, parseCliEnvironmentAndRest, resolveTokenPda } from "./localUtils";
+import type { MintTokenTxParams } from "../src/client/types";
+
+/**
+ * Parse deposit CLI argument:
+ * - **Integer string** (digits only): amount in collateral base units (e.g. lamports).
+ * - **Decimal string** (contains `.`): human amount in token units (e.g. `0.5` SOL); converted with {@link fromUiAmount} (rounds to nearest base unit).
+ */
+function parseDepositAmount(amountStr: string, collateralDecimals: number): BN {
+  const trimmed = amountStr.trim();
+  if (trimmed === "" || trimmed === ".") {
+    throw new Error("empty amount");
+  }
+
+  if (/^\d+$/.test(trimmed)) {
+    return new BN(trimmed, 10);
+  }
+
+  const normalized = trimmed.startsWith(".") ? `0${trimmed}` : trimmed;
+  if (!/^\d+(\.\d+)?$/.test(normalized)) {
+    throw new Error("invalid decimal amount");
+  }
+  const ui = parseFloat(normalized);
+  if (!Number.isFinite(ui) || ui < 0) {
+    throw new Error("invalid decimal amount");
+  }
+  return fromUiAmount(ui, collateralDecimals);
+}
+
+/**
+ * Deposits collateral and mints yTokens via `refresh_token_state` (and yielding-bank
+ * refreshes as needed) then `mint_token`. For SOL collateral, `tx.mintToken.getTx` wraps
+ * `DEPOSIT_RAW` from the signer's SOL into WSOL in the same transaction; for other
+ * collaterals the user's collateral ATA must already hold `DEPOSIT_RAW`.
+ *
+ * Usage:
+ *   From this package: `pnpm run mint-token -- test|prod <TOKEN_PDA|COLLATERAL_SYMBOL> [AMOUNT] [KEYPAIR_JSON]`
+ *   From repo root:   `pnpm lyc:mint-token -- test|prod …`
+ *
+ * `AMOUNT`: integer string = base units (e.g. lamports); decimal string = token units
+ * (e.g. `0.5` for half a SOL). Omit to deposit the entire collateral ATA balance ("all").
+ * Default signer keypair: {@link TP_ID_KEYPAIR_FP} from `common`; override with the optional path.
+ */
+async function main() {
+  const { env, rest } = parseCliEnvironmentAndRest("mint-token");
+  const { rest: args, keypairPath: keypairFlagPath } = extractKeypairFlag(rest);
+
+  const tokenArg = args[0];
+  const depositRawStr = args[1];
+  const keypairPath = keypairFlagPath ?? args[2] ?? TP_ID_KEYPAIR_FP;
+
+  if (tokenArg === undefined) {
+    console.error(
+      "Usage: pnpm run mint-token -- [test|prod] <TOKEN_PDA|COLLATERAL_SYMBOL> [AMOUNT] [KEYPAIR_JSON]"
+    );
+    process.exit(1);
+  }
+
+  const { signer: userSigner, web3Keypair } = await loadLocalKeypairWithWeb3(keypairPath);
+  const provider = createDefaultAnchorProvider(env, web3Keypair);
+  const client = new LongYieldCarryClient(provider, env);
+
+  const { tokenPda, collateralSymbol, collateralDecimals } = await resolveTokenPda(
+    client,
+    tokenArg
+  );
+
+  let depositAmount: BN | "all";
+  if (depositRawStr === undefined || depositRawStr === "all") {
+    depositAmount = "all";
+  } else {
+    try {
+      depositAmount = parseDepositAmount(depositRawStr, collateralDecimals);
+    } catch {
+      console.error(
+        `Invalid deposit amount "${depositRawStr}" (use integer base units, a decimal token amount e.g. 0.5, or "all").`
+      );
+      process.exit(1);
+    }
+
+    if (depositAmount.lte(new BN(0))) {
+      console.error("Deposit amount must be positive.");
+      process.exit(1);
+    }
+  }
+
+  const refreshPlan = await client.tx.refreshTokens.getTx({
+    signer: userSigner.address,
+    params: {
+      tokens: [tokenPda],
+    },
+  });
+  await client.sendTransaction(userSigner, refreshPlan);
+
+  const mintParams: MintTokenTxParams = { depositAmount };
+  const mintPlan = await client.tx.mintToken.getTx({
+    signer: userSigner.address,
+    token: tokenPda,
+    params: mintParams,
+  });
+  const sig = await client.sendTransaction(userSigner, mintPlan);
+
+  console.log("mint_token succeeded.");
+  console.log("  environment:", env);
+  console.log("  signer:", userSigner.address);
+  console.log("  token PDA:", tokenPda);
+  console.log("  underlying collateral:", collateralSymbol);
+  console.log("  deposit:", depositAmount === "all" ? "all" : depositAmount.toString());
+  console.log("  signature:", sig);
+}
+
+main()
+  .then(() => console.log("Finished"))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/scripts/processAsyncBurns.ts

@@ -0,0 +1,89 @@
+import "./env";
+import {
+  loadLocalKeypairWithWeb3,
+  toUiAmount,
+  createDefaultAnchorProvider,
+  redactRpcUrlForLog,
+} from "common";
+import { LongYieldCarryClient } from "../src/client/client";
+import { LYC_MANAGER_KEYPAIR_FP } from "../src/constants/general";
+import { RedemptionService } from "../src/services/redemption";
+import { extractKeypairFlag, parseCliEnvironmentAndRest } from "./localUtils";
+
+/**
+ * Finds all pending redemption epochs and processes them through the full
+ * lifecycle: close → fund (DCP + withdraw) → process all requests.
+ *
+ * Usage:
+ *   pnpm run process-async-burns -- test|prod [--keypair MANAGER_KEYPAIR_JSON]
+ *
+ * Keypair defaults to ~/.config/solana/tp-lyc-manager-{env}.json
+ */
+async function main() {
+  const { env, rest } = parseCliEnvironmentAndRest("process-async-burns");
+  const { keypairPath: keypairFlagPath } = extractKeypairFlag(rest);
+
+  const keypairPath = keypairFlagPath ?? LYC_MANAGER_KEYPAIR_FP[env];
+  const { signer: managerSigner, web3Keypair } = await loadLocalKeypairWithWeb3(keypairPath);
+  const provider = createDefaultAnchorProvider(env, web3Keypair);
+  const client = new LongYieldCarryClient(provider, env);
+  const redemption = new RedemptionService(client);
+
+  console.log("=== Process Async Burns ===");
+  console.log("  environment:", env);
+  console.log("  rpc:", redactRpcUrlForLog(provider.connection.rpcEndpoint));
+  console.log("  manager:", managerSigner.address);
+  console.log();
+
+  const epochs = await redemption.getAllEpochs();
+  if (epochs.length === 0) {
+    console.log("No pending redemption epochs found.");
+    return;
+  }
+
+  console.log(`Found ${epochs.length} redemption epoch(s).\n`);
+
+  let processed = 0;
+  let failed = 0;
+
+  for (const epoch of epochs) {
+    const token = await client.account.fetchToken(epoch.tokenPda, { fresh: true });
+    const decimals = token.data.collateral.decimals;
+    const statusLabel = epoch.status === 0 ? "Open" : epoch.status === 1 ? "Funding" : "Processing";
+
+    console.log(`── Epoch ${epoch.pda} ──`);
+    console.log(`  Token:    ${epoch.tokenPda}`);
+    console.log(`  Epoch ID: ${epoch.epochId}`);
+    console.log(`  Status:   ${statusLabel} (${epoch.status})`);
+    console.log(`  Requests: ${epoch.processedRequestCount}/${epoch.requestCount} processed`);
+    console.log(`  Funded:   ${epoch.fundedCollateral} / ${epoch.grossCollateralClaim}`);
+    console.log(`  Loss:     ${epoch.realizedUnwindLoss}`);
+    console.log(`  Claim:    ${toUiAmount(epoch.grossCollateralClaim, decimals)} ${token.label}`);
+
+    try {
+      const success = await redemption.processEpoch(managerSigner, epoch, (msg: string) =>
+        console.log(`  ${msg}`)
+      );
+      if (success) {
+        console.log("  ✓ Epoch fully processed and closed.\n");
+        processed++;
+      } else {
+        console.error("  ✗ Epoch could not be fully funded.\n");
+        failed++;
+      }
+    } catch (err) {
+      console.error(`  ✗ Failed:`, err instanceof Error ? err.message : err, "\n");
+      failed++;
+    }
+  }
+
+  console.log(`Summary: ${processed} processed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+}
+
+main()
+  .then(() => console.log("Finished"))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });