@veridex/agentic-payments 0.1.1-beta.1

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to `@veridex/agentic-payments` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-20
+
+### Added
+
+#### Core Features
+- **Session Key Management**
+  - `SessionKeyManager` for creating, validating, and revoking session keys
+  - `SpendingTracker` for daily and per-transaction limit enforcement
+  - `SessionStorage` for encrypted key persistence
+  - Support for 24-hour maximum session duration
+  - Automatic daily limit reset with rolling window
+
+- **x402 Protocol Support**
+  - `X402Client` for automatic HTTP 402 payment handling
+  - `PaymentParser` for parsing payment requirement headers
+  - `PaymentSigner` with ERC-3009 support (transferWithAuthorization)
+  - `NonceManager` for client-side nonce tracking
+
+- **UCP Integration**
+  - `UCPCredentialProvider` for Universal Credential Protocol support
+  - `CapabilityNegotiator` for capability intersection calculation
+  - `PaymentTokenizer` for generating and validating payment tokens
+  - Token refresh and revocation mechanisms
+
+- **MCP Server**
+  - `MCPServer` for Model Context Protocol integration
+  - Tools: `veridex_create_session_key`, `veridex_pay`, `veridex_check_balance`, `veridex_revoke_session`, `veridex_get_payment_history`
+  - JSON Schema validation for all tool parameters
+
+- **Multi-Chain Support**
+  - `ChainClientFactory` for creating chain-specific clients
+  - `EVMChainClient` - Base, Optimism, Arbitrum, Ethereum, Polygon, BSC, Avalanche
+  - `SolanaChainClient` - Solana mainnet and devnet
+  - `AptosChainClient` - Aptos mainnet and testnet
+  - `SuiChainClient` - Sui mainnet and testnet
+  - `StarknetChainClient` - Starknet mainnet and testnet
+
+- **Oracle Integration**
+  - `PythOracle` for real-time price feeds via Hermes API
+  - `PythFeeds` registry for price feed IDs
+  - Support for ETH, SOL, APT, SUI, STRK native token pricing
+
+- **Cross-Chain Routing**
+  - `CrossChainRouter` for finding optimal payment routes
+  - `FeeEstimator` for gas and bridge fee calculation
+  - `BridgeOrchestrator` for Wormhole integration
+
+- **Monitoring & Compliance**
+  - `AuditLogger` for payment audit trails
+  - `AlertManager` with configurable spending thresholds
+  - High-value transaction approval workflow (5-minute window)
+  - Anomaly detection for unusual transaction patterns
+  - Webhook notifications for alerts
+  - `ComplianceExporter` for CSV/JSON export
+
+- **Performance Optimizations**
+  - `NonceManager` - Client-side nonce tracking
+  - `TransactionQueue` - Batch transaction support
+  - `TransactionPoller` - 2-second confirmation polling
+  - `BalanceCache` - 10-second TTL caching
+
+- **Error Handling**
+  - `AgentPaymentError` with structured error codes
+  - Remediation suggestions for all error types
+  - Retry flag for transient errors
+  - Exponential backoff (2s, 4s, 8s) for retries
+
+- **React Hooks**
+  - `useAgentWallet` - Wallet state management
+  - `usePaymentHistory` - Transaction history with pagination
+  - `useSessionStatus` - Real-time session status
+
+- **Developer Experience**
+  - Full TypeScript support with `.d.ts` generation
+  - Dual ESM/CJS builds
+  - Comprehensive README documentation
+  - Example files for all major use cases
+
+### Test Coverage
+- 136 tests passing
+- Property-based tests with fast-check
+- Integration tests for full payment flows
+- Unit tests for all modules
+
+### Dependencies
+- `@veridex/sdk` - Core SDK integration
+- `ethers` - EVM interactions
+- `@solana/web3.js` - Solana interactions
+- `axios` - HTTP client for Pyth oracle
+- `zod` - Schema validation
+
+## [Unreleased]
+
+### Planned
+- Connection pooling for HTTP requests
+- Parallel route finding optimization
+- React hooks unit tests
+- Cross-browser testing
+- Migration guide from `@veridex/sdk`
+- DEX integration for token swapping
+- Cross-chain recovery mechanisms

package/MIGRATION.md

@@ -0,0 +1,307 @@
+# Migration Guide: @veridex/sdk to @veridex/agentic-payments
+
+This guide helps you migrate from using `@veridex/sdk` directly to using `@veridex/agentic-payments` for agent-based payment workflows.
+
+## Overview
+
+`@veridex/agentic-payments` is built on top of `@veridex/sdk` and provides:
+- **Session key management** with spending limits
+- **Automatic x402 payment handling**
+- **UCP credential provider** for payment tokenization
+- **MCP server** for LLM integration
+- **Multi-chain support** with unified interface
+
+## Installation
+
+```bash
+# Remove direct @veridex/sdk usage (if only used for payments)
+npm uninstall @veridex/sdk
+
+# Install the agentic payments SDK
+npm install @veridex/agentic-payments
+```
+
+> Note: `@veridex/agentic-payments` includes `@veridex/sdk` as a dependency, so you still have access to core SDK features.
+
+## Key Differences
+
+| Feature | @veridex/sdk | @veridex/agentic-payments |
+|---------|-------------|---------------------------|
+| Authentication | Direct passkey | Session keys with limits |
+| Payments | Manual signing | Automatic with retry |
+| Multi-chain | Chain-specific clients | Unified interface |
+| x402 | Manual handling | Automatic interception |
+| Monitoring | None | Audit logging, alerts |
+
+## Migration Steps
+
+### 1. Replace Direct Wallet Usage
+
+**Before (with @veridex/sdk):**
+
+```typescript
+import { VeridexSDK } from '@veridex/sdk';
+
+const sdk = await VeridexSDK.create({
+  chainPreset: 'base',
+  networkType: 'mainnet',
+});
+
+// Direct signing with master key
+const tx = await sdk.hub.executePayment({
+  recipient: '0x...',
+  amount: '10000000', // 10 USDC
+  token: '0x...',
+});
+```
+
+**After (with @veridex/agentic-payments):**
+
+```typescript
+import { createAgentWallet } from '@veridex/agentic-payments';
+
+const agent = await createAgentWallet({
+  masterCredential: {
+    credentialId: 'your-passkey-credential',
+    publicKeyX: BigInt('...'),
+    publicKeyY: BigInt('...'),
+    keyHash: '0x...',
+  },
+  session: {
+    dailyLimitUSD: 100,
+    perTransactionLimitUSD: 25,
+    expiryHours: 8,
+    allowedChains: [30], // Base
+  },
+});
+
+// Payment with automatic limit checking
+const receipt = await agent.pay({
+  recipient: '0x...',
+  amount: '10.00',
+  token: 'USDC',
+  chain: 30,
+});
+```
+
+### 2. Replace Manual x402 Handling
+
+**Before:**
+
+```typescript
+async function fetchWithPayment(url: string) {
+  let response = await fetch(url);
+  
+  if (response.status === 402) {
+    const paymentHeader = response.headers.get('X-Payment-Required');
+    const parsed = JSON.parse(atob(paymentHeader));
+    
+    // Manual payment logic
+    const tx = await sdk.hub.executePayment({
+      recipient: parsed.recipient,
+      amount: parsed.amount,
+      token: parsed.token,
+    });
+    
+    // Retry with proof
+    response = await fetch(url, {
+      headers: {
+        'X-Payment-Proof': tx.hash,
+      },
+    });
+  }
+  
+  return response;
+}
+```
+
+**After:**
+
+```typescript
+// Automatic handling built-in
+const response = await agent.fetch('https://api.paid-service.com/resource');
+// Payment automatically handled on 402 response
+```
+
+### 3. Replace Chain-Specific Clients
+
+**Before:**
+
+```typescript
+import { EVMClient } from '@veridex/sdk/chains/evm';
+import { SolanaClient } from '@veridex/sdk/chains/solana';
+
+const evmClient = new EVMClient({ /* config */ });
+const solanaClient = new SolanaClient({ /* config */ });
+
+// Different APIs for each chain
+const evmBalance = await evmClient.getBalance();
+const solBalance = await solanaClient.getBalance();
+```
+
+**After:**
+
+```typescript
+import { ChainClientFactory } from '@veridex/agentic-payments';
+
+// Unified interface
+const baseClient = ChainClientFactory.createClient('base', 'mainnet');
+const solanaClient = ChainClientFactory.createClient('solana', 'mainnet');
+
+// Same API for all chains
+const baseBalance = await baseClient.getBalance(address);
+const solBalance = await solanaClient.getBalance(address);
+
+// Or use multi-chain balance
+const allBalances = await agent.getMultiChainBalance();
+```
+
+### 4. Add Session Management
+
+Sessions are a new concept in `@veridex/agentic-payments`:
+
+```typescript
+// Check session status
+const status = agent.getSessionStatus();
+console.log(`Remaining: $${status.remainingDailyLimitUSD}`);
+console.log(`Expires: ${new Date(status.expiresAt)}`);
+
+// Revoke session (requires master key)
+await agent.revokeSession();
+```
+
+### 5. Add Monitoring
+
+**New features not available in @veridex/sdk:**
+
+```typescript
+// Subscribe to spending alerts
+agent.onSpendingAlert((alert) => {
+  console.log(`Alert: ${alert.type} - ${alert.message}`);
+});
+
+// Get payment history
+const history = await agent.getPaymentHistory({
+  limit: 50,
+  chain: 30,
+});
+
+// Export audit logs
+const csv = await agent.exportAuditLog('csv');
+```
+
+## React Migration
+
+### Before (manual state management):
+
+```typescript
+import { useState, useEffect } from 'react';
+import { VeridexSDK } from '@veridex/sdk';
+
+function PaymentComponent() {
+  const [sdk, setSdk] = useState(null);
+  
+  useEffect(() => {
+    VeridexSDK.create(config).then(setSdk);
+  }, []);
+  
+  // Manual state management...
+}
+```
+
+### After (with hooks):
+
+```typescript
+import { useAgentWallet, useSessionStatus, usePaymentHistory } from '@veridex/agentic-payments';
+
+function PaymentComponent() {
+  const { wallet, isLoading, error } = useAgentWallet(config);
+  const { status } = useSessionStatus(wallet);
+  const { history } = usePaymentHistory(wallet);
+  
+  return (
+    <div>
+      <p>Remaining: ${status?.remainingDailyLimitUSD}</p>
+      <button onClick={() => wallet?.pay(params)}>Pay</button>
+    </div>
+  );
+}
+```
+
+## API Changes Summary
+
+### Imports
+
+```typescript
+// Before
+import { VeridexSDK, EVMClient } from '@veridex/sdk';
+
+// After
+import { 
+  createAgentWallet,
+  ChainClientFactory,
+  SessionKeyManager,
+  X402Client,
+} from '@veridex/agentic-payments';
+```
+
+### Payment Parameters
+
+```typescript
+// Before
+await sdk.hub.executePayment({
+  recipient: '0x...',
+  amount: '10000000',  // Raw units
+  token: '0x...',      // Address
+});
+
+// After
+await agent.pay({
+  recipient: '0x...',
+  amount: '10.00',     // Human-readable
+  token: 'USDC',       // Symbol
+  chain: 30,           // Chain ID
+});
+```
+
+### Error Handling
+
+```typescript
+// Before - generic errors
+try {
+  await sdk.hub.executePayment(params);
+} catch (error) {
+  console.error(error.message);
+}
+
+// After - structured errors with remediation
+import { AgentPaymentError } from '@veridex/agentic-payments';
+
+try {
+  await agent.pay(params);
+} catch (error) {
+  if (error instanceof AgentPaymentError) {
+    console.log(`Code: ${error.code}`);
+    console.log(`Fix: ${error.remediation}`);
+    console.log(`Retryable: ${error.retryable}`);
+  }
+}
+```
+
+## Accessing Core SDK
+
+If you need access to the underlying SDK for advanced use cases:
+
+```typescript
+// The core SDK is re-exported
+import { VeridexSDK, EVMClient } from '@veridex/agentic-payments';
+
+// Or access via the agent wallet
+const coreClient = agent.getChainClient(30);
+```
+
+## Need Help?
+
+- [Full API Documentation](https://docs.veridex.network/agentic-payments)
+- [GitHub Issues](https://github.com/veridex/agent-payments/issues)
+- [Discord Community](https://discord.gg/veridex)