uvd-x402-sdk 2.15.2 → 2.16.2

package/README.md

@@ -1,12 +1,12 @@
 # uvd-x402-sdk
 
-Gasless crypto payments across 16 blockchain networks using the x402 protocol.
+Gasless crypto payments across 17 blockchain networks using the x402 protocol.
 
 Users sign a message or transaction, and the Ultravioleta facilitator handles on-chain settlement. No gas fees for users.
 
 ## Features
 
-- **16 Networks**: EVM (10), Solana, Fogo, Stellar, NEAR, Algorand (2)
+- **17 Networks**: EVM (10), Solana, Fogo, Stellar, NEAR, Algorand, Sui
 - **Multi-Stablecoin**: USDC, EURC, AUSD, PYUSD, USDT
 - **x402 v1 & v2**: Both protocol versions with auto-detection
 - **Gasless**: Facilitator pays all network fees
@@ -36,6 +36,9 @@ npm install @near-wallet-selector/core @near-wallet-selector/my-near-wallet
 
 # Algorand
 npm install algosdk lute-connect
+
+# Sui
+npm install @mysten/sui
 ```
 
 ## Quick Start
@@ -98,6 +101,29 @@ Algorand uses atomic transaction groups:
 - Transaction 0: Fee payment (unsigned, facilitator signs)
 - Transaction 1: USDC ASA transfer (signed by user)
 
+### Sui
+
+```typescript
+import { SuiProvider } from 'uvd-x402-sdk/sui';
+import { getChainByName } from 'uvd-x402-sdk';
+
+const sui = new SuiProvider();
+const address = await sui.connect(); // Sui Wallet
+const chainConfig = getChainByName('sui')!;
+
+const payload = await sui.signPayment({
+  recipient: '0x1234...', // 66-char Sui address
+  amount: '10.00',
+}, chainConfig);
+
+const header = sui.encodePaymentHeader(payload, chainConfig);
+```
+
+Sui uses sponsored transactions:
+- User creates and signs a programmable transaction block
+- Facilitator sponsors gas (pays in SUI)
+- User pays zero gas fees
+
 ### Stellar
 
 ```typescript
@@ -118,12 +144,17 @@ const header = stellar.encodePaymentHeader(payload);
 
 ### NEAR
 
+> **Important:** The SDK's `NEARProvider.signPayment()` only works with **injected wallets** (browser extensions).
+> For **browser-redirect wallets** like MyNearWallet via `@near-wallet-selector`, you must use the popup flow below.
+
+#### Option 1: Injected Wallet (Browser Extension)
+
 ```typescript
 import { NEARProvider } from 'uvd-x402-sdk/near';
 import { getChainByName } from 'uvd-x402-sdk';
 
 const near = new NEARProvider();
-const accountId = await near.connect(); // MyNearWallet
+const accountId = await near.connect(); // MyNearWallet browser extension
 const chainConfig = getChainByName('near')!;
 
 const payload = await near.signPayment({
@@ -134,6 +165,209 @@ const payload = await near.signPayment({
 const header = near.encodePaymentHeader(payload);
 ```
 
+#### Option 2: Browser-Redirect Wallet (Popup Flow) - Recommended
+
+MyNearWallet via `@near-wallet-selector` is a browser-redirect wallet that requires a popup flow.
+This is the recommended approach and works with the custom MyNearWallet deployment that supports NEP-366.
+
+```typescript
+import { setupWalletSelector } from '@near-wallet-selector/core';
+import { setupModal } from '@near-wallet-selector/modal-ui';
+import { setupMyNearWallet } from '@near-wallet-selector/my-near-wallet';
+import '@near-wallet-selector/modal-ui/styles.css';
+
+// Configuration
+const NEAR_CONFIG = {
+  usdcContract: '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1',
+  recipientAccount: 'merchant.near',
+  // Custom MyNearWallet with NEP-366 signDelegateAction support
+  walletUrl: 'https://mynearwallet.ultravioletadao.xyz',
+};
+
+// Step 1: Initialize wallet selector
+const selector = await setupWalletSelector({
+  network: 'mainnet',
+  modules: [
+    setupMyNearWallet({ walletUrl: NEAR_CONFIG.walletUrl }),
+  ],
+});
+
+const modal = setupModal(selector, {
+  contractId: NEAR_CONFIG.usdcContract,
+});
+
+// Step 2: Connect wallet
+modal.show(); // User selects wallet
+// Wait for connection via selector.store.observable.subscribe()
+const state = selector.store.getState();
+const accountId = state.accounts[0].accountId;
+
+// Step 3: Create payment with popup flow
+async function createNearPayment(amount: string): Promise<string> {
+  const amountRaw = Math.floor(parseFloat(amount) * 1_000_000); // 6 decimals
+
+  // Get access key info and block height from RPC
+  const [accessKeyInfo, blockInfo] = await Promise.all([
+    getNearAccessKeyInfo(accountId),
+    getNearBlockHeight(),
+  ]);
+
+  const nonce = accessKeyInfo.nonce + 1;
+  const maxBlockHeight = blockInfo.blockHeight + 1000; // ~17 minutes
+
+  // Build wallet URL for signDelegateAction
+  const popupUrl = new URL(NEAR_CONFIG.walletUrl);
+  popupUrl.pathname = '/sign-delegate-action';
+  popupUrl.searchParams.set('receiverId', NEAR_CONFIG.usdcContract);
+  popupUrl.searchParams.set('actions', JSON.stringify([{
+    methodName: 'ft_transfer',
+    args: {
+      receiver_id: NEAR_CONFIG.recipientAccount,
+      amount: amountRaw.toString(),
+      memo: 'x402 payment',
+    },
+    gas: '30000000000000', // 30 TGas
+    deposit: '1', // 1 yoctoNEAR
+  }]));
+  popupUrl.searchParams.set('callbackUrl', window.location.origin + '/near-callback');
+  popupUrl.searchParams.set('meta', JSON.stringify({
+    sender: accountId,
+    nonce,
+    maxBlockHeight,
+    publicKey: accessKeyInfo.publicKey,
+  }));
+
+  // Open popup
+  const popup = window.open(popupUrl.toString(), 'nearWallet', 'width=500,height=700');
+  if (!popup) throw new Error('Popup blocked. Please allow popups.');
+
+  // Wait for redirect with signedDelegateAction
+  const signedDelegateAction = await new Promise<string>((resolve, reject) => {
+    const checkInterval = setInterval(() => {
+      if (popup.closed) {
+        clearInterval(checkInterval);
+        reject(new Error('Wallet popup closed'));
+        return;
+      }
+      try {
+        const url = popup.location.href;
+        if (url.includes('signedDelegateAction=')) {
+          clearInterval(checkInterval);
+          popup.close();
+          const params = new URLSearchParams(new URL(url).search);
+          const errorCode = params.get('errorCode');
+          if (errorCode) {
+            reject(new Error(params.get('errorMessage') || errorCode));
+            return;
+          }
+          resolve(params.get('signedDelegateAction')!);
+        }
+      } catch { /* cross-origin, keep waiting */ }
+    }, 500);
+
+    setTimeout(() => {
+      clearInterval(checkInterval);
+      if (!popup.closed) popup.close();
+      reject(new Error('Popup timeout'));
+    }, 300000); // 5 min timeout
+  });
+
+  // Return x402 payload
+  return JSON.stringify({
+    signedDelegateAction,
+    network: 'near',
+  });
+}
+
+// Helper: Get access key info from NEAR RPC
+async function getNearAccessKeyInfo(accountId: string) {
+  const rpcUrls = [
+    'https://near.drpc.org',
+    'https://rpc.mainnet.near.org',
+  ];
+
+  for (const rpcUrl of rpcUrls) {
+    try {
+      const response = await fetch(rpcUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 'dontcare',
+          method: 'query',
+          params: {
+            request_type: 'view_access_key_list',
+            finality: 'final',
+            account_id: accountId,
+          },
+        }),
+      });
+      const data = await response.json();
+      if (data.error) continue;
+
+      const fullAccessKey = data.result.keys.find(
+        (k: any) => k.access_key.permission === 'FullAccess'
+      );
+      return {
+        nonce: fullAccessKey.access_key.nonce,
+        publicKey: fullAccessKey.public_key,
+      };
+    } catch { continue; }
+  }
+  throw new Error('Failed to get NEAR access key info');
+}
+
+// Helper: Get block height from NEAR RPC
+async function getNearBlockHeight() {
+  const rpcUrls = [
+    'https://near.drpc.org',
+    'https://rpc.mainnet.near.org',
+  ];
+
+  for (const rpcUrl of rpcUrls) {
+    try {
+      const response = await fetch(rpcUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 'dontcare',
+          method: 'block',
+          params: { finality: 'final' },
+        }),
+      });
+      const data = await response.json();
+      if (data.error) continue;
+      return { blockHeight: data.result.header.height };
+    } catch { continue; }
+  }
+  throw new Error('Failed to get NEAR block height');
+}
+
+// Step 4: Encode payment header
+function encodeNearPaymentHeader(payload: string): string {
+  const parsed = JSON.parse(payload);
+  const x402Payload = {
+    x402Version: 1,
+    scheme: 'exact',
+    network: 'near',
+    payload: {
+      signedDelegateAction: parsed.signedDelegateAction,
+    },
+  };
+  return btoa(JSON.stringify(x402Payload));
+}
+
+// Usage
+const payload = await createNearPayment('10.00');
+const header = encodeNearPaymentHeader(payload);
+await fetch('/api/purchase', {
+  headers: { 'X-PAYMENT': header },
+});
+```
+
+See [402milly's full implementation](https://github.com/UltravioletaDAO/402milly/blob/main/frontend/src/services/x402-sdk.ts) for a production-ready example.
+
 ## Wagmi/RainbowKit
 
 ```typescript
@@ -220,14 +454,19 @@ const header = svm.encodePaymentHeader(payload, chainConfig);
 | Solana | USDC, AUSD | Phantom |
 | Fogo | USDC | Phantom |
 
-### Algorand (2)
+### Algorand
 
 | Network | USDC ASA | Wallet |
 |---------|----------|--------|
 | Algorand | 31566704 | Lute, Pera |
-| Algorand Testnet | 10458941 | Lute, Pera |
 
-### Other (2)
+### Sui
+
+| Network | Tokens | Wallet |
+|---------|--------|--------|
+| Sui | USDC, AUSD | Sui Wallet |
+
+### Other
 
 | Network | Wallet |
 |---------|--------|
@@ -247,10 +486,12 @@ FACILITATOR_ADDRESSES.solana;   // F742C4VfFLQ9zRQyithoj5229ZgtX2WqKCSFKgH2EThq
 FACILITATOR_ADDRESSES.algorand; // KIMS5H6QLCUDL65L5UBTOXDPWLMTS7N3AAC3I6B2NCONEI5QIVK7LH2C2I
 FACILITATOR_ADDRESSES.stellar;  // GCHPGXJT2WFFRFCA5TV4G4E3PMMXLNIDUH27PKDYA4QJ2XGYZWGFZNHB
 FACILITATOR_ADDRESSES.near;     // uvd-facilitator.near
+FACILITATOR_ADDRESSES.sui;      // 0xe7bbf2b13f7d72714760aa16e024fa1b35a978793f9893d0568a4fbf356a764a
 
 // Or get by chain name
 getFacilitatorAddress('algorand'); // KIMS5H6...
 getFacilitatorAddress('base', 'evm'); // 0x1030...
+getFacilitatorAddress('sui'); // 0xe7bbf...
 ```
 
 ## Backend

package/dist/adapters/index.d.mts

@@ -1,4 +1,4 @@
-import { l as X402Version, f as PaymentResult } from '../index-BYIugZlE.mjs';
+import { m as X402Version, f as PaymentResult } from '../index-BE5cH7oS.mjs';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { l as X402Version, f as PaymentResult } from '../index-BYIugZlE.js';
+import { m as X402Version, f as PaymentResult } from '../index-BE5cH7oS.js';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter

package/dist/adapters/index.js

@@ -613,6 +613,84 @@ var SUPPORTED_CHAINS = {
       facilitatorUrl: DEFAULT_FACILITATOR_URL,
       enabled: true
     }
+  },
+  // ============================================================================
+  // SUI (2 networks) - Uses sponsored transactions (facilitator pays gas)
+  // ============================================================================
+  sui: {
+    chainId: 0,
+    // Non-EVM
+    chainIdHex: "0x0",
+    name: "sui",
+    displayName: "Sui",
+    networkType: "sui",
+    rpcUrl: "https://fullnode.mainnet.sui.io:443",
+    explorerUrl: "https://suiscan.xyz/mainnet",
+    nativeCurrency: {
+      name: "Sui",
+      symbol: "SUI",
+      decimals: 9
+    },
+    usdc: {
+      // USDC coin type on Sui mainnet
+      address: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+      decimals: 6,
+      name: "USDC",
+      version: "1"
+    },
+    tokens: {
+      usdc: {
+        address: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+        decimals: 6,
+        name: "USDC",
+        version: "1"
+      },
+      ausd: {
+        // AUSD (Agora USD) coin type on Sui mainnet
+        address: "0x2053d08c1e2bd02791056171aab0fd12bd7cd7efad2ab8f6b9c8902f14df2ff2::ausd::AUSD",
+        decimals: 6,
+        name: "AUSD",
+        version: "1"
+      }
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true
+    }
+  },
+  "sui-testnet": {
+    chainId: 0,
+    // Non-EVM
+    chainIdHex: "0x0",
+    name: "sui-testnet",
+    displayName: "Sui Testnet",
+    networkType: "sui",
+    rpcUrl: "https://fullnode.testnet.sui.io:443",
+    explorerUrl: "https://suiscan.xyz/testnet",
+    nativeCurrency: {
+      name: "Sui",
+      symbol: "SUI",
+      decimals: 9
+    },
+    usdc: {
+      // USDC coin type on Sui testnet
+      address: "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC",
+      decimals: 6,
+      name: "USDC",
+      version: "1"
+    },
+    tokens: {
+      usdc: {
+        address: "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC",
+        decimals: 6,
+        name: "USDC",
+        version: "1"
+      }
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true
+    }
   }
 };
 function getChainByName(name) {
@@ -641,7 +719,10 @@ var CAIP2_IDENTIFIERS = {
   near: "near:mainnet",
   // Algorand
   algorand: "algorand:mainnet",
-  "algorand-testnet": "algorand:testnet"
+  "algorand-testnet": "algorand:testnet",
+  // Sui
+  sui: "sui:mainnet",
+  "sui-testnet": "sui:testnet"
 };
 Object.fromEntries(
   Object.entries(CAIP2_IDENTIFIERS).map(([k, v]) => [v, k])