feat(widget): make ZEC a destination-only chain and check receivers per destination chain

.changeset/token-pick-receiver-reset.md

@@ -0,0 +1,5 @@
+---
+'@lifi/widget': patch
+---
+
+A token pick that moves the destination chain, for example from "All networks", now resets a receiver the new chain cannot take, as the chain select already does.

.changeset/zcash-destination-only.md

@@ -0,0 +1,18 @@
+---
+'@lifi/widget': minor
+'@lifi/widget-provider': minor
+'@lifi/widget-checkout': patch
+'@lifi/wallet-management': patch
+'@lifi/widget-provider-bitcoin': patch
+'@lifi/widget-provider-ethereum': patch
+'@lifi/widget-provider-solana': patch
+'@lifi/widget-provider-stellar': patch
+'@lifi/widget-provider-sui': patch
+'@lifi/widget-provider-tron': patch
+---
+
+ZEC is a destination-only chain. It never appears as a source chain or source token, and a `fromChain` of ZEC from the widget config or the URL is ignored. A ZEC receiver must be a transparent Zcash address (`t1…` or `t3…`) or a unified address (`u1…`) with an Orchard receiver; Sapling, TEX and other unified addresses get a message that names the accepted formats. The address inputs take up to 512 characters, so a unified address fits.
+
+Receivers are now checked against the destination chain, not only its chain type, so a Bitcoin address no longer passes as a ZEC receiver. A connected Bitcoin wallet is never filled in, offered, seeded or priced as a ZEC receiver, and a BTC → ZEC route asks for a receiver. Bookmarks of other ecosystems still save as before, and a Zcash bookmark shows the Zcash icon. The reverse and swap controls stay hidden while the destination chain is not allowed as a source by `chains.from`, so they never select a source chain the config excludes.
+
+`@lifi/widget-provider` exports `useAddressForChain`, which returns `isAddressForChain(address, chain)`, and the `ChainRef` and `IsAddressForChain` types. Every package that depends on the SDK requires the release whose `isAddress` accepts a chain ID, so a consumer keeps a single `@lifi/sdk`. The widget now passes the chain ID to each provider's `isAddress`, so upgrade the `@lifi/widget-provider-*` packages together with `@lifi/widget`: an older `@lifi/widget-provider-bitcoin` refuses every Bitcoin receiver and hides Bitcoin balances. `name` and `version` exported from `@lifi/widget` stay the widget's own now that `@lifi/sdk` exports the same names.

.changeset/zcash-provider-package.md

@@ -0,0 +1,7 @@
+---
+'@lifi/widget-provider-zcash': minor
+'@lifi/widget-provider': minor
+'@lifi/widget': minor
+---
+
+New package `@lifi/widget-provider-zcash`. Add `ZcashProvider()` to `providers` to offer ZEC as a destination; without it the widget shows no ZEC, because no ZEC receiver could be validated. With external wallet management the widget ignores `providers`, so render the component that `ZcashProvider()` returns around the widget, next to the other ecosystem providers. `@lifi/widget-provider` exports `ZcashContext` and `useZcashContext`, asks the provider that serves a chain for receiver checks, and recognises a Zcash address without a chain, so a Zcash bookmark keeps the Zcash icon.

.github/workflows/e2e-playground-dev.yml

@@ -23,6 +23,7 @@ on:
       - 'packages/widget-provider-stellar/**'
       - 'packages/widget-provider-sui/**'
       - 'packages/widget-provider-tron/**'
+      - 'packages/widget-provider-zcash/**'
       # Dev smoke test code and config
       - 'e2e/tests/dev/**'
       - 'e2e/tests/components/**'

.github/workflows/e2e-playground.yml

@@ -18,6 +18,7 @@ on:
       - 'packages/widget-provider-stellar/**'
       - 'packages/widget-provider-sui/**'
       - 'packages/widget-provider-tron/**'
+      - 'packages/widget-provider-zcash/**'
       # E2E test code (widget-light and widget-embedded are not playground dependencies)
       - 'e2e/tests/playground/**'
       - 'e2e/tests/components/**'

.size-limit.json

@@ -4,7 +4,7 @@
     "path": "packages/widget/dist/esm/index.js",
     "import": "{ LiFiWidget }",
     "ignore": ["react", "react-dom", "@tanstack/react-query", "*.json"],
-    "limit": "321 kB"
+    "limit": "322 kB"
   },
   {
     "name": "@lifi/widget · English translations (always loaded)",
@@ -77,14 +77,14 @@
     "path": "packages/widget-provider-solana/dist/esm/index.js",
     "import": "{ SolanaProvider }",
     "ignore": ["react", "bs58", "@lifi/sdk", "@lifi/widget-provider"],
-    "limit": "36 kB"
+    "limit": "39 kB"
   },
   {
     "name": "Providers · bitcoin",
     "path": "packages/widget-provider-bitcoin/dist/esm/index.js",
     "import": "{ BitcoinProvider }",
     "ignore": ["react", "@bigmi/react", "@lifi/sdk", "@lifi/widget-provider"],
-    "limit": "106 kB"
+    "limit": "107 kB"
   },
   {
     "name": "Providers · sui",
@@ -108,14 +108,21 @@
       "@lifi/sdk",
       "@lifi/widget-provider"
     ],
-    "limit": "876 kB"
+    "limit": "877 kB"
   },
   {
     "name": "Providers · stellar",
     "path": "packages/widget-provider-stellar/dist/esm/index.js",
     "import": "{ StellarProvider }",
     "ignore": ["react", "@lifi/sdk", "@lifi/widget-provider"],
-    "limit": "212 kB"
+    "limit": "213 kB"
+  },
+  {
+    "name": "Providers · zcash",
+    "path": "packages/widget-provider-zcash/dist/esm/index.js",
+    "import": "{ ZcashProvider }",
+    "ignore": ["react", "@lifi/sdk", "@lifi/widget-provider"],
+    "limit": "8 kB"
   },
   {
     "name": "Full integration · LiFiWidget + all providers + their peers (incl. on-demand code)",
@@ -126,9 +133,10 @@
       "packages/widget-provider-bitcoin/dist/esm/index.js": "{ BitcoinProvider }",
       "packages/widget-provider-sui/dist/esm/index.js": "{ SuiProvider }",
       "packages/widget-provider-tron/dist/esm/index.js": "{ TronProvider }",
-      "packages/widget-provider-stellar/dist/esm/index.js": "{ StellarProvider }"
+      "packages/widget-provider-stellar/dist/esm/index.js": "{ StellarProvider }",
+      "packages/widget-provider-zcash/dist/esm/index.js": "{ ZcashProvider }"
     },
     "ignore": ["react", "react-dom", "@tanstack/react-query"],
-    "limit": "2278 kB"
+    "limit": "2292 kB"
   }
 ]

packages/widget-checkout/src/hooks/useDefaultWalletRecipient.test.tsx

@@ -10,6 +10,23 @@ interface MockAccount {
 
 let mockAccounts: MockAccount[] = []
 let mockFundingSource: string | null = 'wallet'
+let mockDestinationChain: { id: number; chainType: string } = {
+  id: 1,
+  chainType: 'EVM',
+}
+// EVM chains take 0x addresses; ZEC takes t1 addresses only.
+const mockIsAddressForChain = (
+  address: string,
+  chain: { id: number; chainType: string }
+) => {
+  if (chain.chainType === 'EVM') {
+    return address.startsWith('0x')
+  }
+  if (chain.id === 20000000000005) {
+    return address.startsWith('t1')
+  }
+  return address.startsWith('bc1')
+}
 let mockResolved: {
   isUserSettable: boolean
   isUserSet: boolean
@@ -23,7 +40,10 @@ vi.mock('@lifi/wallet-management', () => ({
 }))
 vi.mock('@lifi/widget/shared', () => ({
   useWidgetConfig: () => ({ toChain: 1 }),
-  useChain: () => ({ chain: { chainType: 'EVM' } }),
+  useChain: () => ({ chain: mockDestinationChain }),
+}))
+vi.mock('@lifi/widget-provider', () => ({
+  useAddressForChain: () => ({ isAddressForChain: mockIsAddressForChain }),
 }))
 vi.mock('../stores/useCheckoutFlowStore.js', () => ({
   useCheckoutFlowStore: (
@@ -41,6 +61,7 @@ describe('useDefaultWalletRecipient', () => {
     setUserRecipient.mockReset()
     mockAccounts = [{ isConnected: true, address: '0xabc', chainType: 'EVM' }]
     mockFundingSource = 'wallet'
+    mockDestinationChain = { id: 1, chainType: 'EVM' }
     mockResolved = { isUserSettable: true, isUserSet: false, setUserRecipient }
   })
 
@@ -75,4 +96,17 @@ describe('useDefaultWalletRecipient', () => {
     renderHook(() => useDefaultWalletRecipient())
     expect(setUserRecipient).not.toHaveBeenCalled()
   })
+
+  it('does not seed a Bitcoin wallet for a ZEC destination', () => {
+    mockDestinationChain = { id: 20000000000005, chainType: 'UTXO' }
+    mockAccounts = [
+      {
+        isConnected: true,
+        address: 'bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq',
+        chainType: 'UTXO',
+      },
+    ]
+    renderHook(() => useDefaultWalletRecipient())
+    expect(setUserRecipient).not.toHaveBeenCalled()
+  })
 })

packages/widget-checkout/src/hooks/useDefaultWalletRecipient.ts

@@ -1,6 +1,7 @@
 'use client'
 import { useAccount } from '@lifi/wallet-management'
 import { useChain, useWidgetConfig } from '@lifi/widget/shared'
+import { useAddressForChain } from '@lifi/widget-provider'
 import { useEffect, useRef } from 'react'
 import { useCheckoutFlowStore } from '../stores/useCheckoutFlowStore.js'
 import { useResolvedCheckoutRecipient } from './useResolvedCheckoutRecipient.js'
@@ -18,6 +19,7 @@ export function useDefaultWalletRecipient(): void {
   const { isUserSettable, isUserSet, setUserRecipient } =
     useResolvedCheckoutRecipient()
   const { accounts } = useAccount()
+  const { isAddressForChain } = useAddressForChain()
   const seededRef = useRef(false)
 
   useEffect(() => {
@@ -32,7 +34,9 @@ export function useDefaultWalletRecipient(): void {
     }
     const match = accounts.find(
       (a) =>
-        a.isConnected && a.address && a.chainType === destinationChain.chainType
+        a.isConnected &&
+        a.address &&
+        isAddressForChain(a.address, destinationChain)
     )
     if (match?.address) {
       seededRef.current = true
@@ -48,5 +52,6 @@ export function useDefaultWalletRecipient(): void {
     destinationChain,
     accounts,
     setUserRecipient,
+    isAddressForChain,
   ])
 }

packages/widget-checkout/src/hooks/useResolvedCheckoutRecipient.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment happy-dom
+import { renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+let mockSavedRecipient: { address: string; chainType: string } | undefined
+
+vi.mock('@lifi/widget/shared', () => ({
+  useWidgetConfig: () => ({ toChain: 20000000000005 }),
+  useChain: () => ({ chain: { id: 20000000000005, chainType: 'UTXO' } }),
+}))
+vi.mock('@lifi/widget-provider/checkout', () => ({
+  useCheckoutConfig: () => ({
+    integrator: 'test',
+    allowUserDestinationAddress: true,
+  }),
+}))
+vi.mock('@lifi/widget-provider', () => ({
+  useAddressForChain: () => ({
+    isAddressForChain: (address: string) => address.startsWith('t1'),
+  }),
+}))
+vi.mock('../stores/useCheckoutRecipientStore.js', () => ({
+  useCheckoutRecipientStore: (selector: (state: unknown) => unknown) =>
+    selector({
+      recipients: { test: mockSavedRecipient },
+      setRecipient: vi.fn(),
+      clearRecipient: vi.fn(),
+    }),
+}))
+
+import { useResolvedCheckoutRecipient } from './useResolvedCheckoutRecipient.js'
+
+describe('useResolvedCheckoutRecipient', () => {
+  beforeEach(() => {
+    mockSavedRecipient = undefined
+  })
+
+  it('drops a saved Bitcoin recipient for a ZEC destination', () => {
+    mockSavedRecipient = {
+      address: 'bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq',
+      chainType: 'UTXO',
+    }
+    const { result } = renderHook(() => useResolvedCheckoutRecipient())
+    expect(result.current.recipient).toBeNull()
+    expect(result.current.isUserSet).toBe(false)
+  })
+
+  it('keeps a saved Zcash recipient for a ZEC destination', () => {
+    mockSavedRecipient = {
+      address: 't1VmmGiyjVNeCjxDZzg7vZmd99WyzVby9yC',
+      chainType: 'UTXO',
+    }
+    const { result } = renderHook(() => useResolvedCheckoutRecipient())
+    expect(result.current.recipient?.address).toBe(
+      't1VmmGiyjVNeCjxDZzg7vZmd99WyzVby9yC'
+    )
+  })
+})

packages/widget-checkout/src/hooks/useResolvedCheckoutRecipient.ts

@@ -1,5 +1,6 @@
 import type { ChainType } from '@lifi/sdk'
 import { useChain, useWidgetConfig } from '@lifi/widget/shared'
+import { useAddressForChain } from '@lifi/widget-provider'
 import { useCheckoutConfig } from '@lifi/widget-provider/checkout'
 import { useCallback, useMemo } from 'react'
 import {
@@ -21,24 +22,24 @@ export interface ResolvedCheckoutRecipient {
 export function useResolvedCheckoutRecipient(): ResolvedCheckoutRecipient {
   const { toAddress, toChain } = useWidgetConfig()
   const { chain: destinationChain } = useChain(toChain)
+  const { isAddressForChain } = useAddressForChain()
   const { integrator, allowUserDestinationAddress } = useCheckoutConfig()
   const userRecipient = useCheckoutRecipientStore(
     (s) => s.recipients[integrator] ?? null
   )
 
-  // Drop a persisted recipient that no longer matches the destination ecosystem.
   const validUserRecipient = useMemo(() => {
     if (!userRecipient) {
       return null
     }
     if (
       destinationChain &&
-      userRecipient.chainType !== destinationChain.chainType
+      !isAddressForChain(userRecipient.address, destinationChain)
     ) {
       return null
     }
     return userRecipient
-  }, [userRecipient, destinationChain])
+  }, [userRecipient, destinationChain, isAddressForChain])
   const setRecipient = useCheckoutRecipientStore((s) => s.setRecipient)
   const clearRecipient = useCheckoutRecipientStore((s) => s.clearRecipient)
 

packages/widget-checkout/src/pages/SetDestinationAddressPage/SetDestinationAddressPage.tsx

@@ -8,6 +8,7 @@ import {
   useHeader,
   useWidgetConfig,
 } from '@lifi/widget/shared'
+import { useAddressForChain } from '@lifi/widget-provider'
 import WalletOutlinedIcon from '@mui/icons-material/AccountBalanceWalletOutlined'
 import {
   Avatar,
@@ -44,6 +45,7 @@ export const SetDestinationAddressPage: React.FC = (): JSX.Element => {
   const { setFieldValue } = useFieldActions()
   const { openWalletMenu } = useWalletMenu()
   const { accounts } = useAccount()
+  const { isAddressForChain } = useAddressForChain()
 
   const [value, setValue] = useState('')
   const [error, setError] = useState<string | null>(null)
@@ -66,26 +68,16 @@ export const SetDestinationAddressPage: React.FC = (): JSX.Element => {
     setError(null)
     const result = await validateAddress({
       value: value.trim(),
-      chainType: destinationChain?.chainType,
       chain: destinationChain,
     })
     if (!result.isValid) {
       setError(result.error)
       return
     }
-    if (destinationChain && result.chainType !== destinationChain.chainType) {
-      setError(
-        t('error.title.walletAddressInvalid', {
-          context: 'chain',
-          chainName: destinationChain.name,
-        })
-      )
-      return
-    }
     commitRecipient(result.address, result.chainType)
-  }, [value, destinationChain, validateAddress, commitRecipient, t])
+  }, [value, destinationChain, validateAddress, commitRecipient])
 
-  // Adopt the first connected account matching the destination ecosystem after connect.
+  // Adopt the first connected account matching the destination chain after connect.
   const awaitingConnectRef = useRef(false)
   const handleConnectWallet = useCallback(() => {
     awaitingConnectRef.current = true
@@ -98,28 +90,31 @@ export const SetDestinationAddressPage: React.FC = (): JSX.Element => {
     }
     const match = accounts.find(
       (a) =>
-        a.isConnected && a.address && a.chainType === destinationChain.chainType
+        a.isConnected &&
+        a.address &&
+        isAddressForChain(a.address, destinationChain)
     )
     if (match?.address) {
       awaitingConnectRef.current = false
       commitRecipient(match.address, destinationChain.chainType)
     }
-  }, [accounts, destinationChain, commitRecipient])
+  }, [accounts, destinationChain, commitRecipient, isAddressForChain])
 
-  // Connected wallets in the destination ecosystem, offered as one-tap recipients.
+  // Connected wallets that can receive on the destination chain, offered as one-tap recipients.
   const connectedAccounts = useMemo(() => {
     const byAddress = new Map<string, (typeof accounts)[number]>()
     for (const account of accounts) {
       if (
         account.isConnected &&
         account.address &&
-        account.chainType === destinationChain?.chainType
+        destinationChain &&
+        isAddressForChain(account.address, destinationChain)
       ) {
         byAddress.set(account.address.toLowerCase(), account)
       }
     }
     return [...byAddress.values()]
-  }, [accounts, destinationChain])
+  }, [accounts, destinationChain, isAddressForChain])
 
   return (
     <PageContainer bottomGutters>

packages/widget-playground/package.json

@@ -35,6 +35,7 @@
     "@lifi/widget-provider-sui": "workspace:*",
     "@lifi/widget-provider-transak": "workspace:*",
     "@lifi/widget-provider-tron": "workspace:*",
+    "@lifi/widget-provider-zcash": "workspace:*",
     "@metamask/connect-evm": "^2.1.1",
     "@mui/icons-material": "^9.4.0",
     "@mui/material": "^9.4.0",