feat: detect preferredTokens and filtered for payment options

Author: akbarsaputrait

examples/nextjs-app/package.json

@@ -14,7 +14,7 @@
     "@headlessui/react": "^2.2.0",
     "@rainbow-me/rainbowkit": "^2.2.8",
     "@rozoai/intent-common": "0.1.7-beta.2",
-    "@rozoai/intent-pay": "0.1.7-beta.6",
+    "@rozoai/intent-pay": "0.1.7-beta.7",
     "@tanstack/react-query": "^5.51.11",
     "@types/react-syntax-highlighter": "^15.5.13",
     "@wagmi/core": "^2.22.0",

examples/nextjs-app/src/app/basic/README.md

@@ -29,15 +29,19 @@ This demo showcases a minimal implementation of `RozoPayButton` that enables cro
 The main payment component that handles the entire payment flow:
 
 ```typescript
+import { TokenSymbol } from "@rozoai/intent-common";
+import { RozoPayButton } from "@rozoai/intent-pay";
+
 <RozoPayButton
   appId="your-app-id"
   toChain={chainId}
   toAddress={recipientAddress}
   toToken={tokenAddress}
   toUnits={amount}
+  preferredSymbol={[TokenSymbol.USDC, TokenSymbol.USDT]}
   onPaymentStarted={(event) => console.log(event)}
   onPaymentCompleted={(event) => console.log(event)}
-/>
+/>;
 ```
 
 ### Event Callbacks
@@ -48,6 +52,48 @@ Track payment lifecycle with built-in callbacks:
 - `onPaymentCompleted`: Triggered when payment is confirmed on-chain
 - `onPayoutCompleted`: Triggered when funds arrive at destination
 
+### Preferred Token Symbols
+
+The `preferredSymbol` prop allows you to specify which token symbols should appear first in the token selection list. This is useful for prioritizing specific stablecoins across all supported chains.
+
+**Key Features:**
+
+- **Supported Symbols**: Only `USDC`, `USDT`, and `EURC` are allowed
+- **Default Behavior**: If not provided, defaults to `[USDC, USDT]`
+- **Cross-Chain**: Automatically finds matching tokens across all supported chains (Base, Polygon, Ethereum, Solana, Stellar)
+- **Precedence**: If `preferredTokens` is explicitly provided, it takes precedence over `preferredSymbol`
+
+**Example Usage:**
+
+```typescript
+import { TokenSymbol } from "@rozoai/intent-common";
+
+// Prioritize USDC and USDT (default)
+<RozoPayButton
+  preferredSymbol={[TokenSymbol.USDC, TokenSymbol.USDT]}
+  // ... other props
+/>
+
+// Prioritize EURC only
+<RozoPayButton
+  preferredSymbol={[TokenSymbol.EURC]}
+  // ... other props
+/>
+
+// Multiple preferred symbols
+<RozoPayButton
+  preferredSymbol={[TokenSymbol.USDC, TokenSymbol.USDT, TokenSymbol.EURC]}
+  // ... other props
+/>
+```
+
+**How It Works:**
+
+- The `preferredSymbol` array is internally converted to a `preferredTokens` array
+- The SDK searches for all tokens matching the specified symbols across supported chains
+- These tokens are then prioritized in the token selection UI
+- Invalid symbols are filtered out with a console warning
+
 ## Developer Notes
 
 - Uses `react-syntax-highlighter` for clean code display
@@ -57,29 +103,33 @@ Track payment lifecycle with built-in callbacks:
 
 ## Props Reference
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `appId` | `string` | Your RozoAI Intent Pay application ID |
-| `toChain` | `number` | Destination blockchain network ID |
-| `toAddress` | `Address` | Recipient wallet address (checksummed) |
-| `toToken` | `Address` | Token contract address to receive |
-| `toUnits` | `string` | Amount in token's smallest unit |
-| `onPaymentStarted` | `(event) => void` | Payment initiation callback |
-| `onPaymentCompleted` | `(event) => void` | Payment completion callback |
+| Prop                 | Type              | Description                                                                                                                         |
+| -------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `appId`              | `string`          | Your RozoAI Intent Pay application ID                                                                                               |
+| `toChain`            | `number`          | Destination blockchain network ID                                                                                                   |
+| `toAddress`          | `Address`         | Recipient wallet address (checksummed)                                                                                              |
+| `toToken`            | `Address`         | Token contract address to receive                                                                                                   |
+| `toUnits`            | `string`          | Amount in token's smallest unit                                                                                                     |
+| `preferredSymbol`    | `TokenSymbol[]`   | Preferred token symbols (USDC, USDT, EURC). These tokens will appear first in the token selection list. Defaults to `[USDC, USDT]`. |
+| `onPaymentStarted`   | `(event) => void` | Payment initiation callback                                                                                                         |
+| `onPaymentCompleted` | `(event) => void` | Payment completion callback                                                                                                         |
 
 ## Cross-Chain Payments
 
 For Stellar/Solana destinations, use bridge configuration:
 
 ```typescript
+import { TokenSymbol } from "@rozoai/intent-common";
+
 <RozoPayButton
   appId="your-app-id"
   toChain={8453} // Base Chain
   toToken="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" // Base USDC
   toAddress="0x..." // Any EVM address
   toStellarAddress="GABC..." // or toSolanaAddress
   toUnits="1000000"
-/>
+  preferredSymbol={[TokenSymbol.USDC, TokenSymbol.USDT]}
+/>;
 ```
 
 ## Learn More

examples/nextjs-app/src/app/basic/page.tsx

@@ -500,6 +500,20 @@ export default function DemoBasic() {
                     Amount in USD (e.g., 100.00)
                   </dd>
                 </div>
+                <div>
+                  <dt className="font-mono font-semibold text-blue-800">
+                    preferredSymbol
+                  </dt>
+                  <dd className="text-gray-700 ml-4">
+                    Preferred token symbols (USDC, USDT, EURC). These tokens
+                    will appear first in the token selection list. Defaults to{" "}
+                    <code className="bg-blue-100 px-1 rounded">
+                      [USDC, USDT]
+                    </code>
+                    . Automatically finds matching tokens across all supported
+                    chains.
+                  </dd>
+                </div>
                 <div>
                   <dt className="font-mono font-semibold text-blue-800">
                     onPaymentStarted / onPaymentCompleted

packages/connectkit/bundle-analysis.html

@@ -1,7 +1,7 @@
 {
   "name": "@rozoai/intent-pay",
   "private": false,
-  "version": "0.1.7-beta.6",
+  "version": "0.1.7-beta.7",
   "author": "RozoAI",
   "homepage": "https://github.com/RozoAI/intent-pay",
   "license": "BSD-2-Clause",

packages/connectkit/package.json

@@ -195,6 +195,9 @@ export const RozoPayModal: React.FC<{
         setSelectedStellarTokenOption(undefined);
         context.setRoute(ROUTES.SELECT_TOKEN, meta);
       }
+    } else if (context.route === ROUTES.SELECT_WALLET_CHAIN) {
+      setSelectedWallet(undefined);
+      context.setRoute(ROUTES.CONNECTORS, meta);
     } else {
       context.setRoute(ROUTES.SELECT_METHOD, meta);
     }

packages/connectkit/src/components/DaimoPayModal/index.tsx

@@ -7,6 +7,7 @@ import {
   setupRefreshState,
   shouldSkipRefresh,
 } from "./refreshUtils";
+import { useSupportedChains } from "./useSupportedChains";
 
 /** Wallet payment options. User picks one. */
 export function useSolanaPaymentOptions({
@@ -34,10 +35,25 @@ export function useSolanaPaymentOptions({
   // Track if we have initial data to prevent clearing options on refresh (prevents flickering)
   const hasInitialData = useRef<boolean>(false);
 
+  const { chains } = useSupportedChains();
+
+  // Get Solana chain IDs from supported chains
+  const solanaChainIds = useMemo(() => {
+    return new Set(
+      chains.filter((c) => c.type === "solana").map((c) => c.chainId)
+    );
+  }, [chains]);
+
   const stableAppId = useMemo(() => {
     return payParams?.appId;
   }, [payParams]);
 
+  const memoizedPreferredTokens = useMemo(
+    () => payParams?.preferredTokens,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(payParams?.preferredTokens)]
+  );
+
   const filteredOptions = useMemo(() => {
     if (!options) return [];
 
@@ -96,11 +112,17 @@ export function useSolanaPaymentOptions({
     }
 
     try {
+      // Filter preferredTokenAddress to only include Solana chain tokens
+      const solanaPreferredTokenAddresses = (memoizedPreferredTokens ?? [])
+        .filter((t) => solanaChainIds.has(t.chainId))
+        .map((t) => t.token);
+
       const newOptions = await trpc.getSolanaPaymentOptions.query({
         pubKey: address,
         // API expects undefined for deposit flow.
         usdRequired: isDepositFlow ? undefined : usdRequired,
         appId: stableAppId,
+        preferredTokenAddress: solanaPreferredTokenAddresses,
       });
       setOptions(newOptions);
       hasInitialData.current = true;
@@ -114,7 +136,14 @@ export function useSolanaPaymentOptions({
       isApiCallInProgress.current = false;
       setIsLoading(false);
     }
-  }, [address, usdRequired, isDepositFlow, trpc, stableAppId]);
+  }, [
+    address,
+    usdRequired,
+    isDepositFlow,
+    trpc,
+    stableAppId,
+    memoizedPreferredTokens,
+  ]);
 
   // Create refresh function using shared utility
   const refreshOptions = createRefreshFunction(fetchBalances, {
@@ -145,6 +174,7 @@ export function useSolanaPaymentOptions({
       usdRequired,
       isDepositFlow,
       stableAppId,
+      memoizedPreferredTokens,
     });
 
     // Skip if we've already executed with these exact parameters
@@ -162,15 +192,22 @@ export function useSolanaPaymentOptions({
       lastExecutedParams,
       isApiCallInProgress,
     });
-  }, [address, usdRequired, isDepositFlow, stableAppId]);
+  }, [
+    address,
+    usdRequired,
+    isDepositFlow,
+    stableAppId,
+    memoizedPreferredTokens,
+  ]);
 
   // Initial fetch when hook mounts with valid parameters or when key parameters change
   useEffect(() => {
     if (address != null && usdRequired != null && stableAppId != null) {
       refreshOptions();
     }
     // refreshOptions is stable (created from fetchBalances which only changes when dependencies change)
-  }, [address, usdRequired, stableAppId]); // eslint-disable-line react-hooks/exhaustive-deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [address, usdRequired, stableAppId, memoizedPreferredTokens]);
 
   return {
     options: filteredOptions,

packages/connectkit/src/hooks/useSolanaPaymentOptions.ts

@@ -23,7 +23,14 @@ export function useStellarPaymentOptions({
   isDepositFlow: boolean;
   payParams: PayParams | undefined;
 }) {
-  const { tokens } = useSupportedChains();
+  const { chains, tokens } = useSupportedChains();
+
+  // Get Stellar chain IDs from supported chains
+  const stellarChainIds = useMemo(() => {
+    return new Set(
+      chains.filter((c) => c.type === "stellar").map((c) => c.chainId)
+    );
+  }, [chains]);
 
   const [options, setOptions] = useState<WalletPaymentOption[] | null>(null);
   const [isLoading, setIsLoading] = useState(false);
@@ -102,14 +109,17 @@ export function useStellarPaymentOptions({
     setIsLoading(true);
 
     try {
+      // Filter preferredTokenAddress to only include Stellar chain tokens
+      const stellarPreferredTokenAddresses = (memoizedPreferredTokens ?? [])
+        .filter((t) => stellarChainIds.has(t.chainId))
+        .map((t) => t.token);
+
       const newOptions = await trpc.getStellarPaymentOptions.query({
         stellarAddress: address,
         // API expects undefined for deposit flow.
         usdRequired: isDepositFlow ? undefined : usdRequired,
         appId: stableAppId,
-        preferredTokenAddress: (memoizedPreferredTokens ?? []).map(
-          (t) => t.token
-        ),
+        preferredTokenAddress: stellarPreferredTokenAddresses,
       });
       setOptions(newOptions);
     } catch (error) {
@@ -119,7 +129,16 @@ export function useStellarPaymentOptions({
       isApiCallInProgress.current = false;
       setIsLoading(false);
     }
-  }, [address, usdRequired, isDepositFlow, trpc, stableAppId]);
+  }, [
+    address,
+    usdRequired,
+    isDepositFlow,
+    trpc,
+    stableAppId,
+    memoizedPreferredTokens,
+    // stellarChainIds is derived from chains and is stable, so we don't need it in deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  ]);
 
   // Create refresh function using shared utility
   const refreshOptions = createRefreshFunction(fetchBalances, {
@@ -143,6 +162,7 @@ export function useStellarPaymentOptions({
       usdRequired,
       isDepositFlow,
       stableAppId,
+      memoizedPreferredTokens,
     });
 
     // Skip if we've already executed with these exact parameters
@@ -160,14 +180,21 @@ export function useStellarPaymentOptions({
       lastExecutedParams,
       isApiCallInProgress,
     });
-  }, [address, usdRequired, isDepositFlow, stableAppId]);
+  }, [
+    address,
+    usdRequired,
+    isDepositFlow,
+    stableAppId,
+    memoizedPreferredTokens,
+  ]);
 
   // Initial fetch when hook mounts with valid parameters or when key parameters change
   useEffect(() => {
     if (address != null && usdRequired != null && stableAppId != null) {
       refreshOptions();
     }
-  }, [address, usdRequired, stableAppId]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [address, usdRequired, stableAppId, memoizedPreferredTokens]);
 
   return {
     options: filteredOptions,