uvd-x402-sdk 2.0.1

package/src/index.ts

@@ -0,0 +1,166 @@
+/**
+ * uvd-x402-sdk
+ *
+ * x402 Payment SDK - Gasless crypto payments using the Ultravioleta facilitator.
+ *
+ * Supports 15 blockchain networks:
+ * - EVM (11): Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche, Celo, HyperEVM, Unichain, Monad, BSC(disabled)
+ * - SVM (2): Solana, Fogo
+ * - Stellar (1): Stellar
+ * - NEAR (1): NEAR Protocol
+ *
+ * Supports both x402 v1 and v2 protocols.
+ *
+ * @example Basic usage (EVM)
+ * ```ts
+ * import { X402Client } from 'uvd-x402-sdk';
+ *
+ * const client = new X402Client({ defaultChain: 'base' });
+ *
+ * // Connect wallet
+ * await client.connect('base');
+ *
+ * // Create payment
+ * const result = await client.createPayment({
+ *   recipient: '0x...',
+ *   amount: '10.00',
+ * });
+ *
+ * // Use result.paymentHeader in X-PAYMENT HTTP header
+ * ```
+ *
+ * @example With SVM (Solana/Fogo)
+ * ```ts
+ * import { SVMProvider } from 'uvd-x402-sdk/solana';
+ * import { getChainByName } from 'uvd-x402-sdk';
+ *
+ * const svm = new SVMProvider();
+ * const address = await svm.connect();
+ *
+ * // Solana payment
+ * const solanaConfig = getChainByName('solana')!;
+ * const payload = await svm.signPayment(paymentInfo, solanaConfig);
+ * const header = svm.encodePaymentHeader(payload, solanaConfig);
+ *
+ * // Fogo payment (same provider, different config)
+ * const fogoConfig = getChainByName('fogo')!;
+ * const fogoPayload = await svm.signPayment(paymentInfo, fogoConfig);
+ * const fogoHeader = svm.encodePaymentHeader(fogoPayload, fogoConfig);
+ * ```
+ *
+ * @example With NEAR
+ * ```ts
+ * import { NEARProvider } from 'uvd-x402-sdk/near';
+ * import { getChainByName } from 'uvd-x402-sdk';
+ *
+ * const near = new NEARProvider();
+ * const accountId = await near.connect();
+ * const nearConfig = getChainByName('near')!;
+ * const payload = await near.signPayment(paymentInfo, nearConfig);
+ * const header = near.encodePaymentHeader(payload);
+ * ```
+ *
+ * @example With React
+ * ```tsx
+ * import { X402Provider, useX402, usePayment } from 'uvd-x402-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <X402Provider>
+ *       <PaymentButton />
+ *     </X402Provider>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Main client
+export { X402Client } from './client';
+
+// Chain configuration
+export {
+  SUPPORTED_CHAINS,
+  DEFAULT_CHAIN,
+  DEFAULT_FACILITATOR_URL,
+  getChainById,
+  getChainByName,
+  isChainSupported,
+  getEnabledChains,
+  getChainsByNetworkType,
+  getEVMChainIds,
+  getSVMChains,
+  isSVMChain,
+  getNetworkType,
+  getExplorerTxUrl,
+  getExplorerAddressUrl,
+} from './chains';
+
+// x402 utilities
+export {
+  detectX402Version,
+  chainToCAIP2,
+  caip2ToChain,
+  parseNetworkIdentifier,
+  encodeX402Header,
+  decodeX402Header,
+  createX402V1Header,
+  createX402V2Header,
+  createX402Header,
+  generatePaymentOptions,
+  isCAIP2Format,
+  convertX402Header,
+} from './utils';
+
+// Types
+export type {
+  // Chain types
+  ChainConfig,
+  USDCConfig,
+  NativeCurrency,
+  NetworkType,
+
+  // Wallet types
+  WalletState,
+  WalletAdapter,
+  EIP712Domain,
+  EIP712Types,
+
+  // Payment types
+  PaymentInfo,
+  PaymentRequest,
+  PaymentResult,
+  PaymentPayload,
+  EVMPaymentPayload,
+  SolanaPaymentPayload,
+  StellarPaymentPayload,
+  NEARPaymentPayload,
+
+  // x402 header types (v1 and v2)
+  X402Version,
+  X402Header,
+  X402HeaderV1,
+  X402HeaderV2,
+  X402PaymentOption,
+  X402PayloadData,
+  X402EVMPayload,
+  X402SolanaPayload,
+  X402StellarPayload,
+  X402NEARPayload,
+
+  // Config types
+  X402ClientConfig,
+  MultiPaymentConfig,
+  NetworkBalance,
+
+  // Event types
+  X402Event,
+  X402EventData,
+  X402EventHandler,
+
+  // Error types
+  X402ErrorCode,
+} from './types';
+
+export { X402Error, DEFAULT_CONFIG, CAIP2_IDENTIFIERS, CAIP2_TO_CHAIN } from './types';

package/src/providers/evm/index.ts

@@ -0,0 +1,394 @@
+/**
+ * uvd-x402-sdk - EVM Provider
+ *
+ * Provides EVM wallet connection and payment creation.
+ * Uses EIP-712 typed data signing for ERC-3009 TransferWithAuthorization.
+ *
+ * Supports MetaMask, Rabby, and other injected EVM wallets.
+ * WalletConnect support is available for mobile wallets.
+ *
+ * @example
+ * ```ts
+ * import { EVMProvider } from 'uvd-x402-sdk/evm';
+ *
+ * const evm = new EVMProvider();
+ *
+ * // Connect to Base
+ * const address = await evm.connect('base');
+ *
+ * // Create payment
+ * const paymentHeader = await evm.signPayment(paymentInfo, chainConfig);
+ * ```
+ */
+
+import { ethers } from 'ethers';
+import type {
+  ChainConfig,
+  PaymentInfo,
+  EVMPaymentPayload,
+  WalletAdapter,
+} from '../../types';
+import { X402Error } from '../../types';
+import { getChainByName, getChainById } from '../../chains';
+
+/**
+ * Ethereum provider interface
+ */
+interface EthereumProvider {
+  request: (args: { method: string; params?: unknown[] }) => Promise<unknown>;
+  on?: (event: string, handler: (...args: unknown[]) => void) => void;
+  removeListener?: (event: string, handler: (...args: unknown[]) => void) => void;
+}
+
+/**
+ * EVMProvider - Wallet adapter for EVM chains
+ */
+export class EVMProvider implements WalletAdapter {
+  readonly id = 'injected';
+  readonly name = 'EVM Wallet';
+  readonly networkType = 'evm' as const;
+
+  private provider: ethers.BrowserProvider | null = null;
+  private signer: ethers.Signer | null = null;
+  private address: string | null = null;
+  private chainId: number | null = null;
+  private chainName: string | null = null;
+
+  /**
+   * Check if an EVM wallet is available
+   */
+  isAvailable(): boolean {
+    if (typeof window === 'undefined') return false;
+    return typeof (window as Window & { ethereum?: EthereumProvider }).ethereum !== 'undefined';
+  }
+
+  /**
+   * Connect to an EVM wallet
+   */
+  async connect(chainName?: string): Promise<string> {
+    const targetChainName = chainName || 'base';
+    const chain = getChainByName(targetChainName);
+
+    if (!chain) {
+      throw new X402Error(`Unsupported chain: ${targetChainName}`, 'CHAIN_NOT_SUPPORTED');
+    }
+
+    if (chain.networkType !== 'evm') {
+      throw new X402Error(`${targetChainName} is not an EVM chain`, 'CHAIN_NOT_SUPPORTED');
+    }
+
+    const ethereum = (window as Window & { ethereum?: EthereumProvider }).ethereum;
+    if (!ethereum) {
+      throw new X402Error(
+        'No Ethereum wallet found. Please install MetaMask or another EVM wallet.',
+        'WALLET_NOT_FOUND'
+      );
+    }
+
+    try {
+      this.provider = new ethers.BrowserProvider(ethereum);
+
+      // Request account access
+      await this.provider.send('eth_requestAccounts', []);
+
+      // Switch to target chain
+      await this.switchChain(targetChainName);
+
+      // Get signer and address
+      this.signer = await this.provider.getSigner();
+      this.address = await this.signer.getAddress();
+
+      return this.address;
+    } catch (error: unknown) {
+      if (error instanceof Error) {
+        if (error.message.includes('User rejected') || (error as { code?: number }).code === 4001) {
+          throw new X402Error('Connection rejected by user', 'WALLET_CONNECTION_REJECTED');
+        }
+      }
+      throw new X402Error(
+        `Failed to connect wallet: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'UNKNOWN_ERROR',
+        error
+      );
+    }
+  }
+
+  /**
+   * Disconnect from wallet
+   */
+  async disconnect(): Promise<void> {
+    this.provider = null;
+    this.signer = null;
+    this.address = null;
+    this.chainId = null;
+    this.chainName = null;
+  }
+
+  /**
+   * Switch to a different EVM chain
+   */
+  async switchChain(chainName: string): Promise<void> {
+    const chain = getChainByName(chainName);
+
+    if (!chain) {
+      throw new X402Error(`Unsupported chain: ${chainName}`, 'CHAIN_NOT_SUPPORTED');
+    }
+
+    if (!this.provider) {
+      throw new X402Error('Wallet not connected', 'WALLET_NOT_CONNECTED');
+    }
+
+    try {
+      await this.provider.send('wallet_switchEthereumChain', [{ chainId: chain.chainIdHex }]);
+    } catch (switchError: unknown) {
+      // Chain not added - try to add it
+      if ((switchError as { code?: number }).code === 4902) {
+        try {
+          await this.provider.send('wallet_addEthereumChain', [
+            {
+              chainId: chain.chainIdHex,
+              chainName: chain.displayName,
+              nativeCurrency: chain.nativeCurrency,
+              rpcUrls: [chain.rpcUrl],
+              blockExplorerUrls: [chain.explorerUrl],
+            },
+          ]);
+        } catch (addError) {
+          throw new X402Error(
+            `Failed to add ${chain.displayName} network`,
+            'CHAIN_SWITCH_REJECTED',
+            addError
+          );
+        }
+      } else if ((switchError as { code?: number }).code === 4001) {
+        throw new X402Error('Network switch rejected by user', 'CHAIN_SWITCH_REJECTED');
+      } else {
+        throw new X402Error(
+          `Failed to switch to ${chain.displayName}`,
+          'CHAIN_SWITCH_REJECTED',
+          switchError
+        );
+      }
+    }
+
+    this.chainId = chain.chainId;
+    this.chainName = chain.name;
+  }
+
+  /**
+   * Get current address
+   */
+  getAddress(): string | null {
+    return this.address;
+  }
+
+  /**
+   * Get current chain ID
+   */
+  getChainId(): number | null {
+    return this.chainId;
+  }
+
+  /**
+   * Get current chain name
+   */
+  getChainName(): string | null {
+    return this.chainName;
+  }
+
+  /**
+   * Get USDC balance
+   */
+  async getBalance(chainConfig: ChainConfig): Promise<string> {
+    if (!this.address) {
+      throw new X402Error('Wallet not connected', 'WALLET_NOT_CONNECTED');
+    }
+
+    // Use public RPC for balance check
+    const publicProvider = new ethers.JsonRpcProvider(chainConfig.rpcUrl);
+
+    const usdcAbi = ['function balanceOf(address owner) view returns (uint256)'];
+    const usdcContract = new ethers.Contract(chainConfig.usdc.address, usdcAbi, publicProvider);
+
+    try {
+      const balance = await usdcContract.balanceOf(this.address);
+      const formatted = ethers.formatUnits(balance, chainConfig.usdc.decimals);
+      return parseFloat(formatted).toFixed(2);
+    } catch {
+      return '0.00';
+    }
+  }
+
+  /**
+   * Create EVM payment (EIP-712 TransferWithAuthorization)
+   */
+  async signPayment(paymentInfo: PaymentInfo, chainConfig: ChainConfig): Promise<string> {
+    if (!this.signer || !this.address) {
+      throw new X402Error('Wallet not connected', 'WALLET_NOT_CONNECTED');
+    }
+
+    // Get recipient
+    const recipient = paymentInfo.recipients?.evm || paymentInfo.recipient;
+
+    // Generate random nonce
+    const nonceBytes = new Uint8Array(32);
+    if (typeof window !== 'undefined' && window.crypto) {
+      window.crypto.getRandomValues(nonceBytes);
+    } else {
+      for (let i = 0; i < 32; i++) {
+        nonceBytes[i] = Math.floor(Math.random() * 256);
+      }
+    }
+    const nonce = ethers.hexlify(nonceBytes);
+
+    // Set validity window
+    const validAfter = 0;
+    const validityWindowSeconds = chainConfig.name === 'base' ? 300 : 60;
+    const validBefore = Math.floor(Date.now() / 1000) + validityWindowSeconds;
+
+    // EIP-712 domain
+    const domain = {
+      name: chainConfig.usdc.name,
+      version: chainConfig.usdc.version,
+      chainId: chainConfig.chainId,
+      verifyingContract: chainConfig.usdc.address,
+    };
+
+    // EIP-712 types for TransferWithAuthorization (ERC-3009)
+    const types = {
+      TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+      ],
+    };
+
+    // Parse amount
+    const value = ethers.parseUnits(paymentInfo.amount, chainConfig.usdc.decimals);
+    const from = this.address;
+    const to = ethers.getAddress(recipient);
+
+    // Message to sign
+    const message = {
+      from,
+      to,
+      value,
+      validAfter,
+      validBefore,
+      nonce,
+    };
+
+    // Sign the EIP-712 message
+    let signature: string;
+    try {
+      signature = await this.signer.signTypedData(domain, types, message);
+    } catch (error: unknown) {
+      if (error instanceof Error && (error.message.includes('User rejected') || (error as { code?: number }).code === 4001)) {
+        throw new X402Error('Signature rejected by user', 'SIGNATURE_REJECTED');
+      }
+      throw new X402Error(
+        `Failed to sign payment: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'PAYMENT_FAILED',
+        error
+      );
+    }
+
+    const sig = ethers.Signature.from(signature);
+
+    // Construct payload
+    const payload: EVMPaymentPayload = {
+      from,
+      to,
+      value: value.toString(),
+      validAfter,
+      validBefore,
+      nonce,
+      v: sig.v,
+      r: sig.r,
+      s: sig.s,
+      chainId: chainConfig.chainId,
+      token: chainConfig.usdc.address,
+    };
+
+    return JSON.stringify(payload);
+  }
+
+  /**
+   * Encode EVM payment as X-PAYMENT header
+   */
+  encodePaymentHeader(paymentPayload: string, chainConfig: ChainConfig): string {
+    const payload = JSON.parse(paymentPayload) as EVMPaymentPayload;
+
+    // Reconstruct full signature
+    const fullSignature = payload.r + payload.s.slice(2) + payload.v.toString(16).padStart(2, '0');
+
+    const x402Payload = {
+      x402Version: 1,
+      scheme: 'exact',
+      network: chainConfig.name,
+      payload: {
+        signature: fullSignature,
+        authorization: {
+          from: payload.from,
+          to: payload.to,
+          value: payload.value,
+          validAfter: payload.validAfter.toString(),
+          validBefore: payload.validBefore.toString(),
+          nonce: payload.nonce,
+        },
+      },
+    };
+
+    return btoa(JSON.stringify(x402Payload));
+  }
+
+  /**
+   * Setup event listeners for wallet events
+   */
+  setupEventListeners(
+    onAccountsChanged?: (accounts: string[]) => void,
+    onChainChanged?: (chainId: number) => void
+  ): () => void {
+    const ethereum = (window as Window & { ethereum?: EthereumProvider }).ethereum;
+    if (!ethereum?.on || !ethereum?.removeListener) {
+      return () => {};
+    }
+
+    const handleAccountsChanged = (accounts: unknown) => {
+      if (Array.isArray(accounts)) {
+        if (accounts.length === 0) {
+          this.disconnect();
+        } else if (accounts[0] !== this.address) {
+          this.address = accounts[0] as string;
+        }
+        onAccountsChanged?.(accounts as string[]);
+      }
+    };
+
+    const handleChainChanged = (chainIdHex: unknown) => {
+      if (typeof chainIdHex === 'string') {
+        const chainId = parseInt(chainIdHex, 16);
+        const chain = getChainById(chainId);
+        if (chain) {
+          this.chainId = chainId;
+          this.chainName = chain.name;
+        }
+        onChainChanged?.(chainId);
+      }
+    };
+
+    ethereum.on('accountsChanged', handleAccountsChanged);
+    ethereum.on('chainChanged', handleChainChanged);
+
+    // Return cleanup function
+    return () => {
+      ethereum.removeListener!('accountsChanged', handleAccountsChanged);
+      ethereum.removeListener!('chainChanged', handleChainChanged);
+    };
+  }
+}
+
+export default EVMProvider;