@agirails/sdk 2.2.0 → 2.2.2

package/dist/types/erc8004.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * ERC-8004 Trustless Agents - SDK Types
+ *
+ * Types and constants for ERC-8004 integration.
+ *
+ * SECURITY NOTES:
+ * - Identity Registry is read-only (safe, no gas)
+ * - Reputation Registry writes require gas (requester pays)
+ * - Replay protection via feedbackHash = keccak256(txId)
+ * - ERC-8004 restriction: feedback submitter ≠ agent owner
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-8004
+ * @module types/erc8004
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTP_FEEDBACK_TAGS = exports.ERC8004_DEFAULT_RPC = exports.ERC8004_REPUTATION_ABI = exports.ERC8004_IDENTITY_ABI = exports.ERC8004_REPUTATION_REGISTRY = exports.ERC8004_IDENTITY_REGISTRY = exports.ERC8004Error = exports.ERC8004ErrorCode = void 0;
+// ============================================================================
+// Errors
+// ============================================================================
+/**
+ * ERC-8004 error codes.
+ */
+var ERC8004ErrorCode;
+(function (ERC8004ErrorCode) {
+    // Identity errors
+    ERC8004ErrorCode["AGENT_NOT_FOUND"] = "AGENT_NOT_FOUND";
+    ERC8004ErrorCode["INVALID_AGENT_ID"] = "INVALID_AGENT_ID";
+    ERC8004ErrorCode["WALLET_NOT_FOUND"] = "WALLET_NOT_FOUND";
+    ERC8004ErrorCode["METADATA_FETCH_FAILED"] = "METADATA_FETCH_FAILED";
+    // Reputation errors
+    ERC8004ErrorCode["REPORT_FAILED"] = "REPORT_FAILED";
+    ERC8004ErrorCode["ALREADY_REPORTED"] = "ALREADY_REPORTED";
+    ERC8004ErrorCode["NOT_AUTHORIZED"] = "NOT_AUTHORIZED";
+    // Network errors
+    ERC8004ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ERC8004ErrorCode["INVALID_NETWORK"] = "INVALID_NETWORK";
+})(ERC8004ErrorCode || (exports.ERC8004ErrorCode = ERC8004ErrorCode = {}));
+/**
+ * Custom error for ERC-8004 operations.
+ */
+class ERC8004Error extends Error {
+    constructor(message, code, agentId, cause) {
+        super(message);
+        this.code = code;
+        this.agentId = agentId;
+        this.cause = cause;
+        this.name = 'ERC8004Error';
+        // Maintain proper stack trace in V8
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ERC8004Error);
+        }
+    }
+}
+exports.ERC8004Error = ERC8004Error;
+// ============================================================================
+// Registry Addresses
+// ============================================================================
+/**
+ * ERC-8004 Identity Registry addresses per network.
+ *
+ * Canonical CREATE2 addresses from: https://github.com/erc-8004/erc-8004-contracts
+ * Vanity prefix 0x8004 ensures same address across all EVM chains.
+ */
+exports.ERC8004_IDENTITY_REGISTRY = {
+    ethereum: '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432', // Ethereum Mainnet
+    base: '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432', // Base Mainnet
+    'base-sepolia': '0x8004A818BFB912233c491871b3d84c89A494BD9e', // Base Sepolia
+};
+/**
+ * ERC-8004 Reputation Registry addresses per network.
+ *
+ * Canonical CREATE2 addresses from: https://github.com/erc-8004/erc-8004-contracts
+ * Vanity prefix 0x8004 ensures same address across all EVM chains.
+ */
+exports.ERC8004_REPUTATION_REGISTRY = {
+    ethereum: '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63', // Ethereum Mainnet
+    base: '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63', // Base Mainnet
+    'base-sepolia': '0x8004B663056A597Dffe9eCcC1965A193B7388713', // Base Sepolia
+};
+// ============================================================================
+// ABI Fragments (minimal, view-only for Bridge)
+// ============================================================================
+/**
+ * Minimal ABI for ERC-8004 Identity Registry.
+ * Only includes view functions needed by ERC8004Bridge.
+ */
+exports.ERC8004_IDENTITY_ABI = [
+    'function ownerOf(uint256 agentId) view returns (address)',
+    'function getAgentURI(uint256 agentId) view returns (string)',
+    'function balanceOf(address owner) view returns (uint256)',
+    'function tokenOfOwnerByIndex(address owner, uint256 index) view returns (uint256)',
+];
+/**
+ * Minimal ABI for ERC-8004 Reputation Registry.
+ * Includes both read and write functions.
+ */
+exports.ERC8004_REPUTATION_ABI = [
+    // Write
+    'function giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash) external',
+    'function revokeLatest(uint256 agentId, uint64 feedbackIndex) external',
+    // Read
+    'function getSummary(uint256 agentId, address[] clientAddresses, string tag1, string tag2) view returns (uint256 count, int256 summaryValue, uint8 summaryValueDecimals)',
+    'function readFeedback(uint256 agentId, uint64 feedbackIndex) view returns (tuple(int128 value, uint8 valueDecimals, string tag1, string tag2, bool isRevoked, uint64 feedbackIndex))',
+];
+// ============================================================================
+// Default RPC URLs
+// ============================================================================
+/**
+ * Default RPC URLs for each network.
+ * Used when no custom RPC is provided.
+ */
+exports.ERC8004_DEFAULT_RPC = {
+    ethereum: 'https://eth.llamarpc.com',
+    base: 'https://mainnet.base.org',
+    'base-sepolia': 'https://sepolia.base.org',
+};
+// ============================================================================
+// ACTP-specific constants
+// ============================================================================
+/**
+ * ACTP feedback tags for ERC-8004 Reputation.
+ */
+exports.ACTP_FEEDBACK_TAGS = {
+    /** Successful settlement */
+    SETTLED: 'actp_settled',
+    /** Agent won dispute */
+    DISPUTE_WON: 'actp_dispute_won',
+    /** Agent lost dispute (requester won) */
+    DISPUTE_LOST: 'actp_dispute_lost',
+};
+//# sourceMappingURL=erc8004.js.map

package/dist/types/erc8004.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"erc8004.js","sourceRoot":"","sources":["../../src/types/erc8004.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAgJH,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E;;GAEG;AACH,IAAY,gBAeX;AAfD,WAAY,gBAAgB;IAC1B,kBAAkB;IAClB,uDAAmC,CAAA;IACnC,yDAAqC,CAAA;IACrC,yDAAqC,CAAA;IACrC,mEAA+C,CAAA;IAE/C,oBAAoB;IACpB,mDAA+B,CAAA;IAC/B,yDAAqC,CAAA;IACrC,qDAAiC,CAAA;IAEjC,iBAAiB;IACjB,mDAA+B,CAAA;IAC/B,uDAAmC,CAAA;AACrC,CAAC,EAfW,gBAAgB,gCAAhB,gBAAgB,QAe3B;AAED;;GAEG;AACH,MAAa,YAAa,SAAQ,KAAK;IACrC,YACE,OAAe,EACC,IAAsB,EACtB,OAAgB,EAChB,KAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAkB;QACtB,YAAO,GAAP,OAAO,CAAS;QAChB,UAAK,GAAL,KAAK,CAAQ;QAG7B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAE3B,oCAAoC;QACpC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;CACF;AAfD,oCAeC;AAED,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;GAKG;AACU,QAAA,yBAAyB,GAAmC;IACvE,QAAQ,EAAE,4CAA4C,EAAE,mBAAmB;IAC3E,IAAI,EAAE,4CAA4C,EAAE,eAAe;IACnE,cAAc,EAAE,4CAA4C,EAAE,eAAe;CAC9E,CAAC;AAEF;;;;;GAKG;AACU,QAAA,2BAA2B,GAAmC;IACzE,QAAQ,EAAE,4CAA4C,EAAE,mBAAmB;IAC3E,IAAI,EAAE,4CAA4C,EAAE,eAAe;IACnE,cAAc,EAAE,4CAA4C,EAAE,eAAe;CAC9E,CAAC;AAEF,+EAA+E;AAC/E,gDAAgD;AAChD,+EAA+E;AAE/E;;;GAGG;AACU,QAAA,oBAAoB,GAAG;IAClC,0DAA0D;IAC1D,6DAA6D;IAC7D,0DAA0D;IAC1D,mFAAmF;CAC3E,CAAC;AAEX;;;GAGG;AACU,QAAA,sBAAsB,GAAG;IACpC,QAAQ;IACR,yKAAyK;IACzK,uEAAuE;IACvE,OAAO;IACP,yKAAyK;IACzK,sLAAsL;CAC9K,CAAC;AAEX,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;GAGG;AACU,QAAA,mBAAmB,GAAmC;IACjE,QAAQ,EAAE,0BAA0B;IACpC,IAAI,EAAE,0BAA0B;IAChC,cAAc,EAAE,0BAA0B;CAC3C,CAAC;AAEF,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E;;GAEG;AACU,QAAA,kBAAkB,GAAG;IAChC,4BAA4B;IAC5B,OAAO,EAAE,cAAc;IAEvB,wBAAwB;IACxB,WAAW,EAAE,kBAAkB;IAE/B,yCAAyC;IACzC,YAAY,EAAE,mBAAmB;CACzB,CAAC"}

package/dist/types/index.d.ts

@@ -8,4 +8,7 @@ export * from './message';
 export * from './eip712';
 export * from './agent';
 export * from './did';
+export * from './adapter';
+export * from './x402';
+export * from './erc8004';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC"}

package/dist/types/index.js

@@ -24,6 +24,9 @@ __exportStar(require("./message"), exports);
 __exportStar(require("./eip712"), exports);
 __exportStar(require("./agent"), exports);
 __exportStar(require("./did"), exports);
+__exportStar(require("./adapter"), exports);
+__exportStar(require("./x402"), exports);
+__exportStar(require("./erc8004"), exports);
 // Note: storage and archive types are not yet implemented in this version
 // export * from './storage';
 // export * from './archive';

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,gDAA8B;AAC9B,2CAAyB;AACzB,4CAA0B;AAC1B,2CAAyB;AACzB,0CAAwB;AACxB,wCAAsB;AACtB,0EAA0E;AAC1E,6BAA6B;AAC7B,6BAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,gDAA8B;AAC9B,2CAAyB;AACzB,4CAA0B;AAC1B,2CAAyB;AACzB,0CAAwB;AACxB,wCAAsB;AACtB,4CAA0B;AAC1B,yCAAuB;AACvB,4CAA0B;AAC1B,0EAA0E;AAC1E,6BAA6B;AAC7B,6BAA6B"}

package/dist/types/transaction.d.ts

@@ -19,6 +19,12 @@ export interface Transaction {
     attestationUID: string;
     metadata: string;
     platformFeeBpsLocked: number;
+    /**
+     * ERC-8004 agent token ID (optional).
+     * 0 or undefined = not an ERC-8004 agent.
+     * See ADR-001 for architectural rationale.
+     */
+    agentId?: string;
 }
 /**
  * Parameters for creating a new transaction
@@ -30,6 +36,12 @@ export interface CreateTransactionParams {
     deadline: number;
     disputeWindow: number;
     metadata?: string;
+    /**
+     * ERC-8004 agent token ID (optional).
+     * Set to 0 or omit if provider is not registered in ERC-8004 Identity Registry.
+     * See ADR-001 for architectural rationale.
+     */
+    agentId?: string;
 }
 /**
  * Dispute resolution split

package/dist/types/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/types/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/types/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;CAC5B"}

package/dist/types/x402.d.ts

@@ -0,0 +1,162 @@
+/**
+ * X402 Protocol Types and Constants
+ *
+ * Defines types for the HTTP 402 Payment Required protocol implementation.
+ * X402 enables atomic, instant API payments - NO escrow, NO state machine.
+ *
+ * Key difference from ACTP:
+ * - ACTP: escrow → state machine → disputes → explicit release
+ * - x402: atomic payment → instant settlement → done
+ *
+ * Flow:
+ * 1. Client requests protected HTTPS endpoint → gets 402 response
+ * 2. Parse X-Payment-* headers (address, amount, network, deadline)
+ * 3. Execute atomic USDC transfer to provider (no escrow!)
+ * 4. Retry request with tx hash as proof
+ * 5. Return response - payment complete, no release needed
+ *
+ * Use x402 for: Simple API calls, instant delivery, low-value transactions
+ * Use ACTP for: Complex services, dispute protection, high-value transactions
+ *
+ * @module types/x402
+ */
+/**
+ * Standard X402 payment headers sent in 402 responses.
+ *
+ * These headers inform the client how to pay for the requested resource.
+ */
+export declare const X402_HEADERS: {
+    /** Indicates payment is required (must be "true") */
+    readonly REQUIRED: "x-payment-required";
+    /** Provider's wallet address (0x-prefixed) */
+    readonly ADDRESS: "x-payment-address";
+    /** Amount in USDC wei (6 decimals) */
+    readonly AMOUNT: "x-payment-amount";
+    /** Network identifier (base-mainnet or base-sepolia) */
+    readonly NETWORK: "x-payment-network";
+    /** Token type (currently only USDC) */
+    readonly TOKEN: "x-payment-token";
+    /** Unix timestamp deadline for payment */
+    readonly DEADLINE: "x-payment-deadline";
+    /** Optional: Dispute window in seconds */
+    readonly DISPUTE_WINDOW: "x-dispute-window";
+    /** Optional: Service identifier for tracking */
+    readonly SERVICE_ID: "x-service-id";
+};
+/**
+ * Proof headers sent when retrying with payment.
+ *
+ * After creating an ACTP transaction, the client includes these
+ * headers to prove payment was made.
+ */
+export declare const X402_PROOF_HEADERS: {
+    /** ACTP transaction ID (bytes32 hex) */
+    readonly TX_ID: "x-payment-tx-id";
+    /** ACTP escrow ID (bytes32 hex) */
+    readonly ESCROW_ID: "x-payment-escrow-id";
+};
+/** Supported networks for x402 payments */
+export type X402Network = 'base-mainnet' | 'base-sepolia';
+/** Supported tokens (currently only USDC) */
+export type X402Token = 'USDC';
+/**
+ * Parsed payment headers from HTTP 402 response.
+ *
+ * Contains all information needed to create an ACTP transaction
+ * for the requested resource.
+ */
+export interface X402PaymentHeaders {
+    /** Whether payment is required (always true for valid 402) */
+    required: boolean;
+    /** Provider's wallet address (0x-prefixed, 42 chars) */
+    paymentAddress: string;
+    /** Amount in USDC wei (6 decimals, as string) */
+    amount: string;
+    /** Target network */
+    network: X402Network;
+    /** Token type */
+    token: X402Token;
+    /** Unix timestamp deadline for accepting payment */
+    deadline: number;
+    /** Optional: Dispute window in seconds */
+    disputeWindow?: number;
+    /** Optional: Service identifier for tracking/debugging */
+    serviceId?: string;
+}
+/**
+ * Error codes for X402 protocol failures.
+ *
+ * Used to identify specific error types and enable proper error handling.
+ */
+export declare enum X402ErrorCode {
+    /** Response status was not 402 */
+    NOT_402_RESPONSE = "NOT_402_RESPONSE",
+    /** Required X-Payment-* headers are missing */
+    MISSING_HEADERS = "MISSING_HEADERS",
+    /** X-Payment-Amount is invalid (not a number, negative, etc.) */
+    INVALID_AMOUNT = "INVALID_AMOUNT",
+    /** X-Payment-Address is not a valid Ethereum address */
+    INVALID_ADDRESS = "INVALID_ADDRESS",
+    /** X-Payment-Network is not a recognized network */
+    INVALID_NETWORK = "INVALID_NETWORK",
+    /** Server's network doesn't match client's expected network */
+    NETWORK_MISMATCH = "NETWORK_MISMATCH",
+    /** Failed to create ACTP transaction or link escrow */
+    PAYMENT_FAILED = "PAYMENT_FAILED",
+    /** Retry request with proof headers failed */
+    RETRY_FAILED = "RETRY_FAILED",
+    /** X-Payment-Deadline has already passed */
+    DEADLINE_PASSED = "DEADLINE_PASSED",
+    /** HTTPS protocol required but HTTP used */
+    INSECURE_PROTOCOL = "INSECURE_PROTOCOL"
+}
+/**
+ * Custom error for X402 protocol failures.
+ *
+ * Provides structured error information for debugging and error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await x402Adapter.pay({ to: 'https://api.example.com', amount: '10' });
+ * } catch (error) {
+ *   if (error instanceof X402Error) {
+ *     if (error.code === X402ErrorCode.NETWORK_MISMATCH) {
+ *       console.error('Wrong network:', error.message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class X402Error extends Error {
+    readonly code: X402ErrorCode;
+    readonly response?: Response | undefined;
+    readonly name = "X402Error";
+    /**
+     * Creates a new X402Error.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param response - Optional HTTP response that triggered the error
+     */
+    constructor(message: string, code: X402ErrorCode, response?: Response | undefined);
+    /**
+     * Creates a detailed error message with code.
+     */
+    toString(): string;
+}
+/**
+ * Type guard to check if an error is an X402Error.
+ *
+ * @param error - Error to check
+ * @returns True if error is X402Error
+ */
+export declare function isX402Error(error: unknown): error is X402Error;
+/**
+ * Validates that a network string is a valid X402Network.
+ *
+ * @param network - Network string to validate
+ * @returns True if valid X402Network
+ */
+export declare function isValidX402Network(network: string): network is X402Network;
+//# sourceMappingURL=x402.d.ts.map

package/dist/types/x402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../src/types/x402.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH;;;;GAIG;AACH,eAAO,MAAM,YAAY;IACvB,qDAAqD;;IAErD,8CAA8C;;IAE9C,sCAAsC;;IAEtC,wDAAwD;;IAExD,uCAAuC;;IAEvC,0CAA0C;;IAE1C,0CAA0C;;IAE1C,gDAAgD;;CAExC,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;IAC7B,wCAAwC;;IAExC,mCAAmC;;CAE3B,CAAC;AAMX,2CAA2C;AAC3C,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,cAAc,CAAC;AAE1D,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAElB,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAC;IAEvB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IAEf,qBAAqB;IACrB,OAAO,EAAE,WAAW,CAAC;IAErB,iBAAiB;IACjB,KAAK,EAAE,SAAS,CAAC;IAEjB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IAEjB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;GAIG;AACH,oBAAY,aAAa;IACvB,kCAAkC;IAClC,gBAAgB,qBAAqB;IAErC,+CAA+C;IAC/C,eAAe,oBAAoB;IAEnC,iEAAiE;IACjE,cAAc,mBAAmB;IAEjC,wDAAwD;IACxD,eAAe,oBAAoB;IAEnC,oDAAoD;IACpD,eAAe,oBAAoB;IAEnC,+DAA+D;IAC/D,gBAAgB,qBAAqB;IAErC,uDAAuD;IACvD,cAAc,mBAAmB;IAEjC,8CAA8C;IAC9C,YAAY,iBAAiB;IAE7B,4CAA4C;IAC5C,eAAe,oBAAoB;IAEnC,4CAA4C;IAC5C,iBAAiB,sBAAsB;CACxC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SAAU,SAAQ,KAAK;aAYhB,IAAI,EAAE,aAAa;aACnB,QAAQ,CAAC;IAZ3B,SAAgB,IAAI,eAAe;IAEnC;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,aAAa,EACnB,QAAQ,CAAC,sBAAU;IAUrC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,WAAW,CAE1E"}

package/dist/types/x402.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * X402 Protocol Types and Constants
+ *
+ * Defines types for the HTTP 402 Payment Required protocol implementation.
+ * X402 enables atomic, instant API payments - NO escrow, NO state machine.
+ *
+ * Key difference from ACTP:
+ * - ACTP: escrow → state machine → disputes → explicit release
+ * - x402: atomic payment → instant settlement → done
+ *
+ * Flow:
+ * 1. Client requests protected HTTPS endpoint → gets 402 response
+ * 2. Parse X-Payment-* headers (address, amount, network, deadline)
+ * 3. Execute atomic USDC transfer to provider (no escrow!)
+ * 4. Retry request with tx hash as proof
+ * 5. Return response - payment complete, no release needed
+ *
+ * Use x402 for: Simple API calls, instant delivery, low-value transactions
+ * Use ACTP for: Complex services, dispute protection, high-value transactions
+ *
+ * @module types/x402
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidX402Network = exports.isX402Error = exports.X402Error = exports.X402ErrorCode = exports.X402_PROOF_HEADERS = exports.X402_HEADERS = void 0;
+// ============================================================================
+// X402 Header Constants
+// ============================================================================
+/**
+ * Standard X402 payment headers sent in 402 responses.
+ *
+ * These headers inform the client how to pay for the requested resource.
+ */
+exports.X402_HEADERS = {
+    /** Indicates payment is required (must be "true") */
+    REQUIRED: 'x-payment-required',
+    /** Provider's wallet address (0x-prefixed) */
+    ADDRESS: 'x-payment-address',
+    /** Amount in USDC wei (6 decimals) */
+    AMOUNT: 'x-payment-amount',
+    /** Network identifier (base-mainnet or base-sepolia) */
+    NETWORK: 'x-payment-network',
+    /** Token type (currently only USDC) */
+    TOKEN: 'x-payment-token',
+    /** Unix timestamp deadline for payment */
+    DEADLINE: 'x-payment-deadline',
+    /** Optional: Dispute window in seconds */
+    DISPUTE_WINDOW: 'x-dispute-window',
+    /** Optional: Service identifier for tracking */
+    SERVICE_ID: 'x-service-id',
+};
+/**
+ * Proof headers sent when retrying with payment.
+ *
+ * After creating an ACTP transaction, the client includes these
+ * headers to prove payment was made.
+ */
+exports.X402_PROOF_HEADERS = {
+    /** ACTP transaction ID (bytes32 hex) */
+    TX_ID: 'x-payment-tx-id',
+    /** ACTP escrow ID (bytes32 hex) */
+    ESCROW_ID: 'x-payment-escrow-id',
+};
+// ============================================================================
+// X402 Error Handling
+// ============================================================================
+/**
+ * Error codes for X402 protocol failures.
+ *
+ * Used to identify specific error types and enable proper error handling.
+ */
+var X402ErrorCode;
+(function (X402ErrorCode) {
+    /** Response status was not 402 */
+    X402ErrorCode["NOT_402_RESPONSE"] = "NOT_402_RESPONSE";
+    /** Required X-Payment-* headers are missing */
+    X402ErrorCode["MISSING_HEADERS"] = "MISSING_HEADERS";
+    /** X-Payment-Amount is invalid (not a number, negative, etc.) */
+    X402ErrorCode["INVALID_AMOUNT"] = "INVALID_AMOUNT";
+    /** X-Payment-Address is not a valid Ethereum address */
+    X402ErrorCode["INVALID_ADDRESS"] = "INVALID_ADDRESS";
+    /** X-Payment-Network is not a recognized network */
+    X402ErrorCode["INVALID_NETWORK"] = "INVALID_NETWORK";
+    /** Server's network doesn't match client's expected network */
+    X402ErrorCode["NETWORK_MISMATCH"] = "NETWORK_MISMATCH";
+    /** Failed to create ACTP transaction or link escrow */
+    X402ErrorCode["PAYMENT_FAILED"] = "PAYMENT_FAILED";
+    /** Retry request with proof headers failed */
+    X402ErrorCode["RETRY_FAILED"] = "RETRY_FAILED";
+    /** X-Payment-Deadline has already passed */
+    X402ErrorCode["DEADLINE_PASSED"] = "DEADLINE_PASSED";
+    /** HTTPS protocol required but HTTP used */
+    X402ErrorCode["INSECURE_PROTOCOL"] = "INSECURE_PROTOCOL";
+})(X402ErrorCode || (exports.X402ErrorCode = X402ErrorCode = {}));
+/**
+ * Custom error for X402 protocol failures.
+ *
+ * Provides structured error information for debugging and error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await x402Adapter.pay({ to: 'https://api.example.com', amount: '10' });
+ * } catch (error) {
+ *   if (error instanceof X402Error) {
+ *     if (error.code === X402ErrorCode.NETWORK_MISMATCH) {
+ *       console.error('Wrong network:', error.message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class X402Error extends Error {
+    /**
+     * Creates a new X402Error.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param response - Optional HTTP response that triggered the error
+     */
+    constructor(message, code, response) {
+        super(message);
+        this.code = code;
+        this.response = response;
+        this.name = 'X402Error';
+        // Maintains proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, X402Error);
+        }
+    }
+    /**
+     * Creates a detailed error message with code.
+     */
+    toString() {
+        return `X402Error [${this.code}]: ${this.message}`;
+    }
+}
+exports.X402Error = X402Error;
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard to check if an error is an X402Error.
+ *
+ * @param error - Error to check
+ * @returns True if error is X402Error
+ */
+function isX402Error(error) {
+    return error instanceof X402Error;
+}
+exports.isX402Error = isX402Error;
+/**
+ * Validates that a network string is a valid X402Network.
+ *
+ * @param network - Network string to validate
+ * @returns True if valid X402Network
+ */
+function isValidX402Network(network) {
+    return network === 'base-mainnet' || network === 'base-sepolia';
+}
+exports.isValidX402Network = isValidX402Network;
+//# sourceMappingURL=x402.js.map

package/dist/types/x402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.js","sourceRoot":"","sources":["../../src/types/x402.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAEH,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;GAIG;AACU,QAAA,YAAY,GAAG;IAC1B,qDAAqD;IACrD,QAAQ,EAAE,oBAAoB;IAC9B,8CAA8C;IAC9C,OAAO,EAAE,mBAAmB;IAC5B,sCAAsC;IACtC,MAAM,EAAE,kBAAkB;IAC1B,wDAAwD;IACxD,OAAO,EAAE,mBAAmB;IAC5B,uCAAuC;IACvC,KAAK,EAAE,iBAAiB;IACxB,0CAA0C;IAC1C,QAAQ,EAAE,oBAAoB;IAC9B,0CAA0C;IAC1C,cAAc,EAAE,kBAAkB;IAClC,gDAAgD;IAChD,UAAU,EAAE,cAAc;CAClB,CAAC;AAEX;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG;IAChC,wCAAwC;IACxC,KAAK,EAAE,iBAAiB;IACxB,mCAAmC;IACnC,SAAS,EAAE,qBAAqB;CACxB,CAAC;AA4CX,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;GAIG;AACH,IAAY,aA8BX;AA9BD,WAAY,aAAa;IACvB,kCAAkC;IAClC,sDAAqC,CAAA;IAErC,+CAA+C;IAC/C,oDAAmC,CAAA;IAEnC,iEAAiE;IACjE,kDAAiC,CAAA;IAEjC,wDAAwD;IACxD,oDAAmC,CAAA;IAEnC,oDAAoD;IACpD,oDAAmC,CAAA;IAEnC,+DAA+D;IAC/D,sDAAqC,CAAA;IAErC,uDAAuD;IACvD,kDAAiC,CAAA;IAEjC,8CAA8C;IAC9C,8CAA6B,CAAA;IAE7B,4CAA4C;IAC5C,oDAAmC,CAAA;IAEnC,4CAA4C;IAC5C,wDAAuC,CAAA;AACzC,CAAC,EA9BW,aAAa,6BAAb,aAAa,QA8BxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,SAAU,SAAQ,KAAK;IAGlC;;;;;;OAMG;IACH,YACE,OAAe,EACC,IAAmB,EACnB,QAAmB;QAEnC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAe;QACnB,aAAQ,GAAR,QAAQ,CAAW;QAZrB,SAAI,GAAG,WAAW,CAAC;QAgBjC,kDAAkD;QAClD,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,cAAc,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACrD,CAAC;CACF;AA7BD,8BA6BC;AAED,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,SAAS,CAAC;AACpC,CAAC;AAFD,kCAEC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,OAAe;IAChD,OAAO,OAAO,KAAK,cAAc,IAAI,OAAO,KAAK,cAAc,CAAC;AAClE,CAAC;AAFD,gDAEC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agirails/sdk",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "AGIRAILS SDK for the ACTP (Agent Commerce Transaction Protocol) - Unified mock + blockchain support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -79,7 +79,8 @@
     "ethr-did-resolver": "11.0.5",
     "fast-json-stable-stringify": "2.1.0",
     "kubo-rpc-client": "3.0.1",
-    "proper-lockfile": "4.1.2"
+    "proper-lockfile": "4.1.2",
+    "zod": "^3.22.4"
   },
   "devDependencies": {
     "@nomicfoundation/hardhat-ethers": "3.0.0",