@varla/sdk 1.11.4 → 1.13.2

package/src/views/pool.ts

@@ -0,0 +1,277 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+import type { Address } from "viem";
+
+export type ReadPoolSnapshot = {
+  totalAssets: bigint;
+  totalBorrowed: bigint;
+  available: bigint;
+  utilization: bigint;
+  borrowRate: bigint;
+  supplyAPY: bigint;
+  borrowIndex: bigint;
+};
+
+export type ReadPoolDebtState = {
+  totalBorrowed: bigint;
+  currentBorrowIndex: bigint;
+  borrowRate: bigint;
+};
+
+// wraps: VarlaPool.getPoolStats
+export async function readPoolSnapshot(params: {
+  pool: {
+    read: {
+      getPoolStats: () => Promise<unknown>;
+    };
+  };
+}): Promise<ReadPoolSnapshot> {
+  const raw = await params.pool.read.getPoolStats();
+  const r: any = raw as any;
+
+  // Tuple order in VarlaPool.getPoolStats:
+  // (_totalAssets,_totalBorrowed,_available,_utilization,_borrowRate,_supplyAPY,_borrowIndex)
+  const totalAssets = r._totalAssets ?? r[0];
+  const totalBorrowed = r._totalBorrowed ?? r[1];
+  const available = r._available ?? r[2];
+  const utilization = r._utilization ?? r[3];
+  const borrowRate = r._borrowRate ?? r[4];
+  const supplyAPY = r._supplyAPY ?? r[5];
+  const borrowIndex = r._borrowIndex ?? r[6];
+
+  if (
+    typeof totalAssets !== "bigint" ||
+    typeof totalBorrowed !== "bigint" ||
+    typeof available !== "bigint" ||
+    typeof utilization !== "bigint" ||
+    typeof borrowRate !== "bigint" ||
+    typeof supplyAPY !== "bigint" ||
+    typeof borrowIndex !== "bigint"
+  ) {
+    throw new Error("Unexpected getPoolStats() return shape");
+  }
+
+  return {
+    totalAssets,
+    totalBorrowed,
+    available,
+    utilization,
+    borrowRate,
+    supplyAPY,
+    borrowIndex,
+  };
+}
+
+export type ReadPoolCaps = {
+  depositCap: bigint;
+  borrowCap: bigint;
+};
+
+/**
+ * Reads depositCap/borrowCap (useful for frontends + monitoring).
+ */
+// wraps: VarlaPool.depositCap,VarlaPool.borrowCap
+export async function readPoolCaps(params: {
+  pool: {
+    read: {
+      depositCap: () => Promise<bigint>;
+      borrowCap: () => Promise<bigint>;
+    };
+  };
+}): Promise<ReadPoolCaps> {
+  const [depositCap, borrowCap] = await Promise.all([
+    params.pool.read.depositCap(),
+    params.pool.read.borrowCap(),
+  ]);
+  return { depositCap, borrowCap };
+}
+
+export type ReadPoolAccounting = {
+  reserveBalance: bigint;
+  scaledTotalBorrowed: bigint;
+  borrowIndex: bigint;
+  lastUpdateTimestamp: bigint;
+};
+
+/**
+ * Reads accounting/index variables that are commonly required in analytics.
+ */
+// wraps: VarlaPool.reserveBalance,VarlaPool.scaledTotalBorrowed,VarlaPool.borrowIndex,VarlaPool.lastUpdateTimestamp
+export async function readPoolAccounting(params: {
+  pool: {
+    read: {
+      reserveBalance: () => Promise<bigint>;
+      scaledTotalBorrowed: () => Promise<bigint>;
+      borrowIndex: () => Promise<bigint>;
+      lastUpdateTimestamp: () => Promise<bigint | number>;
+    };
+  };
+}): Promise<ReadPoolAccounting> {
+  const [reserveBalance, scaledTotalBorrowed, borrowIndex, lastUpdateTimestamp] = await Promise.all(
+    [
+      params.pool.read.reserveBalance(),
+      params.pool.read.scaledTotalBorrowed(),
+      params.pool.read.borrowIndex(),
+      params.pool.read.lastUpdateTimestamp(),
+    ],
+  );
+
+  return {
+    reserveBalance,
+    scaledTotalBorrowed,
+    borrowIndex,
+    lastUpdateTimestamp: BigInt(lastUpdateTimestamp),
+  };
+}
+
+export type ReadPoolRates = {
+  utilization: bigint;
+  borrowRate: bigint;
+  supplyAPY: bigint;
+  availableLiquidity: bigint;
+  maxBorrow: bigint;
+};
+
+export type ReadPoolSharePrice = {
+  /** Total pool assets attributable to LPs (excludes reserve). */
+  totalAssets: bigint;
+  /** Total ERC4626 shares (vault token supply). */
+  totalShares: bigint;
+  /** WAD (1e18): totalAssets / totalShares. 0 when totalShares == 0. */
+  assetsPerShareWad: bigint;
+};
+
+export type ReadPoolHealthScore =
+  | {
+      kind: "ok";
+      /** Utilization in WAD (1e18 = 100%). */
+      utilizationWad: bigint;
+      /** Score in BPS (0..10_000). Higher is "safer" in this simplified metric. */
+      scoreBps: bigint;
+    }
+  | {
+      /** Pool has no LP assets. Utilization reads as 0, but a safety score would be misleading. */
+      kind: "no-liquidity";
+    };
+
+/**
+ * Reads pool “rates” and near-term capacity in one convenience call.
+ */
+// wraps: VarlaPool.getUtilization,VarlaPool.getInterestRate,VarlaPool.getSupplyAPY,VarlaPool.getAvailableLiquidity,VarlaPool.maxBorrow
+export async function readPoolRates(params: {
+  pool: {
+    read: {
+      getUtilization: () => Promise<bigint>;
+      getInterestRate: () => Promise<bigint>;
+      getSupplyAPY: () => Promise<bigint>;
+      getAvailableLiquidity: () => Promise<bigint>;
+      maxBorrow: () => Promise<bigint>;
+    };
+  };
+}): Promise<ReadPoolRates> {
+  const [utilization, borrowRate, supplyAPY, availableLiquidity, maxBorrow] = await Promise.all([
+    params.pool.read.getUtilization(),
+    params.pool.read.getInterestRate(),
+    params.pool.read.getSupplyAPY(),
+    params.pool.read.getAvailableLiquidity(),
+    params.pool.read.maxBorrow(),
+  ]);
+
+  return { utilization, borrowRate, supplyAPY, availableLiquidity, maxBorrow };
+}
+
+/**
+ * Reads the current pool "share price" (assets per share).
+ *
+ * Useful for:
+ * - lending UI (convert shares to assets)
+ * - charting / APR displays
+ *
+ * Notes:
+ * - This is a pure on-chain primitive. It does NOT attempt to compute user PnL.
+ * - Uses `totalAssets()` which already excludes protocol reserve.
+ */
+// wraps: VarlaPool.totalAssets,VarlaPool.totalSupply
+export async function readPoolSharePrice(params: {
+  pool: {
+    read: {
+      totalAssets: () => Promise<bigint>;
+      totalSupply: () => Promise<bigint>;
+    };
+  };
+}): Promise<ReadPoolSharePrice> {
+  const [totalAssets, totalShares] = await Promise.all([
+    params.pool.read.totalAssets(),
+    params.pool.read.totalSupply(),
+  ]);
+
+  const assetsPerShareWad =
+    totalShares === 0n ? 0n : (totalAssets * 1_000_000_000_000_000_000n) / totalShares;
+
+  return { totalAssets, totalShares, assetsPerShareWad };
+}
+
+/**
+ * A simplified pool "safety" / "health" score for UIs.
+ *
+ * Current implementation:
+ * - when pool has 0 totalAssets => return { kind: "no-liquidity" }
+ * - otherwise score = (1 - utilization) in BPS
+ *
+ * This intentionally avoids reporting 100% for empty pools (which is misleading).
+ */
+// wraps: VarlaPool.totalAssets,VarlaPool.getUtilization
+export async function readPoolHealthScore(params: {
+  pool: {
+    read: {
+      totalAssets: () => Promise<bigint>;
+      getUtilization: () => Promise<bigint>;
+    };
+  };
+}): Promise<ReadPoolHealthScore> {
+  const [totalAssets, utilizationWad] = await Promise.all([
+    params.pool.read.totalAssets(),
+    params.pool.read.getUtilization(),
+  ]);
+
+  if (totalAssets === 0n) return { kind: "no-liquidity" };
+
+  // Clamp utilizationWad into [0, 1e18] to keep score bounded.
+  const one = 1_000_000_000_000_000_000n;
+  const u = utilizationWad < 0n ? 0n : utilizationWad > one ? one : utilizationWad;
+  const scoreBps = ((one - u) * 10_000n) / one;
+
+  return { kind: "ok", utilizationWad: u, scoreBps };
+}
+
+/**
+ * Pool debt/index primitives commonly used by UIs.
+ */
+// wraps: VarlaPool.getTotalBorrowed,VarlaPool.getCurrentBorrowIndex,VarlaPool.borrowRate
+export async function readPoolDebtState(params: {
+  pool: {
+    read: {
+      getTotalBorrowed: () => Promise<bigint>;
+      getCurrentBorrowIndex: () => Promise<bigint>;
+      borrowRate: () => Promise<bigint>;
+    };
+  };
+}): Promise<ReadPoolDebtState> {
+  const [totalBorrowed, currentBorrowIndex, borrowRate] = await Promise.all([
+    params.pool.read.getTotalBorrowed(),
+    params.pool.read.getCurrentBorrowIndex(),
+    params.pool.read.borrowRate(),
+  ]);
+  return { totalBorrowed, currentBorrowIndex, borrowRate };
+}
+
+// wraps: VarlaPool.varlaCore
+export async function readPoolCoreAddress(params: {
+  pool: {
+    read: {
+      varlaCore: () => Promise<Address>;
+    };
+  };
+}): Promise<Address> {
+  return params.pool.read.varlaCore();
+}

package/src/views/system.ts

@@ -0,0 +1,42 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+import type { ReadDefaultLtvConfig, ReadLiquidationConfig } from "./core.js";
+import { readDefaultLtvConfig, readLiquidationConfig } from "./core.js";
+import type { ReadOracleConfig } from "./oracle.js";
+import { readOracleConfig } from "./oracle.js";
+import type { ReadPoolAccounting, ReadPoolCaps, ReadPoolSnapshot } from "./pool.js";
+import { readPoolAccounting, readPoolCaps, readPoolSnapshot } from "./pool.js";
+
+export type ReadSystemSnapshot = {
+  pool: ReadPoolSnapshot;
+  poolCaps: ReadPoolCaps;
+  poolAccounting: ReadPoolAccounting;
+  coreLtv: ReadDefaultLtvConfig;
+  coreLiquidation: ReadLiquidationConfig;
+  oracle: ReadOracleConfig;
+};
+
+/**
+ * A lightweight “global protocol state” read for dashboards.
+ *
+ * - no scanning
+ * - no registry enumeration
+ * - just the config + accounting primitives needed by frontends and monitoring
+ */
+// wraps: VarlaPool.getPoolStats,VarlaPool.depositCap,VarlaPool.borrowCap,VarlaPool.reserveBalance,VarlaPool.scaledTotalBorrowed,VarlaPool.borrowIndex,VarlaPool.lastUpdateTimestamp,VarlaCore.getDefaultLtvConfig,VarlaCore.getLiquidationConfig,VarlaOracle.maxStaleness,VarlaOracle.liquidationGracePeriod,VarlaOracle.defaultEarlyClosureWindow
+export async function readSystemSnapshot(params: {
+  pool: any;
+  core: any;
+  oracle: any;
+}): Promise<ReadSystemSnapshot> {
+  const [pool, poolCaps, poolAccounting, coreLtv, coreLiquidation, oracle] = await Promise.all([
+    readPoolSnapshot({ pool: params.pool }),
+    readPoolCaps({ pool: params.pool }),
+    readPoolAccounting({ pool: params.pool }),
+    readDefaultLtvConfig({ core: params.core }),
+    readLiquidationConfig({ core: params.core }),
+    readOracleConfig({ oracle: params.oracle }),
+  ]);
+
+  return { pool, poolCaps, poolAccounting, coreLtv, coreLiquidation, oracle };
+}

package/BACKEND.md

@@ -1,405 +0,0 @@
-# Backend integration guide (Node.js services: indexer + oracle updater + ops)
-
-This SDK is intentionally **batteries-not-included** for:
-
-- RPC configuration (URLs, retries, fallbacks, rate limits)
-- job scheduling / queues
-- persistence (db schemas, migrations)
-- reorg handling strategy (confirmations, replay windows)
-
-The SDK *does* provide:
-
-- canonical ABIs + deployed addresses
-- typed viem contract bindings (`getVarlaContracts` / `getRequiredVarlaContracts`)
-- read facades (`@varla/sdk/views`) built around multicall + paging
-- simulate-first write helpers (`@varla/sdk/actions`) for safer writes
-- event/indexer helpers (`@varla/sdk/events`) for log syncing
-
-This doc shows a recommended setup for **Node.js backend services**, split into common roles:
-
-- **Indexer / monitor** (reads + events)
-- **Oracle updater** (offchain prices → onchain updates)
-- **Ops / admin runner** (RBAC + seeding + parameter changes)
-
----
-
-## 1) RPC + viem client setup (service-side)
-
-The SDK does not ship RPC URLs.
-
-Recommended:
-- configure explicit RPCs per chain (Polygon/BSC)
-- use `fallback([http(primary), http(secondary)])`
-- add retries/backoff at the transport layer (your code) or via a proxy provider
-
-Example `rpc.ts`:
-
-```ts
-import { createPublicClient, fallback, http } from "viem";
-import { polygon, bsc } from "viem/chains";
-
-const POLYGON_RPC_URL = process.env.POLYGON_RPC_URL;
-const POLYGON_RPC_URL_BACKUP = process.env.POLYGON_RPC_URL_BACKUP;
-const BSC_RPC_URL = process.env.BSC_RPC_URL;
-const BSC_RPC_URL_BACKUP = process.env.BSC_RPC_URL_BACKUP;
-
-if (!POLYGON_RPC_URL) throw new Error("Missing POLYGON_RPC_URL");
-if (!BSC_RPC_URL) throw new Error("Missing BSC_RPC_URL");
-
-export const polygonClient = createPublicClient({
-  chain: polygon,
-  transport: fallback([
-    http(POLYGON_RPC_URL),
-    ...(POLYGON_RPC_URL_BACKUP ? [http(POLYGON_RPC_URL_BACKUP)] : []),
-  ]),
-});
-
-export const bscClient = createPublicClient({
-  chain: bsc,
-  transport: fallback([
-    http(BSC_RPC_URL),
-    ...(BSC_RPC_URL_BACKUP ? [http(BSC_RPC_URL_BACKUP)] : []),
-  ]),
-});
-```
-
-Notes:
-- You should own your own retry policy (especially for high-volume reads).
-- For “safe finality” reads, prefer waiting N blocks and/or reading with a stable provider.
-
----
-
-## 2) Getting Varla bindings (typed viem)
-
-```ts
-import { getVarlaContracts } from "@varla/sdk";
-import { polygonClient } from "./rpc";
-
-const c = getVarlaContracts({ chain: "polygon", client: polygonClient });
-
-// Typed reads
-const stats = await c.pool.read.getPoolStats();
-```
-
-If your service *requires* certain optional deployments (e.g. adapters, liquidators), use:
-
-```ts
-import { getRequiredVarlaContracts } from "@varla/sdk";
-
-const c = getRequiredVarlaContracts({
-  chain: "polygon",
-  client: polygonClient,
-  require: ["liquidator"],
-});
-```
-
----
-
-## 3) High-volume reads: views + batching + paging
-
-For most backend tasks, prefer SDK view helpers:
-
-```ts
-import * as views from "@varla/sdk/views";
-
-const snap = await views.readSystemSnapshot({ pool: c.pool, core: c.core, oracle: c.oracle });
-```
-
-### Oracle registry (configured positionIds)
-
-The oracle can have many configured positionIds. Use paging helpers:
-
-```ts
-const page = await views.readOracleRegistryPage({
-  oracle: c.oracle,
-  client: polygonClient,
-  start: 0,
-  limit: 500,
-});
-
-console.log(page.positionIds);
-```
-
-### Borrowers list
-
-Borrowers are tracked on-chain as a set. Use paging:
-
-```ts
-const borrowers = await views.readBorrowersPage({
-  core: c.core,
-  client: polygonClient,
-  start: 0,
-  limit: 200,
-});
-```
-
----
-
-## 4) Event-driven indexing
-
-For indexers, event-driven discovery is often cheaper than full scans.
-
-The SDK provides helpers under `@varla/sdk/events` for chunked log fetching and registry sync.
-
-Typical pattern:
-
-1) pick a block range window (e.g. 50k blocks)
-2) fetch logs in chunks
-3) persist a cursor (last processed block)
-4) on restart, resume from the cursor
-
-If you only need the oracle registry (configured positions), use the SDK’s event sync helper
-and then hydrate state via multicall:
-
-```ts
-import * as events from "@varla/sdk/events";
-import * as views from "@varla/sdk/views";
-
-// 1) discover positionIds from events
-const positionIds = await events.syncOracleRegistryViaEvents({
-  oracleAddress: c.oracle.address,
-  client: polygonClient,
-  fromBlock: 0n,
-  toBlock: "latest",
-});
-
-// 2) hydrate snapshots in multicall batches
-const snaps = await views.readManyPositionSnapshots({
-  oracle: { address: c.oracle.address },
-  client: polygonClient,
-  positionIds,
-});
-```
-
-Reorg handling:
-- Maintain a **reorg buffer** (e.g. always reprocess last 50–200 blocks).
-- Store both `blockNumber` and `blockHash` if you need strong guarantees.
-
----
-
-## 5) Writes from a backend: wallet client + simulate-first
-
-Backend writes should be explicit and auditable:
-
-- hold operator keys securely (HSM/KMS if possible)
-- simulate first to catch reverts
-- send
-- wait for receipts with confirmations
-
-Example `wallet.ts`:
-
-```ts
-import { createWalletClient, http } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
-import { polygon } from "viem/chains";
-
-const pk = process.env.OPERATOR_PRIVATE_KEY;
-if (!pk) throw new Error("Missing OPERATOR_PRIVATE_KEY");
-
-export const operatorAccount = privateKeyToAccount(pk as `0x${string}`);
-
-export const polygonWallet = createWalletClient({
-  chain: polygon,
-  transport: http(process.env.POLYGON_RPC_URL!),
-  account: operatorAccount,
-});
-```
-
-Then use SDK actions:
-
-```ts
-import * as actions from "@varla/sdk/actions";
-
-const sim = await actions.prepareCoreBorrow({
-  publicClient: polygonClient,
-  coreAddress: c.core.address,
-  account: operatorAccount.address,
-  amount: 1_000_000n,
-});
-
-const hash = await actions.sendTx({ walletClient: polygonWallet, request: sim.request });
-await polygonClient.waitForTransactionReceipt({ hash, confirmations: 2 });
-```
-
----
-
-## 6) RBAC preflight (AccessManager)
-
-The protocol uses OZ `AccessManager`.
-
-For admin services, do a preflight check before attempting writes:
-
-```ts
-import * as actions from "@varla/sdk/actions";
-
-// Example: ensure caller can call `configurePositionsBatch(...)` immediately.
-const selector = actions.selectorFromSignature(actions.ORACLE_SIGS.configurePositionsBatch);
-
-await actions.assertCanCallImmediate({
-  accessManager: c.accessManager,
-  caller: operatorAccount.address,
-  target: c.oracle.address,
-  selector,
-});
-```
-
-Tip: if you expect scheduled execution (delays), use the “delayed” flows and build a queue.
-
----
-
-## 7) Oracle seeding (plan → prepare → execute)
-
-The SDK provides **idempotent** seeding planners. Your backend can generate JSON lists
-and then run the seeder.
-
-Important: some operations must be done in 2 phases.
-
-- `configureOppositePositions(yesPid, noPid)` will revert unless both PIDs are already configured.
-
-Therefore:
-1) seed markets/configure positions
-2) seed opposites + negRisk
-
-Node convenience helper:
-
-```ts
-import * as actions from "@varla/sdk/actions";
-
-const seeded = await actions.seedOracleFromJsonFiles({
-  oracle: c.oracle,
-  marketsPath: "./markets.polygon.json",
-  oppositesPath: "./opposites.polygon.json",
-  negRiskPath: "./negrisk.polygon.json",
-  prepare: {
-    publicClient: polygonClient,
-    oracleAddress: c.oracle.address,
-    account: operatorAccount.address,
-  },
-});
-
-console.log(seeded.plan);
-
-if ("prepared" in seeded) {
-  const hashes = await actions.executeOracleSeedPlan({
-    walletClient: polygonWallet,
-    prepared: seeded.prepared,
-  });
-  console.log(hashes);
-}
-```
-
----
-
-## 8) Monitoring / alerting hooks
-
-Useful health signals to emit from a backend:
-
-- `views.readSystemSnapshot` periodically
-- staleness checks on configured oracle positions
-- borrower health factor checks (paging) and alert on `HF < 1.0`
-- pool utilization + borrow rates
-
----
-
-## 9) Gotchas
-
-- **Viem args are arrays**: `contract.read.fn([arg1, arg2])`.
-- Always wait for receipts with confirmations on critical admin writes.
-- Treat RPC errors as expected: implement retry/backoff and fallbacks.
-- Keep multicalls bounded (chunking) to avoid RPC provider limits.
-
----
-
-## All view helpers (generated)
-
-<!-- BEGIN GENERATED:VIEW_HELPERS -->
-<!--
-This section is auto-generated by scripts/sdk-generate-docs.ts.
-Do not edit manually.
--->
-
-- `getInterestRateStrategyFromPool`
-- `hydrateOraclePositionIds`
-- `previewBorrow`
-- `previewRepay`
-- `readAccessManagerBasics`
-- `readAccountPositions`
-- `readAccountPositionsFull`
-- `readAccountSnapshot`
-- `readAdapterInfo`
-- `readBadDebtStatus`
-- `readBorrowLimits`
-- `readBorrowerState`
-- `readBorrowers`
-- `readBorrowersPage`
-- `readCalculateLiquidationBonus`
-- `readCanLiquidate`
-- `readConfiguredPositionIds`
-- `readConvertLiquidatorBasics`
-- `readCoreAddresses`
-- `readCoreGlobalDebt`
-- `readDefaultLtvConfig`
-- `readHasRole`
-- `readHealthFactor`
-- `readHypotheticalBorrowCapacity`
-- `readInterestRateStrategyBasics`
-- `readLenderSnapshot`
-- `readLiquidationBonusBps`
-- `readLiquidationConfig`
-- `readLiquidationParamsForPosition`
-- `readLiquidatorBasics`
-- `readLiquidity`
-- `readLtvForPosition`
-- `readManyAccountSnapshots`
-- `readManyBorrowLimits`
-- `readManyHasRole`
-- `readManyLiquidationBonusBps`
-- `readManyOraclePositionMeta`
-- `readManyPositionSnapshots`
-- `readManyTargetConfigs`
-- `readManyTargetFunctionRoles`
-- `readMaxPositionsConfig`
-- `readMaxRedeem`
-- `readMaxWithdraw`
-- `readMergeLiquidatorBasics`
-- `readNegRiskMarketPositionIds`
-- `readOracleBasics`
-- `readOracleCollateralStatus`
-- `readOracleConfig`
-- `readOracleFinalizationStatus`
-- `readOracleGuardsStatus`
-- `readOraclePositionMeta`
-- `readOraclePriceData`
-- `readOracleRegistry`
-- `readOracleRegistryPage`
-- `readOracleTiming`
-- `readPoolAccounting`
-- `readPoolCaps`
-- `readPoolCoreAddress`
-- `readPoolDebtState`
-- `readPoolHealthScore`
-- `readPoolRates`
-- `readPoolSharePrice`
-- `readPoolSnapshot`
-- `readPortfolioValue`
-- `readPositionBalance`
-- `readPositionBalances`
-- `readPositionCount`
-- `readPositionLiquidationConfigOverride`
-- `readPositionLtvOverride`
-- `readPositionSnapshot`
-- `readPreviewLiquidation`
-- `readPrice`
-- `readProxyAdminPaused`
-- `readRepayTiming`
-- `readRiskTier`
-- `readRoleSummary`
-- `readSpotPrice`
-- `readSystemSnapshot`
-- `readTargetConfig`
-- `readTierLiquidationConfig`
-- `readTieredLtvConfig`
-- `readTryGetPrice`
-- `readTwap`
-<!-- END GENERATED:VIEW_HELPERS -->
-