@obelyzk/sdk 1.3.0 → 1.5.0

package/dist/client-DFxKbDns.d.mts

@@ -0,0 +1,199 @@
+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;
+}
+/** Full evaluation result from classify → submit → resolve. */
+interface EvaluateActionResult {
+    /** Classification result from the ZKML classifier. */
+    classification: ClassifyResult;
+    /** Decision after on-chain resolution (may differ from classification if escalated). */
+    decision: Decision;
+    /** Threat score applied to the agent's EMA. */
+    threatScore: number;
+    /** Action ID on the firewall contract. */
+    actionId: number;
+    /** Transaction hash of the resolve call. */
+    txHash: string;
+}
+/** 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>;
+    /** Get the decision for an action (0=pending, 1=approved, 2=escalated, 3=blocked). */
+    getActionDecision(actionId: number): Promise<number>;
+    /** Get the threat score for a resolved action. */
+    getActionThreatScore(actionId: number): Promise<number>;
+    /** Get the IO commitment for an action. */
+    getActionIoCommitment(actionId: number): Promise<string>;
+    /**
+     * Submit a pending action to the firewall contract.
+     * Returns the action_id assigned by the contract.
+     */
+    submitAction(agentId: string, target: string, value: string, selector: number, ioCommitment: string): Promise<SubmitActionResult>;
+    /**
+     * Resolve a pending action with a verified ZKML proof.
+     * The proof must already be verified on the ObelyskVerifier contract.
+     */
+    resolveAction(actionId: number, proofHash: string, originalIoLen: number, packedRawIo: string[]): Promise<ResolveResult>;
+    /** Approve an escalated action (human-in-the-loop). */
+    approveEscalated(actionId: number): Promise<string>;
+    /** Reject an escalated action and add a strike. */
+    rejectEscalated(actionId: number): Promise<string>;
+    private requireAccount;
+}
+
+export { AgentFirewallSDK as A, type ClassifyResult as C, type Decision as D, type EvaluateActionResult as E, type FirewallConfig as F, type ResolveResult as R, type SubmitActionResult as S, type TransactionFeatures as T, type AgentStatus as a };

package/dist/client-DFxKbDns.d.ts

@@ -0,0 +1,199 @@
+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;
+}
+/** Full evaluation result from classify → submit → resolve. */
+interface EvaluateActionResult {
+    /** Classification result from the ZKML classifier. */
+    classification: ClassifyResult;
+    /** Decision after on-chain resolution (may differ from classification if escalated). */
+    decision: Decision;
+    /** Threat score applied to the agent's EMA. */
+    threatScore: number;
+    /** Action ID on the firewall contract. */
+    actionId: number;
+    /** Transaction hash of the resolve call. */
+    txHash: string;
+}
+/** 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>;
+    /** Get the decision for an action (0=pending, 1=approved, 2=escalated, 3=blocked). */
+    getActionDecision(actionId: number): Promise<number>;
+    /** Get the threat score for a resolved action. */
+    getActionThreatScore(actionId: number): Promise<number>;
+    /** Get the IO commitment for an action. */
+    getActionIoCommitment(actionId: number): Promise<string>;
+    /**
+     * Submit a pending action to the firewall contract.
+     * Returns the action_id assigned by the contract.
+     */
+    submitAction(agentId: string, target: string, value: string, selector: number, ioCommitment: string): Promise<SubmitActionResult>;
+    /**
+     * Resolve a pending action with a verified ZKML proof.
+     * The proof must already be verified on the ObelyskVerifier contract.
+     */
+    resolveAction(actionId: number, proofHash: string, originalIoLen: number, packedRawIo: string[]): Promise<ResolveResult>;
+    /** Approve an escalated action (human-in-the-loop). */
+    approveEscalated(actionId: number): Promise<string>;
+    /** Reject an escalated action and add a strike. */
+    rejectEscalated(actionId: number): Promise<string>;
+    private requireAccount;
+}
+
+export { AgentFirewallSDK as A, type ClassifyResult as C, type Decision as D, type EvaluateActionResult as E, type FirewallConfig as F, type ResolveResult as R, type SubmitActionResult as S, type TransactionFeatures as T, type AgentStatus as a };