@obelyzk/sdk 1.0.1 → 1.2.0

package/dist/firewall/index.d.mts

@@ -0,0 +1,166 @@
+import * as starknet from 'starknet';
+
+/**
+ * Types for the ZKML Agent Firewall SDK.
+ *
+ * These types map 1:1 to the Rust classifier and Cairo AgentFirewallZK contract.
+ */
+/** Transaction features sent to the classifier. */
+interface TransactionFeatures {
+    /** Target contract address (hex, 0x-prefixed). */
+    target: string;
+    /** Transaction value (decimal string, u256). */
+    value?: string;
+    /** Function selector (hex, 4 bytes, 0x-prefixed). */
+    selector?: string;
+    /** Calldata (hex, after selector, 0x-prefixed). */
+    calldata?: string;
+    /** Agent's current trust score (0-100000). */
+    agentTrustScore?: number;
+    /** Agent's current strike count. */
+    agentStrikes?: number;
+    /** Agent age in blocks since registration. */
+    agentAgeBlocks?: number;
+    /** Target contract metadata. */
+    targetVerified?: boolean;
+    targetIsProxy?: boolean;
+    targetHasSource?: boolean;
+    targetInteractionCount?: number;
+    /** Behavioral features. */
+    txFrequency?: number;
+    uniqueTargets24h?: number;
+    avgValue24h?: number;
+    maxValue24h?: number;
+}
+/** Classifier decision. */
+type Decision = "approve" | "escalate" | "block";
+/** Result from evaluating a transaction through the ZKML classifier. */
+interface ClassifyResult {
+    /** Unique request ID. */
+    requestId: string;
+    /** Classifier decision. */
+    decision: Decision;
+    /** Threat score (0-100000). */
+    threatScore: number;
+    /** Raw output scores: [safe, suspicious, malicious]. */
+    scores: [number, number, number];
+    /** IO commitment (Poseidon hash of classifier input + output). */
+    ioCommitment: string;
+    /** Policy commitment (strict policy hash). */
+    policyCommitment: string;
+    /** Proving time in milliseconds. */
+    proveTimeMs: number;
+}
+/** Result from submitting an action to the firewall contract. */
+interface SubmitActionResult {
+    /** Action ID assigned by the contract. */
+    actionId: number;
+    /** Transaction hash. */
+    txHash: string;
+}
+/** Result from resolving an action with a verified proof. */
+interface ResolveResult {
+    /** Final decision after proof verification. */
+    decision: Decision;
+    /** Threat score applied to the agent. */
+    threatScore: number;
+    /** Transaction hash. */
+    txHash: string;
+}
+/** Agent trust status. */
+interface AgentStatus {
+    /** Whether the agent is registered. */
+    registered: boolean;
+    /** Whether the agent is active (not frozen). */
+    active: boolean;
+    /** Current trust score (0-100000, EMA smoothed). */
+    trustScore: number;
+    /** Current strike count. */
+    strikes: number;
+    /** Whether the agent is trusted (active + score < threshold + strikes < max). */
+    trusted: boolean;
+}
+/** Firewall SDK configuration. */
+interface FirewallConfig {
+    /** Prover server URL (for /api/v1/classify). */
+    proverUrl: string;
+    /** AgentFirewallZK contract address on Starknet. */
+    firewallContract: string;
+    /** ObelyskVerifier contract address on Starknet. */
+    verifierContract: string;
+    /** Starknet RPC URL. */
+    rpcUrl: string;
+    /** Starknet account for signing transactions. */
+    account?: starknet.Account;
+    /** API key for the prover server (optional). */
+    apiKey?: string;
+}
+
+/**
+ * AgentFirewallSDK — ZKML-powered transaction guardrails for AI agents.
+ *
+ * Wraps the full flow:
+ *   1. Classify transaction via prove-server (/api/v1/classify)
+ *   2. Submit action to AgentFirewallZK contract
+ *   3. Submit ZKML proof to ObelyskVerifier (streaming or recursive)
+ *   4. Resolve action with proven threat score
+ *   5. Query approval status
+ *
+ * @example
+ * ```typescript
+ * import { AgentFirewallSDK } from '@obelyzk/sdk/firewall';
+ *
+ * const firewall = new AgentFirewallSDK({
+ *   proverUrl: 'https://prover.bitsage.network',
+ *   firewallContract: '0x...',
+ *   verifierContract: '0x...',
+ *   rpcUrl: process.env.STARKNET_RPC!,
+ *   account: myAccount,
+ * });
+ *
+ * const result = await firewall.evaluateAction({
+ *   target: '0x1234...',
+ *   value: '1000000000',
+ *   selector: '0xa9059cbb',
+ * });
+ *
+ * if (result.decision === 'approve') {
+ *   // safe to execute
+ * }
+ * ```
+ */
+
+declare class AgentFirewallSDK {
+    private config;
+    private provider;
+    constructor(config: FirewallConfig);
+    /**
+     * 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.
+     */
+    classify(tx: TransactionFeatures): Promise<ClassifyResult>;
+    /**
+     * Register a new agent on the firewall contract.
+     * The calling account becomes the agent owner.
+     */
+    registerAgent(agentId: string): Promise<string>;
+    /** Deactivate an agent (owner or contract admin). */
+    deactivateAgent(agentId: string): Promise<string>;
+    /** Reactivate an agent and reset strikes (agent owner only). */
+    reactivateAgent(agentId: string): Promise<string>;
+    /** Get the full status of an agent. */
+    getAgentStatus(agentId: string): Promise<AgentStatus>;
+    /** Check if a specific action has been approved. */
+    isActionApproved(actionId: number): Promise<boolean>;
+    /** Check if an agent is trusted. */
+    isAgentTrusted(agentId: string): Promise<boolean>;
+    private requireAccount;
+}
+
+export { AgentFirewallSDK, type AgentStatus, type ClassifyResult, type Decision, type FirewallConfig, type ResolveResult, type SubmitActionResult, type TransactionFeatures };

package/dist/firewall/index.d.ts

@@ -0,0 +1,166 @@
+import * as starknet from 'starknet';
+
+/**
+ * Types for the ZKML Agent Firewall SDK.
+ *
+ * These types map 1:1 to the Rust classifier and Cairo AgentFirewallZK contract.
+ */
+/** Transaction features sent to the classifier. */
+interface TransactionFeatures {
+    /** Target contract address (hex, 0x-prefixed). */
+    target: string;
+    /** Transaction value (decimal string, u256). */
+    value?: string;
+    /** Function selector (hex, 4 bytes, 0x-prefixed). */
+    selector?: string;
+    /** Calldata (hex, after selector, 0x-prefixed). */
+    calldata?: string;
+    /** Agent's current trust score (0-100000). */
+    agentTrustScore?: number;
+    /** Agent's current strike count. */
+    agentStrikes?: number;
+    /** Agent age in blocks since registration. */
+    agentAgeBlocks?: number;
+    /** Target contract metadata. */
+    targetVerified?: boolean;
+    targetIsProxy?: boolean;
+    targetHasSource?: boolean;
+    targetInteractionCount?: number;
+    /** Behavioral features. */
+    txFrequency?: number;
+    uniqueTargets24h?: number;
+    avgValue24h?: number;
+    maxValue24h?: number;
+}
+/** Classifier decision. */
+type Decision = "approve" | "escalate" | "block";
+/** Result from evaluating a transaction through the ZKML classifier. */
+interface ClassifyResult {
+    /** Unique request ID. */
+    requestId: string;
+    /** Classifier decision. */
+    decision: Decision;
+    /** Threat score (0-100000). */
+    threatScore: number;
+    /** Raw output scores: [safe, suspicious, malicious]. */
+    scores: [number, number, number];
+    /** IO commitment (Poseidon hash of classifier input + output). */
+    ioCommitment: string;
+    /** Policy commitment (strict policy hash). */
+    policyCommitment: string;
+    /** Proving time in milliseconds. */
+    proveTimeMs: number;
+}
+/** Result from submitting an action to the firewall contract. */
+interface SubmitActionResult {
+    /** Action ID assigned by the contract. */
+    actionId: number;
+    /** Transaction hash. */
+    txHash: string;
+}
+/** Result from resolving an action with a verified proof. */
+interface ResolveResult {
+    /** Final decision after proof verification. */
+    decision: Decision;
+    /** Threat score applied to the agent. */
+    threatScore: number;
+    /** Transaction hash. */
+    txHash: string;
+}
+/** Agent trust status. */
+interface AgentStatus {
+    /** Whether the agent is registered. */
+    registered: boolean;
+    /** Whether the agent is active (not frozen). */
+    active: boolean;
+    /** Current trust score (0-100000, EMA smoothed). */
+    trustScore: number;
+    /** Current strike count. */
+    strikes: number;
+    /** Whether the agent is trusted (active + score < threshold + strikes < max). */
+    trusted: boolean;
+}
+/** Firewall SDK configuration. */
+interface FirewallConfig {
+    /** Prover server URL (for /api/v1/classify). */
+    proverUrl: string;
+    /** AgentFirewallZK contract address on Starknet. */
+    firewallContract: string;
+    /** ObelyskVerifier contract address on Starknet. */
+    verifierContract: string;
+    /** Starknet RPC URL. */
+    rpcUrl: string;
+    /** Starknet account for signing transactions. */
+    account?: starknet.Account;
+    /** API key for the prover server (optional). */
+    apiKey?: string;
+}
+
+/**
+ * AgentFirewallSDK — ZKML-powered transaction guardrails for AI agents.
+ *
+ * Wraps the full flow:
+ *   1. Classify transaction via prove-server (/api/v1/classify)
+ *   2. Submit action to AgentFirewallZK contract
+ *   3. Submit ZKML proof to ObelyskVerifier (streaming or recursive)
+ *   4. Resolve action with proven threat score
+ *   5. Query approval status
+ *
+ * @example
+ * ```typescript
+ * import { AgentFirewallSDK } from '@obelyzk/sdk/firewall';
+ *
+ * const firewall = new AgentFirewallSDK({
+ *   proverUrl: 'https://prover.bitsage.network',
+ *   firewallContract: '0x...',
+ *   verifierContract: '0x...',
+ *   rpcUrl: process.env.STARKNET_RPC!,
+ *   account: myAccount,
+ * });
+ *
+ * const result = await firewall.evaluateAction({
+ *   target: '0x1234...',
+ *   value: '1000000000',
+ *   selector: '0xa9059cbb',
+ * });
+ *
+ * if (result.decision === 'approve') {
+ *   // safe to execute
+ * }
+ * ```
+ */
+
+declare class AgentFirewallSDK {
+    private config;
+    private provider;
+    constructor(config: FirewallConfig);
+    /**
+     * 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.
+     */
+    classify(tx: TransactionFeatures): Promise<ClassifyResult>;
+    /**
+     * Register a new agent on the firewall contract.
+     * The calling account becomes the agent owner.
+     */
+    registerAgent(agentId: string): Promise<string>;
+    /** Deactivate an agent (owner or contract admin). */
+    deactivateAgent(agentId: string): Promise<string>;
+    /** Reactivate an agent and reset strikes (agent owner only). */
+    reactivateAgent(agentId: string): Promise<string>;
+    /** Get the full status of an agent. */
+    getAgentStatus(agentId: string): Promise<AgentStatus>;
+    /** Check if a specific action has been approved. */
+    isActionApproved(actionId: number): Promise<boolean>;
+    /** Check if an agent is trusted. */
+    isAgentTrusted(agentId: string): Promise<boolean>;
+    private requireAccount;
+}
+
+export { AgentFirewallSDK, type AgentStatus, type ClassifyResult, type Decision, type FirewallConfig, type ResolveResult, type SubmitActionResult, type TransactionFeatures };

package/dist/firewall/index.js

@@ -0,0 +1,232 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/firewall/index.ts
+var firewall_exports = {};
+__export(firewall_exports, {
+  AgentFirewallSDK: () => AgentFirewallSDK
+});
+module.exports = __toCommonJS(firewall_exports);
+
+// src/firewall/client.ts
+var import_starknet = require("starknet");
+var AgentFirewallSDK = class {
+  config;
+  provider;
+  constructor(config) {
+    this.config = config;
+    this.provider = new import_starknet.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: import_starknet.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: import_starknet.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: import_starknet.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 import_starknet.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 import_starknet.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 import_starknet.Contract(
+      FIREWALL_ABI,
+      this.config.firewallContract,
+      this.provider
+    );
+    return contract.is_trusted(agentId);
+  }
+  // ── 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"
+  }
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentFirewallSDK
+});

package/dist/firewall/index.mjs

@@ -0,0 +1,7 @@
+import {
+  AgentFirewallSDK
+} from "../chunk-BHUXKNDT.mjs";
+import "../chunk-Y6FXYEAI.mjs";
+export {
+  AgentFirewallSDK
+};