rainbow-swap-sdk 1.4.4 → 1.4.6

package/README.md

@@ -1,73 +1,88 @@
 # Rainbow Swap 🌈 SDK
 
-This SDK is designed for building applications on top of [Rainbow Swap 🌈](https://github.com/0xblackbot/rainbow-swap) - The Next Gen DEX Aggregator on the TON blockchain 💎.
+This SDK is designed for building applications on top of [Rainbow.ag](https://github.com/0xblackbot/rainbow-swap) - Swap Aggregator on TON blockchain 💎.
 
---- 
+---
 
-**We have plans to integrate commissions and share them with those who have integrated this SDK into their DApps.**
+**To receive your `partnerId`, set custom fees, and enjoy a 50% revenue share, contact us in our [Community Chat](https://t.me/rainbow_swap_chat).**
 
 ---
 
 [![npm version](https://badge.fury.io/js/rainbow-swap-sdk.svg)](https://badge.fury.io/js/rainbow-swap-sdk)
 ![NPM License](https://img.shields.io/npm/l/rainbow-swap-sdk)
 
-### Installation
+## Installation
+
+You can install the Rainbow Swap SDK using either npm or Yarn:
 
-To install the rainbow-swap-sdk, use the following npm command:
+**Using npm:**
 ```shell
 npm install rainbow-swap-sdk
 ```
 
-### Integrate your dApp
-
-```typescript
-import {
-    getAssetsRecord,
-    getBestRoute
-} from 'rainbow-swap-sdk';
-
-// 1. Load the list of available tokens
-const assetsRecord = await getAssetsRecord();
+**Using Yarn:**
+```shell
+yarn add rainbow-swap-sdk
+```
 
-...
+## Integrate Your dApp
 
-// 2. Load the best swap route & swap messages
-const params = {
-  inputAssetAmount: '1000000000', // 1 TON in nano
-  inputAssetAddress: 'ton', // TON
-  outputAssetAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs', // USDT jetton master address
-  maxDepth: 2, // optional number of maximum route length (should be in range from 1 to 3)
-  userAddress: 'UQDGGjjuwhikx8ZPJsrLbKXGq7mx26D8pK_l8GqBejzB52Pa', // optional user wallet address, if set - swapMessages will return
-  slippageTolerance: 5 // optional max slippage value (should be in range )
-};
+### Example: Swapping 1.35 TON to USDT
 
-const bestRouteResponse = await getBestRoute(params);
+```typescript
+import {getAssetsList, getBestRoute, toNano} from 'rainbow-swap-sdk';
 
-const bestRoute = bestRouteResponse.bestRoute; // Route of the best possible swap route
-const swapMessages = bestRouteResponse.swapMessages; // Array of messages that should be sent to @tonconnect
+// 1. Load the list of available tokens
+const assetsList = await getAssetsList({
+    userAssets: [] // Array of asset addresses the user holds; see AssetsListParams for more details.
+});
+
+// Retrieve specific assets by their address
+const inputAsset = assetsList.find(asset => asset.address === 'ton');
+const outputAsset = assetsList.find(asset => asset.address === 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs');
+
+// 2. Load the best swap route and swap messages
+const bestRouteResponse = await getBestRoute({
+    inputAssetAmount: toNano('1.35', inputAsset.decimals).toString(), // Convert 1.35 TON to nano format
+    inputAssetAddress: inputAsset.address,
+    outputAssetAddress: outputAsset.address,
+    senderAddress: 'UQDGGjjuwhikx8ZPJsrLbKXGq7mx26D8pK_l8GqBejzB52Pa', // Optional user wallet address; if set, swap messages will be returned
+    partnerId: 'demo-partner' // Optional unique identifier in our App Developer Partnership program
+});
+
+// 3. Sign and send messages to the blockchain to execute the swap.
+// This example uses the React UI client. For other frameworks, refer to https://docs.ton.org/develop/dapps/ton-connect/overview
+import {useTonConnectUI} from '@tonconnect/ui-react';
+
+const [tonConnectUI] = useTonConnectUI();
+
+const result = await tonConnectUI.sendTransaction({
+    validUntil: Math.floor(Date.now() / 1000) + 60, // 60 seconds from now
+    messages: bestRouteResponse.swapMessages
+});
 ```
 
-### Application status check
+## Application Status Check
 
-Additionally, you might want to check if everything is functioning correctly. For instance, you could temporarily disable swaps if block production on TON is disrupted due to the DOGS listing.
+You may want to check the status of your application to ensure everything is functioning correctly. For example, temporarily disable swaps if block production on TON is disrupted due to an external event like the DOGS listing.
 
 ```typescript
-import { getAppStatus } from 'rainbow-swap-sdk';
+import {getAppStatus} from 'rainbow-swap-sdk';
 
 const {
-    isSwapsEnabled, // true - if everything works fine
-    message // explanations why swaps are disabled
+    isSwapsEnabled, // true if everything is working fine
+    message // Explanation of why swaps are disabled, if applicable
 } = await getAppStatus();
 ```
 
-### Live example
+## Live Example
 
-For a live example of using the SDK, visit [Rainbow Swap 🌈 repository](https://github.com/0xblackbot/rainbow-swap).
+For a live example of using the SDK, visit the [Rainbow Swap 🌈 Repository](https://github.com/0xblackbot/rainbow-swap).
 
-### Contact
+## Contact
 
-For questions and suggestions, contact us at [Blackbot](https://blackbot.technology/).
+For questions and suggestions, visit [Community Chat](https://t.me/rainbow_swap_chat).
 
-### License
+## License
 
 This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

package/dist/index.d.ts

@@ -7,9 +7,11 @@ export type { RouteStep } from './interfaces/route-step.interface';
 export type { RouteStepWithCalculation } from './interfaces/route-step-with-calculation.interface';
 export type { AppStatus } from './types/app-status.type';
 export type { Asset } from './types/asset.type';
+export type { AssetsListParams } from './types/assets-list-patams.type';
 export type { AssetsRecord } from './types/assets-record.type';
 export type { BestRouteParams } from './types/best-route-params.type';
 export type { BestRouteResponse } from './types/best-route-response.type';
 export type { CalculatedSwapRoute } from './types/calculated-swap-route.type';
-export { getAssetsRecord, getBestRoute, getAppStatus } from './utils/api.utils';
+export { getAssetsRecord, getAssetsList, getBestRoute, getAppStatus } from './utils/api.utils';
+export { toNano, fromNano } from './utils/big-int.utils';
 export { getQueryId } from './utils/transfer-params.utils';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getQueryId = exports.getAppStatus = exports.getBestRoute = exports.getAssetsRecord = exports.SwapRouteType = exports.RouteDirectionEnum = exports.DexTypeEnum = exports.mapSwapRouteToRoute = void 0;
+exports.getQueryId = exports.fromNano = exports.toNano = exports.getAppStatus = exports.getBestRoute = exports.getAssetsList = exports.getAssetsRecord = exports.SwapRouteType = exports.RouteDirectionEnum = exports.DexTypeEnum = exports.mapSwapRouteToRoute = void 0;
 var calculated_swap_route_utils_1 = require("./dexes/shared/calculated-swap-route.utils");
 Object.defineProperty(exports, "mapSwapRouteToRoute", { enumerable: true, get: function () { return calculated_swap_route_utils_1.mapSwapRouteToRoute; } });
 var dex_type_enum_1 = require("./enums/dex-type.enum");
@@ -11,7 +11,11 @@ var swap_route_type_enum_1 = require("./enums/swap-route-type.enum");
 Object.defineProperty(exports, "SwapRouteType", { enumerable: true, get: function () { return swap_route_type_enum_1.SwapRouteType; } });
 var api_utils_1 = require("./utils/api.utils");
 Object.defineProperty(exports, "getAssetsRecord", { enumerable: true, get: function () { return api_utils_1.getAssetsRecord; } });
+Object.defineProperty(exports, "getAssetsList", { enumerable: true, get: function () { return api_utils_1.getAssetsList; } });
 Object.defineProperty(exports, "getBestRoute", { enumerable: true, get: function () { return api_utils_1.getBestRoute; } });
 Object.defineProperty(exports, "getAppStatus", { enumerable: true, get: function () { return api_utils_1.getAppStatus; } });
+var big_int_utils_1 = require("./utils/big-int.utils");
+Object.defineProperty(exports, "toNano", { enumerable: true, get: function () { return big_int_utils_1.toNano; } });
+Object.defineProperty(exports, "fromNano", { enumerable: true, get: function () { return big_int_utils_1.fromNano; } });
 var transfer_params_utils_1 = require("./utils/transfer-params.utils");
 Object.defineProperty(exports, "getQueryId", { enumerable: true, get: function () { return transfer_params_utils_1.getQueryId; } });

package/dist/types/assets-list-patams.type.d.ts

@@ -0,0 +1,25 @@
+export type AssetsListParams = {
+    /**
+     * A list of asset addresses that the user holds balances in.
+     *
+     * **Example values:**
+     * - `'ton'` for TON.
+     * - `'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs'` for USDT.
+     *
+     * **Default:** An empty array (`[]`), indicating no specified user assets.
+     */
+    userAssets?: string[];
+    /**
+     * A text string used to filter assets by symbol, name, or address.
+     *
+     * **Default:** An empty string (`''`), indicating no specific filter applied.
+     */
+    searchValue?: string;
+    /**
+     * The maximum number of assets (excluding user-owned) to return in the response.
+     * Acceptable values range from 10 to 200.
+     *
+     * **Default:** `100`
+     */
+    limit?: number;
+};

package/dist/types/assets-list-patams.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/best-route-display-data.type.d.ts

@@ -0,0 +1,11 @@
+export type BestRouteDisplayData = {
+    inputAssetAmount: number;
+    inputAssetUsdAmount: number;
+    outputAssetAmount: number;
+    outputAssetUsdAmount: number;
+    minOutputAssetAmount: number;
+    exchangeRate: number;
+    maxSlippage: number;
+    routingFeePercent: number;
+    priceImprovementPercent: number;
+};

package/dist/types/best-route-display-data.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/best-route-params.type.d.ts

@@ -1,8 +1,60 @@
 export type BestRouteParams = {
+    /**
+     * The amount of the input asset that the user wants to send, specified in nano units.
+     * This should be a string representation of a bigint value.
+     *
+     * **Example:** `'1350000000'` (represents 1.35 TON in nano).
+     */
     inputAssetAmount: string;
+    /**
+     * The address or identifier of the asset that the user wants to send.
+     *
+     * **Example:**
+     * - `'ton'` for TON.
+     * - `'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs'` for USDT.
+     */
     inputAssetAddress: string;
+    /**
+     * The address or identifier of the asset that the user wants to receive.
+     *
+     * **Example:**
+     * - `'ton'` for TON.
+     * - `'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs'` for USDT.
+     */
     outputAssetAddress: string;
+    /**
+     * (Optional) The maximum length of the route.
+     * Should be a number between **1 and 3** (inclusive).
+     *
+     * **Default:** `2`
+     */
     maxDepth?: number;
+    /**
+     * (Optional) The wallet address of the user.
+     * If not provided, the `swapMessages` will return an empty array (`[]`).
+     */
     senderAddress?: string;
+    /**
+     * (Optional) The percentage setting for slippage tolerance.
+     * Should be a number between **0 and 100** (inclusive).
+     *
+     * **Example:** `1.5` for 1.5% slippage tolerance.
+     *
+     * **Default:** `5`
+     */
     maxSlippage?: number;
+    /**
+     * (Optional) The referral address of a user.
+     * Refer a new user and earn a share of their trading fees.
+     *
+     * For more details, visit the **Rewards Center** at [rainbow.ag](https://rainbow.ag).
+     */
+    referralAddress?: string;
+    /**
+     * (Optional) A unique identifier in our App Developer Partnership program.
+     * Integrate our SDK to enable in-app swaps, set custom fees, and enjoy a 50% revenue share.
+     *
+     * For more details, contact us at **Community Chat**: [https://t.me/rainbow_swap_chat](https://t.me/rainbow_swap_chat).
+     */
+    partnerId?: string;
 };

package/dist/types/best-route-response.type.d.ts

@@ -1,17 +1,22 @@
+import { BestRouteDisplayData } from './best-route-display-data.type';
 import { CalculatedSwapRoute } from './calculated-swap-route.type';
 import { Message } from '../interfaces/message.interface';
 export type BestRouteResponse = {
-    bestRoute: CalculatedSwapRoute[];
-    displayData: {
-        inputAssetAmount: number;
-        inputAssetUsdAmount: number;
-        outputAssetAmount: number;
-        outputAssetUsdAmount: number;
-        minOutputAssetAmount: number;
-        exchangeRate: number;
-        maxSlippage: number;
-        routingFeePercent: number;
-        priceImprovementPercent: number;
-    };
+    /**
+     * A user-friendly representation of the best route details.
+     */
+    displayData: BestRouteDisplayData;
+    /**
+     * An array of messages that should be signed and sent to the blockchain to execute the swap.
+     *
+     * - For TON dApps, it is recommended to use `@tonconnect/sdk`.
+     * - If the `senderAddress` parameter in the request was not set, an empty array (`[]`) will be returned.
+     * - An empty array in other cases indicates that no route was found between the input asset and the output asset.
+     */
     swapMessages: Message[];
+    /**
+     * Detailed information about the most efficient routes for swapping the user's input asset,
+     * taking into account swap distribution and gas costs.
+     */
+    bestRoute: CalculatedSwapRoute[];
 };

package/dist/utils/api.utils.d.ts

@@ -1,7 +1,10 @@
 import { AppStatus } from '../types/app-status.type';
+import { Asset } from '../types/asset.type';
+import { AssetsListParams } from '../types/assets-list-patams.type';
 import { AssetsRecord } from '../types/assets-record.type';
 import { BestRouteParams } from '../types/best-route-params.type';
 import { BestRouteResponse } from '../types/best-route-response.type';
 export declare const getAssetsRecord: () => Promise<AssetsRecord>;
+export declare const getAssetsList: (params: AssetsListParams) => Promise<Asset[]>;
 export declare const getBestRoute: (params: BestRouteParams) => Promise<BestRouteResponse>;
 export declare const getAppStatus: () => Promise<AppStatus>;

package/dist/utils/api.utils.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAppStatus = exports.getBestRoute = exports.getAssetsRecord = void 0;
+exports.getAppStatus = exports.getBestRoute = exports.getAssetsList = exports.getAssetsRecord = void 0;
 const globals_1 = require("../globals");
 const getAssetsRecord = () => globals_1.API.get('/assets-record').then(response => response.data);
 exports.getAssetsRecord = getAssetsRecord;
+const getAssetsList = (params) => globals_1.API.post('/assets-list', params).then(response => response.data);
+exports.getAssetsList = getAssetsList;
 const getBestRoute = (params) => globals_1.API.get('/best-route', { params }).then(response => response.data);
 exports.getBestRoute = getBestRoute;
 const getAppStatus = () => globals_1.API.get('/app-status').then(response => response.data);

package/dist/utils/big-int.utils.d.ts

@@ -0,0 +1,2 @@
+export declare const toNano: (src: string, decimals: number) => bigint;
+export declare const fromNano: (value: bigint, decimals: number) => string;

package/dist/utils/big-int.utils.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromNano = exports.toNano = void 0;
+const toNano = (src, decimals) => {
+    const precision = 10n ** BigInt(decimals);
+    // Check sign
+    let neg = false;
+    while (src.startsWith('-')) {
+        neg = !neg;
+        src = src.slice(1);
+    }
+    // Split string
+    if (src === '.') {
+        throw Error('Invalid number');
+    }
+    const parts = src.split('.');
+    if (parts.length > 2) {
+        throw Error('Invalid number');
+    }
+    // Prepare parts
+    let whole = parts[0];
+    let frac = parts[1];
+    if (!whole) {
+        whole = '0';
+    }
+    if (!frac) {
+        frac = '';
+    }
+    if (frac.length > decimals) {
+        throw Error('Invalid number');
+    }
+    while (frac.length < decimals) {
+        frac += '0';
+    }
+    // Convert
+    let r = BigInt(whole) * precision + BigInt(frac);
+    if (neg) {
+        r = -r;
+    }
+    return r;
+};
+exports.toNano = toNano;
+const fromNano = (value, decimals) => String(Number(value) / 10 ** decimals);
+exports.fromNano = fromNano;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rainbow-swap-sdk",
-  "version": "1.4.4",
-  "description": "SDK for building applications on top of Rainbow Swap - Swap Aggregator on TON 💎.",
+  "version": "1.4.6",
+  "description": "SDK for building applications on top of Rainbow.ag - Swap Aggregator on TON 💎.",
   "repository": "https://github.com/0xblackbot/rainbow-swap-sdk.git",
   "license": "Apache-2.0",
   "main": "dist/index.js",