@ton/appkit-react 0.0.6-alpha.2 → 1.0.0-alpha.0

package/src/features/transaction/components/transaction/send.tsx

@@ -7,12 +7,13 @@
  */
 
 import { useCallback, useMemo } from 'react';
-import type { FC, ReactNode, ComponentProps } from 'react';
+import type { FC, ReactNode } from 'react';
 import type { SendTransactionParameters, SendTransactionReturnType } from '@ton/appkit';
 
+import { useI18n } from '../../../settings/hooks/use-i18n';
 import { SendProvider, useSendContext } from '../transaction-provider';
-import { useI18n } from '../../../../hooks/use-i18n';
-import { Button } from '../../../../components/button';
+import { Button } from '../../../../components/ui/button';
+import type { ButtonProps } from '../../../../components/ui/button';
 
 export interface SendRenderProps {
     isLoading: boolean;
@@ -27,7 +28,7 @@ export type SendRequest =
     | (() => SendTransactionParameters)
     | (() => Promise<SendTransactionParameters>);
 
-export interface SendProps extends Omit<ComponentProps<'button'>, 'children' | 'onError'> {
+export interface SendProps extends Omit<ButtonProps, 'children' | 'onError'> {
     /** The transaction request parameters */
     request: SendRequest;
     /** Callback when an error occurs */
@@ -40,7 +41,7 @@ export interface SendProps extends Omit<ComponentProps<'button'>, 'children' | '
     children?: (props: SendRenderProps) => ReactNode;
 }
 
-interface SendContentProps extends Omit<ComponentProps<'button'>, 'children'> {
+interface SendContentProps extends Omit<ButtonProps, 'children'> {
     text?: ReactNode;
     children?: (props: SendRenderProps) => ReactNode;
 }

package/src/features/transaction/components/transaction-progress/transaction-progress-icons.tsx

@@ -10,6 +10,7 @@ import type { ComponentProps, FC } from 'react';
 import clsx from 'clsx';
 import type { TransactionStatus } from '@ton/appkit';
 
+import { FailedIcon, SpinnerIcon, SuccessIcon } from '../../../../components/ui/icons';
 import styles from './transaction-progress.module.css';
 
 export interface TransactionProgressIconsProps extends ComponentProps<'svg'> {
@@ -17,64 +18,19 @@ export interface TransactionProgressIconsProps extends ComponentProps<'svg'> {
     isError: boolean;
 }
 
-const SpinnerIcon: FC<ComponentProps<'svg'>> = ({ className }) => (
-    <svg
-        className={clsx(styles.spinner, className)}
-        xmlns="http://www.w3.org/2000/svg"
-        width="48"
-        height="48"
-        viewBox="0 0 24 24"
-        fill="none"
-        stroke="currentColor"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-    >
-        <path d="M21 12a9 9 0 1 1-6.219-8.56" />
-    </svg>
-);
+const STATUS_ICON_SIZE = 48;
 
-const SuccessIcon: FC<ComponentProps<'svg'>> = ({ className }) => (
-    <svg
-        className={clsx(styles.success, className)}
-        xmlns="http://www.w3.org/2000/svg"
-        width="48"
-        height="48"
-        viewBox="0 0 24 24"
-        fill="none"
-        stroke="currentColor"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-    >
-        <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14" />
-        <polyline points="22 4 12 14.01 9 11.01" />
-    </svg>
-);
+export const TransactionProgressIcon: FC<TransactionProgressIconsProps> = ({
+    status,
+    isError,
+    className,
+    ...props
+}) => {
+    if (status === 'completed')
+        return <SuccessIcon size={STATUS_ICON_SIZE} className={clsx(styles.success, className)} {...props} />;
 
-const FailedIcon: FC<ComponentProps<'svg'>> = ({ className }) => (
-    <svg
-        className={clsx(styles.failed, className)}
-        xmlns="http://www.w3.org/2000/svg"
-        width="48"
-        height="48"
-        viewBox="0 0 24 24"
-        fill="none"
-        stroke="currentColor"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-    >
-        <circle cx="12" cy="12" r="10" />
-        <line x1="15" y1="9" x2="9" y2="15" />
-        <line x1="9" y1="9" x2="15" y2="15" />
-    </svg>
-);
+    if (status === 'failed' || isError)
+        return <FailedIcon size={STATUS_ICON_SIZE} className={clsx(styles.failed, className)} {...props} />;
 
-export const TransactionProgressIcon: FC<TransactionProgressIconsProps> = ({ status, isError, ...props }) => {
-    if (status === 'completed') return <SuccessIcon {...props} />;
-
-    if (status === 'failed' || isError) return <FailedIcon {...props} />;
-
-    return <SpinnerIcon {...props} />;
+    return <SpinnerIcon size={STATUS_ICON_SIZE} className={clsx(styles.spinner, className)} {...props} />;
 };

package/src/features/transaction/components/transaction-progress/transaction-progress.tsx

@@ -10,7 +10,7 @@ import { useMemo } from 'react';
 import type { FC, ReactNode, ComponentProps } from 'react';
 import { clsx } from 'clsx';
 
-import { useI18n } from '../../../../hooks/use-i18n';
+import { useI18n } from '../../../settings/hooks/use-i18n';
 import { TransactionProgressProvider, useTransactionProgressContext } from './transaction-progress-provider';
 import type { TransactionProgressContextValue } from './transaction-progress-provider';
 import { TransactionProgressIcon } from './transaction-progress-icons';

package/src/features/transaction/hooks/use-send-transaction.ts

@@ -19,7 +19,7 @@ import { sendTransactionMutationOptions } from '@ton/appkit/queries';
 
 import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
 
 export type UseSendTransactionParameters<context = unknown> = SendTransactionOptions<context>;
 

package/src/features/transaction/hooks/use-transaction-status.ts

@@ -16,7 +16,8 @@ import { getTransactionStatusQueryOptions } from '@ton/appkit/queries';
 
 import { useQuery } from '../../../libs/query';
 import type { UseQueryReturnType } from '../../../libs/query';
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
+import { useNetwork } from '../../network';
 
 export type UseTransactionStatusParameters<selectData = GetTransactionStatusData> = GetTransactionStatusParameters &
     GetTransactionStatusQueryConfig<selectData>;
@@ -50,6 +51,9 @@ export const useTransactionStatus = <selectData = GetTransactionStatusData>(
     parameters: UseTransactionStatusParameters<selectData>,
 ): UseTransactionStatusReturnType<selectData> => {
     const appKit = useAppKit();
+    const walletNetwork = useNetwork();
 
-    return useQuery(getTransactionStatusQueryOptions(appKit, parameters));
+    return useQuery(
+        getTransactionStatusQueryOptions(appKit, { ...parameters, network: parameters.network ?? walletNetwork }),
+    );
 };

package/src/features/transaction/hooks/use-transfer-ton.ts

@@ -19,7 +19,7 @@ import { transferTonMutationOptions } from '@ton/appkit/queries';
 
 import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
 
 export type UseTransferTonParameters<context = unknown> = TransferTonOptions<context>;
 

package/src/features/transaction/hooks/use-watch-transactions-by-address.ts

@@ -10,7 +10,7 @@ import { useEffect } from 'react';
 import { watchTransactionsByAddress, hasStreamingProvider, resolveNetwork } from '@ton/appkit';
 import type { WatchTransactionsByAddressOptions, TransactionsUpdate } from '@ton/appkit';
 
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
 
 export type UseWatchTransactionsByAddressParameters = Partial<WatchTransactionsByAddressOptions>;
 

package/src/features/wallets/hooks/use-connect.ts

@@ -12,7 +12,7 @@ import type { ConnectData, ConnectErrorType, ConnectOptions, ConnectVariables }
 
 import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
 
 export type UseConnectParameters<context = unknown> = ConnectOptions<context>;
 

package/src/features/wallets/hooks/use-connected-wallets.ts

@@ -10,7 +10,7 @@ import { useSyncExternalStore, useCallback } from 'react';
 import { getConnectedWallets, watchConnectedWallets } from '@ton/appkit';
 import type { GetConnectedWalletsReturnType } from '@ton/appkit';
 
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
 
 export type UseConnectedWalletsReturnType = GetConnectedWalletsReturnType;
 

package/src/features/wallets/hooks/use-connector-by-id.ts

@@ -10,7 +10,7 @@ import { useSyncExternalStore, useCallback } from 'react';
 import { getConnectorById, watchConnectorById } from '@ton/appkit';
 import type { Connector } from '@ton/appkit';
 
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
 
 export const useConnectorById = (id: string): Connector | undefined => {
     const appKit = useAppKit();

package/src/features/wallets/hooks/use-connectors.ts

@@ -10,7 +10,7 @@ import { useSyncExternalStore, useCallback } from 'react';
 import { getConnectors, watchConnectors } from '@ton/appkit';
 import type { GetConnectorsReturnType } from '@ton/appkit';
 
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
 
 export type UseConnectorsReturnType = GetConnectorsReturnType;
 

package/src/features/wallets/hooks/use-disconnect.ts

@@ -14,7 +14,7 @@ import type { DisconnectData, DisconnectErrorType, DisconnectOptions, Disconnect
 
 import { useMutation } from '../../../libs/query';
 import type { UseMutationReturnType } from '../../../libs/query';
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
 
 export type UseDisconnectParameters<context = unknown> = DisconnectOptions<context>;
 

package/src/features/wallets/hooks/use-selected-wallet.ts

@@ -10,7 +10,7 @@ import { useSyncExternalStore, useCallback } from 'react';
 import { getSelectedWallet, watchSelectedWallet, setSelectedWalletId } from '@ton/appkit';
 import type { GetSelectedWalletReturnType } from '@ton/appkit';
 
-import { useAppKit } from '../../../hooks/use-app-kit';
+import { useAppKit } from '../../settings';
 
 export type UseSelectedWalletReturnType = readonly [GetSelectedWalletReturnType, (walletId: string | null) => void];
 

package/src/hooks/use-debounce-callback.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+import { debounce } from '@ton/appkit';
+import type { DebounceOptions } from '@ton/appkit';
+
+import { useUnmount } from './use-unmount';
+
+interface ControlFunctions {
+    cancel: () => void;
+    flush: () => void;
+    isPending: () => boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type DebouncedState<T extends (...args: any[]) => ReturnType<T>> = ((
+    ...args: Parameters<T>
+) => ReturnType<T> | void) &
+    ControlFunctions;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useDebounceCallback<T extends (...args: any[]) => ReturnType<T>>(
+    func: T,
+    delay = 500,
+    options?: DebounceOptions,
+): DebouncedState<T> {
+    const debouncedFunc = useRef<ReturnType<typeof debounce> | null>(null);
+
+    useUnmount(() => {
+        if (debouncedFunc.current) {
+            debouncedFunc.current.cancel();
+        }
+    });
+
+    const debounced = useMemo(() => {
+        const debouncedFuncInstance = debounce(func, delay, options);
+
+        const wrappedFunc: DebouncedState<T> = (...args: Parameters<T>) => {
+            return debouncedFuncInstance(...args);
+        };
+
+        wrappedFunc.cancel = () => {
+            debouncedFuncInstance.cancel();
+        };
+
+        wrappedFunc.isPending = () => {
+            return !!debouncedFunc.current;
+        };
+
+        wrappedFunc.flush = () => {
+            return debouncedFuncInstance.flush();
+        };
+
+        return wrappedFunc;
+    }, [func, delay, options]);
+
+    // Update the debounced function ref whenever func, wait, or options change
+    useEffect(() => {
+        debouncedFunc.current = debounce(func, delay, options);
+    }, [func, delay, options]);
+
+    return debounced;
+}

package/src/hooks/use-debounce-value.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { useRef, useState } from 'react';
+import type { DebounceOptions } from '@ton/appkit';
+
+import type { DebouncedState } from './use-debounce-callback';
+import { useDebounceCallback } from './use-debounce-callback';
+
+interface UseDebounceValueOptions<T> extends DebounceOptions {
+    equalityFn?: (left: T, right: T) => boolean;
+}
+
+export const useDebounceValue = <T>(
+    initialValue: T | (() => T),
+    delay: number,
+    options?: UseDebounceValueOptions<T>,
+): [T, DebouncedState<(value: T) => void>] => {
+    const eq = options?.equalityFn ?? ((left: T, right: T) => left === right);
+    const unwrappedInitialValue = initialValue instanceof Function ? initialValue() : initialValue;
+    const [debouncedValue, setDebouncedValue] = useState<T>(unwrappedInitialValue);
+    const previousValueRef = useRef<T | undefined>(unwrappedInitialValue);
+
+    const updateDebouncedValue = useDebounceCallback(setDebouncedValue, delay, options);
+
+    // Update the debounced value if the initial value changes
+    if (!eq(previousValueRef.current as T, unwrappedInitialValue)) {
+        updateDebouncedValue(unwrappedInitialValue);
+        previousValueRef.current = unwrappedInitialValue;
+    }
+
+    return [debouncedValue, updateDebouncedValue];
+};

package/src/hooks/use-unmount.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { useEffect, useRef } from 'react';
+
+export const useUnmount = (func: () => void) => {
+    const funcRef = useRef(func);
+    funcRef.current = func;
+
+    useEffect(() => () => funcRef.current(), []);
+};

package/src/index.ts

@@ -7,17 +7,27 @@
  */
 
 export { AppKitProvider } from './providers/app-kit-provider';
-export { useAppKit } from './hooks/use-app-kit';
-export { useAppKitTheme } from './hooks/use-app-kit-theme';
 export { I18nProvider } from './providers/i18n-provider';
-export { useI18n } from './hooks/use-i18n';
 
 export * from '@ton/appkit';
 
-export * from './components/block';
-export * from './components/button';
-export * from './components/circle-icon';
-export * from './components/ton-icon';
+export * from './components/ui/block';
+export * from './components/ui/info-block';
+export * from './components/ui/button';
+export * from './components/ui/logo';
+export * from './components/ui/modal';
+export * from './components/ui/skeleton';
+export * from './components/ui/input';
+export * from './components/shared/token-select-modal';
+export * from './components/ui/tabs';
+export * from './components/ui/centered-amount-input';
+export * from './components/shared/amount-presets';
+export * from './components/ui/collapsible';
+export * from './components/ui/select';
+export * from './components/shared/low-balance-modal';
+export * from './components/shared/settings-button';
+export * from './components/shared/option-switcher';
+export * from './components/ui/icons';
 
 export * from './features/balances';
 export * from './features/jettons';
@@ -25,6 +35,9 @@ export * from './features/network';
 export * from './features/nft';
 export * from './features/transaction';
 export * from './features/wallets';
+export * from './features/settings';
 export * from './features/swap';
 export * from './features/signing';
 export * from './features/staking';
+
+export * from './types/appkit-ui-token';

package/src/locales/en.ts

@@ -37,4 +37,86 @@ export default {
     nft: {
         onSale: 'On Sale',
     },
+
+    // Token select modal (shared between swap, etc.)
+    tokenSelect: {
+        emptyNoMatch: "We didn't find any tokens.",
+        emptyTryAddress: 'Try searching by address.',
+        emptyForNetwork: 'No tokens available for the selected network.',
+    },
+
+    // Shared DeFi error messages (rendered by `mapDefiError`)
+    defi: {
+        unsupportedNetwork: 'Network is not supported',
+        networkError: 'Network error, please try again',
+        providerNotFound: 'Provider not found',
+        noDefaultProvider: 'No provider configured',
+        invalidProvider: 'Invalid provider',
+        invalidParams: 'Invalid parameters',
+    },
+
+    // Swap
+    swap: {
+        pay: 'Pay',
+        receive: 'Receive',
+        max: 'MAX',
+        continue: 'Continue',
+        enterAmount: 'Enter an amount',
+        insufficientBalance: 'Insufficient balance',
+        tooManyDecimals: 'Too many decimal places',
+        quoteError: 'Unable to get a quote',
+        invalidQuote: 'Quote is invalid',
+        insufficientLiquidity: 'Insufficient liquidity for this swap',
+        quoteExpired: 'Quote expired, please try again',
+        buildTxFailed: "Couldn't build the swap transaction",
+        selectToken: 'Select Token',
+        searchToken: 'Search...',
+        settings: 'Swap settings',
+        slippage: 'Slippage',
+        slippageError: 'The maximum slippage tolerance cannot be more than 50%. The recommended range is 1%',
+        slippageWarning: 'High slippage tolerance increases the risk of an unfavorable trade',
+        provider: 'Provider',
+        save: 'Save',
+        minReceived: 'Min Received',
+    },
+
+    // Low balance modal (shared between swap, staking, etc.)
+    lowBalance: {
+        title: 'Not enough TON',
+        messageReduce:
+            'This operation requires ~{{ amount }} TON which exceeds your TON balance. Reduce the amount to continue.',
+        messageTopup:
+            'This operation needs ~{{ amount }} TON to cover network fees. Top up your TON balance to continue.',
+        change: 'Change amount',
+        cancel: 'Cancel',
+        close: 'Close',
+    },
+
+    // Staking
+    staking: {
+        stake: 'Stake',
+        unstake: 'Unstake',
+        continue: 'Stake',
+        insufficientBalance: 'Insufficient balance',
+        tooManyDecimals: 'Too many decimal places',
+        quoteError: 'Unable to get a quote',
+        invalidParams: 'Invalid staking parameters',
+        unsupportedOperation: 'Operation not supported by this provider',
+        youGet: 'You get',
+        currentApy: 'Current APY',
+        max: 'MAX',
+        exchangeRate: 'Exchange rate',
+        stakedBalance: 'Staked balance',
+        unstakeType: 'Unstake type',
+        maximumReward: 'Maximum reward',
+        instant: 'Instant',
+        instantLimit: 'Limit: {{ limit }}',
+        maximumRewardLimit: 'Next cycle',
+        whenAvailable: 'When available',
+        whenAvailableLimit: 'No limits',
+        yourBalance: 'Your balance',
+        provider: 'Provider',
+        settings: 'Staking settings',
+        save: 'Save',
+    },
 } as const;

package/src/storybook/fixtures/tokens.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { Network } from '@ton/appkit';
+
+import type { AppkitUIToken } from '../../types/appkit-ui-token';
+
+export const STORY_TOKENS: AppkitUIToken[] = [
+    {
+        symbol: 'TON',
+        name: 'Toncoin',
+        decimals: 9,
+        address: 'ton',
+        network: Network.mainnet(),
+        logo: 'https://asset.ston.fi/img/EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c/c8d21a3d93f9b574381e0a8d8f16d48b325dd8f54ce172f599c1e9d6c62f03f7',
+    },
+    {
+        symbol: 'USD₮',
+        name: 'Tether USD',
+        decimals: 6,
+        address: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
+        network: Network.mainnet(),
+        rate: '1',
+        logo: 'https://asset.ston.fi/img/EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs/1a87edfee9a28b05578853952e5effb8cc30af1e0fb90043aa2ce19dce490849',
+    },
+    {
+        symbol: 'STON',
+        name: 'STON',
+        decimals: 9,
+        address: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO',
+        network: Network.mainnet(),
+        logo: 'https://asset.ston.fi/img/EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO/7c9798ce1e64707fb4cb8f025d4060f66b386ed381b50498e3b88731cedeffe8',
+    },
+    {
+        symbol: 'XAUt0',
+        name: 'Tether Gold',
+        decimals: 6,
+        address: 'EQA1R_LuQCLHlMgOo1S4G7Y7W1cd0FrAkbA10Zq7rddKxi9k',
+        network: Network.mainnet(),
+        logo: 'https://asset.ston.fi/img/EQA1R_LuQCLHlMgOo1S4G7Y7W1cd0FrAkbA10Zq7rddKxi9k/4aaaa7c30d7811bced81ded6bc116dcc82a78c6aea53d6012fd586a5826963ad',
+    },
+    {
+        symbol: 'USDe',
+        name: 'Ethena USDe',
+        decimals: 6,
+        address: 'EQAIb6KmdfdDR7CN1GBqVJuP25iCnLKCvBlJ07Evuu2dzP5f',
+        network: Network.mainnet(),
+        rate: '1',
+        logo: 'https://asset.ston.fi/img/EQAIb6KmdfdDR7CN1GBqVJuP25iCnLKCvBlJ07Evuu2dzP5f/dbcc67993cd4aad4845a97a4a9722c6cb618123997c8112c29d4932b2739c4cd',
+    },
+    {
+        symbol: 'tsTON',
+        name: 'Tonstakers TON',
+        decimals: 9,
+        address: 'EQC98_qAmNEptUtPc7W6xdHh_ZHrBUFpw5Ft_IzNU20QAJav',
+        network: Network.mainnet(),
+        logo: 'https://asset.ston.fi/img/EQC98_qAmNEptUtPc7W6xdHh_ZHrBUFpw5Ft_IzNU20QAJav/38f530facb209e4696b8aef17af51df94d16bd879926c517b07d25841da287b7',
+    },
+    {
+        symbol: 'GEMSTON',
+        name: 'GEMSTON',
+        decimals: 9,
+        address: 'EQBX6K9aXVl3nXINCyPPL86C4ONVmQ8vK360u6dykFKXpHCa',
+        network: Network.mainnet(),
+        logo: 'https://asset.ston.fi/img/EQBX6K9aXVl3nXINCyPPL86C4ONVmQ8vK360u6dykFKXpHCa/c6ab1e58e3b9b58a7429d38b7feab731afae2f66dc301a6c42041fdf7e9d7c9c',
+    },
+    {
+        symbol: 'UTYA',
+        name: 'Utya',
+        decimals: 9,
+        address: 'EQBaCgUwOoc6gHCNln_oJzb0mVs79YG7wYoavh-o1ItaneLA',
+        network: Network.mainnet(),
+        logo: 'https://asset.ston.fi/img/EQBaCgUwOoc6gHCNln_oJzb0mVs79YG7wYoavh-o1ItaneLA/727e6cc971afdfa8ed9c698d0909eee9de344a0b6766ff5e4ddcc3323449d6f6',
+    },
+    {
+        symbol: 'WETH',
+        name: 'Wrapped Ether',
+        decimals: 18,
+        address: 'EQBTkLAhEteZCRgRe_xMs5ZE0bMrduYxKbyzGCpXXW8dRWOT',
+        network: Network.mainnet(),
+        logo: 'https://asset.ston.fi/img/EQBTkLAhEteZCRgRe_xMs5ZE0bMrduYxKbyzGCpXXW8dRWOT/6267787665c30c2500dbde048e2f8a6a6d7ec58633ea038723f4ce1fab337ccb',
+    },
+];

package/src/types/appkit-ui-token.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { Network } from '@ton/appkit';
+
+export interface AppkitUIToken {
+    /** Token symbol, e.g. "TON" */
+    symbol: string;
+    /** Full token name, e.g. "Toncoin" */
+    name: string;
+    /** Number of decimals for the token */
+    decimals: number;
+    /** Jetton contract address (use "ton" for TON) */
+    address: string;
+    /** Optional token logo */
+    logo?: string;
+    /** Optional exchange rate: 1 token = rate fiat units (used for fiat value display) */
+    rate?: string;
+    /** Network the token belongs to. */
+    network: Network;
+}

package/src/utils/map-defi-error.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { DefiError } from '@ton/appkit';
+
+/**
+ * Map a thrown error to an i18n key from the `defi.*` namespace.
+ * Returns `null` when the error isn't a {@link DefiError} or the code isn't recognised —
+ * callers should decide on their own fallback (usually a domain-specific key).
+ */
+export const mapDefiError = (error: unknown): string | null => {
+    if (!(error instanceof DefiError)) return null;
+
+    switch (error.code) {
+        case DefiError.UNSUPPORTED_NETWORK:
+            return 'defi.unsupportedNetwork';
+        case DefiError.NETWORK_ERROR:
+            return 'defi.networkError';
+        case DefiError.PROVIDER_NOT_FOUND:
+            return 'defi.providerNotFound';
+        case DefiError.NO_DEFAULT_PROVIDER:
+            return 'defi.noDefaultProvider';
+        case DefiError.INVALID_PROVIDER:
+            return 'defi.invalidProvider';
+        case DefiError.INVALID_PARAMS:
+            return 'defi.invalidParams';
+        default:
+            return null;
+    }
+};