@chain-lens/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,609 @@
+// src/budget.ts
+import { homedir } from "os";
+import { join } from "path";
+var DEFAULTS = {
+  perCallMaxUsdc: 1,
+  dailyMaxUsdc: 50,
+  monthlyMaxUsdc: 500
+};
+var MS_PER_DAY = 24 * 60 * 60 * 1e3;
+var MS_PER_MONTH = 30 * MS_PER_DAY;
+var BudgetController = class {
+  cfg;
+  db = null;
+  walletAddress;
+  initPromise = null;
+  constructor(walletAddress, cfg = {}) {
+    this.walletAddress = walletAddress;
+    this.cfg = { ...DEFAULTS, ...cfg };
+  }
+  async getDb() {
+    if (this.db) return this.db;
+    if (!this.initPromise) {
+      this.initPromise = this.openDb();
+    }
+    await this.initPromise;
+    return this.db;
+  }
+  async openDb() {
+    try {
+      const { Level } = await import("level");
+      const dbPath = join(
+        homedir(),
+        ".chainlens",
+        "budget",
+        sanitizeAddress(this.walletAddress)
+      );
+      const level = new Level(dbPath, { valueEncoding: "json" });
+      await level.open();
+      this.db = new LevelDB(level);
+    } catch {
+      process.stderr.write(
+        "chain-lens SDK: LevelDB unavailable, using in-memory budget storage.\n"
+      );
+      this.db = new InMemoryDB();
+    }
+  }
+  async canSpend(amount) {
+    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, idempotencyKey) {
+    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 });
+    await db.evictBefore(Date.now() - MS_PER_MONTH);
+  }
+  async currentSpend() {
+    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 };
+  }
+};
+var InMemoryDB = class {
+  records = [];
+  async readAll() {
+    return [...this.records];
+  }
+  async append(record) {
+    this.records.push(record);
+  }
+  async evictBefore(ts) {
+    this.records = this.records.filter((r) => r.ts >= ts);
+  }
+};
+var LevelDB = class {
+  constructor(level) {
+    this.level = level;
+  }
+  level;
+  async readAll() {
+    const records = [];
+    for await (const value of this.level.values()) {
+      try {
+        records.push(JSON.parse(value));
+      } catch {
+      }
+    }
+    return records;
+  }
+  async append(record) {
+    const key = `${record.ts}-${Math.random().toString(36).slice(2)}`;
+    await this.level.put(key, JSON.stringify(record));
+  }
+  async evictBefore(ts) {
+    const batch = this.level.batch();
+    for await (const [key, value] of this.level.iterator()) {
+      try {
+        const record = JSON.parse(value);
+        if (record.ts < ts) batch.del(key);
+      } catch {
+        batch.del(key);
+      }
+    }
+    await batch.write();
+  }
+};
+function sanitizeAddress(addr) {
+  return addr.toLowerCase().replace(/[^a-f0-9x]/g, "").slice(0, 42);
+}
+
+// src/telemetry.ts
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { createHash } from "crypto";
+import { appendFile, mkdir } from "fs/promises";
+var TelemetryRecorder = class {
+  cfg;
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  async record(entry) {
+    if (!this.cfg.enabled) return;
+    const line = JSON.stringify(entry) + "\n";
+    const dir = join2(homedir2(), ".chainlens", "telemetry");
+    const filePath = join2(dir, `${sanitizeAddress2(this.cfg.walletAddress)}.jsonl`);
+    try {
+      await mkdir(dir, { recursive: true });
+      await appendFile(filePath, line, "utf8");
+    } catch {
+    }
+    if (this.cfg.upload) {
+      void this.uploadAsync(entry);
+    }
+  }
+  async uploadAsync(entry) {
+    try {
+      await fetch(`${this.cfg.gatewayUrl}/v1/telemetry/batch`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ events: [entry] })
+      });
+    } catch {
+    }
+  }
+};
+function hashParams(params) {
+  const json = params != null ? JSON.stringify(params) : "";
+  return createHash("sha256").update(json, "utf8").digest("hex").slice(0, 16);
+}
+function sanitizeAddress2(addr) {
+  return addr.toLowerCase().replace(/[^a-f0-9x]/g, "").slice(0, 42);
+}
+
+// src/eip3009.ts
+import { randomBytes } from "crypto";
+var USDC_ADDRESSES = {
+  84532: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+  // Base Sepolia
+  8453: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+  // Base Mainnet
+};
+var CHAIN_LENS_MARKET_ADDRESSES = {
+  84532: "0x45bB56fDB0E6bb14d178E417b67Ed7B3323ffFf7",
+  // Base Sepolia
+  8453: "0x0000000000000000000000000000000000000000"
+  // placeholder — not deployed yet
+};
+var 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" }
+  ]
+};
+async function signReceiveWithAuthorization(opts) {
+  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() / 1e3);
+  const validAfter = BigInt(now - 60);
+  const validBefore = BigInt(now + 300);
+  const nonce = "0x" + randomBytes(32).toString("hex");
+  const typedData = {
+    domain: {
+      name: "USD Coin",
+      version: "2",
+      chainId,
+      verifyingContract: usdcAddress
+    },
+    types: RECEIVE_WITH_AUTHORIZATION_TYPES,
+    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
+  };
+}
+function usdcToAtomic(usdc) {
+  return BigInt(Math.round(usdc * 1e6));
+}
+function atomicToUsdc(atomic) {
+  return Number(BigInt(atomic)) / 1e6;
+}
+
+// src/errors.ts
+var ChainLensError = class extends Error {
+  code;
+  cause;
+  constructor(message, code, cause) {
+    super(message);
+    this.name = "ChainLensError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+var ChainLensResolveError = class extends ChainLensError {
+  constructor(message, cause) {
+    super(message, "RESOLVE", cause);
+    this.name = "ChainLensResolveError";
+  }
+};
+var BudgetExceededError = class extends ChainLensError {
+  reason;
+  constructor(reason) {
+    super(`Budget exceeded: ${reason}`, "BUDGET");
+    this.name = "BudgetExceededError";
+    this.reason = reason;
+  }
+};
+var ChainLensSignError = class extends ChainLensError {
+  constructor(message, cause) {
+    super(message, "SIGN", cause);
+    this.name = "ChainLensSignError";
+  }
+};
+var ChainLensGatewayError = class extends ChainLensError {
+  status;
+  constructor(message, status, cause) {
+    super(message, "GATEWAY", cause);
+    this.name = "ChainLensGatewayError";
+    this.status = status;
+  }
+};
+var ChainLensCallError = class extends ChainLensError {
+  failure;
+  constructor(failure) {
+    super(`Call failed: ${failure.kind} \u2014 ${failure.hint}`, "CALL");
+    this.name = "ChainLensCallError";
+    this.failure = failure;
+  }
+};
+
+// src/call.ts
+async function fetchListingInfo(gatewayUrl, listingId) {
+  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();
+}
+async function executeCall(cfg, budget, telemetry, listingId, params, options = {}) {
+  const t0 = Date.now();
+  let listing;
+  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;
+  const budgetCheck = await budget.canSpend(effectiveMaxUsdc);
+  if (!budgetCheck.ok) {
+    throw new BudgetExceededError(budgetCheck.reason);
+  }
+  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;
+  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);
+  }
+  let res;
+  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 latencyMs2 = Date.now() - t0;
+    await telemetry.record({
+      ts: t0,
+      listingId,
+      amountUsdc: effectiveMaxUsdc,
+      latencyMs: latencyMs2,
+      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;
+  const body = await res.json().catch(() => null);
+  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);
+  }
+  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
+  };
+}
+
+// src/recommend.ts
+async function fetchRecommendations(gatewayUrl, task, maxResults = 5) {
+  const res = await fetch(`${gatewayUrl}/v1/recommend`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ task, maxResults })
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new ChainLensResolveError(`recommend failed: ${res.status} ${body}`);
+  }
+  const data = await res.json();
+  return data.listings ?? [];
+}
+
+// src/provider.ts
+var ProviderClient = class {
+  constructor(gatewayUrl, wallet) {
+    this.gatewayUrl = gatewayUrl;
+    this.wallet = wallet;
+  }
+  gatewayUrl;
+  wallet;
+  async claimable() {
+    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();
+  }
+  async claim() {
+    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);
+    }
+    const data = await res.json();
+    return { txHash: data.txHash };
+  }
+  async listingDashboard(listingId) {
+    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();
+  }
+};
+
+// src/client.ts
+var DEFAULT_GATEWAY = "https://chainlens.pelicanlab.dev";
+var RETRYABLE_KINDS = /* @__PURE__ */ new Set([
+  "http_5xx",
+  "timeout",
+  "schema_mismatch"
+]);
+var ChainLens = class {
+  cfg;
+  budget = null;
+  telemetry = null;
+  walletAddress = null;
+  provider;
+  constructor(cfg) {
+    this.cfg = { gatewayUrl: DEFAULT_GATEWAY, ...cfg };
+    this.provider = new ProviderClient(this.cfg.gatewayUrl, cfg.wallet);
+  }
+  async init() {
+    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 ?? 1e3,
+        gatewayUrl: this.cfg.gatewayUrl,
+        walletAddress: this.walletAddress
+      });
+    }
+    return { budget: this.budget, telemetry: this.telemetry };
+  }
+  async call(listingId, params, options = {}) {
+    const { budget, telemetry } = await this.init();
+    const maxAttempts = options.fallback !== false && this.cfg.fallback?.enabled ? this.cfg.fallback.maxAttempts ?? 2 : 1;
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        const result = await executeCall(this.cfg, budget, telemetry, listingId, params, options);
+        return { ...result, attemptIndex: attempt };
+      } catch (err) {
+        lastErr = err;
+        if (attempt < maxAttempts - 1 && err instanceof ChainLensCallError && RETRYABLE_KINDS.has(err.failure.kind)) {
+          continue;
+        }
+        break;
+      }
+    }
+    throw lastErr;
+  }
+  async recommend(task, maxResults = 5) {
+    return fetchRecommendations(this.cfg.gatewayUrl, task, maxResults);
+  }
+  async currentSpend() {
+    const { budget } = await this.init();
+    return budget.currentSpend();
+  }
+};
+
+// src/wallet/viem.ts
+import { hexToNumber, numberToHex, parseSignature } from "viem";
+var ViemWallet = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async address() {
+    const accounts = await this.client.getAddresses();
+    const addr = accounts[0];
+    if (!addr) throw new Error("ViemWallet: no accounts available");
+    return addr;
+  }
+  async signTypedData(typedData) {
+    const { domain, types, primaryType, message } = typedData;
+    const sig = await this.client.signTypedData({
+      domain: {
+        name: domain.name,
+        version: domain.version,
+        chainId: domain.chainId,
+        verifyingContract: domain.verifyingContract
+      },
+      types,
+      primaryType,
+      message
+    });
+    const parsed = parseSignature(sig);
+    return {
+      v: hexToNumber(numberToHex(parsed.v ?? 27n)),
+      r: parsed.r,
+      s: parsed.s
+    };
+  }
+  async sendTransaction(tx) {
+    const from = await this.address();
+    return this.client.sendTransaction({
+      account: from,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value,
+      chain: this.client.chain ?? null
+    });
+  }
+};
+export {
+  BudgetController,
+  BudgetExceededError,
+  CHAIN_LENS_MARKET_ADDRESSES,
+  ChainLens,
+  ChainLensCallError,
+  ChainLensError,
+  ChainLensGatewayError,
+  ChainLensResolveError,
+  ChainLensSignError,
+  ProviderClient,
+  USDC_ADDRESSES,
+  ViemWallet,
+  atomicToUsdc,
+  signReceiveWithAuthorization,
+  usdcToAtomic
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@chain-lens/sdk",
+  "version": "0.1.0",
+  "description": "ChainLens SDK — pay-and-call AI data APIs on Base with EIP-3009 instant settlement.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "cross-fetch": "^4.0.0",
+    "level": "^8.0.1"
+  },
+  "peerDependencies": {
+    "viem": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "viem": "^2.21.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}