uvd-x402-sdk 2.10.1 → 2.12.0

package/src/providers/algorand/index.ts

@@ -1,9 +1,14 @@
 /**
  * uvd-x402-sdk - Algorand Provider
  *
- * Provides wallet connection and payment creation for Algorand via Pera Wallet.
+ * Provides wallet connection and payment creation for Algorand.
+ * Supports both Lute Wallet (desktop browser extension) and Pera Wallet (mobile).
  * Uses ASA (Algorand Standard Assets) transfers for USDC payments.
  *
+ * Wallet Priority:
+ * 1. Lute Wallet - Desktop browser extension (preferred for desktop)
+ * 2. Pera Wallet - Mobile via WalletConnect (fallback/mobile)
+ *
  * USDC ASA IDs:
  * - Mainnet: 31566704
  * - Testnet: 10458941
@@ -15,7 +20,7 @@
  *
  * const algorand = new AlgorandProvider();
  *
- * // Connect to Pera Wallet
+ * // Connect to Lute (desktop) or Pera (mobile) automatically
  * const address = await algorand.connect();
  *
  * // Create Algorand payment
@@ -50,27 +55,60 @@ function uint8ArrayToBase64(bytes: Uint8Array): string {
 // Lazy import Algorand dependencies
 let algosdk: typeof import('algosdk') | null = null;
 let PeraWalletConnect: typeof import('@perawallet/connect').PeraWalletConnect | null = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let LuteConnect: any = null;
 
 async function loadAlgorandDeps() {
   if (!algosdk) {
     algosdk = await import('algosdk');
   }
+}
+
+async function loadPeraWallet() {
   if (!PeraWalletConnect) {
     const peraModule = await import('@perawallet/connect');
     PeraWalletConnect = peraModule.PeraWalletConnect;
   }
 }
 
+async function loadLuteWallet() {
+  if (!LuteConnect) {
+    try {
+      const luteModule = await import('lute-connect');
+      LuteConnect = luteModule.default;
+    } catch {
+      // Lute not installed, will fall back to Pera
+      LuteConnect = null;
+    }
+  }
+}
+
 /**
- * AlgorandProvider - Wallet adapter for Algorand via Pera Wallet
+ * Check if Lute wallet extension is installed
+ */
+function isLuteAvailable(): boolean {
+  if (typeof window === 'undefined') return false;
+  // Lute injects itself into window.algorand or window.lute
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const win = window as any;
+  return !!(win.algorand || win.lute);
+}
+
+/**
+ * AlgorandProvider - Wallet adapter for Algorand
  *
- * Supports both mainnet and testnet through chain configuration.
+ * Supports Lute Wallet (desktop) and Pera Wallet (mobile).
+ * Automatically detects and uses the best available wallet.
  */
 export class AlgorandProvider implements WalletAdapter {
-  readonly id = 'pera';
-  readonly name = 'Pera Wallet';
+  readonly id = 'algorand';
+  readonly name = 'Algorand Wallet';
   readonly networkType = 'algorand' as const;
 
+  // Active wallet type
+  private walletType: 'lute' | 'pera' | null = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private luteWallet: any = null;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private peraWallet: any = null;
   private address: string | null = null;
@@ -78,19 +116,91 @@ export class AlgorandProvider implements WalletAdapter {
   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"
+   * Check if any Algorand wallet is available
+   * Returns true if Lute extension is installed OR we can use Pera (always available via WalletConnect)
    */
   isAvailable(): boolean {
     return typeof window !== 'undefined';
   }
 
   /**
-   * Connect to Pera Wallet
+   * Get the name of the currently connected wallet
+   */
+  getWalletName(): string {
+    if (this.walletType === 'lute') return 'Lute Wallet';
+    if (this.walletType === 'pera') return 'Pera Wallet';
+    return 'Algorand Wallet';
+  }
+
+  /**
+   * Connect to Algorand wallet
+   * Priority: Lute (desktop extension) > Pera (mobile via WalletConnect)
    */
   async connect(_chainName?: string): Promise<string> {
     await loadAlgorandDeps();
 
+    // Try Lute first (better desktop UX)
+    if (isLuteAvailable()) {
+      try {
+        return await this.connectLute();
+      } catch (error) {
+        // Lute failed, try Pera
+        console.warn('Lute connection failed, falling back to Pera:', error);
+      }
+    }
+
+    // Fall back to Pera (mobile/WalletConnect)
+    return await this.connectPera();
+  }
+
+  /**
+   * Connect to Lute Wallet (desktop browser extension)
+   */
+  private async connectLute(): Promise<string> {
+    await loadLuteWallet();
+
+    if (!LuteConnect) {
+      throw new X402Error('Lute Wallet SDK not available', 'WALLET_NOT_FOUND');
+    }
+
+    try {
+      this.luteWallet = new LuteConnect('402milly');
+
+      // Get Algorand genesis ID for mainnet
+      const genesisId = 'mainnet-v1.0';
+
+      // Connect and get accounts
+      const accounts = await this.luteWallet.connect(genesisId);
+
+      if (!accounts || accounts.length === 0) {
+        throw new X402Error('No accounts returned from Lute Wallet', 'WALLET_CONNECTION_REJECTED');
+      }
+
+      this.address = accounts[0];
+      this.walletType = 'lute';
+
+      return accounts[0];
+    } 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('Connection rejected by user', 'WALLET_CONNECTION_REJECTED');
+        }
+      }
+      throw new X402Error(
+        `Failed to connect Lute Wallet: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'UNKNOWN_ERROR',
+        error
+      );
+    }
+  }
+
+  /**
+   * Connect to Pera Wallet (mobile via WalletConnect)
+   */
+  private async connectPera(): Promise<string> {
+    await loadPeraWallet();
+
     if (!PeraWalletConnect) {
       throw new X402Error('Failed to load Pera Wallet SDK', 'WALLET_NOT_FOUND');
     }
@@ -104,6 +214,7 @@ export class AlgorandProvider implements WalletAdapter {
 
       if (accounts.length > 0) {
         this.address = accounts[0];
+        this.walletType = 'pera';
         return accounts[0];
       }
 
@@ -115,10 +226,12 @@ export class AlgorandProvider implements WalletAdapter {
       }
 
       this.address = newAccounts[0];
+      this.walletType = 'pera';
 
       // Set up disconnect handler
       this.peraWallet.connector?.on('disconnect', () => {
         this.address = null;
+        this.walletType = null;
       });
 
       return newAccounts[0];
@@ -137,18 +250,27 @@ export class AlgorandProvider implements WalletAdapter {
   }
 
   /**
-   * Disconnect from Pera Wallet
+   * Disconnect from wallet
    */
   async disconnect(): Promise<void> {
-    if (this.peraWallet) {
+    if (this.walletType === 'lute' && this.luteWallet) {
+      try {
+        // Lute doesn't have a disconnect method, just clear state
+      } catch {
+        // Ignore disconnect errors
+      }
+      this.luteWallet = null;
+    }
+    if (this.walletType === 'pera' && this.peraWallet) {
       try {
         await this.peraWallet.disconnect();
       } catch {
         // Ignore disconnect errors
       }
+      this.peraWallet = null;
     }
-    this.peraWallet = null;
     this.address = null;
+    this.walletType = null;
     this.algodClients.clear();
   }
 
@@ -196,16 +318,18 @@ export class AlgorandProvider implements WalletAdapter {
   }
 
   /**
-   * Create Algorand ASA transfer payment
+   * Create Algorand atomic group payment (GoPlausible x402-avm spec)
    *
-   * Transaction structure:
-   * 1. ASA Transfer from user to recipient
-   * 2. Facilitator pays transaction fees
+   * Transaction structure (atomic group):
+   * - Transaction 0: Fee payment (UNSIGNED) - facilitator -> facilitator, covers all fees
+   * - Transaction 1: ASA transfer (SIGNED) - client -> merchant
+   *
+   * The facilitator signs transaction 0 and submits the complete atomic group.
    */
   async signPayment(paymentInfo: PaymentInfo, chainConfig: ChainConfig): Promise<string> {
     await loadAlgorandDeps();
 
-    if (!this.peraWallet || !this.address) {
+    if (!this.address || !this.walletType) {
       throw new X402Error('Wallet not connected', 'WALLET_NOT_CONNECTED');
     }
 
@@ -219,6 +343,15 @@ export class AlgorandProvider implements WalletAdapter {
     const recipient = paymentInfo.recipients?.algorand || paymentInfo.recipient;
     const assetId = parseInt(chainConfig.usdc.address, 10);
 
+    // Get facilitator address (fee payer)
+    const facilitatorAddress = paymentInfo.facilitator;
+    if (!facilitatorAddress) {
+      throw new X402Error(
+        'Facilitator address required for Algorand payments. Set paymentInfo.facilitator',
+        'PAYMENT_FAILED'
+      );
+    }
+
     // Parse amount (6 decimals for USDC)
     const amount = Math.floor(parseFloat(paymentInfo.amount) * 1_000_000);
 
@@ -226,32 +359,92 @@ export class AlgorandProvider implements WalletAdapter {
       // Get suggested transaction parameters
       const suggestedParams = await algodClient.getTransactionParams().do();
 
-      // Create ASA transfer transaction
+      // Transaction 0: Fee payment (facilitator -> facilitator, 0 amount)
+      // This transaction pays fees for both txns in the group (fee pooling)
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const txn = algosdk.makeAssetTransferTxnWithSuggestedParamsFromObject({
+      const feeTxn = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+        sender: facilitatorAddress,
+        receiver: facilitatorAddress, // self-transfer
+        amount: 0,
+        suggestedParams: {
+          ...suggestedParams,
+          fee: 2000, // Covers both transactions (1000 each)
+          flatFee: true,
+        },
+      } as any);
+
+      // Transaction 1: ASA transfer (client -> merchant)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const paymentTxn = algosdk.makeAssetTransferTxnWithSuggestedParamsFromObject({
         sender: this.address,
         receiver: recipient,
         amount: BigInt(amount),
         assetIndex: assetId,
-        suggestedParams: suggestedParams,
+        suggestedParams: {
+          ...suggestedParams,
+          fee: 0, // Fee paid by transaction 0
+          flatFee: true,
+        },
         note: new TextEncoder().encode('x402 payment via uvd-x402-sdk'),
       } as any);
 
-      // Sign with Pera Wallet
-      const signedTxns = await this.peraWallet.signTransaction([[{ txn }]]);
+      // Assign group ID to both transactions (creates atomic group)
+      const txnGroup = algosdk.assignGroupID([feeTxn, paymentTxn]);
+
+      // Encode fee transaction (UNSIGNED - facilitator will sign)
+      const unsignedFeeTxnBytes = algosdk.encodeUnsignedTransaction(txnGroup[0]);
+      const unsignedFeeTxnBase64 = uint8ArrayToBase64(unsignedFeeTxnBytes);
+
+      // Sign the payment transaction (index 1) with the active wallet
+      let signedPaymentTxnBytes: Uint8Array;
+
+      if (this.walletType === 'lute' && this.luteWallet) {
+        // Lute uses signTxns with base64 encoded transactions
+        // For atomic groups, pass both txns but only sign the one we control
+        const feeTxnBase64 = uint8ArrayToBase64(txnGroup[0].toByte());
+        const paymentTxnBase64 = uint8ArrayToBase64(txnGroup[1].toByte());
+
+        // Sign only the payment transaction (index 1), leave fee txn unsigned
+        const signedTxns = await this.luteWallet.signTxns([
+          { txn: feeTxnBase64, signers: [] }, // Don't sign - facilitator will
+          { txn: paymentTxnBase64 }, // Sign this one
+        ]);
+
+        if (!signedTxns || signedTxns.length < 2 || !signedTxns[1]) {
+          throw new X402Error('No signed transaction returned', 'SIGNATURE_REJECTED');
+        }
+
+        // Get the signed payment transaction (index 1)
+        const signedResult = signedTxns[1];
+        signedPaymentTxnBytes = this.decodeSignedTxn(signedResult);
+      } else if (this.walletType === 'pera' && this.peraWallet) {
+        // Pera uses signTransaction with transaction objects
+        // For atomic groups, pass both txns but only sign the one we control
+        const signedTxns = await this.peraWallet.signTransaction([
+          [
+            { txn: txnGroup[0], signers: [] }, // Don't sign - facilitator will
+            { txn: txnGroup[1] }, // Sign this one
+          ],
+        ]);
+
+        if (!signedTxns || signedTxns.length < 2 || !signedTxns[1]) {
+          throw new X402Error('No signed transaction returned', 'SIGNATURE_REJECTED');
+        }
 
-      if (!signedTxns || signedTxns.length === 0) {
-        throw new X402Error('No signed transaction returned', 'SIGNATURE_REJECTED');
+        signedPaymentTxnBytes = signedTxns[1];
+      } else {
+        throw new X402Error('No wallet available for signing', 'WALLET_NOT_CONNECTED');
       }
 
-      const signedTxn = signedTxns[0];
+      const signedPaymentTxnBase64 = uint8ArrayToBase64(signedPaymentTxnBytes);
 
+      // Build payload following GoPlausible x402-avm spec
       const payload: AlgorandPaymentPayload = {
-        from: this.address,
-        to: recipient,
-        amount: amount.toString(),
-        assetId: assetId,
-        signedTxn: uint8ArrayToBase64(signedTxn),
+        paymentIndex: 1, // Index of the payment transaction in the group
+        paymentGroup: [
+          unsignedFeeTxnBase64,   // Transaction 0: unsigned fee tx
+          signedPaymentTxnBase64, // Transaction 1: signed payment tx
+        ],
       };
 
       return JSON.stringify(payload);
@@ -272,6 +465,32 @@ export class AlgorandProvider implements WalletAdapter {
     }
   }
 
+  /**
+   * Decode signed transaction from wallet response (handles various formats)
+   */
+  private decodeSignedTxn(signedResult: unknown): Uint8Array {
+    if (signedResult instanceof Uint8Array) {
+      return signedResult;
+    } else if (typeof signedResult === 'string') {
+      // Try to decode as base64
+      try {
+        return Uint8Array.from(atob(signedResult), c => c.charCodeAt(0));
+      } catch {
+        // If standard base64 fails, try URL-safe base64
+        const standardBase64 = signedResult.replace(/-/g, '+').replace(/_/g, '/');
+        return Uint8Array.from(atob(standardBase64), c => c.charCodeAt(0));
+      }
+    } else if (ArrayBuffer.isView(signedResult)) {
+      return new Uint8Array(
+        (signedResult as ArrayBufferView).buffer,
+        (signedResult as ArrayBufferView).byteOffset,
+        (signedResult as ArrayBufferView).byteLength
+      );
+    } else {
+      throw new X402Error('Unexpected signed transaction format', 'PAYMENT_FAILED');
+    }
+  }
+
   /**
    * Encode Algorand payment as X-PAYMENT header
    *
@@ -287,17 +506,19 @@ export class AlgorandProvider implements WalletAdapter {
   ): string {
     const payload = JSON.parse(paymentPayload) as AlgorandPaymentPayload;
 
-    // Use chain name from config, or default to 'algorand'
-    const networkName = chainConfig?.name || 'algorand';
+    // Determine network name for x402
+    // Use "algorand-mainnet" or "algorand-testnet" format for facilitator
+    let networkName: string;
+    if (chainConfig?.name === 'algorand-testnet') {
+      networkName = 'algorand-testnet';
+    } else {
+      networkName = 'algorand-mainnet'; // Default to mainnet
+    }
 
-    // Build the payload data
+    // Build the payload data (GoPlausible x402-avm spec)
     const payloadData = {
-      from: payload.from,
-      to: payload.to,
-      amount: payload.amount,
-      assetId: payload.assetId,
-      signedTxn: payload.signedTxn,
-      ...(payload.note && { note: payload.note }),
+      paymentIndex: payload.paymentIndex,
+      paymentGroup: payload.paymentGroup,
     };
 
     // Format in x402 standard format (v1 or v2)
@@ -311,7 +532,7 @@ export class AlgorandProvider implements WalletAdapter {
       : {
           x402Version: 1 as const,
           scheme: 'exact' as const,
-          network: networkName, // Plain chain name for v1
+          network: networkName,
           payload: payloadData,
         };
 

package/src/types/index.ts

@@ -345,23 +345,21 @@ export interface NEARPaymentPayload {
 /**
  * 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.
+ * Follows the GoPlausible x402-avm spec for atomic groups:
+ * - Transaction 0: Fee payment (UNSIGNED) - facilitator -> facilitator, covers all fees
+ * - Transaction 1: ASA transfer (SIGNED) - client -> merchant
+ *
+ * The facilitator signs transaction 0 and submits the complete atomic 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;
+  /** Index of the payment transaction in the group (always 1) */
+  paymentIndex: number;
+  /**
+   * Array of base64-encoded msgpack transactions forming the atomic group:
+   * - [0]: Unsigned fee transaction (facilitator signs)
+   * - [1]: Signed ASA transfer (client signed)
+   */
+  paymentGroup: string[];
 }
 
 /**
@@ -497,15 +495,13 @@ export interface X402NEARPayload {
 }
 
 /**
- * Algorand-specific payload in x402 header
+ * Algorand-specific payload in x402 header (atomic group format)
  */
 export interface X402AlgorandPayload {
-  from: string;
-  to: string;
-  amount: string;
-  assetId: number;
-  signedTxn: string;
-  note?: string;
+  /** Index of the payment transaction in the group (always 1) */
+  paymentIndex: number;
+  /** Array of base64-encoded msgpack transactions */
+  paymentGroup: string[];
 }
 
 /**