uvd-x402-sdk 2.0.1

package/src/types/index.ts

@@ -0,0 +1,561 @@
+/**
+ * uvd-x402-sdk - Type Definitions
+ *
+ * Core TypeScript interfaces for the x402 payment SDK.
+ * These types define the contract between the SDK and consuming applications.
+ */
+
+// ============================================================================
+// CHAIN CONFIGURATION TYPES
+// ============================================================================
+
+/**
+ * Network type categorization
+ * - 'evm': Ethereum Virtual Machine compatible chains (use EIP-712)
+ * - 'svm': Solana Virtual Machine chains (Solana, Fogo) (use SPL tokens)
+ * - 'stellar': Stellar network (use Soroban)
+ * - 'near': NEAR Protocol (use NEP-366)
+ *
+ * @deprecated 'solana' type is deprecated, use 'svm' instead
+ */
+export type NetworkType = 'evm' | 'svm' | 'solana' | 'stellar' | 'near';
+
+/**
+ * USDC token configuration for a specific chain
+ */
+export interface USDCConfig {
+  /** Contract/mint address */
+  address: string;
+  /** Token decimals (6 for most chains, 7 for Stellar, 18 for BSC) */
+  decimals: number;
+  /** Token name for EIP-712 domain (e.g., "USD Coin" or "USDC") */
+  name: string;
+  /** Token version for EIP-712 domain */
+  version: string;
+}
+
+/**
+ * Native currency configuration
+ */
+export interface NativeCurrency {
+  name: string;
+  symbol: string;
+  decimals: number;
+}
+
+/**
+ * Complete chain configuration
+ */
+export interface ChainConfig {
+  /** Numeric chain ID (0 for non-EVM chains) */
+  chainId: number;
+  /** Hex-encoded chain ID for wallet_switchEthereumChain */
+  chainIdHex: string;
+  /** Internal chain identifier (e.g., 'base', 'solana') */
+  name: string;
+  /** Human-readable display name */
+  displayName: string;
+  /** Network type for routing */
+  networkType: NetworkType;
+  /** Primary RPC endpoint URL */
+  rpcUrl: string;
+  /** Block explorer base URL */
+  explorerUrl: string;
+  /** Native currency info */
+  nativeCurrency: NativeCurrency;
+  /** USDC token configuration */
+  usdc: USDCConfig;
+  /** x402 facilitator configuration */
+  x402: {
+    facilitatorUrl: string;
+    enabled: boolean;
+  };
+}
+
+// ============================================================================
+// WALLET TYPES
+// ============================================================================
+
+/**
+ * Current wallet connection state
+ */
+export interface WalletState {
+  /** Whether a wallet is currently connected */
+  connected: boolean;
+  /** Connected wallet address (null if not connected) */
+  address: string | null;
+  /** Current chain ID (null for non-EVM or disconnected) */
+  chainId: number | null;
+  /** Current network name */
+  network: string | null;
+  /** Network type of connected wallet */
+  networkType: NetworkType | null;
+  /** USDC balance on current chain (null if unknown) */
+  balance: string | null;
+}
+
+/**
+ * Wallet adapter interface for different wallet types
+ */
+export interface WalletAdapter {
+  /** Unique identifier for this wallet type */
+  readonly id: string;
+  /** Display name */
+  readonly name: string;
+  /** Network type this adapter supports */
+  readonly networkType: NetworkType;
+
+  /** Check if this wallet is available/installed */
+  isAvailable(): boolean;
+
+  /** Connect to the wallet */
+  connect(chainName?: string): Promise<string>;
+
+  /** Disconnect from the wallet */
+  disconnect(): Promise<void>;
+
+  /** Switch to a different chain (EVM only) */
+  switchChain?(chainName: string): Promise<void>;
+
+  /** Sign a payment payload */
+  signPayment(paymentInfo: PaymentInfo, chainConfig: ChainConfig): Promise<string>;
+
+  /** Check USDC balance */
+  getBalance(chainConfig: ChainConfig): Promise<string>;
+
+  /** Get current address */
+  getAddress(): string | null;
+
+  /** Get current chain ID (EVM only) */
+  getChainId?(): number | null;
+}
+
+/**
+ * EIP-712 domain for typed data signing
+ */
+export interface EIP712Domain {
+  name: string;
+  version: string;
+  chainId: number;
+  verifyingContract: string;
+}
+
+/**
+ * EIP-712 type definitions
+ */
+export interface EIP712Types {
+  [typeName: string]: Array<{ name: string; type: string }>;
+}
+
+// ============================================================================
+// PAYMENT TYPES
+// ============================================================================
+
+/**
+ * Payment information returned by backend on 402 response
+ */
+export interface PaymentInfo {
+  /** Default recipient address */
+  recipient: string;
+  /** Network-specific recipient addresses */
+  recipients?: {
+    evm?: string;
+    solana?: string;
+    near?: string;
+    stellar?: string;
+  };
+  /** Facilitator address (for Solana fee payer) */
+  facilitator?: string;
+  /** Amount in USD (e.g., "10.00") */
+  amount: string;
+  /** Token symbol (usually "USDC") */
+  token?: string;
+  /** Network hint from backend */
+  network?: string;
+  /** Supported chain IDs */
+  supportedChains?: number[];
+}
+
+/**
+ * Simple payment request from application
+ */
+export interface PaymentRequest {
+  /** Amount in USDC (e.g., "10.00") */
+  amount: string;
+  /** Override recipient address (optional) */
+  recipient?: string;
+  /** Application-specific metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of a payment operation
+ */
+export interface PaymentResult {
+  /** Whether payment was successful */
+  success: boolean;
+  /** Base64-encoded X-PAYMENT header value */
+  paymentHeader: string;
+  /** Transaction hash (if available) */
+  transactionHash?: string;
+  /** Network where payment was made */
+  network: string;
+  /** Payer address */
+  payer?: string;
+  /** Error message (if success is false) */
+  error?: string;
+}
+
+// ============================================================================
+// PAYLOAD TYPES (Internal)
+// ============================================================================
+
+/**
+ * EVM payment payload (ERC-3009 TransferWithAuthorization)
+ */
+export interface EVMPaymentPayload {
+  from: string;
+  to: string;
+  value: string;
+  validAfter: number;
+  validBefore: number;
+  nonce: string;
+  v: number;
+  r: string;
+  s: string;
+  chainId: number;
+  token: string;
+}
+
+/**
+ * Solana payment payload (partially-signed transaction)
+ */
+export interface SolanaPaymentPayload {
+  /** Base64-encoded serialized transaction */
+  transaction: string;
+}
+
+/**
+ * Stellar payment payload (Soroban authorization)
+ */
+export interface StellarPaymentPayload {
+  /** Sender G... public key */
+  from: string;
+  /** Recipient G... public key */
+  to: string;
+  /** Amount in stroops (7 decimals) */
+  amount: string;
+  /** USDC SAC contract address */
+  tokenContract: string;
+  /** Base64 XDR-encoded SorobanAuthorizationEntry */
+  authorizationEntryXdr: string;
+  /** Random 64-bit nonce */
+  nonce: number;
+  /** Ledger when authorization expires */
+  signatureExpirationLedger: number;
+}
+
+/**
+ * NEAR payment payload (NEP-366 meta-transaction)
+ */
+export interface NEARPaymentPayload {
+  /** Base64 Borsh-encoded SignedDelegateAction */
+  signedDelegateAction: string;
+  network: 'near';
+}
+
+/**
+ * Union type for all payment payloads
+ */
+export type PaymentPayload =
+  | EVMPaymentPayload
+  | SolanaPaymentPayload
+  | StellarPaymentPayload
+  | NEARPaymentPayload;
+
+// ============================================================================
+// X402 HEADER TYPES (v1 and v2)
+// ============================================================================
+
+/**
+ * x402 protocol version
+ */
+export type X402Version = 1 | 2;
+
+/**
+ * CAIP-2 chain identifiers for x402 v2
+ * @see https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md
+ */
+export const CAIP2_IDENTIFIERS: Record<string, string> = {
+  // EVM chains
+  base: 'eip155:8453',
+  ethereum: 'eip155:1',
+  polygon: 'eip155:137',
+  arbitrum: 'eip155:42161',
+  optimism: 'eip155:10',
+  avalanche: 'eip155:43114',
+  celo: 'eip155:42220',
+  hyperevm: 'eip155:999',
+  unichain: 'eip155:130',
+  monad: 'eip155:143',
+  bsc: 'eip155:56',
+  // SVM chains
+  solana: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+  fogo: 'svm:fogo',
+  // Stellar
+  stellar: 'stellar:pubnet',
+  // NEAR
+  near: 'near:mainnet',
+};
+
+/**
+ * Reverse mapping from CAIP-2 to chain name
+ */
+export const CAIP2_TO_CHAIN: Record<string, string> = Object.fromEntries(
+  Object.entries(CAIP2_IDENTIFIERS).map(([k, v]) => [v, k])
+);
+
+/**
+ * x402 v1 header structure (network as string)
+ */
+export interface X402HeaderV1 {
+  x402Version: 1;
+  scheme: 'exact';
+  network: string;
+  payload: X402PayloadData;
+}
+
+/**
+ * x402 v2 payment option
+ */
+export interface X402PaymentOption {
+  network: string; // CAIP-2 format
+  asset: string;
+  amount: string;
+  facilitator?: string;
+}
+
+/**
+ * x402 v2 header structure (CAIP-2 network, accepts array)
+ */
+export interface X402HeaderV2 {
+  x402Version: 2;
+  scheme: 'exact';
+  network: string; // CAIP-2 format
+  payload: X402PayloadData;
+  accepts?: X402PaymentOption[];
+}
+
+/**
+ * Union type for both v1 and v2 headers
+ */
+export type X402Header = X402HeaderV1 | X402HeaderV2;
+
+/**
+ * EVM-specific payload in x402 header
+ */
+export interface X402EVMPayload {
+  signature: string;
+  authorization: {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+  };
+}
+
+/**
+ * Solana-specific payload in x402 header
+ */
+export interface X402SolanaPayload {
+  transaction: string;
+}
+
+/**
+ * Stellar-specific payload in x402 header
+ */
+export interface X402StellarPayload {
+  from: string;
+  to: string;
+  amount: string;
+  tokenContract: string;
+  authorizationEntryXdr: string;
+  nonce: number;
+  signatureExpirationLedger: number;
+}
+
+/**
+ * NEAR-specific payload in x402 header
+ */
+export interface X402NEARPayload {
+  signedDelegateAction: string;
+}
+
+/**
+ * Union of all x402 payload types
+ */
+export type X402PayloadData =
+  | X402EVMPayload
+  | X402SolanaPayload
+  | X402StellarPayload
+  | X402NEARPayload;
+
+// ============================================================================
+// CLIENT CONFIGURATION
+// ============================================================================
+
+/**
+ * Multi-payment configuration for supporting multiple networks
+ */
+export interface MultiPaymentConfig {
+  /** Networks to support (e.g., ['base', 'solana', 'stellar', 'near']) */
+  networks: string[];
+  /** Default network if user hasn't selected one */
+  defaultNetwork?: string;
+  /** Whether to auto-detect user's preferred network based on wallet */
+  autoDetect?: boolean;
+}
+
+/**
+ * SDK client configuration options
+ */
+export interface X402ClientConfig {
+  /** Facilitator URL (default: https://facilitator.ultravioletadao.xyz) */
+  facilitatorUrl?: string;
+  /** Default chain to connect to */
+  defaultChain?: string;
+  /** Auto-connect on initialization */
+  autoConnect?: boolean;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Custom chain configurations (override defaults) */
+  customChains?: Record<string, Partial<ChainConfig>>;
+  /** Wallet preference order */
+  walletPreference?: string[];
+  /** Custom RPC URLs (override defaults) */
+  rpcOverrides?: Record<string, string>;
+  /**
+   * x402 protocol version to use
+   * - 1: Classic format with network as string (e.g., "base")
+   * - 2: CAIP-2 format with accepts array (e.g., "eip155:8453")
+   * - 'auto': Auto-detect from 402 response (default)
+   */
+  x402Version?: X402Version | 'auto';
+  /** Multi-payment configuration for supporting multiple networks */
+  multiPayment?: MultiPaymentConfig;
+}
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG: Required<Pick<X402ClientConfig, 'facilitatorUrl' | 'defaultChain' | 'autoConnect' | 'debug' | 'x402Version'>> = {
+  facilitatorUrl: 'https://facilitator.ultravioletadao.xyz',
+  defaultChain: 'base',
+  autoConnect: false,
+  debug: false,
+  x402Version: 'auto',
+};
+
+// ============================================================================
+// BALANCE TYPES
+// ============================================================================
+
+/**
+ * Balance information for a single network
+ */
+export interface NetworkBalance {
+  /** Chain name */
+  chainName: string;
+  /** Human-readable display name */
+  displayName: string;
+  /** Formatted balance (e.g., "15.50") or null if loading/error */
+  balance: string | null;
+  /** Whether balance is currently being fetched */
+  isLoading: boolean;
+  /** Error message if fetch failed */
+  error: string | null;
+}
+
+// ============================================================================
+// EVENT TYPES
+// ============================================================================
+
+/**
+ * Events emitted by the SDK client
+ */
+export type X402Event =
+  | 'connect'
+  | 'disconnect'
+  | 'chainChanged'
+  | 'accountChanged'
+  | 'balanceChanged'
+  | 'paymentStarted'
+  | 'paymentSigned'
+  | 'paymentCompleted'
+  | 'paymentFailed';
+
+/**
+ * Event data types
+ */
+export interface X402EventData {
+  connect: WalletState;
+  disconnect: void;
+  chainChanged: { chainId: number; chainName: string };
+  accountChanged: { address: string };
+  balanceChanged: { balance: string };
+  paymentStarted: { amount: string; network: string };
+  paymentSigned: { paymentHeader: string };
+  paymentCompleted: PaymentResult;
+  paymentFailed: { error: string; code: X402ErrorCode };
+}
+
+/**
+ * Event handler type
+ */
+export type X402EventHandler<E extends X402Event> = (data: X402EventData[E]) => void;
+
+// ============================================================================
+// ERROR TYPES
+// ============================================================================
+
+/**
+ * Error codes for categorizing errors
+ */
+export type X402ErrorCode =
+  | 'WALLET_NOT_FOUND'
+  | 'WALLET_NOT_CONNECTED'
+  | 'WALLET_CONNECTION_REJECTED'
+  | 'WALLET_CONNECTION_TIMEOUT'
+  | 'CHAIN_NOT_SUPPORTED'
+  | 'CHAIN_SWITCH_REJECTED'
+  | 'INSUFFICIENT_BALANCE'
+  | 'SIGNATURE_REJECTED'
+  | 'PAYMENT_FAILED'
+  | 'PAYMENT_TIMEOUT'
+  | 'NETWORK_ERROR'
+  | 'INVALID_CONFIG'
+  | 'INVALID_AMOUNT'
+  | 'INVALID_RECIPIENT'
+  | 'UNKNOWN_ERROR';
+
+/**
+ * SDK-specific error class
+ */
+export class X402Error extends Error {
+  public readonly code: X402ErrorCode;
+  public readonly details?: unknown;
+
+  constructor(message: string, code: X402ErrorCode, details?: unknown) {
+    super(message);
+    this.name = 'X402Error';
+    this.code = code;
+    this.details = details;
+
+    // Maintains proper stack trace for where error was thrown (V8 engines)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, X402Error);
+    }
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,20 @@
+/**
+ * uvd-x402-sdk - Utilities
+ *
+ * Re-exports all utility functions.
+ */
+
+export {
+  detectX402Version,
+  chainToCAIP2,
+  caip2ToChain,
+  parseNetworkIdentifier,
+  encodeX402Header,
+  decodeX402Header,
+  createX402V1Header,
+  createX402V2Header,
+  createX402Header,
+  generatePaymentOptions,
+  isCAIP2Format,
+  convertX402Header,
+} from './x402';