uvd-x402-sdk 2.31.0 → 2.32.2

package/README.md

@@ -48,7 +48,85 @@ npm install @mysten/sui
 
 ## Quick Start
 
-### EVM Chains
+### Server + Client (Private Key)
+
+The fastest way to get up and running. No browser wallet needed — works in Node.js, scripts, and agents.
+
+**.env**
+
+```bash
+RECEIVING_ADDRESS=0xYourWalletAddress
+PRIVATE_KEY=0xYourPrivateKey
+```
+
+**Server (Hono)**
+
+```bash
+npm install hono @hono/node-server uvd-x402-sdk dotenv
+```
+
+```typescript
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { createHonoMiddleware } from 'uvd-x402-sdk';
+import 'dotenv/config';
+
+const app = new Hono();
+const receiver = process.env.RECEIVING_ADDRESS as string;
+
+// x402 payment middleware — handles 402, verify, and settle automatically
+const paywall = createHonoMiddleware({
+  accepts: [{
+    network: 'skale-base',
+    asset: '0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20',
+    amount: '1000000', // $1.00 USDC.e (6 decimals)
+    payTo: receiver,
+    extra: {
+      name: 'Bridged USDC (SKALE Bridge)',
+      version: '2',
+    },
+  }],
+});
+
+app.get('/api/free', (c) => c.json({ message: 'This endpoint is free!' }));
+
+app.get('/api/premium', paywall, (c) => {
+  return c.json({ message: 'Payment verified and settled!', timestamp: new Date().toISOString() });
+});
+
+serve({ fetch: app.fetch, port: 3000 });
+console.log('Server running on http://localhost:3000');
+```
+
+**Client (Private Key)**
+
+```bash
+npm install uvd-x402-sdk ethers dotenv
+```
+
+```typescript
+import { X402Client } from 'uvd-x402-sdk';
+import 'dotenv/config';
+
+const client = new X402Client({ defaultChain: 'skale-base' });
+await client.connectWithPrivateKey(process.env.PRIVATE_KEY as string);
+
+const result = await client.createPayment({
+  recipient: process.env.RECEIVING_ADDRESS as string,
+  amount: '1.00',
+});
+
+const response = await fetch('http://localhost:3000/api/premium', {
+  headers: { 'X-PAYMENT': result.paymentHeader },
+});
+
+const data = await response.json();
+console.log('Response:', data);
+```
+
+This example uses SKALE Base (zero gas costs). Replace `network`, `asset`, and `extra` to use any supported chain — see [Supported Networks](#supported-networks).
+
+### EVM Chains (Browser Wallet)
 
 ```typescript
 import { X402Client } from 'uvd-x402-sdk';
@@ -550,7 +628,7 @@ app.post('/api/premium', async (req, res) => {
 });
 ```
 
-`createPaymentMiddleware()` and `createHonoMiddleware()` verify by default and attach settlement context for manual control. Use `settlementStrategy: 'before-handler'` only if you intentionally want eager settlement before your handler runs.
+`createPaymentMiddleware()` and `createHonoMiddleware()` verify and settle automatically by default (`before-handler`). Use `settlementStrategy: 'manual'` if you need to control when settlement happens (e.g., settle only after confirming you can fulfill the request).
 
 ## React
 

package/dist/backend/index.d.mts

@@ -1937,6 +1937,11 @@ interface AdvancedEscrowClientOptions {
  * (AUTHORIZE goes through the facilitator, not directly on-chain)
  */
 declare const OPERATOR_ABI: string[];
+/**
+ * CREATE3-deployed operators (SKALE, future chains) use updated ABI with extra `bytes data` param
+ * on release() and refundInEscrow(). Pass empty bytes (0x) for the data parameter.
+ */
+declare const OPERATOR_ABI_CREATE3: string[];
 /**
  * AdvancedEscrowClient provides the 5 Advanced Escrow flows via the
  * PaymentOperator contract on 9 supported EVM networks.
@@ -2133,4 +2138,4 @@ declare class AdvancedEscrowClient {
     refundPostEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string, tokenCollector?: string, collectorData?: string): Promise<AdvancedTransactionResult>;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type HonoMiddlewareOptions, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type HonoMiddlewareOptions, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };

package/dist/backend/index.d.ts

@@ -1937,6 +1937,11 @@ interface AdvancedEscrowClientOptions {
  * (AUTHORIZE goes through the facilitator, not directly on-chain)
  */
 declare const OPERATOR_ABI: string[];
+/**
+ * CREATE3-deployed operators (SKALE, future chains) use updated ABI with extra `bytes data` param
+ * on release() and refundInEscrow(). Pass empty bytes (0x) for the data parameter.
+ */
+declare const OPERATOR_ABI_CREATE3: string[];
 /**
  * AdvancedEscrowClient provides the 5 Advanced Escrow flows via the
  * PaymentOperator contract on 9 supported EVM networks.
@@ -2133,4 +2138,4 @@ declare class AdvancedEscrowClient {
     refundPostEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string, tokenCollector?: string, collectorData?: string): Promise<AdvancedTransactionResult>;
 }
 
-export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type HonoMiddlewareOptions, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };
+export { type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, BASE_MAINNET_CONTRACTS, type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, DEPOSIT_LIMIT_USDC, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, type HonoMiddlewareOptions, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type ProofOfPayment, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type SettleRequest, type SettleResponse, type SettleResponseWithProof, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isEscrowExpired, isEscrowSupportedOnChain, parsePaymentHeader };

package/dist/backend/index.js

@@ -1438,15 +1438,16 @@ async function resolvePaymentRequirement(payment, requirements, resolver) {
   return { requirement: matches[0] };
 }
 function createVerifiedPaymentState(client, payment, requirements, verifyResult) {
-  let settleResult = null;
+  let settlePromise = null;
   return {
     payment,
     requirements,
     verifyResult,
-    settle: async () => {
-      if (settleResult) return settleResult;
-      settleResult = await client.settle(payment, requirements);
-      return settleResult;
+    settle: () => {
+      if (!settlePromise) {
+        settlePromise = client.settle(payment, requirements);
+      }
+      return settlePromise;
     }
   };
 }
@@ -3098,6 +3099,15 @@ var ESCROW_CONTRACTS = {
     protocolFeeConfig: "0xD979dBfBdA5f4b16AAF60Eaab32A44f352076838",
     refundRequest: "0xc1256Bb30bd0cdDa07D8C8Cf67a59105f2EA1b98",
     usdc: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
+  },
+  // SKALE Base (chain 1187947933) - CREATE3 deployment, operator via factory
+  1187947933: {
+    operator: "0x28c23AE8f55aDe5Ea10a5353FC40418D0c1B3d33",
+    escrow: "0xBC151792f80C0EB1973d56b0235e6bee2A60e245",
+    tokenCollector: "0x9A12A116a44636F55c9e135189A1321Abcfe2f30",
+    protocolFeeConfig: "0xf62788834C99B2E85a6891C0b46D1EB996f8f596",
+    refundRequest: "0x69e9BF2b40Ed472b55E47e9D4205d93Ed673093F",
+    usdc: "0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20"
   }
 };
 var BASE_MAINNET_CONTRACTS = ESCROW_CONTRACTS[8453];
@@ -3122,6 +3132,13 @@ var OPERATOR_ABI = [
   "function charge(tuple(address operator, address payer, address receiver, address token, uint120 maxAmount, uint48 preApprovalExpiry, uint48 authorizationExpiry, uint48 refundExpiry, uint16 minFeeBps, uint16 maxFeeBps, address feeReceiver, uint256 salt) paymentInfo, uint256 amount, address tokenCollector, bytes collectorData)",
   "function refundPostEscrow(tuple(address operator, address payer, address receiver, address token, uint120 maxAmount, uint48 preApprovalExpiry, uint48 authorizationExpiry, uint48 refundExpiry, uint16 minFeeBps, uint16 maxFeeBps, address feeReceiver, uint256 salt) paymentInfo, uint256 amount, address tokenCollector, bytes collectorData)"
 ];
+var OPERATOR_ABI_CREATE3 = [
+  "function release(tuple(address operator, address payer, address receiver, address token, uint120 maxAmount, uint48 preApprovalExpiry, uint48 authorizationExpiry, uint48 refundExpiry, uint16 minFeeBps, uint16 maxFeeBps, address feeReceiver, uint256 salt) paymentInfo, uint256 amount, bytes data)",
+  "function refundInEscrow(tuple(address operator, address payer, address receiver, address token, uint120 maxAmount, uint48 preApprovalExpiry, uint48 authorizationExpiry, uint48 refundExpiry, uint16 minFeeBps, uint16 maxFeeBps, address feeReceiver, uint256 salt) paymentInfo, uint120 amount, bytes data)",
+  "function charge(tuple(address operator, address payer, address receiver, address token, uint120 maxAmount, uint48 preApprovalExpiry, uint48 authorizationExpiry, uint48 refundExpiry, uint16 minFeeBps, uint16 maxFeeBps, address feeReceiver, uint256 salt) paymentInfo, uint256 amount, address tokenCollector, bytes collectorData)",
+  "function refundPostEscrow(tuple(address operator, address payer, address receiver, address token, uint120 maxAmount, uint48 preApprovalExpiry, uint48 authorizationExpiry, uint48 refundExpiry, uint16 minFeeBps, uint16 maxFeeBps, address feeReceiver, uint256 salt) paymentInfo, uint256 amount, address tokenCollector, bytes collectorData)"
+];
+var CREATE3_CHAIN_IDS = /* @__PURE__ */ new Set([1187947933]);
 var AdvancedEscrowClient = class {
   facilitatorUrl;
   chainId;
@@ -3370,10 +3387,12 @@ var AdvancedEscrowClient = class {
     if (!this.payerAddress) await this.init();
     try {
       const { ethers } = await import('ethers');
-      const contract = new ethers.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
+      const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
+      const contract = new ethers.Contract(this.contracts.operator, abi, this.signer);
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
-      const tx = await contract.release(tuple, amt, { gasLimit: this.gasLimit });
+      const tx = isCreate3 ? await contract.release(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.release(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
         success: receipt.status === 1,
@@ -3397,10 +3416,12 @@ var AdvancedEscrowClient = class {
     if (!this.payerAddress) await this.init();
     try {
       const { ethers } = await import('ethers');
-      const contract = new ethers.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
+      const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
+      const contract = new ethers.Contract(this.contracts.operator, abi, this.signer);
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
-      const tx = await contract.refundInEscrow(tuple, amt, { gasLimit: this.gasLimit });
+      const tx = isCreate3 ? await contract.refundInEscrow(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.refundInEscrow(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
         success: receipt.status === 1,
@@ -3754,6 +3775,7 @@ exports.Erc8004Client = Erc8004Client;
 exports.EscrowClient = EscrowClient;
 exports.FacilitatorClient = FacilitatorClient;
 exports.OPERATOR_ABI = OPERATOR_ABI;
+exports.OPERATOR_ABI_CREATE3 = OPERATOR_ABI_CREATE3;
 exports.PAYMENT_INFO_TYPEHASH = PAYMENT_INFO_TYPEHASH;
 exports.TIER_TIMINGS = TIER_TIMINGS;
 exports.USDC_DOMAIN_NAME = USDC_DOMAIN_NAME;