@chain-lens/sdk 0.1.0

package/src/budget.ts

@@ -0,0 +1,182 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { BudgetConfig } from "./types.js";
+
+const DEFAULTS: BudgetConfig = {
+  perCallMaxUsdc: 1,
+  dailyMaxUsdc: 50,
+  monthlyMaxUsdc: 500,
+};
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const MS_PER_MONTH = 30 * MS_PER_DAY;
+
+interface SpendRecord {
+  ts: number;
+  amount: number;
+  idempotencyKey?: string;
+}
+
+/**
+ * Off-chain rolling-window budget controller.
+ *
+ * Persists spend records to LevelDB under ~/.chainlens/budget/<wallet>/.
+ * Falls back to in-memory when LevelDB is unavailable (browser / ephemeral).
+ */
+export class BudgetController {
+  private readonly cfg: BudgetConfig;
+  private db: BudgetDB | null = null;
+  private readonly walletAddress: string;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(walletAddress: string, cfg: Partial<BudgetConfig> = {}) {
+    this.walletAddress = walletAddress;
+    this.cfg = { ...DEFAULTS, ...cfg };
+  }
+
+  private async getDb(): Promise<BudgetDB> {
+    if (this.db) return this.db;
+    if (!this.initPromise) {
+      this.initPromise = this.openDb();
+    }
+    await this.initPromise;
+    return this.db!;
+  }
+
+  private async openDb(): Promise<void> {
+    try {
+      const { Level } = await import("level");
+      const dbPath = join(
+        homedir(),
+        ".chainlens",
+        "budget",
+        sanitizeAddress(this.walletAddress),
+      );
+      const level = new Level<string, string>(dbPath, { valueEncoding: "json" });
+      await level.open();
+      this.db = new LevelDB(level);
+    } catch {
+      // LevelDB unavailable (browser/ephemeral) — use in-memory
+      process.stderr.write(
+        "chain-lens SDK: LevelDB unavailable, using in-memory budget storage.\n",
+      );
+      this.db = new InMemoryDB();
+    }
+  }
+
+  async canSpend(amount: number): Promise<{ ok: true } | { ok: false; reason: string }> {
+    if (amount > this.cfg.perCallMaxUsdc) {
+      return { ok: false, reason: `per-call cap: $${amount} > $${this.cfg.perCallMaxUsdc}` };
+    }
+
+    const db = await this.getDb();
+    const now = Date.now();
+    const records = await db.readAll();
+    const alive = records.filter((r) => now - r.ts < MS_PER_MONTH);
+
+    const dailySpend = alive
+      .filter((r) => now - r.ts < MS_PER_DAY)
+      .reduce((s, r) => s + r.amount, 0);
+
+    const monthlySpend = alive.reduce((s, r) => s + r.amount, 0);
+
+    if (dailySpend + amount > this.cfg.dailyMaxUsdc) {
+      return {
+        ok: false,
+        reason: `daily cap: $${(dailySpend + amount).toFixed(4)} > $${this.cfg.dailyMaxUsdc}`,
+      };
+    }
+    if (monthlySpend + amount > this.cfg.monthlyMaxUsdc) {
+      return {
+        ok: false,
+        reason: `monthly cap: $${(monthlySpend + amount).toFixed(4)} > $${this.cfg.monthlyMaxUsdc}`,
+      };
+    }
+    return { ok: true };
+  }
+
+  async debit(amount: number, idempotencyKey?: string): Promise<void> {
+    const db = await this.getDb();
+    if (idempotencyKey) {
+      const existing = await db.readAll();
+      if (existing.some((r) => r.idempotencyKey === idempotencyKey)) return;
+    }
+    await db.append({ ts: Date.now(), amount, idempotencyKey });
+    // Evict records older than 30 days
+    await db.evictBefore(Date.now() - MS_PER_MONTH);
+  }
+
+  async currentSpend(): Promise<{ dailyUsdc: number; monthlyUsdc: number }> {
+    const db = await this.getDb();
+    const now = Date.now();
+    const records = await db.readAll();
+    const dailyUsdc = records
+      .filter((r) => now - r.ts < MS_PER_DAY)
+      .reduce((s, r) => s + r.amount, 0);
+    const monthlyUsdc = records
+      .filter((r) => now - r.ts < MS_PER_MONTH)
+      .reduce((s, r) => s + r.amount, 0);
+    return { dailyUsdc, monthlyUsdc };
+  }
+}
+
+// ─── storage backends ─────────────────────────────────────────────────
+
+interface BudgetDB {
+  readAll(): Promise<SpendRecord[]>;
+  append(record: SpendRecord): Promise<void>;
+  evictBefore(ts: number): Promise<void>;
+}
+
+class InMemoryDB implements BudgetDB {
+  private records: SpendRecord[] = [];
+
+  async readAll() { return [...this.records]; }
+
+  async append(record: SpendRecord) { this.records.push(record); }
+
+  async evictBefore(ts: number) {
+    this.records = this.records.filter((r) => r.ts >= ts);
+  }
+}
+
+class LevelDB implements BudgetDB {
+  constructor(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private readonly level: any,
+  ) {}
+
+  async readAll(): Promise<SpendRecord[]> {
+    const records: SpendRecord[] = [];
+    for await (const value of this.level.values()) {
+      try {
+        records.push(JSON.parse(value) as SpendRecord);
+      } catch {
+        // skip corrupt entries
+      }
+    }
+    return records;
+  }
+
+  async append(record: SpendRecord): Promise<void> {
+    const key = `${record.ts}-${Math.random().toString(36).slice(2)}`;
+    await this.level.put(key, JSON.stringify(record));
+  }
+
+  async evictBefore(ts: number): Promise<void> {
+    const batch = this.level.batch();
+    for await (const [key, value] of this.level.iterator()) {
+      try {
+        const record = JSON.parse(value) as SpendRecord;
+        if (record.ts < ts) batch.del(key);
+      } catch {
+        batch.del(key);
+      }
+    }
+    await batch.write();
+  }
+}
+
+function sanitizeAddress(addr: string): string {
+  return addr.toLowerCase().replace(/[^a-f0-9x]/g, "").slice(0, 42);
+}

package/src/call.ts

@@ -0,0 +1,164 @@
+import {
+  usdcToAtomic,
+  atomicToUsdc,
+  signReceiveWithAuthorization,
+  CHAIN_LENS_MARKET_ADDRESSES,
+} from "./eip3009.js";
+import type { ChainLensConfig, CallOptions, CallResult, ListingInfo } from "./types.js";
+import type { BudgetController } from "./budget.js";
+import type { TelemetryRecorder } from "./telemetry.js";
+import { hashParams } from "./telemetry.js";
+import {
+  ChainLensResolveError,
+  BudgetExceededError,
+  ChainLensSignError,
+  ChainLensGatewayError,
+  ChainLensCallError,
+} from "./errors.js";
+
+export async function fetchListingInfo(
+  gatewayUrl: string,
+  listingId: number,
+): Promise<ListingInfo> {
+  const res = await fetch(`${gatewayUrl}/v1/listings/${listingId}`);
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new ChainLensResolveError(
+      `Failed to fetch listing ${listingId}: ${res.status} ${body}`,
+    );
+  }
+  return res.json() as Promise<ListingInfo>;
+}
+
+export async function executeCall(
+  cfg: ChainLensConfig & { gatewayUrl: string },
+  budget: BudgetController,
+  telemetry: TelemetryRecorder,
+  listingId: number,
+  params: unknown,
+  options: CallOptions = {},
+): Promise<CallResult> {
+  const t0 = Date.now();
+
+  // Step 1+2: Resolve listing and fetch pricing
+  let listing: ListingInfo;
+  try {
+    listing = await fetchListingInfo(cfg.gatewayUrl, listingId);
+  } catch (err) {
+    throw err instanceof ChainLensResolveError
+      ? err
+      : new ChainLensResolveError(String(err));
+  }
+
+  const priceUsdc = listing.priceAtomic ? atomicToUsdc(listing.priceAtomic) : 0;
+  const effectiveMaxUsdc = options.maxUsdc ?? priceUsdc;
+
+  // Step 3+4: Budget checks — must happen before signing
+  const budgetCheck = await budget.canSpend(effectiveMaxUsdc);
+  if (!budgetCheck.ok) {
+    throw new BudgetExceededError(budgetCheck.reason);
+  }
+
+  // Step 5: Sign EIP-3009 authorization
+  const marketAddress = CHAIN_LENS_MARKET_ADDRESSES[cfg.chainId];
+  if (!marketAddress) throw new ChainLensResolveError(`No market address for chainId=${cfg.chainId}`);
+  const amountAtomic = usdcToAtomic(effectiveMaxUsdc);
+
+  let auth: Awaited<ReturnType<typeof signReceiveWithAuthorization>>;
+  try {
+    auth = await signReceiveWithAuthorization({
+      wallet: cfg.wallet,
+      chainId: cfg.chainId,
+      amount: amountAtomic,
+      to: marketAddress,
+      signal: options.signal,
+    });
+  } catch (err) {
+    throw new ChainLensSignError(String(err), err);
+  }
+
+  // Step 6: POST /v1/call
+  let res: Response;
+  try {
+    res = await fetch(`${cfg.gatewayUrl}/v1/call`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      signal: options.signal,
+      body: JSON.stringify({
+        listingId,
+        params,
+        auth: {
+          from: auth.from,
+          to: auth.to,
+          amount: auth.amount,
+          validAfter: auth.validAfter,
+          validBefore: auth.validBefore,
+          nonce: auth.nonce,
+          v: auth.v,
+          r: auth.r,
+          s: auth.s,
+        },
+      }),
+    });
+  } catch (err) {
+    const latencyMs = Date.now() - t0;
+    await telemetry.record({
+      ts: t0,
+      listingId,
+      amountUsdc: effectiveMaxUsdc,
+      latencyMs,
+      ok: false,
+      failure: { kind: "unknown", hint: String(err) },
+      paramsHash: hashParams(params),
+    });
+    throw new ChainLensGatewayError(`Network error: ${String(err)}`, 0, err);
+  }
+
+  const latencyMs = Date.now() - t0;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const body = (await res.json().catch(() => null)) as any;
+
+  // Step 8: On failure, record telemetry and throw typed error
+  if (!res.ok || !body?.ok) {
+    const failure = body?.failure ?? { kind: "unknown", hint: `HTTP ${res.status}` };
+    await telemetry.record({
+      ts: t0,
+      listingId,
+      amountUsdc: effectiveMaxUsdc,
+      latencyMs,
+      ok: false,
+      failure,
+      paramsHash: hashParams(params),
+    });
+    throw new ChainLensCallError(failure);
+  }
+
+  // Step 7: On success, debit budget and record telemetry
+  const amountUsdc = body.amount ? atomicToUsdc(body.amount) : effectiveMaxUsdc;
+  const feeUsdc = body.fee ? atomicToUsdc(body.fee) : 0;
+  const netUsdc = body.net ? atomicToUsdc(body.net) : amountUsdc - feeUsdc;
+
+  await budget.debit(amountUsdc, options.idempotencyKey);
+
+  await telemetry.record({
+    ts: t0,
+    listingId,
+    amountUsdc,
+    latencyMs,
+    ok: true,
+    txHash: body.settlement?.txHash,
+    paramsHash: hashParams(params),
+  });
+
+  return {
+    ok: true,
+    data: body.response,
+    listingId,
+    amountUsdc,
+    feeUsdc,
+    netUsdc,
+    settlement: body.settlement,
+    latencyMs,
+    attemptIndex: 0,
+  };
+}

package/src/client.ts

@@ -0,0 +1,90 @@
+import type { ChainLensConfig, CallOptions, CallResult, RankedListing } from "./types.js";
+import { BudgetController } from "./budget.js";
+import { TelemetryRecorder } from "./telemetry.js";
+import { executeCall } from "./call.js";
+import { fetchRecommendations } from "./recommend.js";
+import { ProviderClient } from "./provider.js";
+import { ChainLensCallError } from "./errors.js";
+import type { FailureMetadata } from "./types.js";
+
+const DEFAULT_GATEWAY = "https://chainlens.pelicanlab.dev";
+
+const RETRYABLE_KINDS: ReadonlySet<FailureMetadata["kind"]> = new Set([
+  "http_5xx",
+  "timeout",
+  "schema_mismatch",
+]);
+
+export class ChainLens {
+  private readonly cfg: ChainLensConfig & { gatewayUrl: string };
+  private budget: BudgetController | null = null;
+  private telemetry: TelemetryRecorder | null = null;
+  private walletAddress: string | null = null;
+  readonly provider: ProviderClient;
+
+  constructor(cfg: ChainLensConfig) {
+    this.cfg = { gatewayUrl: DEFAULT_GATEWAY, ...cfg };
+    this.provider = new ProviderClient(this.cfg.gatewayUrl, cfg.wallet);
+  }
+
+  private async init(): Promise<{ budget: BudgetController; telemetry: TelemetryRecorder }> {
+    if (!this.walletAddress) {
+      this.walletAddress = await this.cfg.wallet.address();
+    }
+    if (!this.budget) {
+      this.budget = new BudgetController(this.walletAddress, this.cfg.budget);
+    }
+    if (!this.telemetry) {
+      this.telemetry = new TelemetryRecorder({
+        enabled: this.cfg.telemetry?.enabled ?? true,
+        upload: this.cfg.telemetry?.upload ?? false,
+        bufferMaxEntries: this.cfg.telemetry?.bufferMaxEntries ?? 1000,
+        gatewayUrl: this.cfg.gatewayUrl,
+        walletAddress: this.walletAddress,
+      });
+    }
+    return { budget: this.budget, telemetry: this.telemetry };
+  }
+
+  async call<T = unknown>(
+    listingId: number,
+    params: unknown,
+    options: CallOptions = {},
+  ): Promise<CallResult<T>> {
+    const { budget, telemetry } = await this.init();
+
+    const maxAttempts =
+      options.fallback !== false && this.cfg.fallback?.enabled
+        ? (this.cfg.fallback.maxAttempts ?? 2)
+        : 1;
+
+    let lastErr: unknown;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        const result = await executeCall(this.cfg, budget, telemetry, listingId, params, options);
+        return { ...result, attemptIndex: attempt } as CallResult<T>;
+      } catch (err) {
+        lastErr = err;
+        if (
+          attempt < maxAttempts - 1 &&
+          err instanceof ChainLensCallError &&
+          RETRYABLE_KINDS.has(err.failure.kind)
+        ) {
+          continue;
+        }
+        break;
+      }
+    }
+
+    throw lastErr;
+  }
+
+  async recommend(task: string, maxResults = 5): Promise<RankedListing[]> {
+    return fetchRecommendations(this.cfg.gatewayUrl, task, maxResults);
+  }
+
+  async currentSpend(): Promise<{ dailyUsdc: number; monthlyUsdc: number }> {
+    const { budget } = await this.init();
+    return budget.currentSpend();
+  }
+}

package/src/eip3009.ts

@@ -0,0 +1,99 @@
+import { randomBytes } from "node:crypto";
+import type { WalletAdapter, TypedData } from "./types.js";
+
+/** Chain-specific USDC contract addresses. */
+export const USDC_ADDRESSES: Record<number, `0x${string}`> = {
+  84532: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // Base Sepolia
+  8453: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // Base Mainnet
+};
+
+/** ChainLensMarket addresses per chain. */
+export const CHAIN_LENS_MARKET_ADDRESSES: Record<number, `0x${string}`> = {
+  84532: "0x45bB56fDB0E6bb14d178E417b67Ed7B3323ffFf7", // Base Sepolia
+  8453: "0x0000000000000000000000000000000000000000",  // placeholder — not deployed yet
+};
+
+export const RECEIVE_WITH_AUTHORIZATION_TYPES = {
+  ReceiveWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ],
+} as const;
+
+export interface Eip3009Auth {
+  from: `0x${string}`;
+  to: `0x${string}`;
+  amount: string;
+  validAfter: string;
+  validBefore: string;
+  nonce: `0x${string}`;
+  v: number;
+  r: `0x${string}`;
+  s: `0x${string}`;
+}
+
+export async function signReceiveWithAuthorization(opts: {
+  wallet: WalletAdapter;
+  chainId: number;
+  amount: bigint;
+  to: `0x${string}`;
+  signal?: AbortSignal;
+}): Promise<Eip3009Auth> {
+  const { wallet, chainId, amount, to } = opts;
+
+  const usdcAddress = USDC_ADDRESSES[chainId];
+  if (!usdcAddress) throw new Error(`No USDC address for chainId=${chainId}`);
+
+  const from = await wallet.address();
+  const now = Math.floor(Date.now() / 1000);
+  const validAfter = BigInt(now - 60);
+  const validBefore = BigInt(now + 300);
+  const nonce = ("0x" + randomBytes(32).toString("hex")) as `0x${string}`;
+
+  const typedData: TypedData = {
+    domain: {
+      name: "USD Coin",
+      version: "2",
+      chainId,
+      verifyingContract: usdcAddress,
+    },
+    types: RECEIVE_WITH_AUTHORIZATION_TYPES as unknown as Record<string, Array<{ name: string; type: string }>>,
+    primaryType: "ReceiveWithAuthorization",
+    message: {
+      from,
+      to,
+      value: amount,
+      validAfter,
+      validBefore,
+      nonce,
+    },
+  };
+
+  const sig = await wallet.signTypedData(typedData);
+
+  return {
+    from,
+    to,
+    amount: amount.toString(),
+    validAfter: validAfter.toString(),
+    validBefore: validBefore.toString(),
+    nonce,
+    v: sig.v,
+    r: sig.r,
+    s: sig.s,
+  };
+}
+
+/** Convert USDC display units (e.g. 0.05) to atomic units (50000). */
+export function usdcToAtomic(usdc: number): bigint {
+  return BigInt(Math.round(usdc * 1_000_000));
+}
+
+/** Convert atomic USDC units to display units. */
+export function atomicToUsdc(atomic: bigint | string): number {
+  return Number(BigInt(atomic)) / 1_000_000;
+}

package/src/errors.ts

@@ -0,0 +1,62 @@
+import type { FailureMetadata } from "./types.js";
+
+export class ChainLensError extends Error {
+  readonly code: string;
+  readonly cause?: unknown;
+
+  constructor(message: string, code: string, cause?: unknown) {
+    super(message);
+    this.name = "ChainLensError";
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+/** Listing not found or task query produced no match. */
+export class ChainLensResolveError extends ChainLensError {
+  constructor(message: string, cause?: unknown) {
+    super(message, "RESOLVE", cause);
+    this.name = "ChainLensResolveError";
+  }
+}
+
+/** Off-chain budget limit exceeded before any signature was produced. */
+export class BudgetExceededError extends ChainLensError {
+  readonly reason: string;
+
+  constructor(reason: string) {
+    super(`Budget exceeded: ${reason}`, "BUDGET");
+    this.name = "BudgetExceededError";
+    this.reason = reason;
+  }
+}
+
+/** EIP-3009 signing failed. */
+export class ChainLensSignError extends ChainLensError {
+  constructor(message: string, cause?: unknown) {
+    super(message, "SIGN", cause);
+    this.name = "ChainLensSignError";
+  }
+}
+
+/** Gateway returned a non-200 HTTP status. */
+export class ChainLensGatewayError extends ChainLensError {
+  readonly status: number;
+
+  constructor(message: string, status: number, cause?: unknown) {
+    super(message, "GATEWAY", cause);
+    this.name = "ChainLensGatewayError";
+    this.status = status;
+  }
+}
+
+/** The call completed but the provider reported failure (no settlement). */
+export class ChainLensCallError extends ChainLensError {
+  readonly failure: FailureMetadata;
+
+  constructor(failure: FailureMetadata) {
+    super(`Call failed: ${failure.kind} — ${failure.hint}`, "CALL");
+    this.name = "ChainLensCallError";
+    this.failure = failure;
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export { ChainLens } from "./client.js";
+export { ViemWallet } from "./wallet/viem.js";
+export { BudgetController } from "./budget.js";
+export { ProviderClient } from "./provider.js";
+export {
+  ChainLensError,
+  ChainLensResolveError,
+  BudgetExceededError,
+  ChainLensSignError,
+  ChainLensGatewayError,
+  ChainLensCallError,
+} from "./errors.js";
+export {
+  signReceiveWithAuthorization,
+  usdcToAtomic,
+  atomicToUsdc,
+  USDC_ADDRESSES,
+  CHAIN_LENS_MARKET_ADDRESSES,
+} from "./eip3009.js";
+export type {
+  ChainLensConfig,
+  WalletAdapter,
+  TypedData,
+  TxRequest,
+  CallOptions,
+  CallResult,
+  RankedListing,
+  FailureMetadata,
+  ListingInfo,
+  BudgetConfig,
+} from "./types.js";
+export type { TelemetryEntry, TelemetryConfig } from "./telemetry.js";
+export type { ClaimableResult, ListingDashboard } from "./provider.js";

package/src/provider.ts

@@ -0,0 +1,75 @@
+import type { WalletAdapter } from "./types.js";
+import { ChainLensResolveError, ChainLensGatewayError } from "./errors.js";
+
+export interface ClaimableResult {
+  totalUsdc: number;
+  atomicBalance: string;
+}
+
+export interface ListingDashboard {
+  listingId: number;
+  name: string | null;
+  totalEarnedUsdc: number;
+  claimableUsdc: number;
+  callCount: number;
+  successRate: number;
+  p50LatencyMs: number;
+}
+
+export class ProviderClient {
+  constructor(
+    private readonly gatewayUrl: string,
+    private readonly wallet: WalletAdapter,
+  ) {}
+
+  async claimable(): Promise<ClaimableResult> {
+    const address = await this.wallet.address();
+    const res = await fetch(
+      `${this.gatewayUrl}/v1/provider/claimable?address=${address}`,
+    );
+    if (!res.ok) {
+      throw new ChainLensGatewayError(
+        `claimable fetch failed: ${res.status}`,
+        res.status,
+      );
+    }
+    return res.json() as Promise<ClaimableResult>;
+  }
+
+  async claim(): Promise<{ txHash: `0x${string}` } | { skipped: true }> {
+    const claimable = await this.claimable();
+    if (BigInt(claimable.atomicBalance) === 0n) {
+      return { skipped: true };
+    }
+    const address = await this.wallet.address();
+    const res = await fetch(`${this.gatewayUrl}/v1/provider/claim`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ address }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new ChainLensGatewayError(`claim failed: ${res.status} ${body}`, res.status);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const data = (await res.json()) as any;
+    return { txHash: data.txHash as `0x${string}` };
+  }
+
+  async listingDashboard(listingId: number): Promise<ListingDashboard> {
+    const address = await this.wallet.address();
+    const res = await fetch(
+      `${this.gatewayUrl}/v1/provider/listing/${listingId}?address=${address}`,
+    );
+    if (!res.ok) {
+      if (res.status === 403) {
+        throw new ChainLensResolveError(`Not authorized to view listing ${listingId}`);
+      }
+      throw new ChainLensGatewayError(
+        `dashboard fetch failed: ${res.status}`,
+        res.status,
+      );
+    }
+    return res.json() as Promise<ListingDashboard>;
+  }
+}