uvd-x402-sdk 2.6.0 → 2.10.0

package/src/chains/index.ts

@@ -1,11 +1,12 @@
 /**
  * uvd-x402-sdk - Chain Registry
  *
- * Complete configuration for all 15 supported blockchain networks.
- * EVM chains (11): Use ERC-3009 TransferWithAuthorization
+ * Complete configuration for all 16 supported blockchain networks.
+ * EVM chains (10): Use ERC-3009 TransferWithAuthorization
  * SVM chains (2): Solana and Fogo - Use SPL tokens with partially-signed transactions
  * Stellar (1): Uses Soroban authorization entries
  * NEAR (1): Uses NEP-366 meta-transactions
+ * Algorand (2): Uses ASA transfers with atomic transaction groups
  */
 
 import type { ChainConfig, NetworkType, TokenType, TokenConfig } from '../types';
@@ -541,6 +542,76 @@ export const SUPPORTED_CHAINS: Record<string, ChainConfig> = {
       enabled: true, // NEP-366 meta-transactions supported
     },
   },
+
+  // ============================================================================
+  // ALGORAND (2 networks) - Uses ASA transfers with atomic transaction groups
+  // ============================================================================
+
+  algorand: {
+    chainId: 0, // Non-EVM (Algorand uses genesis hash for network identification)
+    chainIdHex: '0x0',
+    name: 'algorand',
+    displayName: 'Algorand',
+    networkType: 'algorand',
+    rpcUrl: 'https://mainnet-api.algonode.cloud',
+    explorerUrl: 'https://allo.info',
+    nativeCurrency: {
+      name: 'Algo',
+      symbol: 'ALGO',
+      decimals: 6, // Algorand uses 6 decimals (microAlgos)
+    },
+    usdc: {
+      address: '31566704', // USDC ASA ID on Algorand mainnet
+      decimals: 6,
+      name: 'USDC',
+      version: '1',
+    },
+    tokens: {
+      usdc: {
+        address: '31566704', // USDC ASA ID on Algorand mainnet
+        decimals: 6,
+        name: 'USDC',
+        version: '1',
+      },
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true,
+    },
+  },
+
+  'algorand-testnet': {
+    chainId: 0, // Non-EVM
+    chainIdHex: '0x0',
+    name: 'algorand-testnet',
+    displayName: 'Algorand Testnet',
+    networkType: 'algorand',
+    rpcUrl: 'https://testnet-api.algonode.cloud',
+    explorerUrl: 'https://testnet.allo.info',
+    nativeCurrency: {
+      name: 'Algo',
+      symbol: 'ALGO',
+      decimals: 6,
+    },
+    usdc: {
+      address: '10458941', // USDC ASA ID on Algorand testnet
+      decimals: 6,
+      name: 'USDC',
+      version: '1',
+    },
+    tokens: {
+      usdc: {
+        address: '10458941', // USDC ASA ID on Algorand testnet
+        decimals: 6,
+        name: 'USDC',
+        version: '1',
+      },
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true,
+    },
+  },
 };
 
 /**
@@ -637,6 +708,8 @@ export function getExplorerTxUrl(chainName: string, txHash: string): string | nu
       return `${chain.explorerUrl}/tx/${txHash}`;
     case 'near':
       return `${chain.explorerUrl}/txns/${txHash}`;
+    case 'algorand':
+      return `${chain.explorerUrl}/tx/${txHash}`;
     default:
       return null;
   }
@@ -659,11 +732,30 @@ export function getExplorerAddressUrl(chainName: string, address: string): strin
       return `${chain.explorerUrl}/account/${address}`;
     case 'near':
       return `${chain.explorerUrl}/address/${address}`;
+    case 'algorand':
+      return `${chain.explorerUrl}/account/${address}`;
     default:
       return null;
   }
 }
 
+/**
+ * Get list of Algorand chains
+ */
+export function getAlgorandChains(): ChainConfig[] {
+  return Object.values(SUPPORTED_CHAINS).filter(
+    chain => chain.networkType === 'algorand' && chain.x402.enabled
+  );
+}
+
+/**
+ * Check if a chain is Algorand-based
+ */
+export function isAlgorandChain(chainName: string): boolean {
+  const chain = getChainByName(chainName);
+  return chain?.networkType === 'algorand';
+}
+
 // ============================================================================
 // MULTI-TOKEN SUPPORT FUNCTIONS
 // ============================================================================

package/src/index.ts

@@ -3,11 +3,12 @@
  *
  * x402 Payment SDK - Gasless crypto payments using the Ultravioleta facilitator.
  *
- * Supports 14 blockchain networks:
+ * Supports 16 blockchain networks:
  * - EVM (10): Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche, Celo, HyperEVM, Unichain, Monad
  * - SVM (2): Solana, Fogo
  * - Stellar (1): Stellar
  * - NEAR (1): NEAR Protocol
+ * - Algorand (2): Algorand mainnet and testnet
  *
  * Supports both x402 v1 and v2 protocols.
  *
@@ -60,6 +61,18 @@
  * const header = near.encodePaymentHeader(payload);
  * ```
  *
+ * @example With Algorand
+ * ```ts
+ * import { AlgorandProvider } from 'uvd-x402-sdk/algorand';
+ * import { getChainByName } from 'uvd-x402-sdk';
+ *
+ * const algorand = new AlgorandProvider();
+ * const address = await algorand.connect();
+ * const algorandConfig = getChainByName('algorand')!;
+ * const payload = await algorand.signPayment(paymentInfo, algorandConfig);
+ * const header = algorand.encodePaymentHeader(payload, algorandConfig);
+ * ```
+ *
  * @example With React
  * ```tsx
  * import { X402Provider, useX402, usePayment } from 'uvd-x402-sdk/react';
@@ -100,6 +113,9 @@ export {
   getSupportedTokens,
   isTokenSupported,
   getChainsByToken,
+  // Algorand helper functions
+  getAlgorandChains,
+  isAlgorandChain,
 } from './chains';
 
 // x402 utilities
@@ -154,6 +170,7 @@ export type {
   SolanaPaymentPayload,
   StellarPaymentPayload,
   NEARPaymentPayload,
+  AlgorandPaymentPayload,
   X402HeaderName,
 
   // x402 header types (v1 and v2)
@@ -167,6 +184,7 @@ export type {
   X402SolanaPayload,
   X402StellarPayload,
   X402NEARPayload,
+  X402AlgorandPayload,
 
   // Config types
   X402ClientConfig,

package/src/providers/algorand/index.ts

@@ -0,0 +1,356 @@
+/**
+ * uvd-x402-sdk - Algorand Provider
+ *
+ * Provides wallet connection and payment creation for Algorand via Pera Wallet.
+ * Uses ASA (Algorand Standard Assets) transfers for USDC payments.
+ *
+ * USDC ASA IDs:
+ * - Mainnet: 31566704
+ * - Testnet: 10458941
+ *
+ * @example
+ * ```ts
+ * import { AlgorandProvider } from 'uvd-x402-sdk/algorand';
+ * import { getChainByName } from 'uvd-x402-sdk';
+ *
+ * const algorand = new AlgorandProvider();
+ *
+ * // Connect to Pera Wallet
+ * const address = await algorand.connect();
+ *
+ * // Create Algorand payment
+ * const chainConfig = getChainByName('algorand')!;
+ * const paymentPayload = await algorand.signPayment(paymentInfo, chainConfig);
+ * const header = algorand.encodePaymentHeader(paymentPayload, chainConfig);
+ * ```
+ */
+
+import type {
+  ChainConfig,
+  PaymentInfo,
+  AlgorandPaymentPayload,
+  WalletAdapter,
+  X402Version,
+} from '../../types';
+import { X402Error } from '../../types';
+import { getChainByName } from '../../chains';
+import { chainToCAIP2 } from '../../utils';
+
+/**
+ * Browser-compatible base64 encoding for Uint8Array
+ */
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+// Lazy import Algorand dependencies
+let algosdk: typeof import('algosdk') | null = null;
+let PeraWalletConnect: typeof import('@perawallet/connect').PeraWalletConnect | null = null;
+
+async function loadAlgorandDeps() {
+  if (!algosdk) {
+    algosdk = await import('algosdk');
+  }
+  if (!PeraWalletConnect) {
+    const peraModule = await import('@perawallet/connect');
+    PeraWalletConnect = peraModule.PeraWalletConnect;
+  }
+}
+
+/**
+ * AlgorandProvider - Wallet adapter for Algorand via Pera Wallet
+ *
+ * Supports both mainnet and testnet through chain configuration.
+ */
+export class AlgorandProvider implements WalletAdapter {
+  readonly id = 'pera';
+  readonly name = 'Pera Wallet';
+  readonly networkType = 'algorand' as const;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private peraWallet: any = null;
+  private address: string | null = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private algodClients: Map<string, any> = new Map();
+
+  /**
+   * Check if Pera Wallet is available
+   * Note: Pera works as a WalletConnect modal, so it's always "available"
+   */
+  isAvailable(): boolean {
+    return typeof window !== 'undefined';
+  }
+
+  /**
+   * Connect to Pera Wallet
+   */
+  async connect(_chainName?: string): Promise<string> {
+    await loadAlgorandDeps();
+
+    if (!PeraWalletConnect) {
+      throw new X402Error('Failed to load Pera Wallet SDK', 'WALLET_NOT_FOUND');
+    }
+
+    try {
+      // Create Pera Wallet instance
+      this.peraWallet = new PeraWalletConnect!();
+
+      // Try to reconnect from previous session
+      const accounts = await this.peraWallet.reconnectSession();
+
+      if (accounts.length > 0) {
+        this.address = accounts[0];
+        return accounts[0];
+      }
+
+      // If no previous session, connect fresh
+      const newAccounts = await this.peraWallet.connect();
+
+      if (newAccounts.length === 0) {
+        throw new X402Error('No accounts returned from Pera Wallet', 'WALLET_CONNECTION_REJECTED');
+      }
+
+      this.address = newAccounts[0];
+
+      // Set up disconnect handler
+      this.peraWallet.connector?.on('disconnect', () => {
+        this.address = null;
+      });
+
+      return newAccounts[0];
+    } catch (error: unknown) {
+      if (error instanceof Error) {
+        if (error.message.includes('rejected') || error.message.includes('cancelled')) {
+          throw new X402Error('Connection rejected by user', 'WALLET_CONNECTION_REJECTED');
+        }
+      }
+      throw new X402Error(
+        `Failed to connect Pera Wallet: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'UNKNOWN_ERROR',
+        error
+      );
+    }
+  }
+
+  /**
+   * Disconnect from Pera Wallet
+   */
+  async disconnect(): Promise<void> {
+    if (this.peraWallet) {
+      try {
+        await this.peraWallet.disconnect();
+      } catch {
+        // Ignore disconnect errors
+      }
+    }
+    this.peraWallet = null;
+    this.address = null;
+    this.algodClients.clear();
+  }
+
+  /**
+   * Get current address
+   */
+  getAddress(): string | null {
+    return this.address;
+  }
+
+  /**
+   * Get USDC (ASA) balance
+   */
+  async getBalance(chainConfig: ChainConfig): Promise<string> {
+    await loadAlgorandDeps();
+
+    if (!this.address) {
+      throw new X402Error('Wallet not connected', 'WALLET_NOT_CONNECTED');
+    }
+
+    const algodClient = await this.getAlgodClient(chainConfig);
+    const assetId = parseInt(chainConfig.usdc.address, 10);
+
+    try {
+      const accountInfo = await algodClient.accountInformation(this.address).do();
+
+      // Find the USDC asset in the account's assets
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const assets: any[] = accountInfo.assets || accountInfo['assets'] || [];
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const usdcAsset = assets.find((asset: any) =>
+        (asset.assetId || asset['asset-id']) === assetId
+      );
+
+      if (!usdcAsset) {
+        return '0.00'; // Account not opted into USDC
+      }
+
+      const amount = Number(usdcAsset.amount || usdcAsset['amount']);
+      const balance = amount / Math.pow(10, chainConfig.usdc.decimals);
+      return balance.toFixed(2);
+    } catch {
+      return '0.00';
+    }
+  }
+
+  /**
+   * Create Algorand ASA transfer payment
+   *
+   * Transaction structure:
+   * 1. ASA Transfer from user to recipient
+   * 2. Facilitator pays transaction fees
+   */
+  async signPayment(paymentInfo: PaymentInfo, chainConfig: ChainConfig): Promise<string> {
+    await loadAlgorandDeps();
+
+    if (!this.peraWallet || !this.address) {
+      throw new X402Error('Wallet not connected', 'WALLET_NOT_CONNECTED');
+    }
+
+    if (!algosdk) {
+      throw new X402Error('Algorand SDK not loaded', 'UNKNOWN_ERROR');
+    }
+
+    const algodClient = await this.getAlgodClient(chainConfig);
+
+    // Get recipient address (use algorand-specific or fallback to default)
+    const recipient = paymentInfo.recipients?.algorand || paymentInfo.recipient;
+    const assetId = parseInt(chainConfig.usdc.address, 10);
+
+    // Parse amount (6 decimals for USDC)
+    const amount = Math.floor(parseFloat(paymentInfo.amount) * 1_000_000);
+
+    try {
+      // Get suggested transaction parameters
+      const suggestedParams = await algodClient.getTransactionParams().do();
+
+      // Create ASA transfer transaction
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const txn = algosdk.makeAssetTransferTxnWithSuggestedParamsFromObject({
+        sender: this.address,
+        receiver: recipient,
+        amount: BigInt(amount),
+        assetIndex: assetId,
+        suggestedParams: suggestedParams,
+        note: new TextEncoder().encode('x402 payment via uvd-x402-sdk'),
+      } as any);
+
+      // Sign with Pera Wallet
+      const signedTxns = await this.peraWallet.signTransaction([[{ txn }]]);
+
+      if (!signedTxns || signedTxns.length === 0) {
+        throw new X402Error('No signed transaction returned', 'SIGNATURE_REJECTED');
+      }
+
+      const signedTxn = signedTxns[0];
+
+      const payload: AlgorandPaymentPayload = {
+        from: this.address,
+        to: recipient,
+        amount: amount.toString(),
+        assetId: assetId,
+        signedTxn: uint8ArrayToBase64(signedTxn),
+      };
+
+      return JSON.stringify(payload);
+    } catch (error: unknown) {
+      if (error instanceof X402Error) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.message.includes('rejected') || error.message.includes('cancelled')) {
+          throw new X402Error('Signature rejected by user', 'SIGNATURE_REJECTED');
+        }
+      }
+      throw new X402Error(
+        `Failed to sign transaction: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'PAYMENT_FAILED',
+        error
+      );
+    }
+  }
+
+  /**
+   * Encode Algorand payment as X-PAYMENT header
+   *
+   * @param paymentPayload - JSON-encoded payment payload from signPayment()
+   * @param chainConfig - Chain configuration
+   * @param version - x402 protocol version (1 or 2, defaults to 1)
+   * @returns Base64-encoded X-PAYMENT header value
+   */
+  encodePaymentHeader(
+    paymentPayload: string,
+    chainConfig?: ChainConfig,
+    version: X402Version = 1
+  ): string {
+    const payload = JSON.parse(paymentPayload) as AlgorandPaymentPayload;
+
+    // Use chain name from config, or default to 'algorand'
+    const networkName = chainConfig?.name || 'algorand';
+
+    // Build the payload data
+    const payloadData = {
+      from: payload.from,
+      to: payload.to,
+      amount: payload.amount,
+      assetId: payload.assetId,
+      signedTxn: payload.signedTxn,
+      ...(payload.note && { note: payload.note }),
+    };
+
+    // 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));
+  }
+
+  // Private helpers
+
+  /**
+   * Get or create an Algod client for a specific chain
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private async getAlgodClient(chainConfig?: ChainConfig): Promise<any> {
+    await loadAlgorandDeps();
+
+    if (!algosdk) {
+      throw new X402Error('Algorand SDK not loaded', 'UNKNOWN_ERROR');
+    }
+
+    const config = chainConfig || getChainByName('algorand');
+    if (!config) {
+      throw new X402Error('Chain config not found', 'CHAIN_NOT_SUPPORTED');
+    }
+
+    // Cache by RPC URL
+    const cacheKey = config.rpcUrl;
+
+    if (this.algodClients.has(cacheKey)) {
+      return this.algodClients.get(cacheKey)!;
+    }
+
+    // Create new Algod client
+    // Algonode.cloud doesn't require auth token
+    const client = new algosdk.Algodv2('', config.rpcUrl, '');
+    this.algodClients.set(cacheKey, client);
+
+    return client;
+  }
+}
+
+// Default export
+export default AlgorandProvider;

package/src/types/index.ts

@@ -15,10 +15,11 @@
  * - 'svm': Solana Virtual Machine chains (Solana, Fogo) (use SPL tokens)
  * - 'stellar': Stellar network (use Soroban)
  * - 'near': NEAR Protocol (use NEP-366)
+ * - 'algorand': Algorand network (use ASA transfers with atomic transactions)
  *
  * @deprecated 'solana' type is deprecated, use 'svm' instead
  */
-export type NetworkType = 'evm' | 'svm' | 'solana' | 'stellar' | 'near';
+export type NetworkType = 'evm' | 'svm' | 'solana' | 'stellar' | 'near' | 'algorand';
 
 /**
  * Supported stablecoin token types
@@ -200,6 +201,7 @@ export interface PaymentInfo {
     solana?: string;
     near?: string;
     stellar?: string;
+    algorand?: string;
   };
   /** Facilitator address (for Solana fee payer) */
   facilitator?: string;
@@ -340,6 +342,28 @@ export interface NEARPaymentPayload {
   network: 'near';
 }
 
+/**
+ * Algorand payment payload (atomic transaction group)
+ *
+ * Algorand uses a unique payment model where the facilitator creates and signs
+ * an atomic transaction group. The user signs their portion (the ASA transfer)
+ * and the facilitator submits the complete group.
+ */
+export interface AlgorandPaymentPayload {
+  /** Sender's Algorand address (58-character base32) */
+  from: string;
+  /** Recipient's Algorand address */
+  to: string;
+  /** Amount in base units (microAlgos for ALGO, or base units for ASA) */
+  amount: string;
+  /** USDC ASA ID (31566704 for mainnet, 10458941 for testnet) */
+  assetId: number;
+  /** Base64-encoded signed transaction bytes */
+  signedTxn: string;
+  /** Optional note field */
+  note?: string;
+}
+
 /**
  * Union type for all payment payloads
  */
@@ -347,7 +371,8 @@ export type PaymentPayload =
   | EVMPaymentPayload
   | SolanaPaymentPayload
   | StellarPaymentPayload
-  | NEARPaymentPayload;
+  | NEARPaymentPayload
+  | AlgorandPaymentPayload;
 
 // ============================================================================
 // X402 HEADER TYPES (v1 and v2)
@@ -381,6 +406,9 @@ export const CAIP2_IDENTIFIERS: Record<string, string> = {
   stellar: 'stellar:pubnet',
   // NEAR
   near: 'near:mainnet',
+  // Algorand
+  algorand: 'algorand:mainnet',
+  'algorand-testnet': 'algorand:testnet',
 };
 
 /**
@@ -468,6 +496,18 @@ export interface X402NEARPayload {
   signedDelegateAction: string;
 }
 
+/**
+ * Algorand-specific payload in x402 header
+ */
+export interface X402AlgorandPayload {
+  from: string;
+  to: string;
+  amount: string;
+  assetId: number;
+  signedTxn: string;
+  note?: string;
+}
+
 /**
  * Union of all x402 payload types
  */
@@ -475,7 +515,8 @@ export type X402PayloadData =
   | X402EVMPayload
   | X402SolanaPayload
   | X402StellarPayload
-  | X402NEARPayload;
+  | X402NEARPayload
+  | X402AlgorandPayload;
 
 // ============================================================================
 // CLIENT CONFIGURATION