@obelyzk/sdk 1.4.0 → 1.6.0

package/dist/chunk-EHI6MQFS.mjs

@@ -0,0 +1,566 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/firewall/client.ts
+import { RpcProvider, Contract, CallData } from "starknet";
+var AgentFirewallSDK = class {
+  config;
+  provider;
+  constructor(config) {
+    this.config = config;
+    this.provider = new RpcProvider({ nodeUrl: config.rpcUrl });
+  }
+  // ── Classification ─────────────────────────────────────────────────
+  /**
+   * Classify a transaction through the ZKML classifier.
+   *
+   * Sends the transaction features to the prove-server, which runs
+   * the MLP classifier and generates a GKR+STARK proof. Returns the
+   * proven threat score and decision.
+   *
+   * Does NOT submit anything on-chain — use `evaluateAction()` for
+   * the full flow including on-chain submission.
+   */
+  async classify(tx) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.config.apiKey) {
+      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    }
+    const body = {
+      target: tx.target,
+      value: tx.value || "0",
+      selector: tx.selector || "0x0",
+      calldata: tx.calldata || "0x",
+      agent_trust_score: tx.agentTrustScore || 0,
+      agent_strikes: tx.agentStrikes || 0,
+      agent_age_blocks: tx.agentAgeBlocks || 0,
+      target_verified: tx.targetVerified || false,
+      target_is_proxy: tx.targetIsProxy || false,
+      target_has_source: tx.targetHasSource || false,
+      target_interaction_count: tx.targetInteractionCount || 0,
+      tx_frequency: tx.txFrequency || 0,
+      unique_targets_24h: tx.uniqueTargets24h || 0,
+      avg_value_24h: tx.avgValue24h || 0,
+      max_value_24h: tx.maxValue24h || 0
+    };
+    const response = await fetch(`${this.config.proverUrl}/api/v1/classify`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: response.statusText }));
+      throw new Error(`Classification failed (${response.status}): ${error.error || response.statusText}`);
+    }
+    const data = await response.json();
+    return {
+      requestId: data.request_id,
+      decision: data.decision,
+      threatScore: data.threat_score,
+      scores: data.scores,
+      ioCommitment: data.io_commitment,
+      policyCommitment: data.policy_commitment,
+      proveTimeMs: data.prove_time_ms
+    };
+  }
+  // ── Agent Management ───────────────────────────────────────────────
+  /**
+   * Register a new agent on the firewall contract.
+   * The calling account becomes the agent owner.
+   */
+  async registerAgent(agentId) {
+    this.requireAccount();
+    const tx = await this.config.account.execute({
+      contractAddress: this.config.firewallContract,
+      entrypoint: "register_agent",
+      calldata: CallData.compile({ agent_id: agentId })
+    });
+    await this.provider.waitForTransaction(tx.transaction_hash);
+    return tx.transaction_hash;
+  }
+  /** Deactivate an agent (owner or contract admin). */
+  async deactivateAgent(agentId) {
+    this.requireAccount();
+    const tx = await this.config.account.execute({
+      contractAddress: this.config.firewallContract,
+      entrypoint: "deactivate_agent",
+      calldata: CallData.compile({ agent_id: agentId })
+    });
+    await this.provider.waitForTransaction(tx.transaction_hash);
+    return tx.transaction_hash;
+  }
+  /** Reactivate an agent and reset strikes (agent owner only). */
+  async reactivateAgent(agentId) {
+    this.requireAccount();
+    const tx = await this.config.account.execute({
+      contractAddress: this.config.firewallContract,
+      entrypoint: "reactivate_agent",
+      calldata: CallData.compile({ agent_id: agentId })
+    });
+    await this.provider.waitForTransaction(tx.transaction_hash);
+    return tx.transaction_hash;
+  }
+  // ── Queries ────────────────────────────────────────────────────────
+  /** Get the full status of an agent. */
+  async getAgentStatus(agentId) {
+    const contract = new Contract(
+      FIREWALL_ABI,
+      this.config.firewallContract,
+      this.provider
+    );
+    const [registered, active, trustScore, strikes, trusted] = await Promise.all([
+      contract.is_agent_registered(agentId),
+      contract.is_agent_active(agentId),
+      contract.get_trust_score(agentId),
+      contract.get_strikes(agentId),
+      contract.is_trusted(agentId)
+    ]);
+    return {
+      registered,
+      active,
+      trustScore: Number(trustScore),
+      strikes: Number(strikes),
+      trusted
+    };
+  }
+  /** Check if a specific action has been approved. */
+  async isActionApproved(actionId) {
+    const contract = new Contract(
+      FIREWALL_ABI,
+      this.config.firewallContract,
+      this.provider
+    );
+    return contract.is_action_approved(actionId);
+  }
+  /** Check if an agent is trusted. */
+  async isAgentTrusted(agentId) {
+    const contract = new Contract(
+      FIREWALL_ABI,
+      this.config.firewallContract,
+      this.provider
+    );
+    return contract.is_trusted(agentId);
+  }
+  /** Get the decision for an action (0=pending, 1=approved, 2=escalated, 3=blocked). */
+  async getActionDecision(actionId) {
+    const contract = new Contract(
+      FIREWALL_ABI,
+      this.config.firewallContract,
+      this.provider
+    );
+    return Number(await contract.get_action_decision(actionId));
+  }
+  /** Get the threat score for a resolved action. */
+  async getActionThreatScore(actionId) {
+    const contract = new Contract(
+      FIREWALL_ABI,
+      this.config.firewallContract,
+      this.provider
+    );
+    return Number(await contract.get_action_threat_score(actionId));
+  }
+  /** Get the IO commitment for an action. */
+  async getActionIoCommitment(actionId) {
+    const contract = new Contract(
+      FIREWALL_ABI,
+      this.config.firewallContract,
+      this.provider
+    );
+    const result = await contract.get_action_io_commitment(actionId);
+    return `0x${BigInt(result).toString(16)}`;
+  }
+  // ── On-Chain Actions ────────────────────────────────────────────────
+  /**
+   * Submit a pending action to the firewall contract.
+   * Returns the action_id assigned by the contract.
+   */
+  async submitAction(agentId, target, value, selector, ioCommitment) {
+    this.requireAccount();
+    const tx = await this.config.account.execute({
+      contractAddress: this.config.firewallContract,
+      entrypoint: "submit_action",
+      calldata: CallData.compile({
+        agent_id: agentId,
+        target,
+        value,
+        selector,
+        io_commitment: ioCommitment
+      })
+    });
+    const receipt = await this.provider.waitForTransaction(tx.transaction_hash);
+    let actionId = 0;
+    const events = receipt.events;
+    if (Array.isArray(events)) {
+      for (const event of events) {
+        if (event.data && event.data.length >= 2) {
+          const candidateId = Number(BigInt(event.data[0]));
+          if (candidateId > 0) {
+            actionId = candidateId;
+            break;
+          }
+        }
+      }
+    }
+    return { actionId, txHash: tx.transaction_hash };
+  }
+  /**
+   * Resolve a pending action with a verified ZKML proof.
+   * The proof must already be verified on the ObelyskVerifier contract.
+   */
+  async resolveAction(actionId, proofHash, originalIoLen, packedRawIo) {
+    this.requireAccount();
+    const tx = await this.config.account.execute({
+      contractAddress: this.config.firewallContract,
+      entrypoint: "resolve_action_with_proof",
+      calldata: CallData.compile({
+        action_id: actionId,
+        proof_hash: proofHash,
+        original_io_len: originalIoLen,
+        packed_raw_io: packedRawIo
+      })
+    });
+    const receipt = await this.provider.waitForTransaction(tx.transaction_hash);
+    let decision = "approve";
+    let threatScore = 0;
+    const resolveEvents = receipt.events;
+    if (Array.isArray(resolveEvents)) {
+      for (const event of resolveEvents) {
+        if (event.data && event.data.length >= 4) {
+          const decisionCode = Number(BigInt(event.data[2]));
+          threatScore = Number(BigInt(event.data[3]));
+          if (decisionCode === 1) decision = "approve";
+          else if (decisionCode === 2) decision = "escalate";
+          else if (decisionCode === 3) decision = "block";
+          break;
+        }
+      }
+    }
+    return { decision, threatScore, txHash: tx.transaction_hash };
+  }
+  /** Approve an escalated action (human-in-the-loop). */
+  async approveEscalated(actionId) {
+    this.requireAccount();
+    const tx = await this.config.account.execute({
+      contractAddress: this.config.firewallContract,
+      entrypoint: "approve_escalated",
+      calldata: CallData.compile({ action_id: actionId })
+    });
+    await this.provider.waitForTransaction(tx.transaction_hash);
+    return tx.transaction_hash;
+  }
+  /** Reject an escalated action and add a strike. */
+  async rejectEscalated(actionId) {
+    this.requireAccount();
+    const tx = await this.config.account.execute({
+      contractAddress: this.config.firewallContract,
+      entrypoint: "reject_escalated",
+      calldata: CallData.compile({ action_id: actionId })
+    });
+    await this.provider.waitForTransaction(tx.transaction_hash);
+    return tx.transaction_hash;
+  }
+  // ── Helpers ────────────────────────────────────────────────────────
+  requireAccount() {
+    if (!this.config.account) {
+      throw new Error(
+        "Account required for write operations. Pass `account` in FirewallConfig."
+      );
+    }
+  }
+};
+var FIREWALL_ABI = [
+  {
+    name: "is_agent_registered",
+    type: "function",
+    inputs: [{ name: "agent_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "is_agent_active",
+    type: "function",
+    inputs: [{ name: "agent_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_trust_score",
+    type: "function",
+    inputs: [{ name: "agent_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_strikes",
+    type: "function",
+    inputs: [{ name: "agent_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "is_trusted",
+    type: "function",
+    inputs: [{ name: "agent_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "is_action_approved",
+    type: "function",
+    inputs: [{ name: "action_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_action_decision",
+    type: "function",
+    inputs: [{ name: "action_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_action_threat_score",
+    type: "function",
+    inputs: [{ name: "action_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_action_io_commitment",
+    type: "function",
+    inputs: [{ name: "action_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_owner",
+    type: "function",
+    inputs: [],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_verifier",
+    type: "function",
+    inputs: [],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_classifier_model_id",
+    type: "function",
+    inputs: [],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_thresholds",
+    type: "function",
+    inputs: [],
+    outputs: [{ type: "felt" }, { type: "felt" }, { type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_agent_owner",
+    type: "function",
+    inputs: [{ name: "agent_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "get_action_agent",
+    type: "function",
+    inputs: [{ name: "action_id", type: "felt" }],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  },
+  {
+    name: "is_paused",
+    type: "function",
+    inputs: [],
+    outputs: [{ type: "felt" }],
+    state_mutability: "view"
+  }
+];
+
+// src/firewall/ciro.ts
+var CiroClient = class {
+  baseUrl;
+  apiKey;
+  org;
+  timeout;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.org = config.org ?? "obelyzk";
+    this.timeout = config.timeout ?? 1e4;
+  }
+  get apiBase() {
+    return `${this.baseUrl}/api/singularity/${this.org}/blockchain`;
+  }
+  async request(method, path, body) {
+    const url = `${this.apiBase}${path}`;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "X-Client": "obelyzk-sdk/1.0"
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: response.statusText }));
+        throw new Error(
+          `CIRO API error (${response.status}): ${error.error || response.statusText}`
+        );
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * Enrich a transaction with CIRO intelligence.
+   * Returns target risk, sanctions status, Forta alerts, and behavioral context.
+   */
+  async enrichTransaction(params) {
+    const raw = await this.request(
+      "POST",
+      "/transactions/enrich",
+      {
+        target: params.target,
+        sender: params.sender,
+        value: params.value ?? "0",
+        selector: params.selector ?? "0x0",
+        chain: "starknet"
+      }
+    );
+    return {
+      targetRisk: raw.target_risk ?? "unknown",
+      targetRiskScore: raw.target_risk_score ?? 0,
+      targetVerified: raw.target_verified ?? false,
+      targetIsProxy: raw.target_is_proxy ?? false,
+      targetHasSource: raw.target_has_source ?? false,
+      targetInteractionCount: raw.target_interaction_count ?? 0,
+      targetUniqueCallers: raw.target_unique_callers ?? 0,
+      targetFirstSeenBlocksAgo: raw.target_first_seen_blocks_ago ?? 0,
+      isSanctioned: raw.is_sanctioned ?? false,
+      sanctionLists: raw.sanction_lists ?? [],
+      fortaAlerts24h: raw.forta_alerts_24h ?? 0,
+      fortaSeverityMax: raw.forta_severity_max ?? null,
+      senderTxFrequency: raw.sender_tx_frequency ?? 0,
+      senderUniqueTargets24h: raw.sender_unique_targets_24h ?? 0,
+      senderAvgValue24h: raw.sender_avg_value_24h ?? 0,
+      senderMaxValue24h: raw.sender_max_value_24h ?? 0,
+      senderAgeBlocks: raw.sender_age_blocks ?? 0,
+      dataFreshnessS: raw.data_freshness_s ?? 0,
+      enrichmentTimeMs: raw.enrichment_time_ms ?? 0
+    };
+  }
+  /**
+   * Get risk assessment for a specific address.
+   */
+  async getAddressRisk(address) {
+    const raw = await this.request(
+      "GET",
+      `/addresses/${address}/risk`
+    );
+    return {
+      address: raw.address ?? address,
+      chain: raw.chain ?? "starknet",
+      riskLevel: raw.risk ?? "unknown",
+      riskScore: raw.risk_score ?? 0,
+      isContract: raw.is_contract ?? false,
+      isVerified: raw.is_verified ?? false,
+      isProxy: raw.is_proxy ?? false,
+      isSanctioned: raw.is_sanctioned ?? false,
+      sanctionLists: raw.sanction_lists ?? [],
+      fortaAlertsCount: raw.forta_alerts_count ?? 0,
+      knownExploitInvolvement: raw.known_exploit_involvement ?? false,
+      exploitNames: raw.exploit_names ?? [],
+      totalTxCount: raw.total_tx_count ?? 0,
+      clusterSize: raw.cluster_size ?? 0
+    };
+  }
+  /**
+   * Get recent alerts from CIRO's detection pipeline.
+   */
+  async getRecentAlerts(params) {
+    const query = new URLSearchParams();
+    if (params?.severity) query.set("severity", params.severity);
+    if (params?.limit) query.set("limit", String(params.limit));
+    const queryStr = query.toString();
+    const path = `/alerts/recent${queryStr ? `?${queryStr}` : ""}`;
+    const raw = await this.request("GET", path);
+    const alerts = raw.alerts ?? [];
+    return alerts.map((a) => ({
+      alertId: a.alert_id ?? "",
+      source: a.source ?? "",
+      severity: a.severity ?? "INFO",
+      chain: a.chain ?? "starknet",
+      timestamp: a.timestamp ?? "",
+      addresses: a.addresses ?? [],
+      txHash: a.tx_hash ?? null,
+      name: a.name ?? "",
+      description: a.description ?? ""
+    }));
+  }
+  /**
+   * Get data lake statistics.
+   */
+  async getStats() {
+    const raw = await this.request("GET", "/stats");
+    return {
+      totalTransactions: raw.total_transactions ?? 0,
+      labeledTransactions: raw.labeled_transactions ?? 0,
+      labelDistribution: raw.label_distribution ?? {},
+      lastUpdated: raw.last_updated ?? "",
+      fortaBotsActive: raw.forta_bots_active ?? 0,
+      addressesIndexed: raw.addresses_indexed ?? 0,
+      sanctionedAddresses: raw.sanctioned_addresses ?? 0
+    };
+  }
+};
+
+export {
+  __commonJS,
+  __export,
+  __toESM,
+  AgentFirewallSDK,
+  CiroClient
+};