uvd-x402-sdk 2.3.0 → 2.5.0

package/src/providers/solana/index.ts

@@ -43,9 +43,11 @@ import type {
   PaymentInfo,
   SolanaPaymentPayload,
   WalletAdapter,
+  X402Version,
 } from '../../types';
 import { X402Error } from '../../types';
 import { getChainByName } from '../../chains';
+import { chainToCAIP2 } from '../../utils';
 
 /**
  * Browser-compatible base64 encoding for Uint8Array
@@ -395,24 +397,41 @@ export class SVMProvider implements WalletAdapter {
   /**
    * Encode SVM payment as X-PAYMENT header
    *
-   * @param paymentPayload - The payment payload JSON string
-   * @param chainConfig - Optional chain config (defaults to 'solana' if not provided)
+   * @param paymentPayload - JSON-encoded payment payload from signPayment()
+   * @param chainConfig - Chain configuration (optional, defaults to 'solana')
+   * @param version - x402 protocol version (1 or 2, defaults to 1)
+   * @returns Base64-encoded X-PAYMENT header value
    */
-  encodePaymentHeader(paymentPayload: string, chainConfig?: ChainConfig): string {
+  encodePaymentHeader(
+    paymentPayload: string,
+    chainConfig?: ChainConfig,
+    version: X402Version = 1
+  ): string {
     const payload = JSON.parse(paymentPayload) as SolanaPaymentPayload;
 
     // Use chain name from config, or default to 'solana' for backward compatibility
     const networkName = chainConfig?.name || 'solana';
 
-    const x402Payload = {
-      x402Version: 1,
-      scheme: 'exact',
-      network: networkName,
-      payload: {
-        transaction: payload.transaction,
-      },
+    // Build the payload data
+    const payloadData = {
+      transaction: payload.transaction,
     };
 
+    // Format in x402 standard format (v1 or v2)
+    const x402Payload = version === 2
+      ? {
+          x402Version: 2 as const,
+          scheme: 'exact' as const,
+          network: chainToCAIP2(networkName), // CAIP-2 format for v2
+          payload: payloadData,
+        }
+      : {
+          x402Version: 1 as const,
+          scheme: 'exact' as const,
+          network: networkName, // Plain chain name for v1
+          payload: payloadData,
+        };
+
     return btoa(JSON.stringify(x402Payload));
   }
 

package/src/providers/stellar/index.ts

@@ -25,8 +25,10 @@ import type {
   PaymentInfo,
   StellarPaymentPayload,
   WalletAdapter,
+  X402Version,
 } from '../../types';
 import { X402Error } from '../../types';
+import { chainToCAIP2 } from '../../utils';
 
 /**
  * Browser-compatible text to Uint8Array encoding
@@ -343,25 +345,40 @@ export class StellarProvider implements WalletAdapter {
 
   /**
    * Encode Stellar payment as X-PAYMENT header
+   *
+   * @param paymentPayload - JSON-encoded payment payload from signPayment()
+   * @param version - x402 protocol version (1 or 2, defaults to 1)
+   * @returns Base64-encoded X-PAYMENT header value
    */
-  encodePaymentHeader(paymentPayload: string): string {
+  encodePaymentHeader(paymentPayload: string, version: X402Version = 1): string {
     const payload = JSON.parse(paymentPayload) as StellarPaymentPayload;
 
-    const x402Payload = {
-      x402Version: 1,
-      scheme: 'exact',
-      network: 'stellar',
-      payload: {
-        from: payload.from,
-        to: payload.to,
-        amount: payload.amount,
-        tokenContract: payload.tokenContract,
-        authorizationEntryXdr: payload.authorizationEntryXdr,
-        nonce: payload.nonce,
-        signatureExpirationLedger: payload.signatureExpirationLedger,
-      },
+    // Build the payload data
+    const payloadData = {
+      from: payload.from,
+      to: payload.to,
+      amount: payload.amount,
+      tokenContract: payload.tokenContract,
+      authorizationEntryXdr: payload.authorizationEntryXdr,
+      nonce: payload.nonce,
+      signatureExpirationLedger: payload.signatureExpirationLedger,
     };
 
+    // Format in x402 standard format (v1 or v2)
+    const x402Payload = version === 2
+      ? {
+          x402Version: 2 as const,
+          scheme: 'exact' as const,
+          network: chainToCAIP2('stellar'), // CAIP-2 format for v2
+          payload: payloadData,
+        }
+      : {
+          x402Version: 1 as const,
+          scheme: 'exact' as const,
+          network: 'stellar', // Plain chain name for v1
+          payload: payloadData,
+        };
+
     return btoa(JSON.stringify(x402Payload));
   }
 

package/src/utils/index.ts

@@ -18,3 +18,8 @@ export {
   isCAIP2Format,
   convertX402Header,
 } from './x402';
+
+export {
+  validateRecipient,
+  validateAmount,
+} from './validation';

package/src/utils/validation.ts

@@ -0,0 +1,151 @@
+/**
+ * uvd-x402-sdk - Validation Utilities
+ *
+ * Functions for validating payment parameters to prevent
+ * invalid or empty values from being processed.
+ */
+
+import { X402Error } from '../types';
+
+/**
+ * Regular expression for validating Ethereum addresses
+ */
+const ETH_ADDRESS_REGEX = /^0x[a-fA-F0-9]{40}$/;
+
+/**
+ * Regular expression for validating Solana addresses (base58, 32-44 chars)
+ */
+const SOLANA_ADDRESS_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+/**
+ * Regular expression for validating Stellar addresses (G... format)
+ */
+const STELLAR_ADDRESS_REGEX = /^G[A-Z2-7]{55}$/;
+
+/**
+ * Regular expression for validating NEAR addresses
+ */
+const NEAR_ADDRESS_REGEX = /^[a-z0-9._-]+$/;
+
+/**
+ * Validate that a recipient address is present and valid
+ *
+ * This function ensures that:
+ * 1. The recipient is not null, undefined, or empty
+ * 2. The recipient is not just whitespace
+ * 3. For EVM, it's a valid checksummed or lowercase 0x address
+ *
+ * @param recipient - The recipient address to validate
+ * @param networkType - Optional network type for format validation
+ * @throws X402Error with code 'INVALID_RECIPIENT' if validation fails
+ */
+export function validateRecipient(
+  recipient: string | undefined | null,
+  networkType?: 'evm' | 'svm' | 'solana' | 'stellar' | 'near'
+): asserts recipient is string {
+  // Check for null, undefined, or empty
+  if (!recipient) {
+    throw new X402Error(
+      'Recipient address is required. The payTo/recipient field cannot be empty. ' +
+      'Please provide a valid recipient address where payments should be sent.',
+      'INVALID_RECIPIENT'
+    );
+  }
+
+  // Check for whitespace-only
+  const trimmed = recipient.trim();
+  if (trimmed === '') {
+    throw new X402Error(
+      'Recipient address cannot be empty or whitespace. ' +
+      'Please provide a valid recipient address.',
+      'INVALID_RECIPIENT'
+    );
+  }
+
+  // Network-specific validation
+  if (networkType) {
+    switch (networkType) {
+      case 'evm':
+        if (!ETH_ADDRESS_REGEX.test(trimmed)) {
+          throw new X402Error(
+            `Invalid EVM recipient address: "${trimmed}". ` +
+            'Expected a 40-character hexadecimal address starting with 0x.',
+            'INVALID_RECIPIENT'
+          );
+        }
+        break;
+
+      case 'svm':
+      case 'solana':
+        if (!SOLANA_ADDRESS_REGEX.test(trimmed)) {
+          throw new X402Error(
+            `Invalid Solana recipient address: "${trimmed}". ` +
+            'Expected a base58-encoded public key (32-44 characters).',
+            'INVALID_RECIPIENT'
+          );
+        }
+        break;
+
+      case 'stellar':
+        if (!STELLAR_ADDRESS_REGEX.test(trimmed)) {
+          throw new X402Error(
+            `Invalid Stellar recipient address: "${trimmed}". ` +
+            'Expected a G-prefixed public key (56 characters).',
+            'INVALID_RECIPIENT'
+          );
+        }
+        break;
+
+      case 'near':
+        if (!NEAR_ADDRESS_REGEX.test(trimmed) || trimmed.length > 64) {
+          throw new X402Error(
+            `Invalid NEAR recipient address: "${trimmed}". ` +
+            'Expected a valid NEAR account ID.',
+            'INVALID_RECIPIENT'
+          );
+        }
+        break;
+    }
+  }
+}
+
+/**
+ * Validate payment amount
+ *
+ * Ensures the amount is a valid positive number string
+ *
+ * @param amount - The amount string to validate
+ * @throws X402Error with code 'INVALID_AMOUNT' if validation fails
+ */
+export function validateAmount(amount: string | undefined | null): asserts amount is string {
+  if (!amount) {
+    throw new X402Error(
+      'Payment amount is required.',
+      'INVALID_AMOUNT'
+    );
+  }
+
+  const trimmed = amount.trim();
+  if (trimmed === '') {
+    throw new X402Error(
+      'Payment amount cannot be empty.',
+      'INVALID_AMOUNT'
+    );
+  }
+
+  // Parse as number
+  const num = parseFloat(trimmed);
+  if (isNaN(num)) {
+    throw new X402Error(
+      `Invalid payment amount: "${trimmed}". Expected a valid number.`,
+      'INVALID_AMOUNT'
+    );
+  }
+
+  if (num <= 0) {
+    throw new X402Error(
+      `Payment amount must be positive. Got: ${trimmed}`,
+      'INVALID_AMOUNT'
+    );
+  }
+}