@veridex/agentic-payments 0.1.1-beta.1

package/src/chains/SolanaChainClient.ts

@@ -0,0 +1,37 @@
+/**
+ * @packageDocumentation
+ * @module SolanaChainClient
+ * @description
+ * Agent adapter for the Solana blockchain.
+ * 
+ * This class extends the core `SolanaClient` to enable agentic operations on Solana.
+ * 
+ * Key Features:
+ * - Manages Solana specific transaction instructions.
+ * - Handles SPL Token transfers.
+ * - Integrates with Wormhole for cross-chain messages.
+ */
+import { SolanaClient as CoreSolanaClient, SolanaClientConfig as CoreSolanaClientConfig } from '@veridex/sdk/chains/solana';
+import { BaseAgentChainClient } from './ChainClient';
+
+/**
+ * Agent-specific Solana chain client.
+ * Extends the core Solana client with agent-centric features.
+ */
+export class SolanaChainClient extends BaseAgentChainClient {
+    private solanaCore: CoreSolanaClient;
+
+    constructor(config: CoreSolanaClientConfig) {
+        const core = new CoreSolanaClient(config);
+        super(core);
+        this.solanaCore = core;
+    }
+
+
+    /**
+     * Helper to get the underlying connection
+     */
+    getConnection() {
+        return this.solanaCore.getConnection();
+    }
+}

package/src/chains/StarknetChainClient.ts

@@ -0,0 +1,36 @@
+/**
+ * @packageDocumentation
+ * @module StarknetChainClient
+ * @description
+ * Agent adapter for the Starknet Validity Rollup.
+ * 
+ * This class handles the specific requirements of Starknet's Account Abstraction model (SNIP-12).
+ * It ensures that agent signatures generated for x402 payments are compatible with
+ * Starknet's native account contracts.
+ * 
+ * Key Features:
+ * - Generates SNIP-12 typed data signatures.
+ * - Manages nonce abstraction for Starknet accounts.
+ * - Interfaces with Starknet RPC providers.
+ */
+import { StarknetClient as CoreStarknetClient, StarknetClientConfig as CoreStarknetClientConfig } from '@veridex/sdk/chains/starknet';
+import { BaseAgentChainClient } from './ChainClient';
+import { RpcProvider } from 'starknet';
+
+/**
+ * Agent-specific Starknet chain client.
+ */
+export class StarknetChainClient extends BaseAgentChainClient {
+    private starknetCore: CoreStarknetClient;
+
+    constructor(config: CoreStarknetClientConfig) {
+        const core = new CoreStarknetClient(config);
+        super(core);
+        this.starknetCore = core;
+    }
+
+
+    getClient(): RpcProvider {
+        return this.starknetCore.getProvider();
+    }
+}

package/src/chains/SuiChainClient.ts

@@ -0,0 +1,28 @@
+/**
+ * @packageDocumentation
+ * @module SuiChainClient
+ * @description
+ * Agent adapter for the Sui blockchain (Move VM).
+ * 
+ * Extends the core SDK to support agent operations on Sui.
+ */
+import { SuiClient as CoreSuiClient, SuiClientConfig as CoreSuiClientConfig } from '@veridex/sdk/chains/sui';
+import { BaseAgentChainClient } from './ChainClient';
+
+/**
+ * Agent-specific Sui chain client.
+ */
+export class SuiChainClient extends BaseAgentChainClient {
+    private suiCore: CoreSuiClient;
+
+    constructor(config: CoreSuiClientConfig) {
+        const core = new CoreSuiClient(config);
+        super(core);
+        this.suiCore = core;
+    }
+
+
+    getClient() {
+        return this.suiCore.getClient();
+    }
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * @packageDocumentation
+ * @module AgentSDK
+ * @description
+ * The main entry point for the Veridex Agent SDK (@veridex/agentic-payments).
+ *
+ * This package provides a high-level, autonomous payment layer for AI agents, built on top of the
+ * core Veridex SDK. It enables agents to manage spending limits, negotiate payments via x402,
+ * and issue Universal Commerce Protocol (UCP) credentials.
+ *
+ * Exports:
+ * - **createAgentWallet**: Factory function to initialize the agent.
+ * - **AgentWallet**: The main class for agent operations.
+ * - **Types**: Comprehensive type definitions for sessions, payments, and protocols.
+ */
+import { AgentWallet } from './AgentWallet';
+import { AgentWalletConfig } from './types/agent';
+
+export async function createAgentWallet(config: AgentWalletConfig): Promise<AgentWallet> {
+  const wallet = new AgentWallet(config);
+  await wallet.init();
+  return wallet;
+}
+
+export * from './AgentWallet';
+export * from './types/agent';
+export * from './types/x402';
+export * from './types/ucp';
+export * from './types/mcp';
+export * from './types/errors';
+
+export * from './session/SessionKeyManager';
+export * from './session/SpendingTracker';
+export * from './session/SessionStorage';
+
+export * from './x402/X402Client';
+export * from './x402/PaymentParser';
+export * from './x402/PaymentSigner';
+export * from './x402/adapters/CronosFacilitatorAdapter';
+
+export * from './ucp/CredentialProvider';
+export * from './ucp/CapabilityNegotiator';
+
+export * from './mcp/MCPServer';
+
+export * from './routing/CrossChainRouter';
+export * from './routing/FeeEstimator';
+export * from './chains/ChainClient';
+export * from './chains/EVMChainClient';
+export * from './chains/SolanaChainClient';
+export * from './chains/AptosChainClient';
+export * from './chains/SuiChainClient';
+export * from './chains/StarknetChainClient';
+export * from './chains/ChainClientFactory';
+export * from './routing/BridgeOrchestrator';
+
+export * from './monitoring/AuditLogger';
+export * from './monitoring/AlertManager';
+export * from './monitoring/ComplianceExporter';
+export * from './monitoring/BalanceCache';
+
+export * from './ucp/PaymentTokenizer';
+
+export * from './react/hooks';
+
+// Performance optimizations
+export * from './performance';
+
+// Oracle
+export * from './oracle/PythOracle';
+export * from './oracle/PythFeeds';
+
+// DEX
+export * from './routing/DEXAggregator';
+
+// Re-export core SDK functions for frontend convenience and to avoid dual-package usage
+export {
+  createSDK,
+  generateSecp256k1KeyPair,
+  computeSessionKeyHash,
+  deriveEncryptionKey,
+  encrypt
+} from '@veridex/sdk';

package/src/mcp/MCPServer.ts

@@ -0,0 +1,73 @@
+/**
+ * @packageDocumentation
+ * @module MCPServer
+ * @description
+ * Implements the Model Context Protocol (MCP) Server for AI Agent Tools.
+ * 
+ * This server exposes the specific capabilities of the Agent SDK (paying, balance checking, etc.)
+ * as standard MCP Tools that can be discovered and executed by LLMs (e.g., Claude, Gemini).
+ * 
+ * Exposed Tools:
+ * - `veridex_create_session_key`: Initialize a new constrained wallet.
+ * - `veridex_pay`: Execute a cross-chain transaction.
+ * - `veridex_check_balance`: Query unified portfolio balance.
+ */
+import { AgentWallet } from '../AgentWallet';
+import { MCPTool, MCPToolResult } from '../types/mcp';
+import * as schemas from './schemas';
+
+export class MCPServer {
+  constructor(private agentWallet: AgentWallet) { }
+
+  getTools(): MCPTool[] {
+    return [
+      {
+        name: 'veridex_create_session_key',
+        description: 'Create a bounded wallet for an AI agent',
+        inputSchema: schemas.CREATE_SESSION_SCHEMA,
+        handler: (params) => this.agentWallet.createSession(params),
+      },
+      {
+        name: 'veridex_pay',
+        description: 'Execute a payment across chains',
+        inputSchema: schemas.PAY_SCHEMA,
+        handler: (params) => this.agentWallet.pay(params),
+      },
+      {
+        name: 'veridex_check_balance',
+        description: 'Query wallet balances across all chains',
+        inputSchema: schemas.CHECK_BALANCE_SCHEMA,
+        handler: (params) => this.agentWallet.getBalance(params.chain),
+      },
+      {
+        name: 'veridex_revoke_session',
+        description: 'Revoke agent wallet access',
+        inputSchema: schemas.REVOKE_SESSION_SCHEMA,
+        handler: () => this.agentWallet.revokeSession(),
+      },
+      {
+        name: 'veridex_get_payment_history',
+        description: 'Retrieve transaction history',
+        inputSchema: schemas.GET_HISTORY_SCHEMA,
+        handler: (params) => this.agentWallet.getPaymentHistory(params),
+      },
+    ];
+  }
+
+  async executeTool(toolName: string, params: any): Promise<MCPToolResult> {
+    const tool = this.getTools().find(t => t.name === toolName);
+    if (!tool) throw new Error(`Tool ${toolName} not found`);
+
+    try {
+      const result = await tool.handler(params);
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (error: any) {
+      return {
+        content: [{ type: 'text', text: `Error: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+}

package/src/mcp/schemas.ts

@@ -0,0 +1,60 @@
+/**
+ * @packageDocumentation
+ * @module MCPSchemas
+ * @description
+ * JSON Schema definitions for MCP Tool inputs.
+ * 
+ * These schemas validate the arguments passed by LLMs when invoking Agent tools
+ * (e.g., 'amount' must be a string, 'chainId' must be a known number).
+ * 
+ * Defined Schemas:
+ * - `CREATE_SESSION_SCHEMA`: Configuration for new session keys.
+ * - `PAY_SCHEMA`: Parameters for cross-chain payments.
+ * - `CHECK_BALANCE_SCHEMA`: Arguments for balance queries.
+ * - `REVOKE_SESSION_SCHEMA`: Arguments for session revocation.
+ */
+export const CREATE_SESSION_SCHEMA = {
+  type: 'object',
+  properties: {
+    dailyLimitUSD: { type: 'number' },
+    perTransactionLimitUSD: { type: 'number' },
+    expiryHours: { type: 'number' },
+    allowedChains: { type: 'array', items: { type: 'number' } }
+  },
+  required: ['dailyLimitUSD', 'perTransactionLimitUSD']
+};
+
+export const PAY_SCHEMA = {
+  type: 'object',
+  properties: {
+    amount: { type: 'string', description: 'Amount in ATOMIC UNITS (wei). E.g. 10 USDC = 10000000 (6 decimals), 1 ETH = 10^18.' },
+    token: { type: 'string', description: 'Token symbol (e.g. "usdc", "eth", "native")' },
+    recipient: { type: 'string', description: 'Recipient wallet address (0x...)' },
+    chain: { type: 'number', description: 'Wormhole Chain ID. Use: 10004=Base Sepolia, 10002=Ethereum Sepolia, 10003=Arbitrum Sepolia, 10005=Optimism Sepolia. Do NOT use native chain IDs like 11155111.' }
+  },
+  required: ['amount', 'recipient', 'chain']
+};
+
+export const CHECK_BALANCE_SCHEMA = {
+  type: 'object',
+  properties: {
+    chain: { type: 'number' }
+  }
+};
+
+export const REVOKE_SESSION_SCHEMA = {
+  type: 'object',
+  properties: {
+    sessionKeyHash: { type: 'string' }
+  },
+  required: ['sessionKeyHash']
+};
+
+export const GET_HISTORY_SCHEMA = {
+  type: 'object',
+  properties: {
+    limit: { type: 'number' },
+    offset: { type: 'number' },
+    chain: { type: 'number' }
+  }
+};

package/src/monitoring/AlertManager.ts

@@ -0,0 +1,258 @@
+/**
+ * @packageDocumentation
+ * @module AlertManager
+ * @description
+ * Real-time monitoring and alerting system for agent spending.
+ * 
+ * Capabilites:
+ * - **Threshold Alerts**: Triggers warnings when spending hits 50%, 80%, 90% of daily limits.
+ * - **High Value Approval**: Pauses large transactions (> $1000) for human approval.
+ * - **Anomaly Detection**: Uses heuristics to detect unusual spending patterns (frequency/amount spikes).
+ * - **Webhooks**: Dispatches critical alerts to external systems (Slack, PagerDuty).
+ */
+import { SpendingAlert } from '../types/agent';
+import { PaymentRecord } from './AuditLogger';
+
+export interface AlertConfig {
+    spendingThresholds: number[]; // e.g., [0.5, 0.8, 0.9, 1.0]
+    highValueThresholdUSD: number; // e.g., 1000
+    anomalyDetectionEnabled: boolean;
+    webhookUrl?: string;
+}
+
+export interface HighValueApproval {
+    transactionId: string;
+    amountUSD: number;
+    requestedAt: number;
+    expiresAt: number;
+    approved: boolean;
+    approvedBy?: string;
+}
+
+const DEFAULT_CONFIG: AlertConfig = {
+    spendingThresholds: [0.5, 0.8, 0.9, 1.0],
+    highValueThresholdUSD: 1000,
+    anomalyDetectionEnabled: true,
+};
+
+export class AlertManager {
+    private config: AlertConfig;
+    private triggeredAlerts: Set<string> = new Set();
+    private callbacks: ((alert: SpendingAlert) => void)[] = [];
+    private transactionHistory: PaymentRecord[] = [];
+    private pendingApprovals: Map<string, HighValueApproval> = new Map();
+    private readonly APPROVAL_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+
+    constructor(config: Partial<AlertConfig> = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+
+    onAlert(callback: (alert: SpendingAlert) => void) {
+        this.callbacks.push(callback);
+    }
+
+    /**
+     * Check spending against thresholds and trigger alerts.
+     */
+    checkSpending(
+        sessionKeyHash: string,
+        dailySpentUSD: number,
+        dailyLimitUSD: number
+    ) {
+        const ratio = dailySpentUSD / dailyLimitUSD;
+
+        for (const threshold of this.config.spendingThresholds) {
+            const alertId = `${sessionKeyHash}_${threshold}`;
+
+            if (ratio >= threshold && !this.triggeredAlerts.has(alertId)) {
+                this.triggeredAlerts.add(alertId);
+
+                const alert: SpendingAlert = {
+                    type: threshold >= 0.9 ? 'CRITICAL' : 'WARNING',
+                    message: `Spending reached ${threshold * 100}% of daily limit.`,
+                    sessionKeyHash,
+                    dailySpentUSD,
+                    dailyLimitUSD,
+                    timestamp: Date.now()
+                };
+
+                this.notify(alert);
+            }
+        }
+
+        // Reset alerts if spending was reset
+        if (ratio < 0.1) {
+            for (const threshold of this.config.spendingThresholds) {
+                this.triggeredAlerts.delete(`${sessionKeyHash}_${threshold}`);
+            }
+        }
+    }
+
+    /**
+     * Check if a transaction is high-value and requires approval.
+     */
+    isHighValueTransaction(amountUSD: number): boolean {
+        return amountUSD >= this.config.highValueThresholdUSD;
+    }
+
+    /**
+     * Request approval for a high-value transaction.
+     */
+    requestApproval(transactionId: string, amountUSD: number): HighValueApproval {
+        const approval: HighValueApproval = {
+            transactionId,
+            amountUSD,
+            requestedAt: Date.now(),
+            expiresAt: Date.now() + this.APPROVAL_WINDOW_MS,
+            approved: false,
+        };
+
+        this.pendingApprovals.set(transactionId, approval);
+
+        // Notify about pending approval
+        const alert: SpendingAlert = {
+            type: 'CRITICAL',
+            message: `High-value transaction ($${amountUSD}) requires approval within 5 minutes.`,
+            sessionKeyHash: transactionId,
+            dailySpentUSD: amountUSD,
+            dailyLimitUSD: this.config.highValueThresholdUSD,
+            timestamp: Date.now(),
+        };
+        this.notify(alert);
+
+        return approval;
+    }
+
+    /**
+     * Approve a pending high-value transaction.
+     */
+    approveTransaction(transactionId: string, approverKey: string): boolean {
+        const approval = this.pendingApprovals.get(transactionId);
+        if (!approval) return false;
+
+        if (Date.now() > approval.expiresAt) {
+            this.pendingApprovals.delete(transactionId);
+            return false; // Expired
+        }
+
+        approval.approved = true;
+        approval.approvedBy = approverKey;
+        return true;
+    }
+
+    /**
+     * Check if a transaction has been approved.
+     */
+    checkApproval(transactionId: string): { approved: boolean; expired: boolean } {
+        const approval = this.pendingApprovals.get(transactionId);
+        if (!approval) {
+            return { approved: false, expired: false };
+        }
+
+        if (Date.now() > approval.expiresAt) {
+            this.pendingApprovals.delete(transactionId);
+            return { approved: false, expired: true };
+        }
+
+        return { approved: approval.approved, expired: false };
+    }
+
+    /**
+     * Detect anomalies in transaction patterns.
+     */
+    detectAnomaly(record: PaymentRecord): boolean {
+        if (!this.config.anomalyDetectionEnabled) return false;
+
+        this.transactionHistory.push(record);
+
+        // Keep only last 100 transactions for analysis
+        if (this.transactionHistory.length > 100) {
+            this.transactionHistory = this.transactionHistory.slice(-100);
+        }
+
+        // Simple anomaly detection: unusual amount or frequency
+        const recentTxs = this.transactionHistory.filter(
+            tx => tx.timestamp > Date.now() - 60 * 60 * 1000 // Last hour
+        );
+
+        // Check for unusual frequency (more than 10 tx/hour)
+        if (recentTxs.length > 10) {
+            this.notify({
+                type: 'WARNING',
+                message: `Unusual transaction frequency detected: ${recentTxs.length} transactions in the last hour.`,
+                sessionKeyHash: record.sessionKeyHash ?? 'unknown',
+                dailySpentUSD: record.amountUSD ?? 0,
+                dailyLimitUSD: 0,
+                timestamp: Date.now(),
+            });
+            return true;
+        }
+
+        // Check for unusual amount (3x average)
+        if (recentTxs.length > 3) {
+            const avgAmount = recentTxs.reduce((sum, tx) => sum + (tx.amountUSD ?? 0), 0) / recentTxs.length;
+            const recordAmount = record.amountUSD ?? 0;
+            if (recordAmount > avgAmount * 3) {
+                this.notify({
+                    type: 'WARNING',
+                    message: `Unusual transaction amount: $${recordAmount} is 3x above average ($${avgAmount.toFixed(2)}).`,
+                    sessionKeyHash: record.sessionKeyHash ?? 'unknown',
+                    dailySpentUSD: recordAmount,
+                    dailyLimitUSD: 0,
+                    timestamp: Date.now(),
+                });
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Send webhook notification for alerts.
+     */
+    private async sendWebhook(alert: SpendingAlert): Promise<boolean> {
+        if (!this.config.webhookUrl) return false;
+
+        try {
+            const response = await fetch(this.config.webhookUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    event: 'spending_alert',
+                    alert,
+                    timestamp: new Date().toISOString(),
+                }),
+            });
+            return response.ok;
+        } catch (error) {
+            console.error('[AlertManager] Webhook delivery failed:', error);
+            return false;
+        }
+    }
+
+    private notify(alert: SpendingAlert) {
+        this.callbacks.forEach(cb => cb(alert));
+        console.warn(`[SpendingAlert] ${alert.type}: ${alert.message} (${alert.sessionKeyHash})`);
+
+        // Send webhook asynchronously
+        if (this.config.webhookUrl) {
+            this.sendWebhook(alert).catch(() => { });
+        }
+    }
+
+    /**
+     * Clean up expired pending approvals.
+     */
+    cleanupExpiredApprovals(): number {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [id, approval] of this.pendingApprovals.entries()) {
+            if (approval.expiresAt < now) {
+                this.pendingApprovals.delete(id);
+                cleaned++;
+            }
+        }
+        return cleaned;
+    }
+}

package/src/monitoring/AuditLogger.ts

@@ -0,0 +1,86 @@
+/**
+ * @packageDocumentation
+ * @module AuditLogger
+ * @description
+ * Immutable transaction logging for compliance and auditing.
+ * 
+ * Every payment attempt (successful or failed) is recorded here. In a production environment,
+ * this should ideally write to a tamper-evident log or database. Currently, it persists
+ * to local storage and memory for the demo.
+ * 
+ * Records:
+ * - Timestamp
+ * - Amount (USD and Native)
+ * - Chain ID
+ * - Recipient
+ * - Session ID
+ */
+import { PaymentReceipt, HistoryOptions } from '../types/agent';
+
+export interface PaymentRecord extends PaymentReceipt {
+  id: string;
+  sessionKeyHash?: string;
+}
+
+export class AuditLogger {
+  private static readonly STORAGE_KEY = 'veridex_audit_log';
+  private inMemoryLogs: PaymentRecord[] = [];
+
+  async log(entry: PaymentReceipt, sessionKeyHash?: string): Promise<void> {
+    const record: PaymentRecord = {
+      ...entry,
+      id: crypto.randomUUID ? crypto.randomUUID() : `log_${Date.now()}_${Math.random()}`,
+      sessionKeyHash
+    };
+
+    this.inMemoryLogs.push(record);
+    this.persistLogs();
+
+    // Original console log
+    console.log('AUDIT:', JSON.stringify(record, (key, value) =>
+      typeof value === 'bigint' ? value.toString() : value
+    ));
+  }
+
+  async getLogs(options: HistoryOptions = {}): Promise<PaymentRecord[]> {
+    this.loadLogs();
+    let logs = [...this.inMemoryLogs];
+
+    // Filter by chain
+    if (options.chain !== undefined) {
+      logs = logs.filter(l => l.chain === options.chain);
+    }
+
+    // Filter by time
+    if (options.startTime) {
+      logs = logs.filter(l => l.timestamp >= options.startTime!);
+    }
+    if (options.endTime) {
+      logs = logs.filter(l => l.timestamp <= options.endTime!);
+    }
+
+    // Sort desc
+    logs.sort((a, b) => b.timestamp - a.timestamp);
+
+    // Pagination
+    const offset = options.offset || 0;
+    const limit = options.limit || 50;
+
+    return logs.slice(offset, offset + limit);
+  }
+
+  private persistLogs() {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem(AuditLogger.STORAGE_KEY, JSON.stringify(this.inMemoryLogs));
+    }
+  }
+
+  private loadLogs() {
+    if (typeof localStorage !== 'undefined') {
+      const data = localStorage.getItem(AuditLogger.STORAGE_KEY);
+      if (data) {
+        this.inMemoryLogs = JSON.parse(data);
+      }
+    }
+  }
+}