uvd-x402-sdk 2.90.0 → 2.92.0

package/README.md

@@ -1,6 +1,6 @@
 # uvd-x402-sdk
 
-Gasless crypto payments across 25 blockchain networks using the x402 protocol.
+Gasless crypto payments across 27 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.
 
@@ -670,6 +670,38 @@ getSupportedTokens('base');     // ['usdc', 'eurc']
 isTokenSupported('base', 'eurc'); // true
 ```
 
+## Validity window (`validitySeconds`)
+
+An EIP-3009 authorization can only be settled until `validBefore = now + validitySeconds`. A seller that settles **after** handing over the resource needs the authorization alive long enough for that settlement to land.
+
+| Where | Scope | Default |
+|---|---|---|
+| `X402ClientConfig.validitySeconds` | every payment this client signs | `300` |
+| `PaymentInfo.validitySeconds` | one payment; wins over the client | — |
+| `maxTimeoutSeconds` in the seller's 402 | `client.fetch()` signs the seller's declared window | — |
+
+```typescript
+import { X402Client, DEFAULT_VALIDITY_SECONDS, MAX_VALIDITY_SECONDS } from 'uvd-x402-sdk';
+
+// Every payment from this client stays settleable for 10 minutes...
+const client = new X402Client({ defaultChain: 'avalanche', validitySeconds: 600 });
+
+// ...except this one, which the seller settles in batches
+const result = await client.createPayment({
+  recipient: '0x...',
+  amount: '1.00',
+  validitySeconds: 1800,
+});
+
+DEFAULT_VALIDITY_SECONDS; // 300
+MAX_VALIDITY_SECONDS;     // 3600
+```
+
+- A value that is not a whole number between 1 and `MAX_VALIDITY_SECONDS` throws `INVALID_CONFIG`: from the constructor for the client config, and before anything is signed for a single payment.
+- `client.fetch()` signs the `maxTimeoutSeconds` the seller's 402 declares, clamped to 1–3600 s. When the 402 declares none, the client's window applies.
+- The facilitator keeps a 6 s clock-skew grace, so the payer really has `validitySeconds - 6` seconds. It never rejects a window for being long.
+- Before 2.91.0 the window was 300 s on Base and 60 s on every other EVM network, and there was no way to change it.
+
 ## AUSD on Solana (Token2022)
 
 ```typescript
@@ -691,7 +723,7 @@ const header = svm.encodePaymentHeader(payload, chainConfig);
 
 ## Supported Networks
 
-### EVM (15)
+### EVM (16)
 
 | Network | Chain ID | Tokens |
 |---------|----------|--------|
@@ -710,6 +742,10 @@ const header = svm.encodePaymentHeader(payload, chainConfig);
 | SKALE Base Sepolia | 324705682 | USDC.e |
 | Robinhood Chain | 4663 | USDG |
 | Robinhood Chain Testnet | 46630 | USDG |
+| Arc | 5042 | USDC |
+| Arc Testnet | 5042002 | USDC |
+
+> **Arc mainnet and testnet:** payment amounts use 6 decimals and the `USDC` / `2` domain. Native gas uses 18 decimals on the same balance. Use `arc` / `eip155:5042` for mainnet and `arc-testnet` / `eip155:5042002` for testnet. See [Arc usage and validation](docs/networks/arc.md).
 
 > **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).
 

package/dist/adapters/index.d.mts

@@ -1,4 +1,4 @@
-import { X as X402Version, a as PaymentResult } from '../index-BWN0Haa0.mjs';
+import { X as X402Version, a as PaymentResult } from '../index-DbauIMV2.mjs';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-Z9v4GxOZ.mjs';
 import '../wallet-w7BnImDG.mjs';
 

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { X as X402Version, a as PaymentResult } from '../index-BWN0Haa0.js';
+import { X as X402Version, a as PaymentResult } from '../index-DbauIMV2.js';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-C-KmORG9.js';
 import '../wallet-w7BnImDG.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 (15 networks)
+  // EVM CHAINS (16 enabled + BSC, disabled)
   // ============================================================================
   base: {
     chainId: 8453,
@@ -636,6 +636,91 @@ var SUPPORTED_CHAINS = {
       enabled: true
     }
   },
+  // Arc testnet (Circle). The stablecoin IS the chain's native asset, so the SAME
+  // balance is readable at TWO precisions:
+  //   - native / gas, via eth_getBalance and EIP-1559 fees: 18 decimals
+  //   - ERC-20 interface, via balanceOf and transferWithAuthorization: 6 decimals
+  //     (the ERC-20 view is floor(native / 10^12))
+  // An x402 payment is an EIP-3009 authorization against the ERC-20 interface, so
+  // its `value` is ALWAYS in the 6 of `tokens.usdc.decimals`. Scaling a price with
+  // `nativeCurrency.decimals` instead charges 10^12 times the amount: $0.01 would
+  // be signed as 10000000000000000 units, i.e. 10 billion USDC. `nativeCurrency`
+  // below is correct where it is actually used -- the wallet_addEthereumChain
+  // params -- and must never reach `parseUnits` for a payment.
+  // Pinned by src/arc-testnet.test.ts.
+  //
+  // Mainnet (5042) and testnet (5042002) were verified independently against
+  // their official RPCs on 2026-09-16. EURC is not registered without its E2E proof.
+  arc: {
+    chainId: 5042,
+    chainIdHex: "0x13b2",
+    name: "arc",
+    displayName: "Arc",
+    networkType: "evm",
+    rpcUrl: "https://rpc.mainnet.arc.io",
+    explorerUrl: "https://explorer.arc.io",
+    nativeCurrency: {
+      name: "USD Coin",
+      symbol: "USDC",
+      decimals: 18
+      // gas precision ONLY -- never the scale of a payment
+    },
+    usdc: {
+      address: "0x3600000000000000000000000000000000000000",
+      decimals: 6,
+      // ERC-20 interface, which is what an EIP-3009 value is denominated in
+      name: "USDC",
+      // on-chain name(); must match the EIP-712 domain exactly
+      version: "2"
+    },
+    tokens: {
+      usdc: {
+        address: "0x3600000000000000000000000000000000000000",
+        decimals: 6,
+        name: "USDC",
+        version: "2"
+      }
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true
+    }
+  },
+  "arc-testnet": {
+    chainId: 5042002,
+    chainIdHex: "0x4cef52",
+    name: "arc-testnet",
+    displayName: "Arc Testnet",
+    networkType: "evm",
+    rpcUrl: "https://rpc.testnet.arc.io",
+    explorerUrl: "https://explorer.testnet.arc.io",
+    nativeCurrency: {
+      name: "USD Coin",
+      symbol: "USDC",
+      decimals: 18
+      // gas precision ONLY -- never the scale of a payment
+    },
+    usdc: {
+      address: "0x3600000000000000000000000000000000000000",
+      decimals: 6,
+      // ERC-20 interface, which is what an EIP-3009 value is denominated in
+      name: "USDC",
+      // on-chain name(); must match the EIP-712 domain exactly
+      version: "2"
+    },
+    tokens: {
+      usdc: {
+        address: "0x3600000000000000000000000000000000000000",
+        decimals: 6,
+        name: "USDC",
+        version: "2"
+      }
+    },
+    x402: {
+      facilitatorUrl: DEFAULT_FACILITATOR_URL,
+      enabled: true
+    }
+  },
   // ============================================================================
   // SVM CHAINS (2 networks) - Solana Virtual Machine
   // ============================================================================
@@ -1016,6 +1101,8 @@ var CAIP2_IDENTIFIERS = {
   "skale-base-sepolia": "eip155:324705682",
   robinhood: "eip155:4663",
   "robinhood-testnet": "eip155:46630",
+  arc: "eip155:5042",
+  "arc-testnet": "eip155:5042002",
   // SVM chains
   solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
   fogo: "svm:fogo",