@ton/appkit 0.0.5-alpha.2 → 1.0.0-alpha.0

package/dist/esm/utils/predicate/is-number.js

@@ -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.
+ *
+ */
+export const isNumber = (value) => {
+    if (typeof value !== 'number') {
+        return false;
+    }
+    if (Number.isNaN(value)) {
+        return false;
+    }
+    return Number.isFinite(value);
+};

package/dist/esm/utils/predicate/is-string.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
-export declare function isString(value: unknown): value is string;
+export declare const isString: (value: unknown) => value is string;
 //# sourceMappingURL=is-string.d.ts.map

package/dist/esm/utils/predicate/is-string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-string.d.ts","sourceRoot":"","sources":["../../../../src/utils/predicate/is-string.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD"}
+{"version":3,"file":"is-string.d.ts","sourceRoot":"","sources":["../../../../src/utils/predicate/is-string.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAElD,CAAC"}

package/dist/esm/utils/predicate/is-string.js

@@ -5,6 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
-export function isString(value) {
+export const isString = (value) => {
     return typeof value === 'string';
-}
+};

package/docs/actions.md

@@ -202,7 +202,6 @@ if (!selectedWallet) {
 const balance = await getJettonBalance(appKit, {
     jettonAddress: 'EQDBE420tTQIkoWcZ9pEOTKY63WVmwyIl3hH6yWl0r_h51Tl',
     ownerAddress: selectedWallet.getAddress(),
-    jettonDecimals: 6,
 });
 console.log('Jetton Balance:', balance.toString());
 ```
@@ -246,7 +245,6 @@ const tx = await createTransferJettonTransaction(appKit, {
     recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
     amount: '100', // 100 USDT
     comment: 'Hello Jetton',
-    jettonDecimals: 6,
 });
 console.log('Transfer Transaction:', tx);
 ```
@@ -260,7 +258,6 @@ const result = await transferJetton(appKit, {
     jettonAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
     recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
     amount: '100',
-    jettonDecimals: 6,
 });
 console.log('Transfer Result:', result);
 ```
@@ -445,11 +442,12 @@ console.log('NFT Transfer Result:', result);
 Register a custom provider in AppKit (e.g., Swap or Streaming).
 
 ```ts
-const omnistonProvider = new OmnistonSwapProvider({
-    defaultSlippageBps: 100, // 1%
-});
-
-registerProvider(appKit, omnistonProvider);
+registerProvider(
+    appKit,
+    createOmnistonProvider({
+        defaultSlippageBps: 100, // 1%
+    }),
+);
 ```
 
 ## Signing
@@ -502,6 +500,45 @@ Get the `SwapManager` instance to interact with swap providers directly.
 const swapManager = getSwapManager(appKit);
 ```
 
+### `getSwapProvider`
+
+Get a specific swap provider by its ID.
+
+```ts
+const swapProvider = getSwapProvider(appKit, { id: 'stonfi' });
+```
+
+### `getSwapProviders`
+
+Get all registered swap providers. The returned array keeps a stable reference until the provider list changes.
+
+```ts
+const swapProviders = getSwapProviders(appKit);
+console.log(
+    'Registered providers:',
+    swapProviders.map((p) => p.providerId),
+);
+```
+
+### `setDefaultSwapProvider`
+
+Set the default swap provider. Subsequent quote and swap-transaction calls will use this provider when none is specified.
+
+```ts
+setDefaultSwapProvider(appKit, { providerId: 'stonfi' });
+```
+
+### `watchSwapProviders`
+
+Watch for new swap providers registration.
+
+```ts
+const unsubscribe = watchSwapProviders(appKit, {
+    onChange: () => console.log('Swap providers updated'),
+});
+unsubscribe();
+```
+
 ### `getSwapQuote`
 
 Get a swap quote from registered providers.
@@ -546,7 +583,7 @@ console.log('Available Staking Providers:', providers);
 
 ### `getStakingProviderInfo`
 
-Get information about a specific staking provider.
+Get dynamic information about a specific staking provider (e.g. APY, rate).
 
 ```ts
 const providerInfo = await getStakingProviderInfo(appKit, {
@@ -555,6 +592,17 @@ const providerInfo = await getStakingProviderInfo(appKit, {
 console.log('Provider Info:', providerInfo);
 ```
 
+### `getStakingProviderMetadata`
+
+Get static metadata about a specific staking provider.
+
+```ts
+const providerMetadata = getStakingProviderMetadata(appKit, {
+    providerId: 'tonstakers',
+});
+console.log('Provider Metadata:', providerMetadata);
+```
+
 ### `getStakingQuote`
 
 Get a staking or unstaking quote.

package/docs/swap.md

@@ -37,11 +37,11 @@ const appKit = new AppKit({
         },
     },
     providers: [
-        new OmnistonSwapProvider({
+        createOmnistonProvider({
             apiUrl: 'https://api.ston.fi',
             defaultSlippageBps: 100, // 1%
         }),
-        new DeDustSwapProvider({
+        createDeDustProvider({
             defaultSlippageBps: 100,
             referralAddress: 'EQ...', // Optional
         }),
@@ -67,8 +67,8 @@ const appKit = new AppKit({
 });
 
 // 2. Register swap providers
-registerProvider(appKit, new OmnistonSwapProvider({ defaultSlippageBps: 100 }));
-registerProvider(appKit, new DeDustSwapProvider({ defaultSlippageBps: 100 }));
+registerProvider(appKit, createOmnistonProvider({ defaultSlippageBps: 100 }));
+registerProvider(appKit, createDeDustProvider({ defaultSlippageBps: 100 }));
 ```
 
 ## Configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ton/appkit",
-  "version": "0.0.5-alpha.2",
+  "version": "1.0.0-alpha.0",
   "description": "",
   "repository": {
     "type": "git",
@@ -79,7 +79,8 @@
     }
   },
   "dependencies": {
-    "@ton/walletkit": "0.0.12-alpha.2"
+    "lru-cache": "11.3.5",
+    "@ton/walletkit": "1.0.0-alpha.0"
   },
   "peerDependencies": {
     "@tanstack/query-core": ">=5.0.0",
@@ -104,7 +105,7 @@
   "devDependencies": {
     "@tanstack/query-core": "5.99.0",
     "@ton/core": "0.63.1",
-    "@tonconnect/ui": "2.4.4",
+    "@tonconnect/ui": "2.5.0-alpha.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.4"
   },

package/src/actions/index.ts

@@ -115,7 +115,19 @@ export { signCell, type SignCellParameters, type SignCellReturnType } from './si
 
 // Swap
 export { getSwapManager, type GetSwapManagerReturnType } from './swap/get-swap-manager';
+export { getSwapProvider, type GetSwapProviderOptions, type GetSwapProviderReturnType } from './swap/get-swap-provider';
+export { getSwapProviders, type GetSwapProvidersReturnType } from './swap/get-swap-providers';
+export {
+    setDefaultSwapProvider,
+    type SetDefaultSwapProviderParameters,
+    type SetDefaultSwapProviderReturnType,
+} from './swap/set-default-swap-provider';
 export { getSwapQuote, type GetSwapQuoteOptions, type GetSwapQuoteReturnType } from './swap/get-swap-quote';
+export {
+    watchSwapProviders,
+    type WatchSwapProvidersParameters,
+    type WatchSwapProvidersReturnType,
+} from './swap/watch-swap-providers';
 export {
     buildSwapTransaction,
     type BuildSwapTransactionOptions,
@@ -125,6 +137,21 @@ export {
 // Staking
 export { getStakingManager, type GetStakingManagerReturnType } from './staking/get-staking-manager';
 export { getStakingProviders, type GetStakingProvidersReturnType } from './staking/get-staking-providers';
+export {
+    getStakingProvider,
+    type GetStakingProviderOptions,
+    type GetStakingProviderReturnType,
+} from './staking/get-staking-provider';
+export {
+    setDefaultStakingProvider,
+    type SetDefaultStakingProviderParameters,
+    type SetDefaultStakingProviderReturnType,
+} from './staking/set-default-staking-provider';
+export {
+    watchStakingProviders,
+    type WatchStakingProvidersParameters,
+    type WatchStakingProvidersReturnType,
+} from './staking/watch-staking-providers';
 export {
     getStakingQuote,
     type GetStakingQuoteOptions,
@@ -145,6 +172,11 @@ export {
     type GetStakingProviderInfoOptions,
     type GetStakingProviderInfoReturnType,
 } from './staking/get-staking-provider-info';
+export {
+    getStakingProviderMetadata,
+    type GetStakingProviderMetadataOptions,
+    type GetStakingProviderMetadataReturnType,
+} from './staking/get-staking-provider-metadata';
 
 // Transactions
 export {

package/src/actions/jettons/create-transfer-jetton-transaction.ts

@@ -17,12 +17,14 @@ import {
 import type { TransactionRequest } from '../../types/transaction';
 import type { AppKit } from '../../core/app-kit';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
+import { getJettonInfo } from './get-jetton-info';
+import { isNumber } from '../../utils';
 
 export interface CreateTransferJettonTransactionParameters {
     jettonAddress: string;
     recipientAddress: string;
     amount: string;
-    jettonDecimals: number;
+    jettonDecimals?: number;
     comment?: string;
 }
 
@@ -44,16 +46,30 @@ export const createTransferJettonTransaction = async (
     }
 
     // Get client from network manager
-    const client = appKit.networkManager.getClient(wallet.getNetwork());
+    const network = wallet.getNetwork();
+    const client = appKit.networkManager.getClient(network);
 
     // Get jetton wallet address
-    const jettonWalletAddress = await getJettonWalletAddressFromClient(client, jettonAddress, wallet.getAddress());
+    const ownerAddress = wallet.getAddress();
+    const jettonWalletAddress = await getJettonWalletAddressFromClient(client, jettonAddress, ownerAddress);
+
+    let decimals = jettonDecimals;
+
+    if (!isNumber(decimals)) {
+        const jettonInfo = await getJettonInfo(appKit, { address: jettonAddress, network });
+
+        if (!isNumber(jettonInfo?.decimals)) {
+            throw new Error(`Jetton decimals not found for address ${jettonAddress}`);
+        }
+
+        decimals = jettonInfo.decimals;
+    }
 
     // Create jetton transfer payload
     const jettonPayload = createJettonTransferPayload({
-        amount: parseUnits(amount, jettonDecimals),
+        amount: parseUnits(amount, decimals),
         destination: recipientAddress,
-        responseDestination: wallet.getAddress(),
+        responseDestination: ownerAddress,
         comment,
     });
 
@@ -62,6 +78,6 @@ export const createTransferJettonTransaction = async (
         targetAddress: jettonWalletAddress,
         amount: DEFAULT_JETTON_GAS_FEE,
         payload: jettonPayload,
-        fromAddress: wallet.getAddress(),
+        fromAddress: ownerAddress,
     });
 };

package/src/actions/jettons/get-jetton-balance.ts

@@ -11,13 +11,14 @@ import type { TokenAmount, UserFriendlyAddress } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
 import { getJettonWalletAddress } from './get-jetton-wallet-address';
-import { resolveNetwork } from '../../utils/network/resolve-network';
+import { getJettonInfo } from './get-jetton-info';
+import { isNumber, resolveNetwork } from '../../utils';
 import type { Network } from '../../types/network';
 
 export interface GetJettonBalanceOptions {
     jettonAddress: UserFriendlyAddress;
     ownerAddress: UserFriendlyAddress;
-    jettonDecimals: number;
+    jettonDecimals?: number;
     network?: Network;
 }
 
@@ -38,5 +39,11 @@ export const getJettonBalance = async (
     });
     const balance = await getJettonBalanceFromClient(client, jettonWalletAddress);
 
-    return formatUnits(balance, jettonDecimals);
+    if (isNumber(jettonDecimals)) {
+        return formatUnits(balance, jettonDecimals);
+    }
+
+    const jettonInfo = await getJettonInfo(appKit, { address: jettonAddress, network });
+
+    return formatUnits(balance, jettonInfo?.decimals ?? 0);
 };

package/src/actions/jettons/get-jetton-info.ts

@@ -9,8 +9,9 @@
 import type { JettonInfo } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
-import { resolveNetwork } from '../../utils/network/resolve-network';
+import { toBounceableAddress, resolveNetwork, isJettonInfo } from '../../utils';
 import type { Network } from '../../types/network';
+import { getCacheKey } from '../../core/cache';
 
 export interface GetJettonInfoOptions {
     address: string;
@@ -19,16 +20,23 @@ export interface GetJettonInfoOptions {
 
 export type GetJettonInfoReturnType = JettonInfo | null;
 
+const getJettonInfoCacheKey = getCacheKey('jetton-info');
+
 export const getJettonInfo = async (
     appKit: AppKit,
     options: GetJettonInfoOptions,
 ): Promise<GetJettonInfoReturnType> => {
-    const { address, network } = options;
+    const address = toBounceableAddress(options.address);
+    const network = resolveNetwork(appKit, options.network);
+    const cacheKey = getJettonInfoCacheKey(address, network.chainId);
+
+    const cached = await appKit.cache.get(cacheKey);
+    if (cached && isJettonInfo(cached)) return cached;
 
-    const client = appKit.networkManager.getClient(resolveNetwork(appKit, network));
+    const client = appKit.networkManager.getClient(network);
 
     const response = await client.jettonsByAddress({
-        address: address,
+        address,
         offset: 0,
         limit: 1,
     });
@@ -61,13 +69,17 @@ export const getJettonInfo = async (
         }
     }
 
-    return {
+    const result: GetJettonInfoReturnType = {
+        address,
         decimals,
-        address: jetton.jetton,
         name: tokenInfo?.name ?? '',
         symbol: tokenInfo?.symbol ?? '',
         description: tokenInfo?.description ?? '',
         image: tokenInfo?.image,
         uri: tokenInfo?.extra?.uri,
     };
+
+    await appKit.cache.set(cacheKey, result);
+
+    return result;
 };

package/src/actions/jettons/get-jetton-wallet-address.ts

@@ -7,11 +7,12 @@
  */
 
 import { getJettonWalletAddressFromClient } from '@ton/walletkit';
-import type { UserFriendlyAddress } from '@ton/walletkit';
 
+import type { UserFriendlyAddress } from '../../types/primitives';
 import type { AppKit } from '../../core/app-kit';
-import { resolveNetwork } from '../../utils/network/resolve-network';
 import type { Network } from '../../types/network';
+import { getCacheKey } from '../../core/cache';
+import { isFriendlyTonAddress, resolveNetwork, toBounceableAddress } from '../../utils';
 
 export interface GetJettonWalletAddressOptions {
     jettonAddress: UserFriendlyAddress;
@@ -21,13 +22,26 @@ export interface GetJettonWalletAddressOptions {
 
 export type GetJettonWalletAddressReturnType = UserFriendlyAddress;
 
+const getJettonWalletCacheKey = getCacheKey('jetton-wallet-address');
+
 export const getJettonWalletAddress = async (
     appKit: AppKit,
     options: GetJettonWalletAddressOptions,
 ): Promise<GetJettonWalletAddressReturnType> => {
-    const { jettonAddress, ownerAddress, network } = options;
+    const ownerAddress = toBounceableAddress(options.ownerAddress);
+    const jettonAddress = toBounceableAddress(options.jettonAddress);
+    const network = resolveNetwork(appKit, options.network);
+
+    const cacheKey = getJettonWalletCacheKey(network.chainId, ownerAddress, jettonAddress);
+
+    const cached = await appKit.cache.get(cacheKey);
+    if (cached && isFriendlyTonAddress(cached)) {
+        return cached;
+    }
 
-    const client = appKit.networkManager.getClient(resolveNetwork(appKit, network));
+    const client = appKit.networkManager.getClient(network);
+    const jettonWalletAddress = await getJettonWalletAddressFromClient(client, jettonAddress, ownerAddress);
+    await appKit.cache.set(cacheKey, jettonWalletAddress);
 
-    return getJettonWalletAddressFromClient(client, jettonAddress, ownerAddress);
+    return jettonWalletAddress;
 };

package/src/actions/nft/get-nft.ts

@@ -19,7 +19,7 @@ export interface GetNftOptions {
     network?: Network;
 }
 
-export type GetNftReturnType = NFT | null;
+export type GetNftReturnType = NFT | undefined;
 
 export const getNft = async (appKit: AppKit, options: GetNftOptions): Promise<GetNftReturnType> => {
     const { address, network } = options;

package/src/actions/staking/get-staking-provider-metadata.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { StakingProviderMetadata, Network } from '@ton/walletkit';
+
+import { resolveNetwork } from '../../utils';
+import type { AppKit } from '../../core/app-kit';
+
+export type GetStakingProviderMetadataOptions = {
+    network?: Network;
+    providerId?: string;
+};
+
+export type GetStakingProviderMetadataReturnType = StakingProviderMetadata;
+
+/**
+ * Get staking provider static metadata
+ */
+export const getStakingProviderMetadata = (
+    appKit: AppKit,
+    options: GetStakingProviderMetadataOptions = {},
+): GetStakingProviderMetadataReturnType => {
+    return appKit.stakingManager.getStakingProviderMetadata(
+        resolveNetwork(appKit, options.network),
+        options.providerId,
+    );
+};

package/src/actions/staking/get-staking-provider.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { StakingProviderInterface } from '@ton/walletkit';
+
+import type { AppKit } from '../../core/app-kit';
+
+export type GetStakingProviderOptions = {
+    /**
+     * Provider ID to get. If not provided, returns default provider.
+     */
+    id?: string;
+};
+
+export type GetStakingProviderReturnType = StakingProviderInterface;
+
+/**
+ * Get staking provider instance
+ */
+export const getStakingProvider = (
+    appKit: AppKit,
+    options: GetStakingProviderOptions = {},
+): GetStakingProviderReturnType => {
+    return appKit.stakingManager.getProvider(options.id);
+};

package/src/actions/staking/get-staking-providers.ts

@@ -6,13 +6,15 @@
  *
  */
 
+import type { StakingProviderInterface } from '@ton/walletkit';
+
 import type { AppKit } from '../../core/app-kit';
 
-export type GetStakingProvidersReturnType = string[];
+export type GetStakingProvidersReturnType = StakingProviderInterface[];
 
 /**
- * Get available staking provider IDs
+ * Get all registered staking providers.
  */
 export const getStakingProviders = (appKit: AppKit): GetStakingProvidersReturnType => {
-    return appKit.stakingManager.getRegisteredProviders();
+    return appKit.stakingManager.getProviders();
 };

package/src/actions/staking/set-default-staking-provider.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 { AppKit } from '../../core/app-kit';
+
+export interface SetDefaultStakingProviderParameters {
+    providerId: string;
+}
+
+export type SetDefaultStakingProviderReturnType = void;
+
+/**
+ * Set the default staking provider.
+ * Subsequent quote and stake-transaction calls will use this provider when none is specified.
+ */
+export const setDefaultStakingProvider = (
+    appKit: AppKit,
+    parameters: SetDefaultStakingProviderParameters,
+): SetDefaultStakingProviderReturnType => {
+    appKit.stakingManager.setDefaultProvider(parameters.providerId);
+};

package/src/actions/staking/watch-staking-providers.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { AppKit } from '../../core/app-kit';
+
+export interface WatchStakingProvidersParameters {
+    onChange: () => void;
+}
+
+export type WatchStakingProvidersReturnType = () => void;
+
+/**
+ * Watch for staking providers registration and default provider changes
+ */
+export const watchStakingProviders = (
+    appKit: AppKit,
+    parameters: WatchStakingProvidersParameters,
+): WatchStakingProvidersReturnType => {
+    const { onChange } = parameters;
+
+    const onEvent = (event: { payload: { type: string } }) => {
+        if (event.payload.type === 'staking') {
+            onChange();
+        }
+    };
+
+    const unsubscribeRegistered = appKit.emitter.on('provider:registered', onEvent);
+    const unsubscribeDefaultChanged = appKit.emitter.on('provider:default-changed', onEvent);
+
+    return () => {
+        unsubscribeRegistered();
+        unsubscribeDefaultChanged();
+    };
+};

package/src/actions/swap/get-swap-provider.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { SwapProviderInterface } from '@ton/walletkit';
+
+import type { AppKit } from '../../core/app-kit';
+
+export interface GetSwapProviderOptions {
+    id?: string;
+}
+
+export type GetSwapProviderReturnType = SwapProviderInterface;
+
+export const getSwapProvider = (appKit: AppKit, options: GetSwapProviderOptions = {}): GetSwapProviderReturnType => {
+    return appKit.swapManager.getProvider(options.id);
+};

package/src/actions/swap/get-swap-providers.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { SwapProviderInterface } from '@ton/walletkit';
+
+import type { AppKit } from '../../core/app-kit';
+
+export type GetSwapProvidersReturnType = SwapProviderInterface[];
+
+/**
+ * Get all registered swap providers.
+ */
+export const getSwapProviders = (appKit: AppKit): GetSwapProvidersReturnType => {
+    return appKit.swapManager.getProviders();
+};

package/src/actions/swap/get-swap-quote.ts

@@ -9,6 +9,7 @@
 import type { SwapQuote, SwapQuoteParams } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
+import { resolveNetwork } from '../../utils';
 
 export type GetSwapQuoteOptions<T = unknown> = SwapQuoteParams<T> & {
     providerId?: string;
@@ -23,5 +24,10 @@ export const getSwapQuote = async <T = unknown>(
     appKit: AppKit,
     options: GetSwapQuoteOptions<T>,
 ): GetSwapQuoteReturnType => {
-    return appKit.swapManager.getQuote(options, options.providerId);
+    const optionsWithNetwork = {
+        ...options,
+        network: resolveNetwork(appKit, options.network),
+    };
+
+    return appKit.swapManager.getQuote(optionsWithNetwork, options.providerId);
 };