uvd-x402-sdk 2.38.0 → 2.41.0

package/README.md

@@ -1,13 +1,13 @@
 # uvd-x402-sdk
 
-Gasless crypto payments across 21 blockchain networks using the x402 protocol.
+Gasless crypto payments across 25 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
 
-- **21 Networks**: EVM (13 including Scroll, SKALE Base), Solana, Fogo, Stellar, NEAR, Algorand, Sui
-- **Multi-Stablecoin**: USDC, EURC, AUSD, PYUSD, USDT
+- **25 Networks**: EVM (15 including Scroll, SKALE Base, Robinhood Chain), Solana, Fogo, Stellar, NEAR, Algorand, Sui, XRP Ledger (mainnet + testnet)
+- **Multi-Stablecoin**: USDC, EURC, AUSD, PYUSD, USDT, USDG (Robinhood Chain)
 - **x402 v1 & v2**: Both protocol versions with auto-detection
 - **Gasless**: Facilitator pays all network fees
 - **Type-Safe**: Full TypeScript support
@@ -47,6 +47,9 @@ npm install algosdk lute-connect
 
 # Sui
 npm install @mysten/sui
+
+# XRPL (XRP Ledger)
+npm install xrpl
 ```
 
 ## Quick Start
@@ -210,6 +213,35 @@ Sui uses sponsored transactions:
 - Facilitator sponsors gas (pays in SUI)
 - User pays zero gas fees
 
+### XRPL (XRP Ledger)
+
+```typescript
+import { XRPLProvider } from 'uvd-x402-sdk/xrpl';
+import { getChainByName } from 'uvd-x402-sdk';
+
+// Seed-based signer (Node.js / server-side)
+const xrpl = new XRPLProvider({ seed: process.env.XRPL_SEED });
+const address = await xrpl.connect(); // classic r-address
+const chainConfig = getChainByName('xrpl-mainnet')!;
+
+// Build + FULLY sign the Payment off-chain. Returns JSON: { signedTxBlob }
+const payload = await xrpl.signPayment({
+  recipient: 'rfADKkVXBNqK3z72tVSS3LVzAR3psYkonp', // classic r-address
+  amount: '10.00',
+}, chainConfig);
+
+const header = xrpl.encodePaymentHeader(payload);
+```
+
+XRPL uses the **t54 "pre-signed Payment blob"** scheme:
+- The client builds and FULLY signs a native XRP `Payment` off-chain (paying its own XRP fee)
+- Only one field is sent to the facilitator: `{ "signedTxBlob": "<hex tx blob>" }`
+- The facilitator decodes the blob to re-derive payer/amount/destination and submits it
+- The Payment sets `LastLedgerSequence`, must NOT set `tfPartialPayment`, and must NOT use `SendMax`
+- All payment-level fields (destination, amount, InvoiceID, SourceTag, Memo) come from the requirements
+
+> Requires the optional peer dependency `xrpl` (`npm install xrpl`).
+
 ### Stellar
 
 ```typescript
@@ -592,7 +624,7 @@ const header = svm.encodePaymentHeader(payload, chainConfig);
 
 ## Supported Networks
 
-### EVM (13)
+### EVM (15)
 
 | Network | Chain ID | Tokens |
 |---------|----------|--------|
@@ -609,6 +641,10 @@ const header = svm.encodePaymentHeader(payload, chainConfig);
 | Scroll | 534352 | USDC |
 | SKALE Base | 1187947933 | USDC.e |
 | SKALE Base Sepolia | 324705682 | USDC.e |
+| Robinhood Chain | 4663 | USDG |
+| Robinhood Chain Testnet | 46630 | USDG |
+
+> **Robinhood Chain / USDG:** Robinhood Chain has no USDC — the settlement stablecoin is Paxos **USDG** (Global Dollar, 6 decimals, EIP-3009). Its on-chain `version()` getter reverts, so the EIP-712 domain `{ name: "Global Dollar", version: "1" }` can never be resolved on-chain. The SDK carries this domain in the chain config; when constructing `PaymentRequirements` yourself, send it in `extra`: `{ "name": "Global Dollar", "version": "1" }`. Use `tokenType: 'usdg'` (or the default, which resolves to USDG on these networks).
 
 ### SVM (2)
 
@@ -629,6 +665,15 @@ const header = svm.encodePaymentHeader(payload, chainConfig);
 |---------|--------|--------|
 | Sui | USDC, AUSD | Sui Wallet |
 
+### XRPL
+
+XRP Ledger settles in **native XRP** (6 decimals / drops) using the **t54 pre-signed Payment blob** scheme. The client builds and fully signs the Payment off-chain and sends `{ signedTxBlob }` to the facilitator. There is no stablecoin/token contract on XRPL. Use network ids `xrpl-mainnet` and `xrpl-testnet`. See [XRPL (XRP Ledger)](#xrpl-xrp-ledger) above for the `uvd-x402-sdk/xrpl` provider usage.
+
+| Network | Asset | Network ID | Provider |
+|---------|-------|------------|----------|
+| XRP Ledger | XRP (native) | xrpl-mainnet | `uvd-x402-sdk/xrpl` |
+| XRP Ledger Testnet | XRP (native) | xrpl-testnet | `uvd-x402-sdk/xrpl` |
+
 ### Other
 
 | Network | Wallet |
@@ -650,11 +695,13 @@ FACILITATOR_ADDRESSES.algorand; // KIMS5H6QLCUDL65L5UBTOXDPWLMTS7N3AAC3I6B2NCONE
 FACILITATOR_ADDRESSES.stellar;  // GCHPGXJT2WFFRFCA5TV4G4E3PMMXLNIDUH27PKDYA4QJ2XGYZWGFZNHB
 FACILITATOR_ADDRESSES.near;     // uvd-facilitator.near
 FACILITATOR_ADDRESSES.sui;      // 0xe7bbf2b13f7d72714760aa16e024fa1b35a978793f9893d0568a4fbf356a764a
+FACILITATOR_ADDRESSES['xrpl-mainnet']; // rfADKkVXBNqK3z72tVSS3LVzAR3psYkonp
 
 // Or get by chain name
 getFacilitatorAddress('algorand'); // KIMS5H6...
 getFacilitatorAddress('base', 'evm'); // 0x1030...
 getFacilitatorAddress('sui'); // 0xe7bbf...
+getFacilitatorAddress('xrpl-mainnet'); // rfADKk...
 ```
 
 ## Backend

package/dist/adapters/index.d.mts

@@ -1,4 +1,4 @@
-import { O as X402Version, k as PaymentResult } from '../index-DsuzwOwF.mjs';
+import { O as X402Version, k as PaymentResult } from '../index-DBCFd6mO.mjs';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-CYIVd4xO.mjs';
 import '../wallet-0cX9Pw2F.mjs';
 

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { O as X402Version, k as PaymentResult } from '../index-DsuzwOwF.js';
+import { O as X402Version, k as PaymentResult } from '../index-DBCFd6mO.js';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-DTDixPzO.js';
 import '../wallet-0cX9Pw2F.js';
 

package/dist/adapters/index.js

@@ -6,7 +6,7 @@ var ethers = require('ethers');
 var DEFAULT_FACILITATOR_URL = "https://facilitator.ultravioletadao.xyz";
 var SUPPORTED_CHAINS = {
   // ============================================================================
-  // EVM CHAINS (10 networks)
+  // EVM CHAINS (15 networks)
   // ============================================================================
   base: {
     chainId: 8453,
@@ -516,6 +516,83 @@ var SUPPORTED_CHAINS = {
       enabled: true
     }
   },
+  // Robinhood Chain (Arbitrum Orbit L2). NOTE: there is NO USDC on this chain -
+  // the settlement stablecoin is Paxos USDG (Global Dollar). The `usdc` field
+  // below carries USDG for interface compatibility (same pattern as XRPL's native
+  // asset), and `tokens.usdg` is the canonical entry.
+  // CRITICAL: USDG's on-chain version() getter REVERTS, so the EIP-712 domain
+  // { name: 'Global Dollar', version: '1' } can NEVER be resolved on-chain and
+  // MUST come from this config (mirrored into PaymentRequirements.extra by callers).
+  robinhood: {
+    chainId: 4663,
+    chainIdHex: "0x1237",
+    name: "robinhood",
+    displayName: "Robinhood Chain",
+    networkType: "evm",
+    rpcUrl: "https://rpc.mainnet.chain.robinhood.com",
+    explorerUrl: "https://robinhoodchain.blockscout.com",
+    nativeCurrency: {
+      name: "Ethereum",
+      symbol: "ETH",
+      decimals: 18
+    },
+    usdc: {
+      address: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+      // Paxos USDG (no USDC on this chain)
+      decimals: 6,
+      name: "Global Dollar",
+      // on-chain version() reverts; domain must be supplied off-chain
+      version: "1"
+    },
+    tokens: {
+      usdg: {
+        address: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+        decimals: 6,
+        name: "Global Dollar",
+        // on-chain version() reverts; domain must be supplied off-chain
+        version: "1"
+      }
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true
+    }
+  },
+  "robinhood-testnet": {
+    chainId: 46630,
+    chainIdHex: "0xb626",
+    name: "robinhood-testnet",
+    displayName: "Robinhood Chain Testnet",
+    networkType: "evm",
+    rpcUrl: "https://rpc.testnet.chain.robinhood.com",
+    explorerUrl: "https://explorer.testnet.chain.robinhood.com",
+    nativeCurrency: {
+      name: "Ethereum",
+      symbol: "ETH",
+      decimals: 18
+    },
+    usdc: {
+      address: "0x7E955252E15c84f5768B83c41a71F9eba181802F",
+      // Paxos USDG testnet (no USDC on this chain)
+      decimals: 6,
+      name: "Global Dollar",
+      // on-chain version() reverts; domain must be supplied off-chain
+      version: "1"
+    },
+    tokens: {
+      usdg: {
+        address: "0x7E955252E15c84f5768B83c41a71F9eba181802F",
+        decimals: 6,
+        name: "Global Dollar",
+        // on-chain version() reverts; domain must be supplied off-chain
+        version: "1"
+      }
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true
+    }
+  },
   // ============================================================================
   // SVM CHAINS (2 networks) - Solana Virtual Machine
   // ============================================================================
@@ -800,6 +877,65 @@ var SUPPORTED_CHAINS = {
       facilitatorUrl: DEFAULT_FACILITATOR_URL,
       enabled: true
     }
+  },
+  // ============================================================================
+  // XRPL (2 networks) - XRP Ledger, native XRP via pre-signed Payment blobs
+  // ============================================================================
+  "xrpl-mainnet": {
+    chainId: 0,
+    // Non-EVM (XRPL uses network id strings, no numeric chain ID)
+    chainIdHex: "0x0",
+    name: "xrpl-mainnet",
+    displayName: "XRP Ledger",
+    networkType: "xrpl",
+    rpcUrl: "https://xrplcluster.com",
+    explorerUrl: "https://livenet.xrpl.org",
+    nativeCurrency: {
+      name: "XRP",
+      symbol: "XRP",
+      decimals: 6
+      // XRPL uses 6 decimals (drops); 1 XRP = 1,000,000 drops
+    },
+    // XRPL settles in native XRP - there is no USDC/token contract.
+    // The `usdc` field describes the native asset for interface compatibility.
+    usdc: {
+      address: "XRP",
+      // Native asset - no token contract
+      decimals: 6,
+      name: "XRP",
+      version: "1"
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true
+    }
+  },
+  "xrpl-testnet": {
+    chainId: 0,
+    // Non-EVM
+    chainIdHex: "0x0",
+    name: "xrpl-testnet",
+    displayName: "XRP Ledger Testnet",
+    networkType: "xrpl",
+    rpcUrl: "https://s.altnet.rippletest.net:51234",
+    explorerUrl: "https://testnet.xrpl.org",
+    nativeCurrency: {
+      name: "XRP",
+      symbol: "XRP",
+      decimals: 6
+    },
+    // XRPL settles in native XRP - there is no USDC/token contract.
+    usdc: {
+      address: "XRP",
+      // Native asset - no token contract
+      decimals: 6,
+      name: "XRP",
+      version: "1"
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true
+    }
   }
 };
 function getChainByName(name) {
@@ -822,6 +958,8 @@ var CAIP2_IDENTIFIERS = {
   scroll: "eip155:534352",
   "skale-base": "eip155:1187947933",
   "skale-base-sepolia": "eip155:324705682",
+  robinhood: "eip155:4663",
+  "robinhood-testnet": "eip155:46630",
   // SVM chains
   solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
   fogo: "svm:fogo",
@@ -834,7 +972,10 @@ var CAIP2_IDENTIFIERS = {
   "algorand-testnet": "algorand:testnet",
   // Sui
   sui: "sui:mainnet",
-  "sui-testnet": "sui:testnet"
+  "sui-testnet": "sui:testnet",
+  // XRPL (XRP Ledger has no CAIP-2 form - the v1 string IS the network id)
+  "xrpl-mainnet": "xrpl-mainnet",
+  "xrpl-testnet": "xrpl-testnet"
 };
 Object.fromEntries(
   Object.entries(CAIP2_IDENTIFIERS).map(([k, v]) => [v, k])
@@ -894,6 +1035,7 @@ var ETH_ADDRESS_REGEX = /^0x[a-fA-F0-9]{40}$/;
 var SOLANA_ADDRESS_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 var STELLAR_ADDRESS_REGEX = /^G[A-Z2-7]{55}$/;
 var NEAR_ADDRESS_REGEX = /^[a-z0-9._-]+$/;
+var XRPL_ADDRESS_REGEX = /^r[1-9A-HJ-NP-Za-km-z]{24,34}$/;
 function validateRecipient(recipient, networkType) {
   if (!recipient) {
     throw new X402Error(
@@ -943,6 +1085,14 @@ function validateRecipient(recipient, networkType) {
           );
         }
         break;
+      case "xrpl":
+        if (!XRPL_ADDRESS_REGEX.test(trimmed)) {
+          throw new X402Error(
+            `Invalid XRPL recipient address: "${trimmed}". Expected a classic r-address (base58, Ripple alphabet).`,
+            "INVALID_RECIPIENT"
+          );
+        }
+        break;
     }
   }
 }