pay-lobster 1.0.0

package/lib/erc8004/index.ts

@@ -0,0 +1,285 @@
+/**
+ * ERC-8004 Trustless Agents - Main Export
+ * 
+ * Complete integration for agent identity, reputation, and discovery.
+ * Designed for seamless integration with USDC payments and x402 protocol.
+ */
+
+export * from './constants';
+export * from './identity';
+export * from './reputation';
+export * from './discovery';
+
+import { ethers } from 'ethers';
+import { 
+  SupportedChain, 
+  AgentRegistration,
+  CHAIN_CONFIG,
+} from './constants';
+import { IdentityClient, createLobsterAgentRegistration, RegisteredAgent } from './identity';
+import { ReputationClient, FeedbackTemplates, ReputationSummary } from './reputation';
+import { DiscoveryService, DiscoveredAgent } from './discovery';
+
+export interface ERC8004ClientConfig {
+  chain: SupportedChain;
+  privateKey?: string;
+  paymentAddress?: string;
+  x402Endpoint?: string;
+}
+
+/**
+ * Unified ERC-8004 Client
+ * 
+ * Provides high-level API for agent registration, discovery, and trust management.
+ */
+export class ERC8004Client {
+  readonly chain: SupportedChain;
+  readonly identity: IdentityClient;
+  readonly reputation: ReputationClient;
+  readonly discovery: DiscoveryService;
+  
+  private config: ERC8004ClientConfig;
+  private myAgentId?: number;
+
+  constructor(config: ERC8004ClientConfig) {
+    this.chain = config.chain;
+    this.config = config;
+    
+    this.identity = new IdentityClient({
+      chain: config.chain,
+      privateKey: config.privateKey,
+    });
+    
+    this.reputation = new ReputationClient({
+      chain: config.chain,
+      privateKey: config.privateKey,
+    });
+    
+    this.discovery = new DiscoveryService({
+      chain: config.chain,
+      privateKey: config.privateKey,
+    });
+  }
+
+  /**
+   * Register this agent with the ERC-8004 Identity Registry
+   */
+  async registerAgent(options: {
+    name: string;
+    description: string;
+    image?: string;
+    capabilities: string[];
+    mcpEndpoint?: string;
+    a2aEndpoint?: string;
+  }): Promise<number> {
+    const registration = createLobsterAgentRegistration({
+      name: options.name,
+      description: options.description,
+      image: options.image,
+      chain: this.chain,
+      capabilities: options.capabilities,
+      paymentAddress: this.config.paymentAddress,
+      x402Endpoint: this.config.x402Endpoint,
+      escrowSupport: true,
+      mcpEndpoint: options.mcpEndpoint,
+      a2aEndpoint: options.a2aEndpoint,
+    });
+
+    this.myAgentId = await this.identity.register(registration);
+    return this.myAgentId;
+  }
+
+  /**
+   * Get my agent ID (if registered)
+   */
+  getMyAgentId(): number | undefined {
+    return this.myAgentId;
+  }
+
+  /**
+   * Set agent ID (if already registered)
+   */
+  setMyAgentId(agentId: number): void {
+    this.myAgentId = agentId;
+  }
+
+  /**
+   * Verify an agent before transacting
+   */
+  async verifyAgent(agentId: number) {
+    return this.discovery.verifyAgent(agentId);
+  }
+
+  /**
+   * Check if payment is safe for an agent
+   */
+  async isPaymentSafe(agentId: number, amountUsdc: number) {
+    return this.discovery.checkPaymentSafety(agentId, amountUsdc);
+  }
+
+  /**
+   * Post feedback after a transaction
+   */
+  async postFeedback(options: {
+    agentId: number;
+    score: number;
+    context: string;
+    txHash?: string;
+  }) {
+    return this.reputation.postFeedback({
+      agentId: options.agentId,
+      score: options.score,
+      context: options.context,
+      taskHash: options.txHash,
+    });
+  }
+
+  /**
+   * Post positive feedback after successful payment
+   */
+  async postPaymentSuccess(agentId: number, txHash: string, amount: string) {
+    const { score, context } = FeedbackTemplates.paymentSuccessful(txHash, amount);
+    return this.postFeedback({ agentId, score, context, txHash });
+  }
+
+  /**
+   * Post negative feedback after failed payment
+   */
+  async postPaymentFailure(agentId: number, reason: string) {
+    const { score, context } = FeedbackTemplates.paymentFailed(reason);
+    return this.postFeedback({ agentId, score, context });
+  }
+
+  /**
+   * Post feedback after escrow completion
+   */
+  async postEscrowFeedback(agentId: number, escrowId: string, outcome: 'released' | 'refunded' | 'disputed', reason?: string) {
+    if (outcome === 'disputed') {
+      const { score, context } = FeedbackTemplates.escrowDisputed(escrowId, reason || 'Unknown');
+      return this.postFeedback({ agentId, score, context });
+    }
+    const { score, context } = FeedbackTemplates.escrowCompleted(escrowId, outcome);
+    return this.postFeedback({ agentId, score, context });
+  }
+
+  /**
+   * Find agents for payment
+   */
+  async findPaymentAgents(minTrustScore?: number) {
+    return this.discovery.findPaymentAgents({ minTrustScore });
+  }
+
+  /**
+   * Find agents with escrow capability
+   */
+  async findEscrowAgents(minTrustLevel?: ReputationSummary['trustLevel']) {
+    return this.discovery.findEscrowAgents({ minTrustLevel });
+  }
+
+  /**
+   * Get my reputation summary
+   */
+  async getMyReputation(): Promise<ReputationSummary | null> {
+    if (!this.myAgentId) return null;
+    return this.reputation.getReputationSummary(this.myAgentId);
+  }
+
+  /**
+   * Get contract addresses for this chain
+   */
+  getContractAddresses() {
+    return CHAIN_CONFIG[this.chain].contracts;
+  }
+
+  /**
+   * Get the agent registry identifier
+   */
+  getAgentRegistry(): string {
+    return this.identity.getAgentRegistry();
+  }
+}
+
+/**
+ * Integration helper: Wrap x402 payment with trust verification
+ */
+export async function createTrustedX402Payment(options: {
+  erc8004: ERC8004Client;
+  targetAgentId: number;
+  amountUsdc: number;
+  endpoint: string;
+  paymentFn: () => Promise<{ success: boolean; txHash?: string; error?: string }>;
+}): Promise<{
+  success: boolean;
+  txHash?: string;
+  trustScore: number;
+  feedbackPosted: boolean;
+  error?: string;
+}> {
+  // Verify agent first
+  const verification = await options.erc8004.verifyAgent(options.targetAgentId);
+  
+  if (!verification.verified) {
+    return {
+      success: false,
+      trustScore: verification.trustScore,
+      feedbackPosted: false,
+      error: `Agent verification failed: ${verification.reasons.join(', ')}`,
+    };
+  }
+
+  // Check payment safety
+  const safety = await options.erc8004.isPaymentSafe(options.targetAgentId, options.amountUsdc);
+  
+  if (!safety.safe) {
+    console.warn(`Payment exceeds recommended limit: ${safety.reason}`);
+    // Continue anyway, but warn
+  }
+
+  // Execute payment
+  const result = await options.paymentFn();
+  
+  // Post feedback
+  let feedbackPosted = false;
+  try {
+    if (result.success && result.txHash) {
+      await options.erc8004.postPaymentSuccess(
+        options.targetAgentId,
+        result.txHash,
+        options.amountUsdc.toString()
+      );
+      feedbackPosted = true;
+    } else if (!result.success) {
+      await options.erc8004.postPaymentFailure(
+        options.targetAgentId,
+        result.error || 'Unknown error'
+      );
+      feedbackPosted = true;
+    }
+  } catch (e) {
+    console.warn('Failed to post feedback:', e);
+  }
+
+  return {
+    success: result.success,
+    txHash: result.txHash,
+    trustScore: verification.trustScore,
+    feedbackPosted,
+    error: result.error,
+  };
+}
+
+/**
+ * Quick setup helper
+ */
+export function createERC8004Client(
+  chain: SupportedChain,
+  privateKey?: string,
+  options?: { paymentAddress?: string; x402Endpoint?: string }
+): ERC8004Client {
+  return new ERC8004Client({
+    chain,
+    privateKey,
+    paymentAddress: options?.paymentAddress,
+    x402Endpoint: options?.x402Endpoint,
+  });
+}

package/lib/erc8004/reputation.ts

@@ -0,0 +1,368 @@
+/**
+ * ERC-8004 Reputation Registry Client
+ * 
+ * Post feedback, query reputation, and manage trust levels.
+ */
+
+import { ethers } from 'ethers';
+import {
+  CHAIN_CONFIG,
+  REPUTATION_REGISTRY_ABI,
+  SupportedChain,
+  Feedback,
+  ReputationSummary,
+  TRUST_LEVELS,
+} from './constants';
+
+export interface ReputationClientConfig {
+  chain: SupportedChain;
+  privateKey?: string;
+  provider?: ethers.Provider;
+}
+
+export interface FeedbackInput {
+  agentId: number;
+  score: number; // -100 to 100
+  context: string;
+  taskHash?: string; // Hash of the task/transaction being rated
+}
+
+export class ReputationClient {
+  private chain: SupportedChain;
+  private provider: ethers.Provider;
+  private signer?: ethers.Wallet;
+  private contract: ethers.Contract;
+  private readOnlyContract: ethers.Contract;
+
+  constructor(config: ReputationClientConfig) {
+    this.chain = config.chain;
+    const chainConfig = CHAIN_CONFIG[config.chain];
+    
+    this.provider = config.provider || new ethers.JsonRpcProvider(chainConfig.rpcUrl);
+    
+    if (config.privateKey) {
+      this.signer = new ethers.Wallet(config.privateKey, this.provider);
+      this.contract = new ethers.Contract(
+        chainConfig.contracts.reputationRegistry,
+        REPUTATION_REGISTRY_ABI,
+        this.signer
+      );
+    }
+    
+    this.readOnlyContract = new ethers.Contract(
+      chainConfig.contracts.reputationRegistry,
+      REPUTATION_REGISTRY_ABI,
+      this.provider
+    );
+  }
+
+  /**
+   * Post feedback for an agent
+   * 
+   * @param feedback Feedback to post
+   * @returns The feedbackId
+   */
+  async postFeedback(feedback: FeedbackInput): Promise<number> {
+    if (!this.contract || !this.signer) {
+      throw new Error('Signer required to post feedback');
+    }
+
+    // Validate score range
+    if (feedback.score < -100 || feedback.score > 100) {
+      throw new Error('Score must be between -100 and 100');
+    }
+
+    // Create task hash if not provided
+    const taskHash = feedback.taskHash 
+      ? ethers.id(feedback.taskHash)
+      : ethers.id(`feedback-${Date.now()}-${Math.random()}`);
+
+    console.log(`Posting feedback for agent ${feedback.agentId}: score=${feedback.score}`);
+    
+    const tx = await this.contract.postFeedback(
+      feedback.agentId,
+      feedback.score,
+      feedback.context,
+      taskHash
+    );
+    const receipt = await tx.wait();
+    
+    // Extract feedbackId from event
+    const event = receipt.logs.find((log: any) => {
+      try {
+        const parsed = this.contract.interface.parseLog(log);
+        return parsed?.name === 'FeedbackPosted';
+      } catch {
+        return false;
+      }
+    });
+    
+    if (!event) {
+      throw new Error('FeedbackPosted event not found');
+    }
+    
+    const parsed = this.contract.interface.parseLog(event);
+    const feedbackId = Number(parsed?.args?.feedbackId);
+    
+    console.log(`Feedback posted with ID: ${feedbackId}`);
+    
+    return feedbackId;
+  }
+
+  /**
+   * Post feedback after a successful x402 payment
+   * 
+   * Links the feedback to the payment transaction for verification
+   */
+  async postPaymentFeedback(options: {
+    agentId: number;
+    score: number;
+    context: string;
+    paymentTxHash: string;
+    paymentAmount: string;
+    serviceUsed: string;
+  }): Promise<number> {
+    const enrichedContext = JSON.stringify({
+      type: 'x402-payment-feedback',
+      context: options.context,
+      payment: {
+        txHash: options.paymentTxHash,
+        amount: options.paymentAmount,
+        service: options.serviceUsed,
+      },
+      timestamp: new Date().toISOString(),
+    });
+
+    return this.postFeedback({
+      agentId: options.agentId,
+      score: options.score,
+      context: enrichedContext,
+      taskHash: options.paymentTxHash,
+    });
+  }
+
+  /**
+   * Get a specific feedback entry
+   */
+  async getFeedback(feedbackId: number): Promise<Feedback | null> {
+    try {
+      const result = await this.readOnlyContract.getFeedback(feedbackId);
+      
+      return {
+        feedbackId,
+        agentId: Number(result.agentId),
+        author: result.author,
+        score: Number(result.score),
+        context: result.context,
+        taskHash: result.taskHash,
+        timestamp: Number(result.timestamp),
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get feedback count for an agent
+   */
+  async getFeedbackCount(agentId: number): Promise<number> {
+    const count = await this.readOnlyContract.getFeedbackCount(agentId);
+    return Number(count);
+  }
+
+  /**
+   * Get recent feedback for an agent
+   */
+  async getRecentFeedback(agentId: number, limit: number = 10): Promise<Feedback[]> {
+    const feedbackIds: bigint[] = await this.readOnlyContract.getFeedbackByAgent(
+      agentId,
+      0,
+      limit
+    );
+    
+    const feedbacks = await Promise.all(
+      feedbackIds.map(id => this.getFeedback(Number(id)))
+    );
+    
+    return feedbacks.filter((f): f is Feedback => f !== null);
+  }
+
+  /**
+   * Get average score for an agent
+   */
+  async getAverageScore(agentId: number): Promise<{ average: number; count: number }> {
+    const [average, count] = await this.readOnlyContract.getAverageScore(agentId);
+    return {
+      average: Number(average),
+      count: Number(count),
+    };
+  }
+
+  /**
+   * Get comprehensive reputation summary for an agent
+   */
+  async getReputationSummary(agentId: number): Promise<ReputationSummary> {
+    const [{ average, count }, recentFeedback] = await Promise.all([
+      this.getAverageScore(agentId),
+      this.getRecentFeedback(agentId, 5),
+    ]);
+
+    // Determine trust level based on score and feedback count
+    let trustLevel: ReputationSummary['trustLevel'] = 'untrusted';
+    
+    if (count >= TRUST_LEVELS.verified.minFeedback && average >= TRUST_LEVELS.verified.minScore) {
+      trustLevel = 'verified';
+    } else if (count >= TRUST_LEVELS.trusted.minFeedback && average >= TRUST_LEVELS.trusted.minScore) {
+      trustLevel = 'trusted';
+    } else if (count >= TRUST_LEVELS.established.minFeedback && average >= TRUST_LEVELS.established.minScore) {
+      trustLevel = 'established';
+    } else if (count >= TRUST_LEVELS.emerging.minFeedback && average >= TRUST_LEVELS.emerging.minScore) {
+      trustLevel = 'emerging';
+    } else if (count >= TRUST_LEVELS.new.minFeedback && average >= TRUST_LEVELS.new.minScore) {
+      trustLevel = 'new';
+    }
+
+    return {
+      agentId,
+      averageScore: average,
+      totalFeedback: count,
+      recentFeedback,
+      trustLevel,
+    };
+  }
+
+  /**
+   * Authorize an address to post feedback for your agent
+   */
+  async authorizeFeedbackAuthor(agentId: number, author: string): Promise<void> {
+    if (!this.contract) {
+      throw new Error('Signer required');
+    }
+    
+    const tx = await this.contract.authorizeFeedback(agentId, author);
+    await tx.wait();
+    
+    console.log(`Authorized ${author} to post feedback for agent ${agentId}`);
+  }
+
+  /**
+   * Revoke feedback authorization
+   */
+  async revokeFeedbackAuthorization(agentId: number, author: string): Promise<void> {
+    if (!this.contract) {
+      throw new Error('Signer required');
+    }
+    
+    const tx = await this.contract.revokeFeedbackAuthorization(agentId, author);
+    await tx.wait();
+    
+    console.log(`Revoked feedback authorization for ${author} on agent ${agentId}`);
+  }
+
+  /**
+   * Check if an address is authorized to post feedback
+   */
+  async isAuthorizedFeedbackAuthor(agentId: number, author: string): Promise<boolean> {
+    return this.readOnlyContract.isAuthorizedFeedbackAuthor(agentId, author);
+  }
+
+  /**
+   * Check if an agent meets minimum trust requirements
+   */
+  async meetsMinimumTrust(agentId: number, minLevel: ReputationSummary['trustLevel']): Promise<boolean> {
+    const summary = await this.getReputationSummary(agentId);
+    
+    const levelOrder: ReputationSummary['trustLevel'][] = [
+      'untrusted', 'new', 'emerging', 'established', 'trusted', 'verified'
+    ];
+    
+    return levelOrder.indexOf(summary.trustLevel) >= levelOrder.indexOf(minLevel);
+  }
+
+  /**
+   * Calculate trust score for payment decisions
+   * 
+   * Returns a 0-100 score combining reputation and feedback volume
+   */
+  async calculateTrustScore(agentId: number): Promise<number> {
+    const summary = await this.getReputationSummary(agentId);
+    
+    // Weight: 70% average score, 30% volume bonus
+    const scoreComponent = Math.max(0, (summary.averageScore + 100) / 2); // Normalize -100..100 to 0..100
+    const volumeBonus = Math.min(30, summary.totalFeedback * 0.3); // Max 30 points from volume
+    
+    return Math.round(scoreComponent * 0.7 + volumeBonus);
+  }
+}
+
+/**
+ * Standard feedback templates for common scenarios
+ */
+export const FeedbackTemplates = {
+  // Positive feedback
+  excellentService: (details?: string) => ({
+    score: 95,
+    context: `Excellent service. ${details || 'Highly recommended.'}`,
+  }),
+  
+  goodService: (details?: string) => ({
+    score: 75,
+    context: `Good service. ${details || 'Would use again.'}`,
+  }),
+  
+  satisfactory: (details?: string) => ({
+    score: 50,
+    context: `Satisfactory service. ${details || 'Met expectations.'}`,
+  }),
+  
+  // Negative feedback
+  poorService: (details?: string) => ({
+    score: -50,
+    context: `Poor service. ${details || 'Did not meet expectations.'}`,
+  }),
+  
+  failed: (details?: string) => ({
+    score: -90,
+    context: `Service failed. ${details || 'Would not recommend.'}`,
+  }),
+  
+  // Payment-specific
+  paymentSuccessful: (txHash: string, amount: string) => ({
+    score: 80,
+    context: JSON.stringify({
+      type: 'payment-feedback',
+      result: 'success',
+      txHash,
+      amount,
+    }),
+  }),
+  
+  paymentFailed: (reason: string) => ({
+    score: -70,
+    context: JSON.stringify({
+      type: 'payment-feedback',
+      result: 'failed',
+      reason,
+    }),
+  }),
+  
+  // Escrow-specific
+  escrowCompleted: (escrowId: string, outcome: 'released' | 'refunded') => ({
+    score: outcome === 'released' ? 85 : 40,
+    context: JSON.stringify({
+      type: 'escrow-feedback',
+      escrowId,
+      outcome,
+    }),
+  }),
+  
+  escrowDisputed: (escrowId: string, reason: string) => ({
+    score: -30,
+    context: JSON.stringify({
+      type: 'escrow-feedback',
+      escrowId,
+      outcome: 'disputed',
+      reason,
+    }),
+  }),
+};