@varla/sdk 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,164 @@
+# @varla/sdk
+
+Published SDK package for Varla.
+
+This package is the single source of truth for:
+- contract **ABIs**
+- per-chain deployed **addresses**
+- shared **types** used by Varla offchain services and apps
+
+It also provides **typed read-only contract bindings** (via `viem`) for convenient access to
+on-chain *view* functions.
+
+## Install
+
+```bash
+# bun
+bun add @varla/sdk
+
+# npm
+npm i @varla/sdk
+```
+
+## Usage
+
+## Testing (SDK)
+
+Run from `packages/sdk`:
+
+```bash
+# Primary suite: regenerate artifacts + build + run bun tests (includes RPC-backed integration tests)
+bun test
+
+# Quick: build + run bun tests (skips regeneration)
+bun run test:quick
+
+# Only RPC-backed integration tests (Polygon + BSC)
+bun run test:rpc
+
+# Only non-RPC smoke tests
+bun run test:smoke
+```
+
+### RPC configuration
+
+By default, RPC-backed tests use public endpoints with fallback & retries.
+For more reliability (recommended in CI), set:
+
+- `POLYGON_RPC_URL`
+- `BSC_RPC_URL`
+
+Note: public RPC providers can change policies over time (rate limits, API keys). If tests become flaky,
+set explicit RPC URLs via env.
+
+### Addresses
+
+```ts
+import * as addresses from "@varla/sdk/addresses";
+
+// e.g.
+// addresses.polygon.core
+// addresses.bsc.pool
+```
+
+### ABIs
+
+```ts
+import * as abi from "@varla/sdk/abi";
+
+// e.g.
+// abi.VARLACORE_ABI
+// abi.POLYMARKETCTFADAPTER_ABI
+```
+
+### Types
+
+```ts
+import type { AddressBook } from "@varla/sdk";
+```
+
+### Read-only contract bindings (viem)
+
+The SDK does not ship RPC URLs.
+Consumers provide their own `viem` `PublicClient`.
+
+```ts
+import { createPublicClient, http } from "viem";
+import { polygon } from "viem/chains";
+import { getVarlaContracts } from "@varla/sdk";
+
+const client = createPublicClient({
+  chain: polygon,
+  transport: http(process.env.POLYGON_RPC_URL!),
+});
+
+const c = getVarlaContracts({ chain: "polygon", client });
+
+// Typed reads (inferred from ABI)
+const stats = await c.pool.read.getPoolStats();
+const hf = await c.core.read.getHealthFactor(["0xYourUserAddress"]); // note viem args are arrays
+```
+
+### Higher-level views (facades)
+
+These are convenience helpers built on top of the contract bindings.
+
+```ts
+import { readOracleRegistry, readPoolSnapshot } from "@varla/sdk";
+
+// Fetch all oracle-configured positionIds (uses multicall + chunking)
+const positionIds = await readOracleRegistry({
+  oracle: c.oracle,
+  client,
+});
+
+// Read pool snapshot (wraps getPoolStats)
+const pool = await readPoolSnapshot({ pool: c.pool });
+```
+
+#### Optional deployments
+
+Some deployments are chain-specific (e.g. adapters). These are exposed as optional properties:
+
+```ts
+if (c.polymarketCtfAdapter) {
+  // polygon
+}
+if (c.opinionCtfExecutionEngineAdapter) {
+  // bsc
+}
+```
+
+If you want to enforce presence for backends, use `getRequiredVarlaContracts`:
+
+```ts
+import { getRequiredVarlaContracts } from "@varla/sdk";
+
+const c = getRequiredVarlaContracts({
+  chain: "polygon",
+  client,
+  require: ["liquidator", "mergeLiquidator"],
+});
+```
+
+### Generic token helpers (ERC20 / ERC1155)
+
+Useful when you discover token addresses via Varla views:
+
+```ts
+import { getErc20, getErc1155 } from "@varla/sdk";
+
+const collateral = await c.core.read.collateralToken();
+const usdc = getErc20({ client, address: collateral });
+const decimals = await usdc.read.decimals();
+
+const positionsToken = await c.core.read.positionsToken();
+const ctf = getErc1155({ client, address: positionsToken });
+const bal = await ctf.read.balanceOf(["0xUser", 123n]);
+```
+
+## How it’s built
+
+On publish, this repo regenerates artifacts from the tracked `deployments/*` and Hardhat `artifacts/*`.
+
+The published output is `dist/` and is exported via package `exports`.

package/dist/batch.d.ts

@@ -0,0 +1,26 @@
+import type { Abi, Address, PublicClient } from "viem";
+export type MulticallChunkOptions = {
+    /** Number of calls per multicall batch. */
+    chunkSize?: number;
+};
+/**
+ * Small utility to chunk an array.
+ */
+export declare function chunk<T>(items: readonly T[], chunkSize: number): T[][];
+/**
+ * Executes `client.multicall` in chunks.
+ *
+ * - Keeps requests bounded for public RPC providers.
+ * - Preserves order.
+ */
+export declare function multicallChunks<TAbi extends Abi>(params: {
+    client: PublicClient;
+    contracts: readonly {
+        address: Address;
+        abi: Abi;
+        functionName: string;
+        args?: readonly unknown[] | undefined;
+    }[];
+    chunkSize?: number;
+}): Promise<Awaited<ReturnType<PublicClient["multicall"]>>>;
+//# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAEvD,MAAM,MAAM,qBAAqB,GAAG;IAClC,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAKtE;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,SAAS,GAAG,EAAE,MAAM,EAAE;IAC9D,MAAM,EAAE,YAAY,CAAC;IAIrB,SAAS,EAAE,SAAS;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,GAAG,EAAE,GAAG,CAAC;QACT,YAAY,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;KACvC,EAAE,CAAC;IACJ,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAiB1D"}

package/dist/batch.js

@@ -0,0 +1,34 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+/**
+ * Small utility to chunk an array.
+ */
+export function chunk(items, chunkSize) {
+    if (chunkSize <= 0)
+        throw new Error(`chunkSize must be > 0 (got ${chunkSize})`);
+    const out = [];
+    for (let i = 0; i < items.length; i += chunkSize)
+        out.push(items.slice(i, i + chunkSize));
+    return out;
+}
+/**
+ * Executes `client.multicall` in chunks.
+ *
+ * - Keeps requests bounded for public RPC providers.
+ * - Preserves order.
+ */
+export async function multicallChunks(params) {
+    const { client } = params;
+    const chunkSize = params.chunkSize ?? 128;
+    const calls = params.contracts;
+    if (calls.length === 0)
+        return [];
+    // Note: we avoid a generic chunk() here because TS can sometimes lose the
+    // `client.multicall` contract-call type across the generic boundary.
+    const out = [];
+    for (let i = 0; i < calls.length; i += chunkSize) {
+        const slice = calls.slice(i, i + chunkSize);
+        const res = await client.multicall({ contracts: slice });
+        out.push(...res);
+    }
+    return out;
+}