@varla/sdk 1.10.9 → 1.10.11

package/AGENTS.md

@@ -0,0 +1,22 @@
+# @varla/sdk (AGENTS)
+
+Published package: **@varla/sdk**
+
+## Install & build
+- Install (repo root): `bun install`
+- Build: `cd packages/sdk && bun run build`
+- Prepack (clean + regenerate + build): `cd packages/sdk && bun run prepack`
+
+## Tests
+- Quick: `cd packages/sdk && bun run test:quick`
+- Types: `cd packages/sdk && bun run test:types`
+- Slow RPC (opt-in): `cd packages/sdk && bun run test:rpc:slow`
+
+## Key exports
+- Addresses: `@varla/sdk/addresses`
+- ABIs: `@varla/sdk/abi`
+- Core types/bindings: `@varla/sdk` (`getVarlaContracts`, `getRequiredVarlaContracts`)
+- Views: `@varla/sdk` or `@varla/sdk/views`
+- Actions: `@varla/sdk/actions`
+- Events/indexer: `@varla/sdk/events`
+- Utilities: `@varla/sdk/batch`, `@varla/sdk/format`

package/FRONTEND.md

@@ -0,0 +1,252 @@
+# Frontend integration guide (Next.js + RainbowKit + wagmi/viem)
+
+This SDK is intentionally **batteries-not-included** for:
+
+- RPC configuration (URLs, retries, fallbacks, rate limits)
+- wallet connection / signers
+- transaction lifecycle UX (toasts, confirmations, polling, reorg handling)
+
+The SDK *does* provide:
+
+- ABIs + deployed addresses
+- typed viem contract bindings (`getVarlaContracts`)
+- high-level read facades (`@varla/sdk/views`)
+- simulate-first write helpers (`@varla/sdk/actions`)
+
+This doc shows a recommended integration setup for **Next.js + RainbowKit**.
+
+---
+
+## 1) Setup: wagmi config with explicit RPCs
+
+The SDK does not ship RPC URLs. Your app should configure those.
+
+Example `wagmi.ts` (app-side):
+
+```ts
+import { http, fallback } from "viem";
+import { polygon, bsc } from "wagmi/chains";
+import { getDefaultConfig } from "@rainbow-me/rainbowkit";
+
+const polygonRpc = process.env.NEXT_PUBLIC_POLYGON_RPC_URL;
+const bscRpc = process.env.NEXT_PUBLIC_BSC_RPC_URL;
+
+if (!polygonRpc) throw new Error("Missing NEXT_PUBLIC_POLYGON_RPC_URL");
+if (!bscRpc) throw new Error("Missing NEXT_PUBLIC_BSC_RPC_URL");
+
+export const wagmiConfig = getDefaultConfig({
+  appName: "Your App",
+  projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID!,
+  chains: [polygon, bsc],
+  transports: {
+    [polygon.id]: fallback([
+      http(polygonRpc),
+      // Optionally add a backup RPC:
+      // http("https://polygon-rpc.com"),
+    ]),
+    [bsc.id]: fallback([
+      http(bscRpc),
+      // http("https://bsc-dataseed.binance.org"),
+    ]),
+  },
+});
+```
+
+Notes:
+- If you need retries/backoff, implement it at the **RPC transport** layer.
+- For high-volume reads, prefer multicall + chunking (the SDK includes `multicallChunks`).
+
+---
+
+## 2) Getting Varla contract bindings (typed viem)
+
+In components/hooks, pull the active `PublicClient` from wagmi and pass it to the SDK:
+
+```ts
+import { usePublicClient } from "wagmi";
+import { getVarlaContracts } from "@varla/sdk";
+
+export function useVarlaContracts() {
+  const publicClient = usePublicClient();
+  // You may want to map `publicClient.chain?.id` to a Varla ChainKey.
+  const chainKey = publicClient.chain?.id === 56 ? "bsc" : "polygon";
+  return getVarlaContracts({ chain: chainKey, client: publicClient });
+}
+```
+
+---
+
+## 3) Reads
+
+### Direct reads
+You can call typed reads on the viem contracts. Reminder: **viem args are arrays**.
+
+```ts
+const hf = await c.core.read.getHealthFactor([userAddress]);
+```
+
+### Prefer SDK view facades for common UI needs
+
+```ts
+import * as views from "@varla/sdk/views";
+
+const snap = await views.readAccountSnapshot({
+  core: c.core,
+  user: userAddress,
+});
+```
+
+---
+
+## 4) Writes (simulate-first) with wagmi
+
+The SDK write helpers return simulated requests; **you send them with your wallet client**.
+
+### Pattern
+
+1) simulate via `PublicClient`
+2) send via `WalletClient`
+3) wait for receipt
+
+```ts
+import { useWalletClient, usePublicClient } from "wagmi";
+import * as actions from "@varla/sdk/actions";
+
+export function useBorrow() {
+  const publicClient = usePublicClient();
+  const { data: walletClient } = useWalletClient();
+
+  return async function borrow(params: {
+    coreAddress: `0x${string}`;
+    amount: bigint;
+    account: `0x${string}`;
+  }) {
+    if (!walletClient) throw new Error("Wallet not connected");
+
+    const sim = await actions.prepareCoreBorrow({
+      publicClient,
+      coreAddress: params.coreAddress,
+      account: params.account,
+      amount: params.amount,
+    });
+
+    const hash = await actions.sendTx({ walletClient, request: sim.request });
+    await publicClient.waitForTransactionReceipt({ hash });
+    return hash;
+  };
+}
+```
+
+### UX expectations
+Your app should own:
+- network switching (`switchChain`) when connected chain != expected chain
+- user rejection handling
+- toasts and pending state
+- refreshing query caches after confirmed receipts
+
+---
+
+## 5) Retries, fallbacks, and rate limits
+
+The SDK intentionally does not enforce a retry policy.
+
+Recommended approach:
+
+- configure **multiple RPC endpoints** per chain via wagmi/viem `fallback([http(...), http(...)])`
+- keep multicalls bounded:
+  - use `@varla/sdk/batch` `multicallChunks` (already used internally by many views)
+- treat RPC errors as expected and surface “try again” UX
+
+---
+
+## 6) Gotchas
+
+- **Viem args are arrays**: `read.fn([arg1, arg2])`.
+- Writes should generally be **simulate-first** to get revert reasons early.
+- Some admin flows may require **two-phase execution** (example: oracle seeding opposites requires markets configured first).
+
+---
+
+## 7) Standard “tx runner” helper (simulate → send → wait → error mapping)
+
+Most apps end up writing the same glue code around transactions.
+
+Recommended: centralize it in one place (app-side), and have UI components call it.
+
+This helper:
+- runs SDK `prepare*` (simulation)
+- sends with the connected `walletClient`
+- waits for a receipt
+- normalizes common error cases
+
+```ts
+import type { PublicClient, WalletClient } from "viem";
+import { sendTx } from "@varla/sdk/actions";
+
+export type TxRunnerErrorCode =
+  | "WALLET_NOT_CONNECTED"
+  | "USER_REJECTED"
+  | "SIMULATION_REVERT"
+  | "UNKNOWN";
+
+export class TxRunnerError extends Error {
+  code: TxRunnerErrorCode;
+  cause?: unknown;
+  constructor(code: TxRunnerErrorCode, message: string, cause?: unknown) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+function isUserRejectedRequest(err: unknown): boolean {
+  // Wallets vary. This is intentionally heuristic.
+  const msg = String((err as any)?.message ?? "").toLowerCase();
+  return msg.includes("user rejected") || msg.includes("rejected the request") || msg.includes("denied");
+}
+
+/**
+ * Runs a simulate-first tx end-to-end.
+ *
+ * Usage:
+ *   await runTx({ publicClient, walletClient, simulate: () => actions.prepareCoreBorrow(...) })
+ */
+export async function runTx(params: {
+  publicClient: Pick<PublicClient, "waitForTransactionReceipt">;
+  walletClient: Pick<WalletClient, "writeContract"> | undefined;
+  simulate: () => Promise<{ request: any }>;
+}): Promise<`0x${string}`> {
+  if (!params.walletClient) {
+    throw new TxRunnerError("WALLET_NOT_CONNECTED", "Wallet not connected");
+  }
+
+  let sim: { request: any };
+  try {
+    sim = await params.simulate();
+  } catch (err) {
+    throw new TxRunnerError("SIMULATION_REVERT", "Transaction simulation failed", err);
+  }
+
+  try {
+    const hash = await sendTx({ walletClient: params.walletClient, request: sim.request });
+    await params.publicClient.waitForTransactionReceipt({ hash });
+    return hash;
+  } catch (err) {
+    if (isUserRejectedRequest(err)) {
+      throw new TxRunnerError("USER_REJECTED", "User rejected the transaction", err);
+    }
+    throw new TxRunnerError("UNKNOWN", "Transaction failed", err);
+  }
+}
+```
+
+With wagmi hooks, you’d pass:
+- `usePublicClient()` → `publicClient`
+- `useWalletClient().data` → `walletClient`
+- `simulate: () => actions.prepare...({ publicClient, account, ... })`
+
+This keeps UI components clean, and gives you one place to wire:
+- toasts
+- analytics
+- receipt confirmations
+- error mapping

package/README.md

@@ -22,6 +22,8 @@ npm i @varla/sdk
 
 ## Usage
 
+Frontend (Next.js + RainbowKit + wagmi/viem): see [`FRONTEND.md`](./FRONTEND.md).
+
 ## Testing (SDK)
 
 Run from `packages/sdk`:

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@varla/sdk",
-  "version": "1.10.9",
+  "version": "1.10.11",
   "private": false,
   "type": "module",
   "sideEffects": false,
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "FRONTEND.md",
+    "AGENTS.md"
   ],
   "exports": {
     ".": {