@varla/sdk 1.13.2 → 2.3.0

package/src/views/liquidators.ts

@@ -1,6 +1,9 @@
 // Note: explicit .js extension is required for Node ESM resolution.
 
-import type { Address } from "viem";
+import type { Address, PublicClient } from "viem";
+
+import { readAccountPositionsFull } from "./core.js";
+import { type ReadPositionSnapshot, readManyPositionSnapshots } from "./oracle.js";
 
 type LiquidatorLike = {
   read: {
@@ -225,3 +228,150 @@ export async function readConvertLiquidatorBasics(params: {
   const negRiskAdapter = await params.liquidator.read.negRiskAdapter();
   return { ...base, negRiskAdapter };
 }
+
+// ---------------------------------------------------------------------------
+// Liquidation candidate ranking
+// ---------------------------------------------------------------------------
+
+/**
+ * A single position candidate for liquidation, enriched with pricing data.
+ */
+export type LiquidationCandidate = {
+  /** The ERC-1155 position token ID. */
+  positionId: bigint;
+  /** User's balance (raw token units). */
+  balance: bigint;
+  /** Oracle price (8 decimals). 0 if price unavailable. */
+  priceE8: bigint;
+  /** Whether the oracle price is valid / not stale. */
+  priceOk: boolean;
+  /** Whether the position has been manually invalidated. */
+  manuallyInvalidated: boolean;
+  /** Notional value = balance × priceE8 / 1e8 (floor). Used for sorting. */
+  notional: bigint;
+};
+
+/**
+ * Pure utility: rank position candidates by notional value (descending).
+ *
+ * Filters out positions with zero balance, unavailable prices, or manual invalidation.
+ * The returned array is ordered so the highest-value positions come first — when passed
+ * directly to `prepareLiquidatorLiquidateMulti`, the liquidator seizes the most valuable
+ * tokens first.
+ *
+ * @param positions - Parallel arrays of position IDs and balances.
+ * @param snapshots - Oracle snapshots (one per position ID, same order or keyed by ID).
+ * @param maxPositions - Optional cap on returned candidates.
+ * @returns Ranked candidates, highest notional first.
+ */
+export function rankPositionsForLiquidation(params: {
+  positionIds: readonly bigint[];
+  balances: readonly bigint[];
+  snapshots: readonly ReadPositionSnapshot[];
+  maxPositions?: number;
+}): LiquidationCandidate[] {
+  const snapshotByPid = new Map(params.snapshots.map((s) => [s.positionId.toString(), s]));
+
+  const candidates: LiquidationCandidate[] = [];
+  for (let i = 0; i < params.positionIds.length; i++) {
+    const positionId = params.positionIds[i]!;
+    const balance = params.balances[i] ?? 0n;
+    if (balance <= 0n) continue;
+
+    const snap = snapshotByPid.get(positionId.toString());
+    const priceOk = snap?.priceOk ?? false;
+    const priceE8 = snap?.priceE8 ?? 0n;
+    const manuallyInvalidated = snap?.manuallyInvalidated ?? false;
+
+    if (!priceOk || manuallyInvalidated || priceE8 <= 0n) continue;
+
+    const notional = (balance * priceE8) / 100_000_000n;
+    candidates.push({ positionId, balance, priceE8, priceOk, manuallyInvalidated, notional });
+  }
+
+  // Sort by notional descending — highest value first.
+  candidates.sort((a, b) => (a.notional > b.notional ? -1 : a.notional < b.notional ? 1 : 0));
+
+  if (params.maxPositions != null && params.maxPositions > 0) {
+    return candidates.slice(0, params.maxPositions);
+  }
+  return candidates;
+}
+
+/**
+ * Result of `readLiquidationCandidates`.
+ */
+export type ReadLiquidationCandidates = {
+  user: Address;
+  /** All candidates ranked by notional value descending. */
+  candidates: LiquidationCandidate[];
+  /** Convenience: just the position IDs, ready to pass to `prepareLiquidatorLiquidateMulti`. */
+  positionIds: bigint[];
+  /** Total notional value across all candidates. */
+  totalNotional: bigint;
+};
+
+/**
+ * Fetch a user's collateral positions, enrich with oracle prices, and return
+ * ranked candidates suitable for multi-position liquidation.
+ *
+ * This is a high-level helper that combines `readAccountPositionsFull` +
+ * `readManyPositionSnapshots` + `rankPositionsForLiquidation` into one call.
+ *
+ * @example
+ * ```ts
+ * const result = await readLiquidationCandidates({
+ *   core: contracts.core,
+ *   oracle: contracts.oracle,
+ *   client: publicClient,
+ *   user: "0x...",
+ *   maxPositions: 10,
+ * });
+ * // result.positionIds → ready for prepareLiquidatorLiquidateMulti
+ * ```
+ */
+// wraps: VarlaCore.getPositions,VarlaOracle.getPositionSnapshot
+export async function readLiquidationCandidates(params: {
+  core: {
+    read: {
+      getPositions: (args: readonly [Address]) => Promise<unknown>;
+    };
+  };
+  oracle: { address: Address };
+  client: Pick<PublicClient, "multicall">;
+  user: Address;
+  maxPositions?: number;
+}): Promise<ReadLiquidationCandidates> {
+  const positions = await readAccountPositionsFull({
+    core: params.core,
+    user: params.user,
+  });
+
+  const heldIds = positions.positionIds.filter((_, i) => (positions.balances[i] ?? 0n) > 0n);
+
+  if (heldIds.length === 0) {
+    return { user: params.user, candidates: [], positionIds: [], totalNotional: 0n };
+  }
+
+  const snapshots = await readManyPositionSnapshots({
+    oracle: params.oracle,
+    client: params.client,
+    positionIds: heldIds,
+  });
+
+  const candidates = rankPositionsForLiquidation({
+    positionIds: positions.positionIds,
+    balances: positions.balances,
+    snapshots,
+    maxPositions: params.maxPositions,
+  });
+
+  const totalNotional = candidates.reduce((sum, c) => sum + c.notional, 0n);
+
+  return {
+    user: params.user,
+    candidates,
+    positionIds: candidates.map((c) => c.positionId),
+    totalNotional,
+  };
+}

package/src/views/oracle.ts

@@ -446,6 +446,7 @@ export type ReadPositionSnapshot = {
   manuallyInvalidated: boolean;
   riskTier: number;
   earlyClosureFactorWad: bigint;
+  isFinalized: boolean;
   lastRecoveryFromStale: bigint;
 };
 
@@ -458,6 +459,7 @@ function normalizePositionSnapshot(raw: unknown, positionId: bigint): ReadPositi
   const riskTier = r.riskTier ?? r[3];
   const earlyClosureFactorWad = r.earlyClosureFactorWad ?? r[4];
   const lastRecoveryFromStale = r.lastRecoveryFromStale_ ?? r.lastRecoveryFromStale ?? r[5];
+  const isFinalized = r.isFinalized_ ?? r.isFinalized ?? r[6];
 
   if (
     typeof priceOk !== "boolean" ||
@@ -465,6 +467,7 @@ function normalizePositionSnapshot(raw: unknown, positionId: bigint): ReadPositi
     typeof manuallyInvalidated !== "boolean" ||
     (typeof riskTier !== "number" && typeof riskTier !== "bigint") ||
     typeof earlyClosureFactorWad !== "bigint" ||
+    typeof isFinalized !== "boolean" ||
     typeof lastRecoveryFromStale !== "bigint"
   ) {
     throw new Error("Unexpected getPositionSnapshot() return shape");
@@ -477,6 +480,7 @@ function normalizePositionSnapshot(raw: unknown, positionId: bigint): ReadPositi
     manuallyInvalidated,
     riskTier: Number(riskTier),
     earlyClosureFactorWad,
+    isFinalized,
     lastRecoveryFromStale,
   };
 }