@vauban-org/agent-sdk 0.16.0

package/src/dataops/voyager.ts

@@ -0,0 +1,215 @@
+/**
+ * VoyagerDataOps — thin wrapper over Starknet JSON-RPC (free tier).
+ *
+ * Uses the Nethermind free RPC endpoint (no API key required).
+ * Rate-limited via configurable inter-call delay.
+ * No indexed REST API — pure JSON-RPC v0.7.
+ */
+
+import { z } from "zod";
+
+const DEFAULT_RPC_URL = "https://free-rpc.nethermind.io/mainnet-juno/";
+const DEFAULT_RATE_LIMIT_MS = 100;
+const DEFAULT_CHUNK_SIZE = 1000;
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+export interface VoyagerConfig {
+  /** Starknet JSON-RPC endpoint URL. Defaults to Nethermind free tier. */
+  rpcUrl?: string;
+  /** Minimum ms between consecutive RPC calls. Default: 100ms. */
+  rateLimitMs?: number;
+  /** Max events per getEvents call. Default: 1000. */
+  chunkSize?: number;
+}
+
+// ─── Domain types ─────────────────────────────────────────────────────────────
+
+export interface WalletEvent {
+  walletAddress: string;
+  txHash: string;
+  blockNumber: number;
+  eventData: string[];
+}
+
+export interface HealthCheckResult {
+  blockNumber: number;
+  latencyMs: number;
+}
+
+// ─── Zod schemas (strict boundary validation) ────────────────────────────────
+
+const RpcResponseSchema = z.object({
+  jsonrpc: z.literal("2.0"),
+  id: z.number(),
+  result: z.unknown().optional(),
+  error: z
+    .object({ code: z.number(), message: z.string() })
+    .optional(),
+});
+
+const EventSchema = z.object({
+  transaction_hash: z.string(),
+  block_number: z.number(),
+  keys: z.array(z.string()),
+  data: z.array(z.string()),
+});
+
+const GetEventsResultSchema = z.object({
+  events: z.array(EventSchema),
+  continuation_token: z.string().optional(),
+});
+
+// ─── VoyagerDataOps ──────────────────────────────────────────────────────────
+
+export class VoyagerDataOps {
+  private readonly rpcUrl: string;
+  private readonly rateLimitMs: number;
+  private readonly chunkSize: number;
+  private lastCallAt = 0;
+  private requestId = 0;
+
+  constructor(config: VoyagerConfig = {}) {
+    this.rpcUrl = config.rpcUrl ?? DEFAULT_RPC_URL;
+    this.rateLimitMs = config.rateLimitMs ?? DEFAULT_RATE_LIMIT_MS;
+    this.chunkSize = config.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  }
+
+  /**
+   * Extract unique wallet addresses that interacted with a protocol contract.
+   * Uses starknet_getEvents; the first element of event.data is the caller.
+   *
+   * @param contractAddress - Protocol contract (e.g. zkLend main contract)
+   * @param eventSelector   - Event key selector (hex string, e.g. Deposit event)
+   * @param limit           - Max wallets to return. Default: 100.
+   */
+  async getProtocolWallets(
+    contractAddress: string,
+    eventSelector: string,
+    limit = 100
+  ): Promise<string[]> {
+    const wallets = new Set<string>();
+    let continuationToken: string | undefined;
+
+    while (wallets.size < limit) {
+      const result = await this.getEvents({
+        address: contractAddress,
+        keys: [[eventSelector]],
+        chunk_size: Math.min(this.chunkSize, limit * 2),
+        continuation_token: continuationToken,
+      });
+
+      for (const event of result.events) {
+        const caller = event.data[0];
+        if (caller) wallets.add(caller);
+        if (wallets.size >= limit) break;
+      }
+
+      continuationToken = result.continuation_token;
+      if (!continuationToken) break;
+    }
+
+    return Array.from(wallets).slice(0, limit);
+  }
+
+  /**
+   * Get events emitted by a specific wallet address for a given contract.
+   */
+  async getWalletEvents(
+    walletAddress: string,
+    contractAddress: string,
+    eventSelector: string
+  ): Promise<WalletEvent[]> {
+    const result = await this.getEvents({
+      address: contractAddress,
+      keys: [[eventSelector]],
+      chunk_size: this.chunkSize,
+    });
+
+    return result.events
+      .filter((e) => e.data[0] === walletAddress)
+      .map((e) => ({
+        walletAddress,
+        txHash: e.transaction_hash,
+        blockNumber: e.block_number,
+        eventData: e.data,
+      }));
+  }
+
+  /**
+   * Verify RPC connectivity and return current block number + latency.
+   */
+  async healthCheck(): Promise<HealthCheckResult> {
+    const t0 = Date.now();
+    const res = await this.rpcCall<number>("starknet_blockNumber", []);
+    return { blockNumber: res, latencyMs: Date.now() - t0 };
+  }
+
+  // ─── Private helpers ───────────────────────────────────────────────────────
+
+  private async getEvents(params: {
+    address: string;
+    keys: string[][];
+    chunk_size: number;
+    continuation_token?: string;
+  }): Promise<z.infer<typeof GetEventsResultSchema>> {
+    const raw = await this.rpcCall<unknown>("starknet_getEvents", [params]);
+    return GetEventsResultSchema.parse(raw);
+  }
+
+  private async rpcCall<T>(method: string, params: unknown[]): Promise<T> {
+    await this.throttle();
+
+    const id = ++this.requestId;
+    const body = JSON.stringify({ jsonrpc: "2.0", method, params, id });
+
+    const response = await fetch(this.rpcUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+    });
+
+    if (!response.ok) {
+      throw new VoyagerRpcError(
+        `HTTP ${response.status} from ${this.rpcUrl}`,
+        response.status
+      );
+    }
+
+    const raw: unknown = await response.json();
+    const parsed = RpcResponseSchema.parse(raw);
+
+    if (parsed.error) {
+      throw new VoyagerRpcError(parsed.error.message, parsed.error.code);
+    }
+
+    return parsed.result as T;
+  }
+
+  private async throttle(): Promise<void> {
+    const now = Date.now();
+    const elapsed = now - this.lastCallAt;
+    if (elapsed < this.rateLimitMs) {
+      await sleep(this.rateLimitMs - elapsed);
+    }
+    this.lastCallAt = Date.now();
+  }
+}
+
+// ─── Error ────────────────────────────────────────────────────────────────────
+
+export class VoyagerRpcError extends Error {
+  constructor(
+    message: string,
+    public readonly code: number
+  ) {
+    super(`VoyagerRpcError(${code}): ${message}`);
+    this.name = "VoyagerRpcError";
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/deprecation.ts

@@ -0,0 +1,102 @@
+/**
+ * Deprecation helpers.
+ *
+ * Usage:
+ *   export function oldApi() {
+ *     deprecated("oldApi", { since: "0.3.0", replacement: "newApi" });
+ *     // ... legacy behaviour
+ *   }
+ *
+ * Behaviour:
+ *   - First call from a given source-location emits one console.warn.
+ *   - Subsequent calls from the same location are silent (deduped by
+ *     stack-frame fingerprint).
+ *   - Calls from a different source-location warn again.
+ *   - Tests can reset state via `_resetDeprecationWarnings()`.
+ *
+ * Policy (per CONTRACT.md):
+ *   - An API marked `@deprecated` at version X.Y.Z is removed at earliest
+ *     X.(Y+2).0 (N-2 minor window). Major bumps MAY remove sooner if
+ *     explicitly listed in the release notes.
+ */
+
+const warnedCallSites = new Set<string>();
+
+export interface DeprecationOptions {
+  /** Version at which the API was marked deprecated, e.g. "0.3.0". */
+  since?: string;
+  /** Name of the replacement API to recommend. */
+  replacement?: string;
+  /** Version at which removal is scheduled, e.g. "0.5.0". */
+  removeIn?: string;
+  /** Free-form rationale appended to the warning. */
+  note?: string;
+  /**
+   * Optional logger override (defaults to `console.warn`). Pass
+   * `noopLogger.warn` in tests that want silence without resetting state.
+   */
+  emit?: (message: string) => void;
+}
+
+/**
+ * Emit a one-time-per-call-site deprecation warning.
+ *
+ * Dedup key is the top-most user frame of the stack; SDK-internal frames
+ * and node:internal frames are skipped so the fingerprint reflects where
+ * the deprecated API is *called from* in consumer code.
+ */
+export function deprecated(
+  apiName: string,
+  options: DeprecationOptions = {},
+): void {
+  const callSite = captureCallSite();
+  const key = `${apiName}@${callSite}`;
+
+  if (warnedCallSites.has(key)) return;
+  warnedCallSites.add(key);
+
+  const parts: string[] = [`[deprecated] ${apiName}`];
+  if (options.since) parts.push(`since ${options.since}`);
+  if (options.removeIn) parts.push(`removing in ${options.removeIn}`);
+  if (options.replacement) parts.push(`use ${options.replacement}`);
+  if (options.note) parts.push(options.note);
+  parts.push(`call-site: ${callSite}`);
+
+  const message = parts.join(" — ");
+  const emit = options.emit ?? ((m: string) => console.warn(m));
+  emit(message);
+}
+
+/** Test helper — clears the per-call-site dedup set. */
+export function _resetDeprecationWarnings(): void {
+  warnedCallSites.clear();
+}
+
+/** Test helper — returns a snapshot of the warned call-sites. */
+export function _deprecationWarnedCallSites(): readonly string[] {
+  return Array.from(warnedCallSites);
+}
+
+// ─── Internal ────────────────────────────────────────────────────────────
+
+/**
+ * Capture the top user-land stack frame. Skips frames inside this file
+ * (deprecation.ts) and node internals. Returns `"unknown"` if unavailable.
+ */
+function captureCallSite(): string {
+  const err = new Error("deprecation-trace");
+  const stack = err.stack ?? "";
+  const lines = stack.split("\n").slice(1); // drop the "Error: ..." header
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("at ")) continue;
+    if (trimmed.includes("deprecation.ts")) continue;
+    if (trimmed.includes("deprecation.js")) continue;
+    if (trimmed.includes("node:internal/")) continue;
+    // Normalise to "file:line:col" form
+    const match = trimmed.match(/\(([^)]+)\)/) ?? trimmed.match(/at (.+)/);
+    if (match?.[1]) return match[1];
+  }
+  return "unknown";
+}