@varla/sdk 1.11.1 → 1.11.2

package/AGENTS.md

@@ -19,3 +19,77 @@ Published package: **@varla/sdk**
 - Actions: `@varla/sdk/actions`
 - Events/indexer: `@varla/sdk/events`
 - Utilities: `@varla/sdk/batch`, `@varla/sdk/format`
+
+---
+
+## Frontend-oriented view helpers (quick map)
+
+> Tip: prefer **subpath imports** so it’s obvious what you’re using:
+>
+> ```ts
+> import * as views from "@varla/sdk/views";
+> import * as actions from "@varla/sdk/actions";
+> ```
+
+### Lend page (pool / lenders)
+
+- **User supplied amount (current value)** + shares + withdrawable
+  - `views.readLenderSnapshot({ pool, user })` →
+    `{ shares, assets, maxWithdrawAssets, maxRedeemShares }`
+  - Notes:
+    - `assets` is the **current underlying value** of the user’s ERC4626 shares (principal + interest).
+    - `maxWithdrawAssets` is the **available-to-withdraw right now** (liquidity + reserve aware).
+
+- **Available-to-withdraw only**
+  - `views.readMaxWithdraw({ pool, user })` → `{ maxWithdrawAssets }`
+
+- **Pool share price (assets per share)**
+  - `views.readPoolSharePrice({ pool })` → `{ assetsPerShareWad }`
+
+- **Pool utilization + rates**
+  - `views.readPoolSnapshot({ pool })` or `views.readPoolRates({ pool })`
+
+- **Pool safety score**
+  - `views.readPoolHealthScore({ pool })` →
+    - `{ kind: "no-liquidity" }` when the pool has 0 assets (prevents showing a misleading 100)
+    - `{ kind: "ok", utilizationWad, scoreBps }` otherwise
+
+### Borrow page (core / borrower risk)
+
+- **Account overview (portfolio, debt, HF, max borrow)**
+  - `views.readAccountSnapshot({ core, user })`
+  - or `views.readBorrowLimits({ core, user })` when you only need limits + HF
+
+- **Max LTV vs tier naming (avoid ambiguity)**
+  - `views.readTieredLtvConfig({ core })` → `{ tier0, tier1, tier2 }` (maps 1:1 to CONSERVATIVE/MODERATE/RISK)
+  - For an actual position, prefer effective LTV:
+    - `views.readLtvForPosition({ core, positionId })` → `{ ltvWad }`
+
+- **Liquidation threshold / params**
+  - `views.readHealthFactor({ core, user })` → `{ healthFactor, canBeLiquidated }`
+  - `views.readLiquidationConfig({ core })` and `views.readTierLiquidationConfig({ core, tier })`
+
+### Home page / “Top opportunities” (suggested inputs)
+
+The SDK can provide raw primitives; **ranking is app-side**:
+- `views.readPoolRates({ pool })` (supplyAPY, utilization)
+- `views.readPoolCaps({ pool })` (capacity constraints)
+- `views.readPoolHealthScore({ pool })` (simple risk signal)
+
+---
+
+## Not provided by the SDK (by design)
+
+- **“Interest accrued / lender earnings” for a user**
+  - ERC4626 does not track principal per-user.
+  - To show “interest accrued”, you need a cost basis, e.g.:
+    - app-side tracking of deposits/withdrawals, or
+    - an indexer that reconstructs deposits/withdrawals from events.
+
+- **Borrow “net rate”**
+  - `borrowRate` and pool `supplyAPY` are available, but “net” is product-specific
+    (depends on whether you consider collateral yield, whether user is also a lender, etc.).
+
+- **Cooldown period**
+  - As of `contracts/VarlaPool.sol` in this repo, there is **no cooldown / withdraw delay** view.
+  - If a cooldown is introduced later, we can add `views.readPoolConfig({ pool })`.

package/FRONTEND.md

@@ -98,6 +98,144 @@ const snap = await views.readAccountSnapshot({
 
 ---
 
+## 3.1) Lend page cookbook (pool / lenders)
+
+> Recommended imports:
+>
+> ```ts
+> import * as views from "@varla/sdk/views";
+> ```
+
+### User supplied amount (current value)
+
+Use `readLenderSnapshot`:
+
+```ts
+const lender = await views.readLenderSnapshot({ pool: c.pool, user: userAddress });
+
+// lender.assets is the current underlying value of the user’s ERC4626 shares
+// (principal + interest), *not* a tracked principal amount.
+```
+
+Return shape:
+- `shares`: ERC4626 vault share balance
+- `assets`: `convertToAssets(shares)` (current redeemable underlying)
+
+### Available to withdraw (overview chart)
+
+If you only need withdrawable amount:
+
+```ts
+const { maxWithdrawAssets } = await views.readMaxWithdraw({ pool: c.pool, user: userAddress });
+```
+
+Or use `readLenderSnapshot` and read `maxWithdrawAssets`.
+
+### Pool share price (charting)
+
+```ts
+const { assetsPerShareWad } = await views.readPoolSharePrice({ pool: c.pool });
+```
+
+### Pool rates + utilization
+
+```ts
+const poolRates = await views.readPoolRates({ pool: c.pool });
+// { utilization, borrowRate, supplyAPY, availableLiquidity, maxBorrow }
+```
+
+### Lender earnings / “interest accrued”
+
+The SDK does **not** currently provide `readLenderEarnings(pool, user)`.
+
+Reason: ERC4626 does not store a per-user principal (cost basis), so “interest accrued”
+cannot be derived purely from the vault without historical data.
+
+Recommended approach:
+- Track deposits/withdrawals in your app (or an indexer) to build a cost basis.
+- Compute earnings as (example):
+  - `earnings = currentAssets - (sumDeposits - sumWithdrawals)`
+
+---
+
+## 3.2) Borrow page cookbook (core / borrower risk)
+
+### Account overview
+
+```ts
+const snap = await views.readAccountSnapshot({ core: c.core, user: userAddress });
+// { portfolioValue, collateralValue, debt, healthFactor, maxBorrow }
+```
+
+### Max LTV clarification (defaults vs effective)
+
+The protocol exposes **default LTV per risk tier**:
+
+```ts
+const tiers = await views.readTieredLtvConfig({ core: c.core });
+// { tier0, tier1, tier2 } == { conservative, moderate, risk }
+```
+
+Important: `tier2`/`risk` is **not universally “the max LTV”**; it’s the default
+for the tier-2 risk category.
+
+For a specific collateral position, prefer the **effective** LTV:
+
+```ts
+const { ltvWad } = await views.readLtvForPosition({ core: c.core, positionId });
+```
+
+### Liquidation threshold
+
+Liquidation eligibility is best represented by health factor:
+
+```ts
+const hf = await views.readHealthFactor({ core: c.core, user: userAddress });
+// { healthFactor, canBeLiquidated }
+```
+
+For parameters behind liquidation incentives/fees:
+
+```ts
+const liq = await views.readLiquidationConfig({ core: c.core });
+const liqTier0 = await views.readTierLiquidationConfig({ core: c.core, tier: 0 });
+```
+
+---
+
+## 3.3) Pool safety score (lend page)
+
+If your UI currently does:
+`(1 - utilization) * 100`, it will misleadingly show **100** when the pool has no liquidity.
+
+Prefer the SDK helper:
+
+```ts
+const score = await views.readPoolHealthScore({ pool: c.pool });
+
+if (score.kind === "no-liquidity") {
+  // show "N/A" or "—"
+} else {
+  // score.scoreBps is 0..10_000
+}
+```
+
+Current formula used by the SDK:
+- if `totalAssets == 0` → `{ kind: "no-liquidity" }`
+- else `scoreBps = (1 - utilizationWad) * 10_000` (clamped to [0..10_000])
+
+---
+
+## 3.4) Home page “top opportunities”
+
+The SDK provides primitives, but **ranking is app-side**:
+
+- `views.readPoolRates({ pool })` (supply APY, utilization)
+- `views.readPoolCaps({ pool })` (capacity constraints)
+- `views.readPoolHealthScore({ pool })` (simple risk signal)
+
+---
+
 ## 4) Writes (simulate-first) with wagmi
 
 The SDK write helpers return simulated requests; **you send them with your wallet client**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@varla/sdk",
-  "version": "1.11.1",
+  "version": "1.11.2",
   "private": false,
   "type": "module",
   "sideEffects": false,