@lifi/widget 4.5.0 → 4.7.0

package/src/stores/recentTokens/createRecentTokensStore.ts

@@ -0,0 +1,107 @@
+import type { StoreApi, UseBoundStore } from 'zustand'
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+import type { PersistStoreProps } from '../types.js'
+import type {
+  RecentToken,
+  RecentTokensProps,
+  RecentTokensState,
+} from './types.js'
+import { getTokenKey } from './utils.js'
+
+const recentTokensLimit = 10
+
+const isStoredRecentToken = (value: unknown): value is RecentToken => {
+  const token = value as Partial<RecentToken> | null
+  return (
+    typeof token === 'object' &&
+    token !== null &&
+    typeof token.chainId === 'number' &&
+    typeof token.address === 'string' &&
+    typeof token.symbol === 'string' &&
+    typeof token.name === 'string' &&
+    typeof token.decimals === 'number' &&
+    (token.logoURI === undefined || typeof token.logoURI === 'string') &&
+    (token.flagged === undefined || typeof token.flagged === 'boolean')
+  )
+}
+
+// The key lives on the integrator's origin, so its content is untrusted.
+const sanitizeRecentTokens = (stored: unknown): RecentToken[] => {
+  if (!Array.isArray(stored)) {
+    return []
+  }
+  const seen = new Set<string>()
+  const recentTokens: RecentToken[] = []
+  for (const token of stored) {
+    if (!isStoredRecentToken(token)) {
+      continue
+    }
+    const key = getTokenKey(token.chainId, token.address)
+    if (!seen.has(key)) {
+      seen.add(key)
+      recentTokens.push(token)
+    }
+  }
+  return recentTokens.slice(0, recentTokensLimit)
+}
+
+export const createRecentTokensStore = ({
+  namePrefix,
+}: PersistStoreProps): UseBoundStore<StoreApi<RecentTokensState>> =>
+  create<RecentTokensState>()(
+    persist(
+      (set, get) => ({
+        recentTokens: [],
+        addRecentToken: (token) => {
+          const key = getTokenKey(token.chainId, token.address)
+          set((state) => ({
+            recentTokens: [
+              token,
+              ...state.recentTokens.filter(
+                (t) => getTokenKey(t.chainId, t.address) !== key
+              ),
+            ].slice(0, recentTokensLimit),
+          }))
+        },
+        removeRecentToken: (chainId, address) => {
+          const key = getTokenKey(chainId, address)
+          set((state) => ({
+            recentTokens: state.recentTokens.filter(
+              (t) => getTokenKey(t.chainId, t.address) !== key
+            ),
+          }))
+        },
+        clearRecentTokens: (entries) =>
+          set((state) => {
+            const removed = new Set(
+              entries.map((e) => getTokenKey(e.chainId, e.address))
+            )
+            return {
+              recentTokens: state.recentTokens.filter(
+                (t) => !removed.has(getTokenKey(t.chainId, t.address))
+              ),
+            }
+          }),
+        isRecentToken: (chainId, address) => {
+          const key = getTokenKey(chainId, address)
+          return get().recentTokens.some(
+            (t) => getTokenKey(t.chainId, t.address) === key
+          )
+        },
+      }),
+      {
+        name: `${namePrefix || 'li.fi'}-recent-tokens`,
+        version: 0,
+        partialize: (state) => ({
+          recentTokens: state.recentTokens,
+        }),
+        merge: (persisted, current) => ({
+          ...current,
+          recentTokens: sanitizeRecentTokens(
+            (persisted as Partial<RecentTokensProps> | undefined)?.recentTokens
+          ),
+        }),
+      }
+    )
+  )

package/src/stores/recentTokens/types.ts

@@ -0,0 +1,37 @@
+import type { StoreApi } from 'zustand'
+import type { UseBoundStoreWithEqualityFn } from 'zustand/traditional'
+
+export interface RecentToken {
+  chainId: number
+  /** The token's own casing. Compared case-insensitively with chainId. */
+  address: string
+  symbol: string
+  name: string
+  decimals: number
+  logoURI?: string
+  flagged?: boolean
+}
+
+/** Compared case-insensitively. */
+export interface RecentTokenId {
+  chainId: number
+  address: string
+}
+
+export interface RecentTokensProps {
+  recentTokens: RecentToken[]
+}
+
+export interface RecentTokensActions {
+  addRecentToken: (token: RecentToken) => void
+  removeRecentToken: (chainId: number, address: string) => void
+  /** Removes exactly these entries, never one outside the band's scope. */
+  clearRecentTokens: (entries: RecentTokenId[]) => void
+  isRecentToken: (chainId: number, address: string) => boolean
+}
+
+export type RecentTokensState = RecentTokensProps & RecentTokensActions
+
+export type RecentTokensStore = UseBoundStoreWithEqualityFn<
+  StoreApi<RecentTokensState>
+>

package/src/stores/recentTokens/utils.ts

@@ -0,0 +1,18 @@
+import type { TokenAmount } from '../../types/token.js'
+import type { RecentToken } from './types.js'
+
+export const getTokenKey = (chainId: number, address: string): string =>
+  `${chainId}-${address.toLowerCase()}`
+
+// No price, and no verdict but a flag: a stale "verified" would hide a warning.
+export const toRecentToken = (token: TokenAmount): RecentToken => ({
+  // Plain-JS configs can pass a string chainId or null fields; hydration rejects both.
+  chainId: Number(token.chainId),
+  // Keep the casing: the form and the selected check compare it exactly.
+  address: token.address,
+  symbol: token.symbol,
+  name: token.name ?? '',
+  decimals: token.decimals,
+  logoURI: token.logoURI ?? undefined,
+  flagged: token.verificationStatus === 'flagged' || undefined,
+})

package/src/types/token.ts

@@ -4,11 +4,16 @@ import type {
   TokenExtended,
 } from '@lifi/sdk'
 
-interface TokenFlags {
+export interface TokenFlags {
   featured?: boolean
   popular?: boolean
   pinned?: boolean
+  /** A copy promoted into the "Recent searches" band. */
+  recent?: boolean
   verified?: boolean
+  native?: boolean
+  /** Came from the main token list rather than from a search. */
+  listed?: boolean
 }
 
 export interface TokenAmount extends SDKTokenAmount, TokenFlags {}
@@ -17,5 +22,5 @@ export interface TokenAmountExtended
   extends SDKTokenAmountExtended,
     TokenFlags {}
 
-export type TokenWithVerified = TokenExtended & { verified?: boolean }
-export type TokensByChain = Record<number, TokenWithVerified[]>
+export type TokenWithFlags = TokenExtended & TokenFlags
+export type TokensByChain = Record<number, TokenWithFlags[]>

package/src/types/widget.ts

@@ -156,6 +156,11 @@ export interface HiddenUIConfig {
    */
   lowAddressActivityConfirmation?: boolean
   poweredBy?: boolean
+  /**
+   * Hide the "Recent searches" section in the token select view.
+   * @default false
+   */
+  recentSearches?: boolean
   reverseTokensButton?: boolean
   routeCardPriceImpact?: boolean
   routeTokenDescription?: boolean

package/src/utils/address.ts

@@ -0,0 +1,21 @@
+import type { ChainType } from '@lifi/sdk'
+
+/**
+ * True when a token search query is a contract address rather than free text.
+ * `getChainTypeFromTokenAddress` asks the configured providers' own
+ * `isTokenAddress` (see `useChainTypeFromAddress`), so it covers the token
+ * identifier of every ecosystem. Two consequences follow. `bitcoin` stays a
+ * name search, because the Bitcoin provider implements no token check. And an
+ * ecosystem is not detected unless the host configures its provider from
+ * `@lifi/sdk` 4.7.0 or later, even when its chains are listed.
+ */
+export const isAddressQuery = (
+  query: string | undefined,
+  getChainTypeFromTokenAddress: (address: string) => ChainType | undefined
+): boolean => {
+  const value = query?.trim()
+  if (!value) {
+    return false
+  }
+  return getChainTypeFromTokenAddress(value) !== undefined
+}

package/src/utils/customReceiver.ts

@@ -0,0 +1,31 @@
+import { ChainType } from '@lifi/sdk'
+
+// Stellar routes always settle to the account that signs them.
+export const isCustomReceiverUnsupported = (
+  fromChainType?: ChainType,
+  toChainType?: ChainType
+): boolean => fromChainType === ChainType.STL && toChainType === ChainType.STL
+
+export interface CustomReceiverBlockedArgs {
+  fromChainType?: ChainType
+  toChainType?: ChainType
+  toAddress?: string
+  signerAddress?: string
+  receiverRequired?: boolean
+}
+
+export const isCustomReceiverBlocked = ({
+  fromChainType,
+  toChainType,
+  toAddress,
+  signerAddress,
+  receiverRequired,
+}: CustomReceiverBlockedArgs): boolean => {
+  if (!isCustomReceiverUnsupported(fromChainType, toChainType)) {
+    return false
+  }
+  if (!toAddress) {
+    return Boolean(receiverRequired)
+  }
+  return toAddress.toLowerCase() !== signerAddress?.toLowerCase()
+}

package/src/utils/gas.ts

@@ -0,0 +1,41 @@
+import type { LiFiStepExtended, RouteExtended } from '@lifi/sdk'
+import { ChainType } from '@lifi/sdk'
+
+/**
+ * Returns how much of a step's gas token the route itself delivers before that
+ * step runs. The previous step must output the gas token on the same chain, and
+ * whatever this step consumes as input is not available for gas.
+ * Stellar routes only — they bridge XLM to the receiver and hold back a buffer
+ * for the account reserve and the destination step fees.
+ */
+export const getSelfFundedGasAmount = (
+  route: RouteExtended,
+  step: LiFiStepExtended,
+  gasChainType?: ChainType
+): bigint => {
+  // TODO: remove the chain gate when the backend reserves gas on every chain
+  if (gasChainType !== ChainType.STL) {
+    return 0n
+  }
+  const gasToken = step.estimate.gasCosts?.[0]?.token
+  const previousStep = route.steps[route.steps.indexOf(step) - 1]
+  if (!gasToken || !previousStep) {
+    return 0n
+  }
+  const { toToken } = previousStep.action
+  if (
+    toToken.chainId !== gasToken.chainId ||
+    toToken.address.toLowerCase() !== gasToken.address.toLowerCase()
+  ) {
+    return 0n
+  }
+  const deliveredAmount = BigInt(previousStep.estimate.toAmountMin)
+  const consumedAmount =
+    step.action.fromToken.address.toLowerCase() ===
+    gasToken.address.toLowerCase()
+      ? BigInt(step.action.fromAmount)
+      : 0n
+  return deliveredAmount > consumedAmount
+    ? deliveredAmount - consumedAmount
+    : 0n
+}

package/src/utils/recentTokens.ts

@@ -0,0 +1,187 @@
+import type { FormType } from '../stores/form/types.js'
+import type {
+  RecentToken,
+  RecentTokenId,
+} from '../stores/recentTokens/types.js'
+import { getTokenKey } from '../stores/recentTokens/utils.js'
+import type { TokenAmount } from '../types/token.js'
+import type { AllowDenySets, WidgetTokens } from '../types/widget.js'
+import { isFormItemAllowed } from './item.js'
+import { getChainTokenAllowSets } from './token.js'
+
+export const collapsedRecentCount = 4
+
+export interface ResolveRecentRowsParams {
+  recentTokens: RecentToken[]
+  availableChainIds: Set<number>
+  configTokens: WidgetTokens | undefined
+  formType: FormType
+  selectedChainId?: number
+  isAllNetworks?: boolean
+  nativeHoisted: boolean
+  disabled: boolean
+}
+
+export interface RecentRows {
+  /** Unsliced; empty when the band is inactive. */
+  rows: TokenAmount[]
+  /** Everything Clear removes, including toggled-away and displaced rows. */
+  bandEntries: RecentTokenId[]
+  recentStartIndex: number
+}
+
+export interface RecentTokensResult {
+  tokens: TokenAmount[]
+  recentCount: number
+  totalRecentCount: number
+}
+
+// Whitelisted fields; a flag is the one verdict kept, as stale it only over-warns.
+const toSnapshotRow = (recent: RecentToken): TokenAmount =>
+  ({
+    chainId: recent.chainId,
+    address: recent.address,
+    symbol: recent.symbol,
+    name: recent.name,
+    decimals: recent.decimals,
+    logoURI: recent.logoURI,
+    priceUSD: '',
+    verificationStatus: recent.flagged ? 'flagged' : undefined,
+  }) as TokenAmount
+
+const isFeaturedCopy = (token: TokenAmount): boolean =>
+  !!token.featured && !token.amount
+
+export const resolveRecentRows = (
+  tokens: TokenAmount[],
+  {
+    recentTokens,
+    availableChainIds,
+    configTokens,
+    formType,
+    selectedChainId,
+    isAllNetworks,
+    nativeHoisted,
+    disabled,
+  }: ResolveRecentRowsParams
+): RecentRows => {
+  let recentStartIndex = nativeHoisted ? 1 : 0
+  while (tokens[recentStartIndex]?.pinned) {
+    recentStartIndex++
+  }
+
+  const inactive: RecentRows = { rows: [], bandEntries: [], recentStartIndex }
+
+  if (disabled || !recentTokens.length || !tokens.length) {
+    return inactive
+  }
+
+  const candidates = recentTokens.filter(
+    (recent) =>
+      (isAllNetworks || recent.chainId === selectedChainId) &&
+      availableChainIds.has(recent.chainId)
+  )
+
+  if (!candidates.length) {
+    return inactive
+  }
+
+  const wanted = new Set(
+    candidates.map((recent) => getTokenKey(recent.chainId, recent.address))
+  )
+  // All-networks holds tens of thousands of rows: test the chain before the key.
+  const wantedChains = new Set(candidates.map((recent) => recent.chainId))
+  const fresh = new Map<string, TokenAmount>()
+  // A featured config copy has no balance and sits above the row with one.
+  let awaitingBalance = 0
+  for (const token of tokens) {
+    if (!wantedChains.has(token.chainId)) {
+      continue
+    }
+    const key = getTokenKey(token.chainId, token.address)
+    if (!wanted.has(key)) {
+      continue
+    }
+    const found = fresh.get(key)
+    if (!found) {
+      fresh.set(key, token)
+      if (isFeaturedCopy(token)) {
+        awaitingBalance++
+      }
+    } else if (token.amount && isFeaturedCopy(found)) {
+      fresh.set(key, {
+        ...found,
+        amount: token.amount,
+        priceUSD: token.priceUSD || found.priceUSD,
+      })
+      awaitingBalance--
+    }
+    if (fresh.size === wanted.size && !awaitingBalance) {
+      break
+    }
+  }
+
+  const allowedByChain = new Map<number, AllowDenySets | undefined>()
+  const allowedFor = (chainId: number) => {
+    if (!allowedByChain.has(chainId)) {
+      allowedByChain.set(
+        chainId,
+        getChainTokenAllowSets(configTokens, chainId, formType)
+      )
+    }
+    return allowedByChain.get(chainId)
+  }
+
+  const hoistedKey = nativeHoisted
+    ? getTokenKey(tokens[0].chainId, tokens[0].address)
+    : undefined
+
+  const rows: TokenAmount[] = []
+  const bandEntries: RecentTokenId[] = []
+  for (const recent of candidates) {
+    const key = getTokenKey(recent.chainId, recent.address)
+    const resolved = fresh.get(key) ?? toSnapshotRow(recent)
+    if (
+      !isFormItemAllowed(resolved, allowedFor(recent.chainId), formType, (t) =>
+        t.address.toLowerCase()
+      )
+    ) {
+      // Denied on this side only, so Clear must leave it for the other side.
+      continue
+    }
+    // Clear owns displaced entries too, or they reappear once unpinned.
+    bandEntries.push({ chainId: recent.chainId, address: recent.address })
+    if (key === hoistedKey || resolved.pinned) {
+      continue
+    }
+    rows.push({ ...resolved, recent: true })
+  }
+
+  if (!rows.length) {
+    return inactive
+  }
+
+  return { rows, bandEntries, recentStartIndex }
+}
+
+export const spliceRecentRows = (
+  tokens: TokenAmount[],
+  { rows, recentStartIndex }: RecentRows,
+  expanded: boolean
+): RecentTokensResult => {
+  if (!rows.length) {
+    return { tokens, recentCount: 0, totalRecentCount: 0 }
+  }
+
+  const visible = expanded ? rows : rows.slice(0, collapsedRecentCount)
+
+  return {
+    tokens: [
+      ...tokens.slice(0, recentStartIndex),
+      ...visible,
+      ...tokens.slice(recentStartIndex),
+    ],
+    recentCount: visible.length,
+    totalRecentCount: rows.length,
+  }
+}

package/src/utils/token.ts

@@ -1,9 +1,39 @@
-import type { BaseToken, RouteExtended, Token, TokenAmount } from '@lifi/sdk'
+import type {
+  BaseToken,
+  ExtendedChain,
+  RouteExtended,
+  StaticToken,
+  Token,
+  TokenAmount,
+  TokenExtended,
+} from '@lifi/sdk'
+import { ChainId } from '@lifi/sdk'
 import type { FormType } from '../stores/form/types.js'
-import type { TokensByChain, TokenWithVerified } from '../types/token.js'
-import type { WidgetChains, WidgetTokens } from '../types/widget.js'
+import type { TokensByChain, TokenWithFlags } from '../types/token.js'
+import type {
+  AllowDenySets,
+  WidgetChains,
+  WidgetTokens,
+} from '../types/widget.js'
 import { getConfigItemSets, isFormItemAllowed } from './item.js'
 
+// Number(): plain-JS integrators may pass chainId as a string.
+export const getChainTokenAllowSets = (
+  configTokens: WidgetTokens | undefined,
+  chainId: number,
+  formType?: FormType
+): AllowDenySets | undefined =>
+  getConfigItemSets(
+    configTokens,
+    (tokens: BaseToken[]) =>
+      new Set(
+        tokens
+          .filter((t) => Number(t.chainId) === chainId)
+          .map((t) => t.address.toLowerCase())
+      ),
+    formType
+  )
+
 /**
  * Builds per-chain sets of lowercase token addresses from the
  * `tokens.verified` config allowlist.
@@ -63,9 +93,39 @@ export const mergeVerifiedWithSearchTokens = (
   return result
 }
 
+/**
+ * `priceUSD` is a required string, so an unknown price arrives as `'0'` or `''`
+ * rather than as an absent key — the same reading as in `useLimitMarketRate`. A
+ * known price must never lose to one, or a route that cannot price its output
+ * blanks a value the cache already knew.
+ */
+export const knownPriceUSD = (fresher: string, cached: string): string =>
+  Number(fresher) ? fresher : cached
+
+/**
+ * Merges a cached token into a route token for display. The route wins on every
+ * field it carries; the cache only fills gaps. Letting the cache win instead
+ * swaps the quoted price for a stale feed price.
+ */
+export const mergeFallbackToken = (
+  routeToken: TokenAmount,
+  cachedToken: TokenExtended | undefined
+): TokenAmount =>
+  cachedToken
+    ? {
+        ...cachedToken,
+        ...routeToken,
+        priceUSD: knownPriceUSD(routeToken.priceUSD, cachedToken.priceUSD),
+        logoURI: routeToken.logoURI || cachedToken.logoURI,
+      }
+    : routeToken
+
 /**
  * Updates a token in the cache by chainId and address.
  * Returns a new cache object with the token updated, or the original if not found.
+ * Addresses are compared case-insensitively: the token list and the route can
+ * spell the same address differently. The incoming token only overwrites what it
+ * actually knows, so an unpriced or logo-less route cannot blank the cache.
  */
 export const updateTokenInCache = (
   data: TokensByChain | undefined,
@@ -78,14 +138,26 @@ export const updateTokenInCache = (
   if (!chainTokens) {
     return data
   }
-  const index = chainTokens.findIndex((t) => t.address === token.address)
+  const address = token.address.toLowerCase()
+  const index = chainTokens.findIndex(
+    (t) => t.address.toLowerCase() === address
+  )
   if (index < 0) {
     return data
   }
   return {
     ...data,
     [token.chainId]: chainTokens.map((t, i) =>
-      i === index ? { ...t, ...token } : t
+      i === index
+        ? {
+            ...t,
+            ...token,
+            // Keep the cached address: other readers hold it as the identity.
+            address: t.address,
+            priceUSD: knownPriceUSD(token.priceUSD, t.priceUSD),
+            logoURI: token.logoURI || t.logoURI,
+          }
+        : t
     ),
   }
 }
@@ -94,7 +166,8 @@ export const filterAllowedTokens = (
   dataTokens: TokensByChain | undefined,
   configTokens?: WidgetTokens,
   chainsConfig?: WidgetChains,
-  formType?: FormType
+  formType?: FormType,
+  nativeTokenAddresses?: Map<number, string>
 ): TokensByChain | undefined => {
   if (!dataTokens) {
     return
@@ -131,25 +204,21 @@ export const filterAllowedTokens = (
       chainIncludedTokens.map((t) => t.address.toLowerCase())
     )
 
-    const allowedAddresses = getConfigItemSets(
+    const allowedAddresses = getChainTokenAllowSets(
       configTokens,
-      (tokens: BaseToken[]) =>
-        new Set(
-          tokens
-            .filter((t) => Number(t.chainId) === chainId)
-            .map((t) => t.address.toLowerCase())
-        ),
+      chainId,
       formType
     )
 
     const verifiedAddresses = verifiedTokensSets?.get(chainId)
+    const nativeAddress = nativeTokenAddresses?.get(chainId)?.toLowerCase()
 
-    const chainTokens: TokenWithVerified[] = [
+    const chainTokens: TokenWithFlags[] = [
       ...(dataTokens[chainId] ?? []),
       ...chainIncludedTokens,
     ]
 
-    const filtered: TokenWithVerified[] = []
+    const filtered: TokenWithFlags[] = []
     const seenAddresses = new Set<string>()
     for (const token of chainTokens) {
       const address = token.address.toLowerCase()
@@ -167,12 +236,18 @@ export const filterAllowedTokens = (
         continue
       }
       // Include and verified-allowlist tokens are explicitly set by the
-      // integrator, mark them as verified
-      if (
+      // integrator, mark them as verified. Flags are only ever set to true,
+      // so a token that earns none keeps its cached object.
+      const markVerified =
         !token.verified &&
         (includedAddresses.has(address) || verifiedAddresses?.has(address))
-      ) {
-        filtered.push({ ...token, verified: true })
+      const markNative = !!nativeAddress && nativeAddress === address
+      if (markVerified || markNative) {
+        filtered.push({
+          ...token,
+          ...(markVerified ? { verified: true } : {}),
+          ...(markNative ? { native: true } : {}),
+        })
       } else {
         filtered.push(token)
       }
@@ -192,3 +267,31 @@ export const getExecutionToToken = (route: RouteExtended): TokenAmount => ({
       route.toAmount
   ),
 })
+
+/** Capitalized name of the first provider that verified the token. */
+export const getTokenVerificationProvider = (
+  token: Pick<StaticToken, 'verificationStatusBreakdown'>
+): string | undefined => {
+  const provider = token.verificationStatusBreakdown?.find(
+    (entry) => entry.result === 'verified'
+  )?.provider
+  return provider
+    ? `${provider.charAt(0).toUpperCase()}${provider.slice(1)}`
+    : undefined
+}
+
+/**
+ * Hyperliquid declares Arbitrum USDC as its native token, Lighter declares
+ * Ethereum USDC. Neither is a gas token you hold there. A chain-local
+ * stablecoin gas token, as on Arc or Stable, is genuine and stays.
+ */
+const chainIdsWithoutNativeToken = new Set([ChainId.HPL, ChainId.LTR])
+
+export const getNativeTokenAddresses = (
+  chains?: ExtendedChain[]
+): Map<number, string> =>
+  new Map(
+    chains
+      ?.filter((chain) => !chainIdsWithoutNativeToken.has(chain.id))
+      .map((chain) => [chain.id, chain.nativeToken.address])
+  )