@varla/sdk 1.10.12 → 1.11.0

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 Published package: **@varla/sdk**
 
-## Setup & build
+## Setup
 - Install: `bun install`
 - Build: `cd packages/sdk && bun run build`
 - Prepack: `cd packages/sdk && bun run prepack`
@@ -12,11 +12,10 @@ Published package: **@varla/sdk**
 - Types: `cd packages/sdk && bun run test:types`
 - Slow RPC (opt-in): `cd packages/sdk && bun run test:rpc:slow`
 
-## Key exports
+## Primary exports
 - Addresses: `@varla/sdk/addresses`
 - ABIs: `@varla/sdk/abi`
-- Core types/bindings: `@varla/sdk` (`getVarlaContracts`, `getRequiredVarlaContracts`)
-- Views: `@varla/sdk` or `@varla/sdk/views`
+- Contracts/bindings + views: `@varla/sdk` or `@varla/sdk/views`
 - Actions: `@varla/sdk/actions`
 - Events/indexer: `@varla/sdk/events`
 - Utilities: `@varla/sdk/batch`, `@varla/sdk/format`

package/BACKEND.md

@@ -0,0 +1,310 @@
+# 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.
+

package/README.md

@@ -22,6 +22,11 @@ npm i @varla/sdk
 
 ## Usage
 
+## Guides
+
+- [Frontend integration](./FRONTEND.md)
+- [Backend integration](./BACKEND.md)
+
 Frontend (Next.js + RainbowKit + wagmi/viem): see [`FRONTEND.md`](./FRONTEND.md).
 
 ## Testing (SDK)
@@ -150,6 +155,7 @@ These are convenience helpers built on top of the contract bindings.
 - `readOracleBasics`
 - `readOracleCollateralStatus`
 - `readOracleConfig`
+- `readOracleFinalizationStatus`
 - `readOracleGuardsStatus`
 - `readOraclePositionMeta`
 - `readOraclePriceData`