uvd-x402-sdk 2.16.1 → 2.17.0

package/dist/backend/index.d.mts

@@ -1,4 +1,4 @@
-import { m as X402Version, n as X402Header } from '../index-B_reIs-L.mjs';
+import { m as X402Version, n as X402Header } from '../index-BE5cH7oS.mjs';
 
 /**
  * uvd-x402-sdk - Backend Utilities
@@ -415,7 +415,7 @@ type BazaarCategory = 'api' | 'data' | 'ai' | 'media' | 'compute' | 'storage' |
 /**
  * Network/chain filter for discovery
  */
-type BazaarNetwork = 'base' | 'ethereum' | 'polygon' | 'arbitrum' | 'optimism' | 'avalanche' | 'celo' | 'hyperevm' | 'unichain' | 'monad' | 'solana' | 'fogo' | 'stellar' | 'near';
+type BazaarNetwork = 'base' | 'ethereum' | 'polygon' | 'arbitrum' | 'optimism' | 'avalanche' | 'celo' | 'hyperevm' | 'unichain' | 'monad' | 'scroll' | 'skale' | 'solana' | 'fogo' | 'stellar' | 'near' | 'algorand' | 'sui';
 /**
  * Token/asset filter for discovery
  */
@@ -1032,5 +1032,395 @@ declare function isEscrowExpired(escrow: EscrowPayment): boolean;
  * @returns Milliseconds until expiration (negative if expired)
  */
 declare function escrowTimeRemaining(escrow: EscrowPayment): number;
+/**
+ * ERC-8004 extension identifier
+ */
+declare const ERC8004_EXTENSION_ID = "8004-reputation";
+/**
+ * ERC-8004 contract addresses per network
+ */
+declare const ERC8004_CONTRACTS: Record<string, {
+    identityRegistry?: string;
+    reputationRegistry?: string;
+    validationRegistry?: string;
+}>;
+/**
+ * Network type for ERC-8004 operations
+ */
+type Erc8004Network = 'ethereum' | 'ethereum-sepolia';
+/**
+ * Proof of payment returned when settling with ERC-8004 extension
+ */
+interface ProofOfPayment {
+    /** Transaction hash of the settled payment */
+    transactionHash: string;
+    /** Block number where the transaction was included */
+    blockNumber: number;
+    /** Network where the payment was settled */
+    network: string;
+    /** The payer (consumer/client) address */
+    payer: string;
+    /** The payee (agent/resource owner) address */
+    payee: string;
+    /** Amount paid in token base units */
+    amount: string;
+    /** Token contract address */
+    token: string;
+    /** Unix timestamp of the block */
+    timestamp: number;
+    /** Keccak256 hash of the payment data for verification */
+    paymentHash: string;
+}
+/**
+ * Extended settle response with ERC-8004 proof of payment
+ */
+interface SettleResponseWithProof extends SettleResponse {
+    /** Proof of payment for ERC-8004 reputation submission */
+    proofOfPayment?: ProofOfPayment;
+}
+/**
+ * Agent identity from the Identity Registry
+ */
+interface AgentIdentity {
+    /** The agent's ID (ERC-721 tokenId) */
+    agentId: number;
+    /** Owner address of the agent NFT */
+    owner: string;
+    /** URI pointing to agent registration file */
+    agentUri: string;
+    /** Payment wallet address (if set) */
+    agentWallet?: string;
+    /** Network where the agent is registered */
+    network: Erc8004Network;
+}
+/**
+ * Agent registration file structure (resolved from agentURI)
+ */
+interface AgentRegistrationFile {
+    /** Type identifier */
+    type: string;
+    /** Agent name */
+    name: string;
+    /** Agent description */
+    description: string;
+    /** Image URL */
+    image?: string;
+    /** List of services the agent provides */
+    services: AgentService[];
+    /** Whether x402 payments are supported */
+    x402Support: boolean;
+    /** Whether the agent is active */
+    active: boolean;
+    /** List of registrations across chains */
+    registrations: AgentRegistration[];
+    /** Supported trust models */
+    supportedTrust: string[];
+}
+/**
+ * Agent service entry
+ */
+interface AgentService {
+    name: string;
+    endpoint: string;
+    version?: string;
+}
+/**
+ * Agent registration reference
+ */
+interface AgentRegistration {
+    agentId: number;
+    agentRegistry: string;
+}
+/**
+ * Reputation summary for an agent
+ */
+interface ReputationSummary {
+    /** Agent ID */
+    agentId: number;
+    /** Number of feedback entries */
+    count: number;
+    /** Aggregated value */
+    summaryValue: number;
+    /** Decimal places for summaryValue */
+    summaryValueDecimals: number;
+    /** Network */
+    network: Erc8004Network;
+}
+/**
+ * Individual feedback entry
+ */
+interface FeedbackEntry {
+    /** Client who submitted the feedback */
+    client: string;
+    /** Feedback index (1-indexed) */
+    feedbackIndex: number;
+    /** Feedback value */
+    value: number;
+    /** Value decimals */
+    valueDecimals: number;
+    /** Primary tag */
+    tag1: string;
+    /** Secondary tag */
+    tag2: string;
+    /** Whether this feedback was revoked */
+    isRevoked: boolean;
+}
+/**
+ * Parameters for submitting reputation feedback
+ */
+interface FeedbackParams {
+    /** The agent's ID (tokenId in Identity Registry) */
+    agentId: number;
+    /** Feedback value (e.g., 87 for 87/100) */
+    value: number;
+    /** Decimal places for value interpretation (0-18) */
+    valueDecimals?: number;
+    /** Primary categorization tag (e.g., "starred", "uptime") */
+    tag1?: string;
+    /** Secondary categorization tag */
+    tag2?: string;
+    /** Service endpoint that was used */
+    endpoint?: string;
+    /** URI to off-chain feedback file (IPFS, HTTPS) */
+    feedbackUri?: string;
+    /** Keccak256 hash of feedback content (for integrity) */
+    feedbackHash?: string;
+    /** Proof of payment (required for authorized feedback) */
+    proof?: ProofOfPayment;
+}
+/**
+ * Feedback request body for POST /feedback
+ */
+interface FeedbackRequest {
+    /** x402 protocol version */
+    x402Version: 1 | 2;
+    /** Network where feedback will be submitted */
+    network: Erc8004Network;
+    /** Feedback parameters */
+    feedback: FeedbackParams;
+}
+/**
+ * Feedback response from POST /feedback
+ */
+interface FeedbackResponse {
+    /** Whether the feedback was successfully submitted */
+    success: boolean;
+    /** Transaction hash of the feedback submission */
+    transaction?: string;
+    /** Feedback index assigned (1-indexed) */
+    feedbackIndex?: number;
+    /** Error message (if failed) */
+    error?: string;
+    /** Network where feedback was submitted */
+    network: Erc8004Network;
+}
+/**
+ * Reputation query response
+ */
+interface ReputationResponse {
+    agentId: number;
+    summary: ReputationSummary;
+    feedback?: FeedbackEntry[];
+    network: Erc8004Network;
+}
+/**
+ * Options for the ERC8004Client
+ */
+interface Erc8004ClientOptions {
+    /** Base URL of the facilitator (default: https://facilitator.ultravioletadao.xyz) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Client for ERC-8004 Trustless Agents API
+ *
+ * Provides methods for:
+ * - Querying agent identity
+ * - Querying agent reputation
+ * - Submitting reputation feedback
+ * - Revoking feedback
+ *
+ * @example
+ * ```ts
+ * const client = new Erc8004Client();
+ *
+ * // Get agent identity
+ * const identity = await client.getIdentity('ethereum', 42);
+ * console.log(identity.agentUri);
+ *
+ * // Get agent reputation
+ * const reputation = await client.getReputation('ethereum', 42);
+ * console.log(`Score: ${reputation.summary.summaryValue}`);
+ *
+ * // Submit feedback after payment
+ * const result = await client.submitFeedback({
+ *   x402Version: 1,
+ *   network: 'ethereum',
+ *   feedback: {
+ *     agentId: 42,
+ *     value: 95,
+ *     valueDecimals: 0,
+ *     tag1: 'quality',
+ *     proof: settleResponse.proofOfPayment,
+ *   },
+ * });
+ * ```
+ */
+declare class Erc8004Client {
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options?: Erc8004ClientOptions);
+    /**
+     * Get agent identity from the Identity Registry
+     *
+     * @param network - Network where agent is registered
+     * @param agentId - Agent's tokenId
+     * @returns Agent identity information
+     */
+    getIdentity(network: Erc8004Network, agentId: number): Promise<AgentIdentity>;
+    /**
+     * Resolve agent registration file from agentURI
+     *
+     * @param agentUri - URI pointing to agent registration file
+     * @returns Resolved agent registration file
+     */
+    resolveAgentUri(agentUri: string): Promise<AgentRegistrationFile>;
+    /**
+     * Get agent reputation from the Reputation Registry
+     *
+     * @param network - Network where agent is registered
+     * @param agentId - Agent's tokenId
+     * @param options - Query options (tag filters, include individual feedback)
+     * @returns Reputation summary and optionally individual feedback entries
+     */
+    getReputation(network: Erc8004Network, agentId: number, options?: {
+        tag1?: string;
+        tag2?: string;
+        includeFeedback?: boolean;
+    }): Promise<ReputationResponse>;
+    /**
+     * Submit reputation feedback for an agent
+     *
+     * Requires proof of payment for authorized feedback submission.
+     *
+     * @param request - Feedback request with agent ID, value, and proof
+     * @returns Feedback response with transaction hash
+     *
+     * @example
+     * ```ts
+     * // After settling a payment with ERC-8004 extension
+     * const settleResult = await facilitator.settle(payment, {
+     *   ...requirements,
+     *   extra: { '8004-reputation': { includeProof: true } },
+     * });
+     *
+     * // Submit feedback with proof of payment
+     * const feedback = await erc8004.submitFeedback({
+     *   x402Version: 1,
+     *   network: 'ethereum',
+     *   feedback: {
+     *     agentId: 42,
+     *     value: 95,  // 95/100
+     *     valueDecimals: 0,
+     *     tag1: 'quality',
+     *     tag2: 'response-time',
+     *     proof: settleResult.proofOfPayment,
+     *   },
+     * });
+     * ```
+     */
+    submitFeedback(request: FeedbackRequest): Promise<FeedbackResponse>;
+    /**
+     * Revoke previously submitted feedback
+     *
+     * Only the original submitter can revoke their feedback.
+     *
+     * @param network - Network where feedback was submitted
+     * @param agentId - Agent ID
+     * @param feedbackIndex - Index of feedback to revoke
+     * @returns Revocation result
+     */
+    revokeFeedback(network: Erc8004Network, agentId: number, feedbackIndex: number): Promise<FeedbackResponse>;
+    /**
+     * Get ERC-8004 contract addresses for a network
+     *
+     * @param network - Network to get contracts for
+     * @returns Contract addresses or undefined if not deployed
+     */
+    getContracts(network: Erc8004Network): typeof ERC8004_CONTRACTS[Erc8004Network] | undefined;
+    /**
+     * Check if ERC-8004 is available on a network
+     *
+     * @param network - Network to check
+     * @returns True if ERC-8004 contracts are deployed
+     */
+    isAvailable(network: string): network is Erc8004Network;
+    /**
+     * Get feedback endpoint metadata
+     *
+     * @returns Endpoint information for /feedback
+     */
+    getFeedbackMetadata(): Promise<{
+        endpoint: string;
+        supportedNetworks: Erc8004Network[];
+        version: string;
+    }>;
+    /**
+     * Append a response to existing feedback
+     *
+     * Allows agents to respond to feedback they received.
+     * Only the agent (identity owner) can append responses.
+     *
+     * @param network - Network where feedback was submitted
+     * @param agentId - Agent ID
+     * @param feedbackIndex - Index of feedback to respond to
+     * @param response - Response content
+     * @param responseUri - Optional URI to off-chain response file
+     * @returns Response result
+     *
+     * @example
+     * ```ts
+     * // Agent responds to feedback
+     * const result = await erc8004.appendResponse(
+     *   'ethereum',
+     *   42,
+     *   1,
+     *   'Thank you for your feedback! We have addressed the issue.',
+     * );
+     * ```
+     */
+    appendResponse(network: Erc8004Network, agentId: number, feedbackIndex: number, response: string, responseUri?: string): Promise<FeedbackResponse>;
+}
+/**
+ * Build payment requirements with ERC-8004 extension
+ *
+ * Adds the 8004-reputation extension to include proof of payment
+ * in settlement responses for reputation submission.
+ *
+ * @param options - Base payment requirements options
+ * @returns Payment requirements with ERC-8004 extension
+ *
+ * @example
+ * ```ts
+ * const requirements = buildErc8004PaymentRequirements({
+ *   amount: '1.00',
+ *   recipient: '0x...',
+ *   resource: 'https://api.example.com/service',
+ *   chainName: 'ethereum',
+ * });
+ *
+ * // Settlement will include proofOfPayment
+ * const result = await facilitator.settle(payment, requirements);
+ * console.log(result.proofOfPayment);
+ * ```
+ */
+declare function buildErc8004PaymentRequirements(options: PaymentRequirementsOptions): PaymentRequirements & {
+    extra: {
+        '8004-reputation': {
+            includeProof: boolean;
+        };
+    };
+};
 
-export { type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, type Dispute, type DisputeOutcome, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type PaymentRequirements, type PaymentRequirementsOptions, type RefundRequest, type RefundStatus, type RequestRefundOptions, type SettleRequest, type SettleResponse, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, isEscrowExpired, parsePaymentHeader };
+export { type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, isEscrowExpired, parsePaymentHeader };