@varla/sdk 1.11.3 → 1.13.2

package/src/contracts.ts

@@ -0,0 +1,232 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+import {
+  type Address,
+  erc20Abi,
+  erc1155Abi,
+  erc4626Abi,
+  type GetContractReturnType,
+  getContract,
+  type PublicClient,
+} from "viem";
+
+import { abis, addresses } from "./generated.js";
+import type { AddressBook, ChainKey } from "./types.js";
+
+/**
+ * A typed viem Contract instance.
+ *
+ * Note: `getContract` infers method typings from the ABI, so consumers get
+ * `contract.read.*` methods with proper argument/return inference.
+ */
+export type ReadonlyContract<TAbi extends readonly unknown[]> = GetContractReturnType<
+  TAbi,
+  PublicClient
+>;
+
+export type VarlaContracts = {
+  chain: ChainKey;
+  addressBook: AddressBook;
+
+  accessManager: ReadonlyContract<typeof abis.VARLAACCESSMANAGER_ABI>;
+  oracle: ReadonlyContract<typeof abis.VARLAORACLE_ABI>;
+  core: ReadonlyContract<typeof abis.VARLACORE_ABI>;
+  pool: ReadonlyContract<typeof abis.VARLAPOOL_ABI>;
+
+  // Optional extras (depend on deployment)
+  oracleUpdaterRouter?: ReadonlyContract<typeof abis.ORACLEUPDATERROUTER_ABI>;
+  interestRateStrategy?: ReadonlyContract<typeof abis.VARLAINTERESTRATESTRATEGY_ABI>;
+  proxyAdmin?: ReadonlyContract<typeof abis.VARLAPROXYADMIN_ABI>;
+
+  liquidator?: ReadonlyContract<typeof abis.VARLALIQUIDATOR_ABI>;
+  mergeLiquidator?: ReadonlyContract<typeof abis.VARLAMERGELIQUIDATOR_ABI>;
+  convertLiquidator?: ReadonlyContract<typeof abis.VARLACONVERTLIQUIDATOR_ABI>;
+
+  polymarketCtfAdapter?: ReadonlyContract<typeof abis.POLYMARKETCTFADAPTER_ABI>;
+  opinionCtfExecutionEngineAdapter?: ReadonlyContract<
+    typeof abis.OPINIONCTFEXECUTIONENGINEADAPTER_ABI
+  >;
+};
+
+export type GetVarlaContractsParams = {
+  chain: ChainKey;
+  client: PublicClient;
+};
+
+export function getAddressBook(chain: ChainKey): AddressBook {
+  if (chain === "polygon") return addresses.polygon;
+  if (chain === "bsc") return addresses.bsc;
+
+  // TypeScript should make this unreachable, but keep a runtime guard.
+  // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+  throw new Error(`Unsupported chain key: ${chain as string}`);
+}
+
+function mustAddress(book: AddressBook, key: keyof AddressBook): Address {
+  const v = book[key];
+  if (!v) {
+    throw new Error(`Missing required deployment address for '${String(key)}'`);
+  }
+  return v as Address;
+}
+
+/**
+ * Returns typed readonly viem contract instances for all known Varla deployments on a chain.
+ *
+ * Optional deployments are returned as `undefined`.
+ */
+export function getVarlaContracts({ chain, client }: GetVarlaContractsParams): VarlaContracts {
+  const book = getAddressBook(chain);
+
+  const accessManager = getContract({
+    address: mustAddress(book, "accessManager"),
+    abi: abis.VARLAACCESSMANAGER_ABI,
+    client,
+  });
+
+  const oracle = getContract({
+    address: mustAddress(book, "oracle"),
+    abi: abis.VARLAORACLE_ABI,
+    client,
+  });
+
+  const core = getContract({
+    address: mustAddress(book, "core"),
+    abi: abis.VARLACORE_ABI,
+    client,
+  });
+
+  const pool = getContract({
+    address: mustAddress(book, "pool"),
+    abi: abis.VARLAPOOL_ABI,
+    client,
+  });
+
+  const oracleUpdaterRouter = book.oracleUpdaterRouter
+    ? getContract({
+        address: book.oracleUpdaterRouter as Address,
+        abi: abis.ORACLEUPDATERROUTER_ABI,
+        client,
+      })
+    : undefined;
+
+  const interestRateStrategy = book.interestRateStrategy
+    ? getContract({
+        address: book.interestRateStrategy as Address,
+        abi: abis.VARLAINTERESTRATESTRATEGY_ABI,
+        client,
+      })
+    : undefined;
+
+  const proxyAdmin = book.proxyAdmin
+    ? getContract({
+        address: book.proxyAdmin as Address,
+        abi: abis.VARLAPROXYADMIN_ABI,
+        client,
+      })
+    : undefined;
+
+  const liquidator = book.liquidator
+    ? getContract({
+        address: book.liquidator as Address,
+        abi: abis.VARLALIQUIDATOR_ABI,
+        client,
+      })
+    : undefined;
+
+  const mergeLiquidator = book.mergeLiquidator
+    ? getContract({
+        address: book.mergeLiquidator as Address,
+        abi: abis.VARLAMERGELIQUIDATOR_ABI,
+        client,
+      })
+    : undefined;
+
+  const convertLiquidator = book.convertLiquidator
+    ? getContract({
+        address: book.convertLiquidator as Address,
+        abi: abis.VARLACONVERTLIQUIDATOR_ABI,
+        client,
+      })
+    : undefined;
+
+  const polymarketCtfAdapter = book.polymarketCtfAdapter
+    ? getContract({
+        address: book.polymarketCtfAdapter as Address,
+        abi: abis.POLYMARKETCTFADAPTER_ABI,
+        client,
+      })
+    : undefined;
+
+  const opinionCtfExecutionEngineAdapter = book.opinionCtfExecutionEngineAdapter
+    ? getContract({
+        address: book.opinionCtfExecutionEngineAdapter as Address,
+        abi: abis.OPINIONCTFEXECUTIONENGINEADAPTER_ABI,
+        client,
+      })
+    : undefined;
+
+  return {
+    chain,
+    addressBook: book,
+    accessManager,
+    oracle,
+    core,
+    pool,
+    oracleUpdaterRouter,
+    interestRateStrategy,
+    proxyAdmin,
+    liquidator,
+    mergeLiquidator,
+    convertLiquidator,
+    polymarketCtfAdapter,
+    opinionCtfExecutionEngineAdapter,
+  };
+}
+
+/**
+ * Same as `getVarlaContracts`, but throws if any optional deployment addresses are missing.
+ * Useful for backend services that assume a fully-featured deployment.
+ */
+export function getRequiredVarlaContracts(
+  params: GetVarlaContractsParams & {
+    require?: Array<
+      | "oracleUpdaterRouter"
+      | "interestRateStrategy"
+      | "proxyAdmin"
+      | "liquidator"
+      | "mergeLiquidator"
+      | "convertLiquidator"
+      | "polymarketCtfAdapter"
+      | "opinionCtfExecutionEngineAdapter"
+    >;
+  },
+): Required<VarlaContracts> {
+  const c = getVarlaContracts(params);
+  const require = params.require ?? [];
+
+  // Convert the optional keys into a runtime check while preserving a nice signature.
+  for (const k of require) {
+    if (!c[k]) {
+      throw new Error(`Missing required deployment: '${k}' on chain '${c.chain}'`);
+    }
+  }
+
+  return c as Required<VarlaContracts>;
+}
+
+// ---------------------------------------------------------------------------
+// Generic helpers (for UIs): ERC20 / ERC1155 / ERC4626
+// ---------------------------------------------------------------------------
+
+export function getErc20(params: { client: PublicClient; address: Address }) {
+  return getContract({ address: params.address, abi: erc20Abi, client: params.client });
+}
+
+export function getErc1155(params: { client: PublicClient; address: Address }) {
+  return getContract({ address: params.address, abi: erc1155Abi, client: params.client });
+}
+
+export function getErc4626(params: { client: PublicClient; address: Address }) {
+  return getContract({ address: params.address, abi: erc4626Abi, client: params.client });
+}

package/src/errors.ts

@@ -0,0 +1,305 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+/**
+ * Error decoding utilities for Varla Protocol contracts.
+ *
+ * Usage:
+ *   import { decodeVarlaError, isVarlaError } from "@varla/sdk/errors";
+ *
+ *   try {
+ *     await publicClient.simulateContract(...);
+ *   } catch (err) {
+ *     const decoded = decodeVarlaError(err);
+ *     if (decoded) console.log(decoded.name, decoded.args);
+ *   }
+ */
+
+import { type Abi, type DecodeErrorResultReturnType, decodeErrorResult, type Hex } from "viem";
+
+/** Minimal ABI error item shape (matches viem/abitype). */
+type AbiErrorItem = {
+  type: "error";
+  name: string;
+  inputs: readonly { name: string; type: string; indexed?: boolean; components?: readonly any[] }[];
+};
+
+import { abis } from "./generated.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type DecodedVarlaError = {
+  /** The Solidity custom error name, e.g. "InsufficientCollateral". */
+  name: string;
+  /** Which contract ABI matched. */
+  contract: string;
+  /** Decoded arguments (typed per ABI). */
+  args: readonly unknown[];
+  /** The raw 4-byte selector. */
+  selector: Hex;
+  /** The full revert data. */
+  data: Hex;
+};
+
+// ---------------------------------------------------------------------------
+// Internal: ABI registry with contract labels
+// ---------------------------------------------------------------------------
+
+type LabeledAbi = { label: string; abi: Abi };
+
+/** All Varla contract ABIs, labeled for error attribution. */
+const VARLA_ABIS: readonly LabeledAbi[] = [
+  { label: "VarlaCore", abi: abis.VARLACORE_ABI as unknown as Abi },
+  { label: "VarlaPool", abi: abis.VARLAPOOL_ABI as unknown as Abi },
+  { label: "VarlaOracle", abi: abis.VARLAORACLE_ABI as unknown as Abi },
+  { label: "VarlaLiquidator", abi: abis.VARLALIQUIDATOR_ABI as unknown as Abi },
+  { label: "VarlaMergeLiquidator", abi: abis.VARLAMERGELIQUIDATOR_ABI as unknown as Abi },
+  { label: "VarlaConvertLiquidator", abi: abis.VARLACONVERTLIQUIDATOR_ABI as unknown as Abi },
+  { label: "VarlaAccessManager", abi: abis.VARLAACCESSMANAGER_ABI as unknown as Abi },
+  { label: "OracleUpdaterRouter", abi: abis.ORACLEUPDATERROUTER_ABI as unknown as Abi },
+  {
+    label: "VarlaInterestRateStrategy",
+    abi: abis.VARLAINTERESTRATESTRATEGY_ABI as unknown as Abi,
+  },
+  { label: "VarlaProxyAdmin", abi: abis.VARLAPROXYADMIN_ABI as unknown as Abi },
+  { label: "PolymarketCtfAdapter", abi: abis.POLYMARKETCTFADAPTER_ABI as unknown as Abi },
+  {
+    label: "OpinionCtfExecutionEngineAdapter",
+    abi: abis.OPINIONCTFEXECUTIONENGINEADAPTER_ABI as unknown as Abi,
+  },
+] as const;
+
+// ---------------------------------------------------------------------------
+// Lazy-built selector → { label, errorAbi } map for O(1) lookup
+// ---------------------------------------------------------------------------
+
+type ErrorEntry = { label: string; errorItem: AbiErrorItem };
+
+let selectorMap: Map<string, ErrorEntry> | undefined;
+
+function ensureSelectorMap(): Map<string, ErrorEntry> {
+  if (selectorMap) return selectorMap;
+
+  // We need to compute the 4-byte selectors ourselves from ABI error items.
+  // viem's `toFunctionSelector` works for errors too (same keccak256 scheme).
+  // But we can also just try decoding against each ABI — the selector map is
+  // an optimization for O(1) lookup vs O(n) trial decoding.
+  //
+  // For simplicity and correctness, we build it lazily by extracting error items.
+  selectorMap = new Map();
+
+  for (const { label, abi } of VARLA_ABIS) {
+    for (const item of abi) {
+      if ((item as any).type === "error") {
+        const errorItem = item as AbiErrorItem;
+        // Compute selector: keccak256 of signature, take first 4 bytes.
+        const sig = formatErrorSignature(errorItem);
+        const selector = computeSelector(sig);
+        // First match wins (in case of selector collisions across contracts).
+        if (!selectorMap.has(selector)) {
+          selectorMap.set(selector, { label, errorItem });
+        }
+      }
+    }
+  }
+
+  return selectorMap;
+}
+
+function formatErrorSignature(errorItem: AbiErrorItem): string {
+  const inputs = (errorItem.inputs ?? [])
+    .map((i: { type: string; components?: readonly any[] }) => {
+      if ((i as any).components) {
+        // Tuple type — recurse.
+        return formatTupleType((i as any).components);
+      }
+      return i.type;
+    })
+    .join(",");
+  return `${errorItem.name}(${inputs})`;
+}
+
+function formatTupleType(
+  components: readonly { type: string; components?: readonly any[] }[],
+): string {
+  const inner = components
+    .map((c) => {
+      if (c.components) return formatTupleType(c.components);
+      return c.type;
+    })
+    .join(",");
+  return `(${inner})`;
+}
+
+function computeSelector(signature: string): string {
+  // Use a simple approach: try to use globalThis.crypto if available (Bun / browser),
+  // otherwise fall back to encoding.
+  // For Bun: crypto.subtle is available but is async. Use the sync digest approach.
+  const encoded = new TextEncoder().encode(signature);
+
+  // Bun and modern runtimes have crypto.createHash or Bun.hash.
+  // Use a portable approach: manually compute or use viem's toFunctionSelector.
+  // Since we already import viem, use its keccak256.
+  // Import dynamically to keep this simple.
+  const hash = keccak256Bytes(encoded);
+  return hash.slice(0, 10); // "0x" + 4 bytes = 10 chars
+}
+
+/**
+ * Simple keccak256 using viem's built-in.
+ */
+function keccak256Bytes(data: Uint8Array): string {
+  // viem exports keccak256 which accepts Hex | ByteArray.
+  // We import it at the top level to avoid dynamic imports.
+  return keccak256Fn(data);
+}
+
+// We import keccak256 lazily to avoid circular issues and keep the import clean.
+import { keccak256 as keccak256Fn } from "viem";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract revert data from various error shapes.
+ *
+ * Supports:
+ * - viem `ContractFunctionRevertedError` (`.data?.data` or `.data`)
+ * - Raw hex string
+ * - `{ data: Hex }` object
+ */
+export function extractRevertData(err: unknown): Hex | null {
+  if (typeof err === "string" && err.startsWith("0x") && err.length >= 10) {
+    return err as Hex;
+  }
+
+  if (err && typeof err === "object") {
+    const anyErr = err as any;
+
+    // viem ContractFunctionRevertedError: err.data is an object with a `data` hex field,
+    // or err.cause?.data, or err.walk?.() to find the inner error.
+    if (typeof anyErr.data === "string" && (anyErr.data as string).startsWith("0x")) {
+      return anyErr.data as Hex;
+    }
+
+    if (anyErr.data && typeof anyErr.data === "object") {
+      if (typeof anyErr.data.data === "string" && (anyErr.data.data as string).startsWith("0x")) {
+        return anyErr.data.data as Hex;
+      }
+    }
+
+    // Walk cause chain (viem errors often nest).
+    if (anyErr.cause) {
+      return extractRevertData(anyErr.cause);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Attempt to decode revert data against all known Varla contract ABIs.
+ *
+ * @param errOrData - A caught error object, or raw revert data hex string.
+ * @returns Decoded error info, or `null` if no match.
+ *
+ * @example
+ * ```ts
+ * import { decodeVarlaError } from "@varla/sdk/errors";
+ *
+ * try {
+ *   await publicClient.simulateContract({ ... });
+ * } catch (err) {
+ *   const decoded = decodeVarlaError(err);
+ *   if (decoded) {
+ *     console.log(`Revert: ${decoded.name} on ${decoded.contract}`);
+ *     console.log("Args:", decoded.args);
+ *   }
+ * }
+ * ```
+ */
+export function decodeVarlaError(errOrData: unknown): DecodedVarlaError | null {
+  const data =
+    typeof errOrData === "string" && errOrData.startsWith("0x")
+      ? (errOrData as Hex)
+      : extractRevertData(errOrData);
+
+  if (!data || data.length < 10) return null;
+
+  const selector = data.slice(0, 10) as Hex;
+  const map = ensureSelectorMap();
+  const entry = map.get(selector);
+
+  if (!entry) return null;
+
+  // Use viem's decodeErrorResult for proper ABI-based decoding.
+  try {
+    const decoded: DecodeErrorResultReturnType = decodeErrorResult({
+      abi: [entry.errorItem] as Abi,
+      data,
+    });
+    return {
+      name: decoded.errorName,
+      contract: entry.label,
+      args: decoded.args ?? [],
+      selector,
+      data,
+    };
+  } catch {
+    // Decoding failed (e.g. data too short for the error's parameters).
+    return null;
+  }
+}
+
+/**
+ * Type guard: returns true if the error is a Varla custom error revert.
+ */
+export function isVarlaError(err: unknown): boolean {
+  return decodeVarlaError(err) !== null;
+}
+
+/**
+ * Format a decoded error into a human-readable string.
+ *
+ * Example output: `"VarlaCore.InsufficientCollateral(required=1000, actual=500)"`
+ */
+export function formatVarlaError(decoded: DecodedVarlaError): string {
+  const args =
+    decoded.args.length > 0 ? `(${decoded.args.map((a) => String(a)).join(", ")})` : "()";
+  return `${decoded.contract}.${decoded.name}${args}`;
+}
+
+/**
+ * Convenience: decode + format in one call.
+ *
+ * @returns Human-readable error string, or `null` if not a known Varla error.
+ */
+export function tryFormatVarlaError(errOrData: unknown): string | null {
+  const decoded = decodeVarlaError(errOrData);
+  if (!decoded) return null;
+  return formatVarlaError(decoded);
+}
+
+/**
+ * Get all known custom error names across all Varla contracts.
+ *
+ * Useful for logging/alerting configuration.
+ */
+export function getAllVarlaErrorNames(): string[] {
+  const map = ensureSelectorMap();
+  return [...new Set([...map.values()].map((e) => e.errorItem.name))];
+}
+
+/**
+ * Get all known error selectors mapped to their names.
+ */
+export function getVarlaErrorSelectors(): ReadonlyMap<Hex, { name: string; contract: string }> {
+  const map = ensureSelectorMap();
+  const result = new Map<Hex, { name: string; contract: string }>();
+  for (const [sel, entry] of map) {
+    result.set(sel as Hex, { name: entry.errorItem.name, contract: entry.label });
+  }
+  return result;
+}

package/src/events/decode.ts

@@ -0,0 +1,37 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+import type { AbiEvent, Log } from "viem";
+import { decodeEventLog } from "viem";
+
+export type DecodedEvent<TArgs = Record<string, unknown>> = {
+  args: TArgs;
+  eventName: string;
+  log: Log;
+};
+
+/**
+ * Decode logs for a single event definition. Returns only successfully decoded entries.
+ */
+export function decodeEventLogs(params: { event: AbiEvent; logs: Log[] }): DecodedEvent[] {
+  const out: DecodedEvent[] = [];
+
+  for (const log of params.logs) {
+    try {
+      const decoded = decodeEventLog({
+        abi: [params.event] as any,
+        data: log.data,
+        topics: log.topics as any,
+      }) as any;
+
+      out.push({
+        args: decoded.args as Record<string, unknown>,
+        eventName: decoded.eventName as string,
+        log,
+      });
+    } catch {
+      // ignore logs that don't decode cleanly (RPCs can return unrelated logs when address is omitted)
+    }
+  }
+
+  return out;
+}

package/src/events/defs.ts

@@ -0,0 +1,70 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+import type { AbiEvent } from "viem";
+import { getAbiItem } from "viem";
+
+import { abis } from "../generated.js";
+
+// ---------------------------------------------------------------------------
+// Oracle
+// ---------------------------------------------------------------------------
+
+export const ORACLE_EVENTS = {
+  PositionConfigured: getAbiItem({
+    abi: abis.VARLAORACLE_ABI,
+    name: "PositionConfigured",
+  }) as AbiEvent,
+  OppositePositionsConfigured: getAbiItem({
+    abi: abis.VARLAORACLE_ABI,
+    name: "OppositePositionsConfigured",
+  }) as AbiEvent,
+  NegRiskPositionConfigured: getAbiItem({
+    abi: abis.VARLAORACLE_ABI,
+    name: "NegRiskPositionConfigured",
+  }) as AbiEvent,
+  NegRiskPositionsBatchConfigured: getAbiItem({
+    abi: abis.VARLAORACLE_ABI,
+    name: "NegRiskPositionsBatchConfigured",
+  }) as AbiEvent,
+  PriceUpdated: getAbiItem({
+    abi: abis.VARLAORACLE_ABI,
+    name: "PriceUpdated",
+  }) as AbiEvent,
+  PositionInvalidated: getAbiItem({
+    abi: abis.VARLAORACLE_ABI,
+    name: "PositionInvalidated",
+  }) as AbiEvent,
+  PositionValidated: getAbiItem({
+    abi: abis.VARLAORACLE_ABI,
+    name: "PositionValidated",
+  }) as AbiEvent,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Core
+// ---------------------------------------------------------------------------
+
+export const CORE_EVENTS = {
+  Deposit: getAbiItem({ abi: abis.VARLACORE_ABI, name: "Deposit" }) as AbiEvent,
+  Withdraw: getAbiItem({ abi: abis.VARLACORE_ABI, name: "Withdraw" }) as AbiEvent,
+  Borrow: getAbiItem({ abi: abis.VARLACORE_ABI, name: "Borrow" }) as AbiEvent,
+  Repay: getAbiItem({ abi: abis.VARLACORE_ABI, name: "Repay" }) as AbiEvent,
+  Liquidate: getAbiItem({ abi: abis.VARLACORE_ABI, name: "Liquidate" }) as AbiEvent,
+  LiquidationDebtRepaid: getAbiItem({
+    abi: abis.VARLACORE_ABI,
+    name: "LiquidationDebtRepaid",
+  }) as AbiEvent,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Pool
+// ---------------------------------------------------------------------------
+
+export const POOL_EVENTS = {
+  Draw: getAbiItem({ abi: abis.VARLAPOOL_ABI, name: "Draw" }) as AbiEvent,
+  Repay: getAbiItem({ abi: abis.VARLAPOOL_ABI, name: "Repay" }) as AbiEvent,
+  AccrueInterest: getAbiItem({
+    abi: abis.VARLAPOOL_ABI,
+    name: "AccrueInterest",
+  }) as AbiEvent,
+} as const;

package/src/events/index.ts

@@ -0,0 +1,7 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+export * from "./decode.js";
+export * from "./defs.js";
+export * from "./logs.js";
+export * from "./oracleRegistrySync.js";
+export * from "./recent.js";

package/src/events/logs.ts

@@ -0,0 +1,42 @@
+// Note: explicit .js extension is required for Node ESM resolution.
+
+import type { AbiEvent, Address, Log, PublicClient } from "viem";
+
+export type GetEventLogsChunkedParams = {
+  client: PublicClient;
+  address?: Address | Address[];
+  event: AbiEvent;
+  // We keep args loosely typed here because viem's `getLogs` args typing is heavily generic
+  // and we want this helper to be ergonomic.
+  args?: Record<string, unknown> | readonly unknown[];
+  strict?: boolean;
+  fromBlock: bigint;
+  toBlock: bigint;
+  /** Max number of blocks per request. */
+  blockRange?: bigint;
+};
+
+/**
+ * Fetch logs in block-range chunks to avoid RPC limits/timeouts.
+ */
+export async function getEventLogsChunked(params: GetEventLogsChunkedParams): Promise<Log[]> {
+  const range = params.blockRange ?? 10_000n;
+  if (range <= 0n) throw new Error(`blockRange must be > 0 (got ${range})`);
+
+  const out: Log[] = [];
+  let start = params.fromBlock;
+  while (start <= params.toBlock) {
+    const end = start + range - 1n <= params.toBlock ? start + range - 1n : params.toBlock;
+    const logs = await params.client.getLogs({
+      address: params.address,
+      event: params.event as any,
+      args: params.args as any,
+      strict: params.strict as any,
+      fromBlock: start,
+      toBlock: end,
+    } as any);
+    out.push(...logs);
+    start = end + 1n;
+  }
+  return out;
+}