@tomo-inc/transaction-builder-sdk 0.0.1-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @tomo-inc/transaction-builder-sdk
+
+## 0.0.1

package/README.md

@@ -0,0 +1,162 @@
+# @tomo-inc/transaction-builder-sdk
+
+Tomo Wallet Transaction Builder SDK is a comprehensive TypeScript library that provides developers with easy-to-use interfaces for integrating wallet functionalities, swap operations, and cross-chain transactions into their applications.
+
+## Features
+
+- **Multi-chain Support**: Works with EVM, Solana, TRON, and other major blockchain platforms
+- **Swap Operations**: Fetch quotes and build transactions for token swaps across DEXes
+- **Cross-chain Bridge**: Support for cross-chain token transfers
+- **Token Approvals**: Handle ERC20 token approvals and permit signatures
+- **Transaction Building**: Generate ready-to-sign transactions for various operations
+- **Chain Information**: Access detailed information about supported blockchain networks
+
+## Installation
+
+```bash
+npm install @tomo-inc/transaction-builder-sdk
+```
+
+## Quick Start
+
+First, initialize the SDK with your API credentials:
+
+```typescript
+import { Business } from "@tomo-inc/transaction-builder-sdk";
+
+const business = new Business({
+  config: {
+    API_KEY: "your-api-key",
+    API_SECRET: "your-api-secret",
+    SALT: "your-salt",
+  },
+  tomoStage: "prod", // or 'dev' for development
+});
+```
+
+## Chain Information
+
+Get information about supported chains for different operations:
+
+```typescript
+// Get all supported chains
+const allChains = business.getChains();
+
+// Get chains that support swap operations
+const swapChains = business.getSwapSupportChains();
+
+// Get chains that support bridge operations
+const bridgeChains = business.getBridgeSupportChains();
+```
+
+## Swap Operations
+
+Fetch quotes and build transactions for token swaps on the same chain:
+
+```typescript
+// Get swap quotes
+const quotes = await business.getSwapQuotes({
+  sender: "0x...", // User's wallet address
+  recipient: "0x...", // Recipient address (usually same as sender)
+  fromToken: {
+    address: "0x...", // Token contract address (use '' for native token)
+    chain: {
+      chainId: 1, // Ethereum mainnet
+      // ... other chain properties
+    },
+  },
+  toToken: {
+    address: "0x...", // Token contract address
+    chain: {
+      chainId: 1, // Must be same chain for swaps
+      // ... other chain properties
+    },
+  },
+  amount: "1000000000000000000", // Amount in token's smallest unit (e.g., wei for ETH)
+  slippage: 5, // 5% slippage tolerance
+});
+
+// Build swap transaction
+const swapTx = await business.swapBuilder(quotes[0], {
+  // Same parameters as getSwapQuotes
+});
+```
+
+## Cross-chain Bridge
+
+Support for cross-chain token transfers:
+
+```typescript
+// Get bridge quotes
+const bridgeQuotes = await business.getBridgeQuotes({
+  sender: "0x...", // User's wallet address on source chain
+  recipient: "0x...", // Recipient address on destination chain
+  fromToken: {
+    address: "0x...", // Token contract address on source chain
+    chain: {
+      chainId: 1, // Source chain (e.g., Ethereum)
+      // ... other chain properties
+    },
+  },
+  toToken: {
+    address: "0x...", // Token contract address on destination chain
+    chain: {
+      chainId: 56, // Destination chain (e.g., BSC)
+      // ... other chain properties
+    },
+  },
+  amount: "1000000000000000000", // Amount in token's smallest unit
+  slippage: 5, // 5% slippage tolerance
+});
+
+// Build bridge transaction
+const bridgeTx = await business.bridgeBuilder(bridgeQuotes[0], {
+  // Same parameters as getBridgeQuotes
+});
+```
+
+## Token Approvals
+
+Handle ERC20 token approvals and permit signatures:
+
+```typescript
+import { useSignTypedData } from "wagmi";
+const { signTypedDataAsync } = useSignTypedData();
+
+// Build approval transaction (for tokens that don't support permit)
+const approveTx = await business.getApproveBuilder(quote, quoteParams);
+
+// For tokens that support permit signatures (EIP-712)
+const permitTypeData = await business.evm.getPermitTypeData(quoteParams, quote);
+// Sign the permit data with wallet
+const signature = await signTypedDataAsync(permitTypeData);
+// Use the signature when building the transaction
+const swapTx = await business.swapBuilder(quote, quoteParams, {
+  signature,
+  permitTypeData,
+});
+```
+
+## API Reference
+
+### Core Methods
+
+- getSwapQuotes(params) - Fetch quotes for token swaps on the same chain
+- getBridgeQuotes(params) - Fetch quotes for cross-chain transfers
+- swapBuilder(quote, quoteParams, permitParams?) - Build swap transaction data
+- bridgeBuilder(quote, quoteParams, permitParams?) - Build bridge transaction data
+- getApproveBuilder(quote, quoteParams) - Build token approval transaction
+
+### EVM-specific Methods
+
+- evm.getPermitTypeData(quoteParams, quote) - Generate EIP-712 typed data for permit signatures
+
+### Chain Functions
+
+- getChains() - Returns all supported chains
+- getSwapSupportChains() - Returns chains that support swap operations
+- getBridgeSupportChains() - Returns chains that support bridge operations
+
+## License
+
+MIT

package/__tests__/business.test.ts

@@ -0,0 +1,316 @@
+// __tests__/business.integration.test.ts
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Business } from "../src";
+import { Chain, IPlatformType } from "../src/types/chain";
+import { TransactionQuoteParams, TransactionQuoteResult, TransactionToken } from "../src/types/swap";
+
+describe("Business Integration", () => {
+  let business: Business;
+  let mockEthChain: Chain;
+  let mockBscChain: Chain;
+  let mockEthToken: TransactionToken;
+  let mockBnbToken: TransactionToken;
+  let mockDaiToken: TransactionToken;
+  let mockBridgeQuoteParams: TransactionQuoteParams;
+  let mockSwapQuoteParams: TransactionQuoteParams;
+
+  beforeEach(() => {
+    business = new Business({
+      config: {
+        API_KEY: "j7sjxxdv5iaqnq69ull0t1rbcc3y6yx5",
+        API_SECRET: "7bk63t810l3czi7b6vvd6gpxlqsq8ype",
+        SALT: "Tomo@2025!@#",
+        CLIENT_ID: "",
+      },
+      tomoStage: "dev",
+    });
+
+    // Setup mock chains
+    mockEthChain = {
+      chainName: "Ethereum",
+      chainId: 1,
+      chainIndex: 100,
+      orderStatusSupport: true,
+      support: true,
+      isListed: true,
+      type: 1,
+      name: "ETH",
+      nativeCurrencyName: "ETH",
+      nativeCurrencySymbol: "ETH",
+      nativeCurrencyDecimals: 18,
+      platformType: IPlatformType.EVM,
+      icon: "https://example.com/eth.png",
+      supportSwap: true,
+      isTestnet: false,
+    };
+
+    mockBscChain = {
+      chainName: "BNB Smart Chain",
+      chainId: 56,
+      chainIndex: 5600,
+      orderStatusSupport: true,
+      support: true,
+      isListed: true,
+      type: 1,
+      name: "BSC",
+      nativeCurrencyName: "BNB",
+      nativeCurrencySymbol: "BNB",
+      nativeCurrencyDecimals: 18,
+      platformType: IPlatformType.EVM,
+      icon: "https://example.com/bnb.png",
+      supportSwap: true,
+      isTestnet: false,
+    };
+
+    // Setup mock tokens
+    mockEthToken = {
+      address: "",
+      chain: mockEthChain,
+    };
+
+    mockBnbToken = {
+      address: "",
+      chain: mockBscChain,
+    };
+
+    mockDaiToken = {
+      address: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+      chain: mockEthChain,
+    };
+
+    // Setup mock quote parameters
+    mockBridgeQuoteParams = {
+      sender: "0x1234567890123456789012345678901234567890",
+      recipient: "0x1234567890123456789012345678901234567890",
+      fromToken: mockEthToken,
+      toToken: mockBnbToken,
+      slippage: 0.5,
+      amount: "1000000000000000000", // 1 ETH
+    };
+
+    mockSwapQuoteParams = {
+      sender: "0x1234567890123456789012345678901234567890",
+      recipient: "0x1234567890123456789012345678901234567890",
+      fromToken: mockEthToken,
+      toToken: mockDaiToken,
+      slippage: 0.5,
+      amount: "1000000000000000000", // 1 ETH
+    };
+  });
+
+  describe("Bridge Flow", () => {
+    it("should get bridge quotes and build bridge transaction", async () => {
+      // Mock the getBridgeQuotes implementation to return a quote result
+      const mockBridgeQuotes: TransactionQuoteResult[] = [
+        {
+          quoteID: "bridge-quote-123",
+          amountIn: "1000000000000000000",
+          amountOut: "995000000000000000",
+          contract: "0xBridgeContractAddress",
+          amountOutMin: "990000000000000000",
+          gasNetWorkFee: "21000",
+          approveGasFee: "50000",
+          crossNetworkFee: {
+            fromChainNetworkFee: "0",
+            toChainNetworkFee: "0",
+            providerServiceFee: "0",
+          },
+          dexInfo: {
+            name: "MockBridge",
+            displayName: "Mock Bridge",
+            logo: "https://example.com/bridge.png",
+          },
+          fromToken: {
+            chainID: "1",
+            address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+            symbol: "ETH",
+            decimals: 18,
+          },
+          toToken: {
+            chainID: "56",
+            address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+            symbol: "BNB",
+            decimals: 18,
+          },
+          extended: {
+            requestID: "bridge-request-123",
+          },
+          routes: [
+            {
+              amountIn: "1000000000000000000",
+              amountOut: "995000000000000000",
+              paths: [
+                {
+                  dexProvider: "MockBridge",
+                  fromToken: {
+                    chainID: "1",
+                    address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+                    symbol: "ETH",
+                    decimals: 18,
+                  },
+                  toToken: {
+                    chainID: "56",
+                    address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+                    symbol: "BNB",
+                    decimals: 18,
+                  },
+                  amountIn: "1000000000000000000",
+                  amountOut: "995000000000000000",
+                },
+              ],
+            },
+          ],
+          estimatedGas: {
+            feeUSD: "1.50",
+            gasLimit: "21000",
+            baseFee: "30",
+            priorityFee: {
+              low: "1",
+              medium: "2",
+              high: "3",
+            },
+          },
+        },
+      ];
+
+      // Mock the bridgeBuilder implementation to return a transaction
+      const mockBridgeTransaction = {
+        chainId: "0x1",
+        data: "0xBridgeTransactionData",
+        gasLimit: "21000",
+        to: "0xBridgeContractAddress",
+        from: "0xUserAddress",
+        value: "0x0",
+        nonce: "0x1",
+      };
+
+      // Mock the implementations
+      vi.spyOn(business, "getBridgeQuotes").mockResolvedValue(mockBridgeQuotes);
+      vi.spyOn(business, "bridgeBuilder").mockResolvedValue(mockBridgeTransaction);
+
+      // Execute the flow: get quotes then build transaction
+      const quotes = await business.getBridgeQuotes(mockBridgeQuoteParams);
+      const transaction = await business.bridgeBuilder(quotes[0], mockBridgeQuoteParams);
+
+      // Verify the flow
+      expect(quotes).toHaveLength(1);
+      expect(quotes[0]).toHaveProperty("quoteID", "bridge-quote-123");
+      expect(quotes[0]).toHaveProperty("amountIn", "1000000000000000000");
+
+      expect(transaction).toHaveProperty("data", "0xBridgeTransactionData");
+      expect(transaction).toHaveProperty("to", "0xBridgeContractAddress");
+
+      // Verify both methods were called
+      expect(business.getBridgeQuotes).toHaveBeenCalledWith(mockBridgeQuoteParams);
+      expect(business.bridgeBuilder).toHaveBeenCalledWith(quotes[0], mockBridgeQuoteParams);
+    });
+  });
+
+  describe("Swap Flow", () => {
+    it("should get swap quotes and build swap transaction", async () => {
+      // Mock the getSwapQuotes implementation to return a quote result
+      const mockSwapQuotes: TransactionQuoteResult[] = [
+        {
+          quoteID: "swap-quote-123",
+          amountIn: "1000000000000000000",
+          amountOut: "3000000000000000000000",
+          contract: "0xSwapContractAddress",
+          amountOutMin: "2985000000000000000000",
+          gasNetWorkFee: "150000",
+          approveGasFee: "50000",
+          crossNetworkFee: {
+            fromChainNetworkFee: "0",
+            toChainNetworkFee: "0",
+            providerServiceFee: "0",
+          },
+          dexInfo: {
+            name: "Uniswap",
+            displayName: "Uniswap V3",
+            logo: "https://example.com/uniswap.png",
+          },
+          fromToken: {
+            chainID: "1",
+            address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+            symbol: "ETH",
+            decimals: 18,
+          },
+          toToken: {
+            chainID: "1",
+            address: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+            symbol: "DAI",
+            decimals: 18,
+          },
+          extended: {
+            requestID: "swap-request-123",
+          },
+          routes: [
+            {
+              amountIn: "1000000000000000000",
+              amountOut: "3000000000000000000000",
+              paths: [
+                {
+                  dexProvider: "Uniswap",
+                  fromToken: {
+                    chainID: "1",
+                    address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+                    symbol: "ETH",
+                    decimals: 18,
+                  },
+                  toToken: {
+                    chainID: "1",
+                    address: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+                    symbol: "DAI",
+                    decimals: 18,
+                  },
+                  amountIn: "1000000000000000000",
+                  amountOut: "3000000000000000000000",
+                },
+              ],
+            },
+          ],
+          estimatedGas: {
+            feeUSD: "5.25",
+            gasLimit: "150000",
+            baseFee: "35",
+            priorityFee: {
+              low: "1",
+              medium: "2",
+              high: "3",
+            },
+          },
+        },
+      ];
+
+      // Mock the swapBuilder implementation to return a transaction
+      const mockSwapTransaction = {
+        chainId: "0x1",
+        data: "0xSwapTransactionData",
+        gasLimit: "150000",
+        to: "0xSwapContractAddress",
+        from: "0xUserAddress",
+        value: "0x0",
+        nonce: "0x2",
+      };
+
+      // Mock the implementations
+      vi.spyOn(business, "getSwapQuotes").mockResolvedValue(mockSwapQuotes);
+      vi.spyOn(business, "swapBuilder").mockResolvedValue(mockSwapTransaction);
+
+      // Execute the flow: get quotes then build transaction
+      const quotes = await business.getSwapQuotes(mockSwapQuoteParams);
+      const transaction = await business.swapBuilder(quotes[0], mockSwapQuoteParams);
+
+      // Verify the flow
+      expect(quotes).toHaveLength(1);
+      expect(quotes[0]).toHaveProperty("quoteID", "swap-quote-123");
+      expect(quotes[0]).toHaveProperty("amountOut", "3000000000000000000000");
+
+      expect(transaction).toHaveProperty("data", "0xSwapTransactionData");
+      expect(transaction).toHaveProperty("gasLimit", "150000");
+
+      // Verify both methods were called
+      expect(business.getSwapQuotes).toHaveBeenCalledWith(mockSwapQuoteParams);
+      expect(business.swapBuilder).toHaveBeenCalledWith(quotes[0], mockSwapQuoteParams);
+    });
+  });
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@tomo-inc/transaction-builder-sdk",
+  "version": "0.0.1-alpha.0",
+  "author": "tomo.inc",
+  "private": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --treeshake",
+    "dev": "tsup src/index.ts --format esm,cjs --watch --dts",
+    "lint": "eslint src/**/*.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@tomo-inc/tomo-api": "workspace:*",
+    "axios": "^1.11.0",
+    "viem": "^2.0.0",
+    "tronweb": "^6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,115 @@
+import { utils } from "@tomo-inc/tomo-api";
+import axios from "axios";
+import { ApiConfig, Config, TomoStage } from "../types";
+import { TransactionQuoteResult } from "../types/swap";
+import stageConfig from "./../constant/stage.json";
+import { IRawApiToken, SwapApiRouterTxRequestV2, SwapApiRouterTxResponseV2, SwapApiRoutesRequestV2 } from "./types";
+
+const QUOTE_API = "/api/v2/quote";
+const BUILD_TRANSACTION_API = "/api/v2/buildTransaction";
+
+const createApiConfig = (stage: TomoStage) => {
+  const routerApiUrl = stageConfig[stage].routerApiUrl;
+  const marketApiUrl = stageConfig[stage].marketApiUrl;
+
+  return {
+    routeApi: axios.create({
+      baseURL: routerApiUrl,
+      headers: {
+        "X-App-Version": "20250427",
+      },
+    }),
+    marketApi: axios.create({
+      baseURL: marketApiUrl,
+    }),
+  };
+};
+
+export const reinitializeApi = (stage: TomoStage, apiConfig: Config | null) => {
+  const { routeApi, marketApi } = createApiConfig(stage);
+
+  if (!apiConfig) {
+    throw new Error("Config was not provided");
+  }
+
+  [routeApi, marketApi].forEach((api) => {
+    api.interceptors.request.use(
+      (config) => {
+        const params = {
+          method: config.method?.toLocaleUpperCase() || "",
+          url: config.url || "",
+          data: config.data,
+          apiKey: apiConfig.API_KEY,
+          apiSecret: apiConfig.API_SECRET,
+          salt: apiConfig.SALT,
+          // debug: true,
+        };
+        const { signature, timestamp } = utils.signature.generateSignature(params);
+
+        Object.assign(config.headers ?? {}, {
+          "client-id": apiConfig.CLIENT_ID,
+          "X-APP-Key": apiConfig.API_KEY,
+          "X-Signature": signature,
+          "X-Timestamp": timestamp,
+        });
+        return config;
+      },
+      (error) => {
+        if (error?.response?.status === 401) {
+          return Promise.reject(error);
+        }
+      },
+    );
+  });
+
+  return {
+    routeApi,
+    marketApi,
+  };
+};
+
+export const reinitializeApiMethods = (apiConfig: ApiConfig) => {
+  const { routeApi, marketApi } = apiConfig;
+  if (!marketApi || !routeApi) {
+    throw new Error("API instances are not initialized");
+  }
+
+  const getTokenInfo = async (queryParameters: {
+    content: string;
+    chainIndex?: number;
+  }): Promise<{
+    data: IRawApiToken[];
+  }> => {
+    const res = await marketApi.get(`/v1/market/token/search`, {
+      params: queryParameters,
+    });
+    return res.data;
+  };
+
+  const getSwapRoutesV2 = async (params: SwapApiRoutesRequestV2): Promise<TransactionQuoteResult[]> => {
+    const res = await routeApi.post(QUOTE_API, params);
+    const data = res?.data?.result?.data;
+    if (!data) {
+      const e = new Error("No route found");
+      e.cause = res?.data;
+      throw e;
+    }
+    return data;
+  };
+
+  const getSwapRoutesTxV2 = async (params: SwapApiRouterTxRequestV2): Promise<SwapApiRouterTxResponseV2> => {
+    const res = await routeApi.post(BUILD_TRANSACTION_API, params);
+    const data = res?.data?.result;
+    if (data?.transactions[0]?.gasInfo) {
+      return res.data.result;
+    } else {
+      throw new Error("Transaction failed");
+    }
+  };
+
+  return {
+    getTokenInfo,
+    getSwapRoutesV2,
+    getSwapRoutesTxV2,
+  };
+};