pay-lobster 1.0.0

package/lib/easy.ts.bak

@@ -0,0 +1,352 @@
+/**
+ * Lobster Pay - Easy Mode
+ * 
+ * One-liner APIs for the most common operations.
+ * Designed for humans AND AI agents to use with minimal setup.
+ */
+
+import { CircleClient, CircleClientConfig } from './circle-client';
+import { X402Client } from './x402-client';
+import { EscrowManager } from './escrow';
+import { EscrowTemplates } from './escrow-templates';
+import { ERC8004Client, createERC8004Client } from './erc8004';
+import { ContactManager } from './contacts';
+import { InvoiceManager } from './invoices';
+
+// Re-export everything for convenience
+export * from './circle-client';
+export * from './x402-client';
+export * from './x402-server';
+export * from './escrow';
+export * from './escrow-templates';
+export * from './condition-builder';
+export * from './erc8004';
+export * from './contacts';
+export * from './invoices';
+export * from './approvals';
+export * from './notifications';
+export * from './analytics';
+export * from './tips';
+export * from './commission';
+
+/**
+ * Quick Setup - Get started in 3 lines
+ */
+export interface QuickConfig {
+  // Circle credentials (required)
+  circleApiKey: string;
+  circleEntitySecret: string;
+  
+  // Network (default: testnet)
+  network?: 'testnet' | 'mainnet';
+  chain?: string;
+  
+  // Optional: ERC-8004 for trust
+  privateKey?: string;
+  
+  // Optional: Your agent info
+  agentName?: string;
+  agentDescription?: string;
+}
+
+export interface LobsterAgent {
+  // Core
+  circle: CircleClient;
+  x402: X402Client;
+  escrow: EscrowManager;
+  contacts: ContactManager;
+  invoices: InvoiceManager;
+  
+  // Trust (if privateKey provided)
+  trust?: ERC8004Client;
+  agentId?: number;
+  
+  // Easy methods
+  balance: () => Promise<string>;
+  send: (to: string, amount: string, memo?: string) => Promise<string>;
+  pay: (url: string, maxAmount?: string) => Promise<any>;
+  createEscrow: (template: string, params: any) => Promise<any>;
+  
+  // Status
+  status: () => Promise<AgentStatus>;
+}
+
+export interface AgentStatus {
+  walletId: string;
+  chain: string;
+  balance: string;
+  agentId?: number;
+  trustScore?: number;
+  reputation?: {
+    score: number;
+    feedbackCount: number;
+    level: string;
+  };
+}
+
+/**
+ * Create a Lobster Pay with one function call
+ * 
+ * @example
+ * ```typescript
+ * const agent = await createLobsterAgent({
+ *   circleApiKey: process.env.CIRCLE_API_KEY!,
+ *   circleEntitySecret: process.env.CIRCLE_ENTITY_SECRET!,
+ * });
+ * 
+ * // Check balance
+ * console.log(await agent.balance());
+ * 
+ * // Send USDC
+ * await agent.send('0x...', '10');
+ * 
+ * // Pay for an API call
+ * const data = await agent.pay('https://api.example.com/premium');
+ * ```
+ */
+export async function createLobsterAgent(config: QuickConfig): Promise<LobsterAgent> {
+  const network = config.network || 'testnet';
+  const chain = config.chain || (network === 'testnet' ? 'ETH-SEPOLIA' : 'ETH-MAINNET');
+  
+  // Initialize Circle client
+  const circle = new CircleClient({
+    apiKey: config.circleApiKey,
+    entitySecret: config.circleEntitySecret,
+  });
+  
+  // Setup wallet
+  await circle.ensureWalletSet();
+  const walletId = circle.getWalletId()!;
+  
+  // Initialize other services
+  const x402 = new X402Client({
+    circleClient: circle,
+    walletId,
+    chain,
+  });
+  
+  const escrow = new EscrowManager({ circleClient: circle });
+  const contacts = new ContactManager();
+  const invoices = new InvoiceManager();
+  
+  // Initialize trust layer if privateKey provided
+  let trust: ERC8004Client | undefined;
+  let agentId: number | undefined;
+  
+  if (config.privateKey) {
+    const erc8004Chain = chain.includes('SEPOLIA') ? 'ETH-SEPOLIA' : 
+                         chain.includes('AMOY') ? 'MATIC-AMOY' :
+                         chain.includes('BASE') ? 'BASE-SEPOLIA' : 'ETH-SEPOLIA';
+    
+    trust = createERC8004Client(
+      erc8004Chain as any,
+      config.privateKey,
+      { paymentAddress: await circle.getReceiveAddress(chain) }
+    );
+    
+    // Register agent if name provided
+    if (config.agentName) {
+      try {
+        agentId = await trust.registerAgent({
+          name: config.agentName,
+          description: config.agentDescription || `${config.agentName} - USDC payment agent`,
+          capabilities: ['usdc-payments', 'x402', 'escrow'],
+        });
+        console.log(`Registered as Agent #${agentId}`);
+      } catch (e) {
+        console.warn('Agent registration failed (may already be registered):', e);
+      }
+    }
+  }
+  
+  // Build the agent interface
+  const agent: LobsterAgent = {
+    circle,
+    x402,
+    escrow,
+    contacts,
+    invoices,
+    trust,
+    agentId,
+    
+    // Easy balance check
+    balance: async () => {
+      const balances = await circle.getAllUSDCBalances();
+      const chainBalance = balances.find((b: any) => b.chain === chain);
+      return chainBalance?.amount || '0';
+    },
+    
+    // Easy send
+    send: async (to: string, amount: string, memo?: string) => {
+      // Check if 'to' is a contact name
+      let address = to;
+      if (!to.startsWith('0x')) {
+        const contact = await contacts.resolveRecipient(to, chain);
+        if (contact) {
+          address = contact.address;
+        } else {
+          throw new Error(`Unknown recipient: ${to}. Use an address or add them as a contact.`);
+        }
+      }
+      
+      const tx = await circle.sendUSDC({
+        fromWalletId: walletId,
+        toAddress: address,
+        amount,
+        chain,
+      });
+      
+      return tx.id;
+    },
+    
+    // Easy x402 payment
+    pay: async (url: string, maxAmount: string = '10') => {
+      const response = await x402.fetch(url, {
+        method: 'GET',
+        maxPayment: maxAmount,
+      });
+      
+      if (!response.ok) {
+        throw new Error(`Payment failed: ${response.statusText}`);
+      }
+      
+      return response.json();
+    },
+    
+    // Easy escrow creation
+    createEscrow: async (template: string, params: any) => {
+      const templateFn = (EscrowTemplates as any)[template];
+      if (!templateFn) {
+        throw new Error(`Unknown template: ${template}. Available: freelance, realEstate, commerce, p2p`);
+      }
+      
+      return escrow.createFromTemplate(templateFn(params));
+    },
+    
+    // Status check
+    status: async () => {
+      const balance = await agent.balance();
+      
+      const status: AgentStatus = {
+        walletId,
+        chain,
+        balance,
+        agentId,
+      };
+      
+      if (trust && agentId) {
+        const rep = await trust.getMyReputation();
+        if (rep) {
+          status.trustScore = await trust.reputation.calculateTrustScore(agentId);
+          status.reputation = {
+            score: rep.averageScore,
+            feedbackCount: rep.totalFeedback,
+            level: rep.trustLevel,
+          };
+        }
+      }
+      
+      return status;
+    },
+  };
+  
+  return agent;
+}
+
+/**
+ * Even simpler: Environment-based setup
+ * 
+ * Just set CIRCLE_API_KEY and CIRCLE_ENTITY_SECRET env vars
+ */
+export async function quickStart(): Promise<LobsterAgent> {
+  const apiKey = process.env.CIRCLE_API_KEY;
+  const entitySecret = process.env.CIRCLE_ENTITY_SECRET;
+  
+  if (!apiKey || !entitySecret) {
+    throw new Error(
+      'Missing environment variables. Set:\n' +
+      '  CIRCLE_API_KEY=your-api-key\n' +
+      '  CIRCLE_ENTITY_SECRET=your-entity-secret\n\n' +
+      'Get credentials at: https://console.circle.com'
+    );
+  }
+  
+  return createLobsterAgent({
+    circleApiKey: apiKey,
+    circleEntitySecret: entitySecret,
+    privateKey: process.env.PRIVATE_KEY,
+    agentName: process.env.AGENT_NAME,
+    network: (process.env.NETWORK as any) || 'testnet',
+  });
+}
+
+/**
+ * CLI helper - parse command line for common operations
+ */
+export async function runCLI(args: string[]): Promise<void> {
+  const agent = await quickStart();
+  const [command, ...rest] = args;
+  
+  switch (command) {
+    case 'balance':
+      console.log(`Balance: ${await agent.balance()} USDC`);
+      break;
+      
+    case 'send':
+      if (rest.length < 2) {
+        console.error('Usage: send <to> <amount>');
+        process.exit(1);
+      }
+      const txId = await agent.send(rest[0], rest[1]);
+      console.log(`Sent! Transaction: ${txId}`);
+      break;
+      
+    case 'pay':
+      if (rest.length < 1) {
+        console.error('Usage: pay <url> [max-amount]');
+        process.exit(1);
+      }
+      const data = await agent.pay(rest[0], rest[1] || '10');
+      console.log('Response:', JSON.stringify(data, null, 2));
+      break;
+      
+    case 'status':
+      const status = await agent.status();
+      console.log('Agent Status:');
+      console.log(`  Wallet: ${status.walletId}`);
+      console.log(`  Chain: ${status.chain}`);
+      console.log(`  Balance: ${status.balance} USDC`);
+      if (status.agentId) {
+        console.log(`  Agent ID: ${status.agentId}`);
+        console.log(`  Trust Score: ${status.trustScore}`);
+        console.log(`  Reputation: ${status.reputation?.level} (${status.reputation?.feedbackCount} reviews)`);
+      }
+      break;
+      
+    default:
+      console.log(`
+Lobster Pay CLI
+
+Commands:
+  balance              Check your USDC balance
+  send <to> <amount>   Send USDC to an address or contact
+  pay <url> [max]      Pay for an API call via x402
+  status               Show agent status and trust score
+
+Environment Variables:
+  CIRCLE_API_KEY       Your Circle API key
+  CIRCLE_ENTITY_SECRET Your Circle entity secret
+  PRIVATE_KEY          (Optional) For ERC-8004 trust features
+  AGENT_NAME           (Optional) Register with this name
+  NETWORK              (Optional) testnet or mainnet
+
+Get started:
+  1. Get credentials at https://console.circle.com
+  2. Set environment variables
+  3. Run: npx lobster-pay balance
+      `);
+  }
+}
+
+// Export templates for easy access
+export { EscrowTemplates } from './escrow-templates';

package/lib/erc8004/constants.ts

@@ -0,0 +1,175 @@
+/**
+ * ERC-8004 Constants & Contract Addresses
+ * 
+ * Official registry deployments from https://github.com/erc-8004/erc-8004-contracts
+ */
+
+export const ERC8004_CONTRACTS = {
+  // Testnets (same addresses across all testnets)
+  testnet: {
+    identityRegistry: '0x8004A818BFB912233c491871b3d84c89A494BD9e',
+    reputationRegistry: '0x8004B663056A597Dffe9eCcC1965A193B7388713',
+  },
+  // Mainnets (same addresses across all mainnets)
+  mainnet: {
+    identityRegistry: '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432',
+    reputationRegistry: '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63',
+  },
+} as const;
+
+export const CHAIN_CONFIG = {
+  'ETH-SEPOLIA': {
+    chainId: 11155111,
+    namespace: 'eip155',
+    rpcUrl: 'https://rpc.sepolia.org',
+    explorer: 'https://sepolia.etherscan.io',
+    contracts: ERC8004_CONTRACTS.testnet,
+  },
+  'BASE-SEPOLIA': {
+    chainId: 84532,
+    namespace: 'eip155',
+    rpcUrl: 'https://sepolia.base.org',
+    explorer: 'https://sepolia.basescan.org',
+    contracts: ERC8004_CONTRACTS.testnet,
+  },
+  'MATIC-AMOY': {
+    chainId: 80002,
+    namespace: 'eip155',
+    rpcUrl: 'https://rpc-amoy.polygon.technology',
+    explorer: 'https://amoy.polygonscan.com',
+    contracts: ERC8004_CONTRACTS.testnet,
+  },
+  'ARB-SEPOLIA': {
+    chainId: 421614,
+    namespace: 'eip155',
+    rpcUrl: 'https://sepolia-rollup.arbitrum.io/rpc',
+    explorer: 'https://sepolia.arbiscan.io',
+    contracts: ERC8004_CONTRACTS.testnet,
+  },
+  // Mainnets
+  'ETH-MAINNET': {
+    chainId: 1,
+    namespace: 'eip155',
+    rpcUrl: 'https://eth.llamarpc.com',
+    explorer: 'https://etherscan.io',
+    contracts: ERC8004_CONTRACTS.mainnet,
+  },
+  'BASE-MAINNET': {
+    chainId: 8453,
+    namespace: 'eip155',
+    rpcUrl: 'https://mainnet.base.org',
+    explorer: 'https://basescan.org',
+    contracts: ERC8004_CONTRACTS.mainnet,
+  },
+} as const;
+
+export type SupportedChain = keyof typeof CHAIN_CONFIG;
+
+// Identity Registry ABI (ERC-721 + URIStorage extension)
+export const IDENTITY_REGISTRY_ABI = [
+  // ERC-721 standard
+  'function balanceOf(address owner) view returns (uint256)',
+  'function ownerOf(uint256 tokenId) view returns (address)',
+  'function tokenURI(uint256 tokenId) view returns (string)',
+  'function totalSupply() view returns (uint256)',
+  'function tokenByIndex(uint256 index) view returns (uint256)',
+  'function tokenOfOwnerByIndex(address owner, uint256 index) view returns (uint256)',
+  
+  // ERC-8004 Identity Registry
+  'function register(string uri) returns (uint256 agentId)',
+  'function setAgentURI(uint256 agentId, string uri)',
+  'function getAgentURI(uint256 agentId) view returns (string)',
+  'function getAgentOwner(uint256 agentId) view returns (address)',
+  'function getAgentsByOwner(address owner) view returns (uint256[])',
+  
+  // Events
+  'event AgentRegistered(uint256 indexed agentId, address indexed owner, string uri)',
+  'event AgentURIUpdated(uint256 indexed agentId, string uri)',
+  'event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)',
+] as const;
+
+// Reputation Registry ABI
+export const REPUTATION_REGISTRY_ABI = [
+  // Post feedback
+  'function postFeedback(uint256 agentId, int8 score, string context, bytes32 taskHash) returns (uint256 feedbackId)',
+  'function postFeedbackWithProof(uint256 agentId, int8 score, string context, bytes32 taskHash, bytes proof) returns (uint256 feedbackId)',
+  
+  // Query feedback
+  'function getFeedback(uint256 feedbackId) view returns (tuple(uint256 agentId, address author, int8 score, string context, bytes32 taskHash, uint256 timestamp))',
+  'function getFeedbackCount(uint256 agentId) view returns (uint256)',
+  'function getFeedbackByAgent(uint256 agentId, uint256 offset, uint256 limit) view returns (uint256[])',
+  'function getAverageScore(uint256 agentId) view returns (int256 average, uint256 count)',
+  
+  // Authorization
+  'function authorizeFeedback(uint256 agentId, address author)',
+  'function revokeFeedbackAuthorization(uint256 agentId, address author)',
+  'function isAuthorizedFeedbackAuthor(uint256 agentId, address author) view returns (bool)',
+  
+  // Events
+  'event FeedbackPosted(uint256 indexed feedbackId, uint256 indexed agentId, address indexed author, int8 score)',
+  'event FeedbackAuthorizationGranted(uint256 indexed agentId, address indexed author)',
+  'event FeedbackAuthorizationRevoked(uint256 indexed agentId, address indexed author)',
+] as const;
+
+// Agent Registration File schema (per ERC-8004 spec)
+export interface AgentRegistration {
+  type: 'https://eips.ethereum.org/EIPS/eip-8004#registration-v1';
+  name: string;
+  description: string;
+  image?: string;
+  services: AgentService[];
+  x402Support: boolean;
+  active: boolean;
+  registrations: {
+    agentId: number;
+    agentRegistry: string; // {namespace}:{chainId}:{identityRegistry}
+  }[];
+  supportedTrust: ('reputation' | 'crypto-economic' | 'tee-attestation' | 'zkml')[];
+  
+  // Pay Lobster specific extensions
+  usdcAgent?: {
+    version: string;
+    capabilities: string[];
+    supportedChains: string[];
+    paymentAddress?: string;
+    escrowSupport: boolean;
+    x402Endpoint?: string;
+  };
+}
+
+export interface AgentService {
+  name: string;
+  endpoint: string;
+  version?: string;
+  skills?: string[];
+  domains?: string[];
+}
+
+// Feedback types
+export interface Feedback {
+  feedbackId: number;
+  agentId: number;
+  author: string;
+  score: number; // -100 to 100
+  context: string;
+  taskHash: string;
+  timestamp: number;
+}
+
+export interface ReputationSummary {
+  agentId: number;
+  averageScore: number;
+  totalFeedback: number;
+  recentFeedback: Feedback[];
+  trustLevel: 'untrusted' | 'new' | 'emerging' | 'established' | 'trusted' | 'verified';
+}
+
+// Trust level thresholds
+export const TRUST_LEVELS = {
+  untrusted: { minScore: -100, minFeedback: 0 },
+  new: { minScore: 0, minFeedback: 1 },
+  emerging: { minScore: 25, minFeedback: 5 },
+  established: { minScore: 50, minFeedback: 20 },
+  trusted: { minScore: 75, minFeedback: 50 },
+  verified: { minScore: 90, minFeedback: 100 },
+} as const;