@agirails/sdk 2.2.0 → 2.2.2

package/dist/erc8004/ERC8004Bridge.js

@@ -0,0 +1,325 @@
+"use strict";
+/**
+ * ERC-8004 Identity Bridge
+ *
+ * READ-ONLY access to ERC-8004 Identity Registry.
+ * Resolves agent IDs to wallet addresses for ACTP payments.
+ *
+ * SECURITY NOTES:
+ * - All operations are view functions (no gas costs)
+ * - Safe to call without signer
+ * - Caches results to minimize RPC calls
+ * - Handles network errors gracefully
+ *
+ * @example
+ * ```typescript
+ * const bridge = new ERC8004Bridge({ network: 'base-sepolia' });
+ *
+ * // Check if agent exists
+ * const exists = await bridge.verifyAgent('12345');
+ *
+ * // Get wallet for payment
+ * const wallet = await bridge.getAgentWallet('12345');
+ *
+ * // Get full agent info
+ * const agent = await bridge.resolveAgent('12345');
+ * ```
+ *
+ * @module erc8004/ERC8004Bridge
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC8004Bridge = void 0;
+const ethers_1 = require("ethers");
+const erc8004_1 = require("../types/erc8004");
+// ============================================================================
+// ERC8004Bridge
+// ============================================================================
+/**
+ * Bridge for reading from ERC-8004 Identity Registry.
+ *
+ * Provides methods to:
+ * - Verify agent existence
+ * - Get agent wallet address for payments
+ * - Resolve full agent info including metadata
+ * - List agents owned by an address
+ */
+class ERC8004Bridge {
+    constructor(config) {
+        this.network = config.network;
+        this.fetchFn = config.fetchFn ?? fetch;
+        this.cacheTimeMs = config.cacheTimeMs ?? 60000;
+        this.metadataTimeoutMs = config.metadataTimeoutMs ?? 10000;
+        this.cache = new Map();
+        // Use injected contract for testing
+        if (config._testContract) {
+            this.provider = null;
+            this.registry = config._testContract;
+            return;
+        }
+        // Setup provider
+        const rpcUrl = config.rpcUrl ?? erc8004_1.ERC8004_DEFAULT_RPC[config.network];
+        this.provider = new ethers_1.ethers.JsonRpcProvider(rpcUrl);
+        // Setup registry contract
+        const registryAddress = config.registryAddress ?? erc8004_1.ERC8004_IDENTITY_REGISTRY[config.network];
+        if (registryAddress === ethers_1.ethers.ZeroAddress) {
+            console.warn(`[ERC8004] Registry not deployed on ${config.network}. Using zero address.`);
+        }
+        this.registry = new ethers_1.ethers.Contract(registryAddress, erc8004_1.ERC8004_IDENTITY_ABI, this.provider);
+    }
+    // ==========================================================================
+    // Public Methods
+    // ==========================================================================
+    /**
+     * Verify agent exists in ERC-8004 Identity Registry.
+     *
+     * Safe to call frequently - uses cache and is a view function.
+     *
+     * @param agentId - ERC-8004 agent ID (uint256 as string)
+     * @returns true if agent exists, false otherwise
+     */
+    async verifyAgent(agentId) {
+        // Validate format first
+        if (!this.isValidAgentId(agentId)) {
+            return false;
+        }
+        // Check cache
+        const cached = this.cache.get(agentId);
+        if (cached && cached.expiresAt > Date.now()) {
+            return true;
+        }
+        try {
+            const owner = await this.registry.ownerOf(agentId);
+            return owner !== ethers_1.ethers.ZeroAddress;
+        }
+        catch {
+            // ownerOf reverts for non-existent tokens (ERC-721 standard)
+            return false;
+        }
+    }
+    /**
+     * Get wallet address for receiving payments.
+     *
+     * Wallet priority:
+     * 1. metadata.paymentAddress (explicit payment destination)
+     * 2. metadata.wallet (alternative field name)
+     * 3. owner address (fallback)
+     *
+     * @param agentId - ERC-8004 agent ID
+     * @returns Checksummed wallet address
+     * @throws ERC8004Error if agent not found
+     */
+    async getAgentWallet(agentId) {
+        const agent = await this.resolveAgent(agentId);
+        return agent.wallet;
+    }
+    /**
+     * Resolve full agent info from ERC-8004.
+     *
+     * Fetches on-chain data (owner, agentURI) and off-chain metadata.
+     * Results are cached for cacheTimeMs.
+     *
+     * @param agentId - ERC-8004 agent ID
+     * @returns Full agent info including metadata
+     * @throws ERC8004Error if agent not found or invalid ID
+     */
+    async resolveAgent(agentId) {
+        // Check cache first
+        const cached = this.cache.get(agentId);
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.agent;
+        }
+        // Validate format
+        if (!this.isValidAgentId(agentId)) {
+            throw new erc8004_1.ERC8004Error(`Invalid agent ID format: "${agentId}"`, erc8004_1.ERC8004ErrorCode.INVALID_AGENT_ID, agentId);
+        }
+        // Fetch on-chain data
+        let owner;
+        let agentURI;
+        try {
+            [owner, agentURI] = await Promise.all([
+                this.registry.ownerOf(agentId),
+                this.registry.getAgentURI(agentId),
+            ]);
+        }
+        catch (error) {
+            // Check if it's a "nonexistent token" error
+            const isNotFound = error instanceof Error &&
+                (error.message.includes('nonexistent') ||
+                    error.message.includes('ERC721') ||
+                    error.message.includes('invalid token'));
+            if (isNotFound) {
+                throw new erc8004_1.ERC8004Error(`Agent ${agentId} not found in ERC-8004 registry`, erc8004_1.ERC8004ErrorCode.AGENT_NOT_FOUND, agentId);
+            }
+            throw new erc8004_1.ERC8004Error(`Failed to fetch agent ${agentId}: ${error instanceof Error ? error.message : 'Unknown error'}`, erc8004_1.ERC8004ErrorCode.NETWORK_ERROR, agentId, error instanceof Error ? error : undefined);
+        }
+        // Check owner is valid
+        if (owner === ethers_1.ethers.ZeroAddress) {
+            throw new erc8004_1.ERC8004Error(`Agent ${agentId} not found in ERC-8004 registry`, erc8004_1.ERC8004ErrorCode.AGENT_NOT_FOUND, agentId);
+        }
+        // Fetch metadata (may return undefined if fetch fails)
+        const metadata = await this.fetchMetadata(agentURI, agentId);
+        // Determine wallet address
+        // Priority: paymentAddress > wallet > owner
+        let walletAddress = owner;
+        if (metadata?.paymentAddress && this.isValidAddress(metadata.paymentAddress)) {
+            walletAddress = metadata.paymentAddress;
+        }
+        else if (metadata?.wallet && this.isValidAddress(metadata.wallet)) {
+            walletAddress = metadata.wallet;
+        }
+        // Build agent object
+        const agent = {
+            agentId,
+            owner: ethers_1.ethers.getAddress(owner), // Checksummed
+            wallet: ethers_1.ethers.getAddress(walletAddress), // Checksummed
+            agentURI,
+            metadata,
+            network: this.network,
+        };
+        // Cache result
+        this.cache.set(agentId, {
+            agent,
+            expiresAt: Date.now() + this.cacheTimeMs,
+        });
+        return agent;
+    }
+    /**
+     * Get all agent IDs owned by an address.
+     *
+     * @param owner - Owner address to query
+     * @returns Array of agent IDs (may be empty)
+     */
+    async getAgentsByOwner(owner) {
+        if (!this.isValidAddress(owner)) {
+            return [];
+        }
+        try {
+            const balance = await this.registry.balanceOf(owner);
+            const balanceNum = Number(balance);
+            if (balanceNum === 0) {
+                return [];
+            }
+            const agentIds = [];
+            for (let i = 0; i < balanceNum; i++) {
+                const agentId = await this.registry.tokenOfOwnerByIndex(owner, i);
+                agentIds.push(agentId.toString());
+            }
+            return agentIds;
+        }
+        catch (error) {
+            console.warn(`[ERC8004] Failed to get agents for owner ${owner}:`, error);
+            return [];
+        }
+    }
+    /**
+     * Clear all cached entries.
+     * Useful for testing or forcing fresh data.
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache statistics (for debugging).
+     */
+    getCacheStats() {
+        return {
+            size: this.cache.size,
+            network: this.network,
+        };
+    }
+    // ==========================================================================
+    // Private Methods
+    // ==========================================================================
+    /**
+     * Validate agent ID format.
+     * Agent IDs are uint256 values (0 to 2^256-1).
+     */
+    isValidAgentId(agentId) {
+        if (!agentId || typeof agentId !== 'string') {
+            return false;
+        }
+        // Must not look like an Ethereum address or URL
+        if (agentId.startsWith('0x') || agentId.includes('://')) {
+            return false;
+        }
+        try {
+            const bn = BigInt(agentId);
+            return bn >= 0n && bn < 2n ** 256n;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Validate Ethereum address format.
+     */
+    isValidAddress(address) {
+        try {
+            ethers_1.ethers.getAddress(address);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Fetch and parse metadata from agentURI.
+     *
+     * Handles:
+     * - IPFS URIs (ipfs://...)
+     * - HTTPS URIs
+     * - Timeout protection
+     * - Parse errors
+     *
+     * Returns undefined on any failure (never throws).
+     */
+    async fetchMetadata(agentURI, agentId) {
+        if (!agentURI) {
+            return undefined;
+        }
+        try {
+            // Convert IPFS URI to HTTP gateway
+            let url = agentURI;
+            if (url.startsWith('ipfs://')) {
+                const cid = url.slice(7);
+                url = `https://ipfs.io/ipfs/${cid}`;
+            }
+            // Validate URL
+            if (!url.startsWith('http://') && !url.startsWith('https://')) {
+                console.warn(`[ERC8004] Invalid agentURI scheme for ${agentId}: ${url}`);
+                return undefined;
+            }
+            // Fetch with timeout
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.metadataTimeoutMs);
+            try {
+                const response = await this.fetchFn(url, {
+                    headers: { Accept: 'application/json' },
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    console.warn(`[ERC8004] Metadata fetch failed for ${agentId}: HTTP ${response.status}`);
+                    return undefined;
+                }
+                const data = await response.json();
+                return data;
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        }
+        catch (error) {
+            // Log but don't throw - metadata is optional
+            const errorMessage = error instanceof Error
+                ? error.name === 'AbortError'
+                    ? 'timeout'
+                    : error.message
+                : 'unknown error';
+            console.warn(`[ERC8004] Metadata fetch failed for ${agentId}: ${errorMessage}`);
+            return undefined;
+        }
+    }
+}
+exports.ERC8004Bridge = ERC8004Bridge;
+//# sourceMappingURL=ERC8004Bridge.js.map

package/dist/erc8004/ERC8004Bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ERC8004Bridge.js","sourceRoot":"","sources":["../../src/erc8004/ERC8004Bridge.ts"],"names":[],"mappings":"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"}

package/dist/erc8004/ReputationReporter.d.ts

@@ -0,0 +1,223 @@
+/**
+ * ERC-8004 Reputation Reporter
+ *
+ * WRITES to ERC-8004 Reputation Registry after ACTP settlements.
+ *
+ * CRITICAL SECURITY NOTES:
+ * 1. Requires signer (pays gas) - typically the requester
+ * 2. Caller MUST NOT be agent owner (ERC-8004 restriction)
+ * 3. Uses feedbackHash = keccak256(txId) for replay protection
+ * 4. Failures are logged but NEVER block ACTP settlement
+ * 5. Local dedup prevents double-reporting in same session
+ *
+ * WHEN TO CALL:
+ * - reportSettlement(): After successful release() (state = SETTLED)
+ * - reportDispute(): After dispute resolution
+ *
+ * FAILURE HANDLING:
+ * - All methods return null on failure (never throw)
+ * - Settlement/dispute already succeeded - reputation is bonus
+ * - Log warnings for debugging
+ *
+ * @example
+ * ```typescript
+ * const reporter = new ReputationReporter({
+ *   network: 'base-sepolia',
+ *   signer: requesterWallet,
+ * });
+ *
+ * // After successful release
+ * const txHash = await reporter.reportSettlement({
+ *   agentId: '12345',
+ *   txId: result.txId,
+ *   capability: 'code_generation',
+ * });
+ *
+ * if (txHash) {
+ *   console.log('Reputation reported:', txHash);
+ * } else {
+ *   console.warn('Report failed (settlement still succeeded)');
+ * }
+ * ```
+ *
+ * @module erc8004/ReputationReporter
+ */
+import { Signer } from 'ethers';
+import { ERC8004Network } from '../types/erc8004';
+/**
+ * Transaction receipt interface for reputation reports.
+ */
+interface TransactionReceipt {
+    hash: string;
+    blockNumber: number;
+    gasUsed: bigint;
+}
+/**
+ * Transaction response interface.
+ */
+interface TransactionResponse {
+    wait(): Promise<TransactionReceipt>;
+}
+/**
+ * Interface for ERC-8004 Reputation Registry contract.
+ * Used for testing with mock implementations.
+ */
+export interface IERC8004ReputationRegistry {
+    giveFeedback(agentId: string, value: number, valueDecimals: number, tag1: string, tag2: string, endpoint: string, feedbackURI: string, feedbackHash: string, txOptions?: {
+        gasLimit?: bigint;
+    }): Promise<TransactionResponse>;
+    getSummary(agentId: string, clientAddresses: string[], tag1: string, tag2: string): Promise<[bigint, bigint, number]>;
+    revokeLatest(agentId: string, feedbackIndex: bigint): Promise<TransactionResponse>;
+}
+/**
+ * Configuration for ReputationReporter.
+ */
+export interface ReputationReporterConfig {
+    /** Target network */
+    network: ERC8004Network;
+    /** Signer for transactions (pays gas) */
+    signer: Signer;
+    /** Override registry address (optional, for testing) */
+    registryAddress?: string;
+    /** Gas limit override (optional) */
+    gasLimit?: bigint;
+    /**
+     * Injected contract instance (optional, for testing).
+     * If provided, skips creating a real ethers Contract.
+     * @internal
+     */
+    _testContract?: IERC8004ReputationRegistry;
+}
+/**
+ * Parameters for reporting a successful settlement.
+ */
+export interface ReportSettlementParams {
+    /** ERC-8004 agent ID */
+    agentId: string;
+    /** ACTP transaction ID (used for replay protection) */
+    txId: string;
+    /** Agent capability (e.g., 'code_generation', 'data_analysis') */
+    capability?: string;
+    /** Service endpoint (optional) */
+    endpoint?: string;
+    /** Link to transaction details (optional, IPFS or HTTPS) */
+    feedbackURI?: string;
+}
+/**
+ * Parameters for reporting a dispute resolution.
+ */
+export interface ReportDisputeParams {
+    /** ERC-8004 agent ID */
+    agentId: string;
+    /** ACTP transaction ID */
+    txId: string;
+    /** true if agent won the dispute, false if requester won */
+    agentWon: boolean;
+    /** Agent capability (optional) */
+    capability?: string;
+    /** Dispute reason/details (optional, stored as feedbackURI) */
+    reason?: string;
+}
+/**
+ * Result of a reputation report.
+ */
+export interface ReportResult {
+    /** Transaction hash */
+    txHash: string;
+    /** Block number */
+    blockNumber: number;
+    /** Gas used */
+    gasUsed: bigint;
+}
+/**
+ * Reporter for submitting ACTP settlement outcomes to ERC-8004 Reputation.
+ *
+ * Designed to never block or fail the main ACTP flow.
+ * All errors are caught and logged, returning null on failure.
+ */
+export declare class ReputationReporter {
+    private readonly registry;
+    private readonly signer;
+    private readonly network;
+    private readonly gasLimit?;
+    /**
+     * Track reported txIds to prevent double-reporting in same session.
+     * Note: This is in-memory only, so restarts allow re-reporting.
+     * On-chain, feedbackHash provides permanent dedup.
+     */
+    private readonly reportedTxIds;
+    constructor(config: ReputationReporterConfig);
+    /**
+     * Report successful ACTP settlement to ERC-8004 Reputation.
+     *
+     * Call this AFTER release() succeeds. Failure here does NOT affect settlement.
+     *
+     * Reports:
+     * - value: 1 (positive feedback)
+     * - valueDecimals: 0 (binary)
+     * - tag1: 'actp_settled'
+     * - tag2: capability
+     * - feedbackHash: keccak256(txId)
+     *
+     * @param params - Settlement details
+     * @returns ReportResult if successful, null if failed
+     */
+    reportSettlement(params: ReportSettlementParams): Promise<ReportResult | null>;
+    /**
+     * Report ACTP dispute resolution to ERC-8004 Reputation.
+     *
+     * Call this after dispute is resolved (either party won).
+     *
+     * Reports:
+     * - value: 1 if agent won, -1 if requester won
+     * - valueDecimals: 0 (binary)
+     * - tag1: 'actp_dispute_won' or 'actp_dispute_lost'
+     * - tag2: capability
+     * - feedbackHash: keccak256(txId)
+     *
+     * @param params - Dispute details
+     * @returns ReportResult if successful, null if failed
+     */
+    reportDispute(params: ReportDisputeParams): Promise<ReportResult | null>;
+    /**
+     * Get reputation summary for an agent.
+     *
+     * This is a READ operation (no gas cost).
+     *
+     * @param agentId - ERC-8004 agent ID
+     * @param tag1 - Filter by tag1 (optional, e.g., 'actp_settled')
+     * @returns Summary if successful, null if failed
+     */
+    getAgentReputation(agentId: string, tag1?: string): Promise<{
+        count: number;
+        score: number;
+    } | null>;
+    /**
+     * Check if a transaction was already reported in this session.
+     *
+     * Note: This is local-only. For on-chain check, you'd need to
+     * query the feedbackHash mapping (not exposed in standard interface).
+     *
+     * @param txId - ACTP transaction ID
+     */
+    isReported(txId: string): boolean;
+    /**
+     * Clear local dedup cache.
+     * Use when starting new session or for testing.
+     */
+    clearReportedCache(): void;
+    /**
+     * Get reporter statistics.
+     */
+    getStats(): {
+        network: ERC8004Network;
+        reportedCount: number;
+    };
+    /**
+     * Log error in consistent format.
+     * NEVER throws - errors are informational only.
+     */
+    private logError;
+}
+export {};
+//# sourceMappingURL=ReputationReporter.d.ts.map

package/dist/erc8004/ReputationReporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReputationReporter.d.ts","sourceRoot":"","sources":["../../src/erc8004/ReputationReporter.ts"],"names":[],"mappings":"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"}