@rhea-finance/cross-chain-aggregation-dex 0.1.5 → 0.1.7

package/README.md

@@ -1,23 +1,27 @@
 # @rhea-finance/cross-chain-aggregation-dex
 
-A powerful TypeScript SDK for cross-chain DEX aggregation and routing on NEAR blockchain. This SDK provides intelligent routing across multiple DEXs, automatic token registration, pre-swap handling for non-bluechip tokens, and seamless integration with NearIntents bridge protocol for cross-chain token swaps.
+A powerful TypeScript SDK for cross-chain DEX aggregation and routing on NEAR and EVM blockchains. This SDK provides intelligent routing across multiple DEXs, automatic token registration, pre-swap handling for non-bluechip tokens, and seamless integration with NearIntents bridge protocol for cross-chain token swaps.
 
 ## Overview
 
-This SDK offers two router implementations for different use cases:
+This SDK offers three router implementations for different use cases:
 
-- **NearSmartRouter (V1)**: Simple routing via FindPath API and REF Finance execution. Best for straightforward swaps without complex recipient handling.
-- **AggregateDexRouter (V2)**: Advanced multi-DEX aggregation with automatic registration handling. Supports complex scenarios with multiple recipients and automatic token registration.
+- **NearSmartRouter (V1)**: Simple routing via FindPath API and REF Finance execution. Best for straightforward swaps on NEAR without complex recipient handling.
+- **AggregateDexRouter (V2)**: Advanced multi-DEX aggregation with automatic registration handling on NEAR. Supports complex scenarios with multiple recipients and automatic token registration.
+- **BitgetRouter (EVM)**: EVM chain router implementation using Bitget DEX aggregator. Supports Ethereum, BSC, Polygon, Base, and other EVM-compatible chains with automatic balance checking, token approval, and gas optimization.
 
-Both routers support optimal path finding, slippage protection, and can be combined with NearIntents for cross-chain functionality.
+All routers support optimal path finding, slippage protection, and can be combined with NearIntents for cross-chain functionality.
 
 ## Features
 
-- 🔄 **DEX Aggregation Routing**: Automatically finds optimal swap paths across multiple DEXs on NEAR
-- 🚀 **Dual Router Support**: Two router implementations (V1 Simple Router & V2 Aggregate Router) for different use cases
+- 🔄 **DEX Aggregation Routing**: Automatically finds optimal swap paths across multiple DEXs on NEAR and EVM chains
+- 🚀 **Multi-Router Support**: Three router implementations (V1 Simple Router, V2 Aggregate Router, and EVM Router) for different use cases
+- ⛓️ **Multi-Chain Support**: Native support for NEAR blockchain and EVM-compatible chains (Ethereum, BSC, Polygon, Base, etc.)
 - 🌉 **Cross-chain Support**: Seamless integration with NearIntents bridge protocol for cross-chain swaps
-- 🔀 **Pre-swap Handling**: Automatically converts non-bluechip tokens to bluechip tokens (USDT/USDC/wNEAR) when needed
-- 🔐 **Auto Registration**: Automatically handles token storage registration for users and contracts
+- 🔀 **Pre-swap Handling**: Automatically converts non-bluechip tokens to bluechip tokens (USDT/USDC/wNEAR/ETH) when needed
+- 🔐 **Auto Registration**: Automatically handles token storage registration for users and contracts (NEAR)
+- 💰 **Auto Approval**: Automatically handles ERC20 token approval with retry mechanism (EVM)
+- ⛽ **Gas Optimization**: Intelligent gas estimation with EIP-1559 support and fallback mechanisms (EVM)
 - 📊 **Multi-Router Comparison**: Compare quotes from multiple routers and select the best one
 - 📦 **Type Safety**: Complete TypeScript type definitions with full IntelliSense support
 - 🔌 **Adapter Pattern**: Flexible adapter interfaces for easy integration with any backend or wallet
@@ -46,6 +50,8 @@ import {
   SwapMultiDexPathAdapter,
   IntentsQuotationAdapter,
   NearChainAdapter,
+  EvmChainAdapter,
+  BitgetAdapter,
   ConfigAdapter,
 } from "@rhea-finance/cross-chain-aggregation-dex";
 
@@ -109,6 +115,65 @@ const nearChainAdapter: NearChainAdapter = {
   },
 };
 
+// Bitget DEX aggregator adapter (for BitgetRouter EVM)
+const bitgetAdapter: BitgetAdapter = {
+  async quote(params) {
+    const response = await fetch("https://api.bitget.com/v1/mix/market/swap-best-book", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        chainId: params.chainId,
+        tokenIn: params.tokenIn,
+        tokenOut: params.tokenOut,
+        amountIn: params.amountIn,
+        slippage: params.slippage,
+        userAddress: params.userAddress,
+      }),
+    });
+    return response.json();
+  },
+  async swap(params) {
+    const response = await fetch("https://api.bitget.com/v1/mix/market/swap", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        chainId: params.chainId,
+        tokenIn: params.tokenIn,
+        tokenOut: params.tokenOut,
+        amountIn: params.amountIn,
+        slippage: params.slippage,
+        userAddress: params.userAddress,
+        market: params.market,
+      }),
+    });
+    return response.json();
+  },
+};
+
+// EVM chain interaction adapter (for BitgetRouter)
+const evmChainAdapter: EvmChainAdapter = {
+  async sendTransaction(params) {
+    // Use your EVM wallet or provider to send transaction
+    // Return { status: "success", txHash: "..." } or { status: "failed", message: "..." }
+  },
+  async getBalance(params) {
+    // Optional: Get token balance (for ERC20) or native balance (if tokenAddress is undefined)
+    // Return balance as string
+  },
+  async getAllowance(params) {
+    // Optional: Get ERC20 token allowance
+    // Return allowance as string
+  },
+  async approve(params) {
+    // Optional: Approve ERC20 token spending
+    // Return { status: "success", txHash: "..." } or { status: "failed", message: "..." }
+  },
+  async getSigner() {
+    // Optional: Get ethers signer for gas estimation
+    // Return ethers.Signer instance
+  },
+};
+
 // Configuration adapter
 const configAdapter: ConfigAdapter = {
   getRefExchangeId: () => "v2.ref-finance.near",
@@ -116,6 +181,7 @@ const configAdapter: ConfigAdapter = {
   getFindPathUrl: () => "https://smartrouter.ref.finance",
   getTokenStorageDepositRead: () => "1250000000000000000000",
   getAggregateDexContractId: () => "aggregate-dex-contract.near", // For V2 Router
+  getEvmNativeWrappedTokenAddress: () => "0x4200000000000000000000000000000000000006", // Optional: WETH address for EVM chains
 };
 ```
 
@@ -145,6 +211,18 @@ const v2Router = new AggregateDexRouter({
 });
 ```
 
+#### Using BitgetRouter (EVM)
+
+```typescript
+import { BitgetRouter } from "@rhea-finance/cross-chain-aggregation-dex";
+
+const evmRouter = new BitgetRouter({
+  bitgetAdapter,
+  evmChainAdapter,
+  chainId: 1, // Ethereum mainnet (1), BSC (56), Polygon (137), Base (8453), etc.
+});
+```
+
 ### 3. Get Quote
 
 #### Using NearSmartRouter (V1)
@@ -152,6 +230,7 @@ const v2Router = new AggregateDexRouter({
 ```typescript
 import { TokenInfo } from "@rhea-finance/cross-chain-aggregation-dex";
 
+// NEAR tokens
 const tokenIn: TokenInfo = {
   address: "token-a.near",
   symbol: "TOKENA",
@@ -166,6 +245,21 @@ const tokenOut: TokenInfo = {
   chain: "near",
 };
 
+// EVM tokens (for BitgetRouter)
+const evmTokenIn: TokenInfo = {
+  address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum
+  symbol: "USDC",
+  decimals: 6,
+  chain: "evm",
+};
+
+const evmTokenOut: TokenInfo = {
+  address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", // USDT on Ethereum
+  symbol: "USDT",
+  decimals: 6,
+  chain: "evm",
+};
+
 // V1 Router - Simple quote (no recipient required)
 const quote = await v1Router.quote({
   tokenIn,
@@ -209,6 +303,29 @@ if (quote.success) {
 }
 ```
 
+#### Using BitgetRouter (EVM)
+
+```typescript
+// EVM Router - Requires sender and recipient
+const quote = await evmRouter.quote({
+  tokenIn: evmTokenIn,
+  tokenOut: evmTokenOut,
+  amountIn: "1000000", // 1 USDC (6 decimals)
+  slippage: 50, // 0.5% (50 basis points)
+  swapType: "EXACT_INPUT",
+  sender: "0x...", // Required for EVM Router
+  recipient: "0x...", // Required for EVM Router (can be same as sender)
+});
+
+if (quote.success) {
+  console.log("Amount out:", quote.amountOut);
+  console.log("Min amount out:", quote.minAmountOut);
+  console.log("Router message:", quote.routerMsg);
+} else {
+  console.error("Quote failed:", quote.error);
+}
+```
+
 ### 4. Execute Swap
 
 #### Using NearSmartRouter (V1)
@@ -249,6 +366,27 @@ if (result.success) {
 
 > **Note**: V2 Router automatically fetches a fresh quote using `receiveUser` (depositAddress) during `executeSwap` to ensure correct `routerMsg` and `signature`. You don't need to call `finalizeQuote` manually.
 
+#### Using BitgetRouter (EVM)
+
+```typescript
+// EVM Router - Requires sender and receiveUser
+const result = await evmRouter.executeSwap({
+  quote,
+  sender: "0x...", // Required for EVM Router
+  receiveUser: "0x...", // Required for EVM Router (usually depositAddress)
+  recipient: "0x...", // Optional, kept for compatibility
+});
+
+if (result.success) {
+  console.log("Transaction hash:", result.txHash);
+  console.log("Transaction hashes:", result.txHashArray);
+} else {
+  console.error("Swap failed:", result.error);
+}
+```
+
+> **Note**: EVM Router automatically checks token balance and approval before executing. If approval is insufficient, it will automatically approve the token with retry mechanism.
+
 ### 5. Complete Quote (DEX Aggregator + NearIntents)
 
 The `completeQuote` function integrates DEX aggregation with NearIntents bridge for cross-chain swaps. It automatically handles pre-swaps when needed:
@@ -256,6 +394,7 @@ The `completeQuote` function integrates DEX aggregation with NearIntents bridge
 ```typescript
 import { completeQuote } from "@rhea-finance/cross-chain-aggregation-dex";
 
+// For NEAR chains
 const bluechipTokens = {
   USDT: {
     address: "usdt.tether-token.near",
@@ -277,7 +416,29 @@ const bluechipTokens = {
   },
 };
 
-// Using single router
+// For EVM chains
+const evmBluechipTokens = {
+  USDT: {
+    address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", // USDT on Ethereum
+    symbol: "USDT",
+    decimals: 6,
+    assetId: "evm:0xdAC17F958D2ee523a2206206994597C13D831ec7",
+  },
+  USDC: {
+    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum
+    symbol: "USDC",
+    decimals: 6,
+    assetId: "evm:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  },
+  ETH: {
+    address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH on Ethereum
+    symbol: "WETH",
+    decimals: 18,
+    assetId: "evm:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+  },
+};
+
+// Using single router (NEAR chain)
 const completeQuoteResult = await completeQuote(
   {
     sourceToken: tokenIn,
@@ -298,6 +459,28 @@ const completeQuoteResult = await completeQuote(
   }
 );
 
+// Using EVM router
+const evmCompleteQuoteResult = await completeQuote(
+  {
+    sourceToken: evmTokenIn,
+    targetToken: tokenOut, // Target token on destination chain
+    sourceChain: "ethereum", // or "evm", "bsc", "polygon", "base", etc.
+    targetChain: "near",
+    amountIn: "1000000", // 1 USDC (6 decimals)
+    slippage: 50,
+    recipient: "user.near", // Target chain address
+    refundTo: "0x...", // EVM address
+    evmChainId: 1, // Optional: explicitly specify EVM chain ID (1 for Ethereum)
+  },
+  {
+    intentsQuotationAdapter,
+    dexRouter: evmRouter,
+    bluechipTokens: evmBluechipTokens, // Use EVM bluechip tokens
+    configAdapter,
+    currentUserAddress: "0x...", // Required for EVM Router
+  }
+);
+
 // Using multiple routers (compares and selects best quote)
 const completeQuoteResult = await completeQuote(
   {
@@ -455,6 +638,66 @@ Returns router capabilities:
 
 Returns the supported chain identifier.
 
+### BitgetRouter (EVM)
+
+EVM chain router implementation using Bitget DEX aggregator. Supports automatic balance checking, token approval, and gas optimization.
+
+#### `quote(params: RecipientQuoteParams): Promise<QuoteResult>`
+
+Get quote method that requires sender and recipient parameters.
+
+**Parameters:**
+- `tokenIn`: Input token information (EVM address)
+- `tokenOut`: Output token information (EVM address)
+- `amountIn`: Input amount (string format, considering decimals)
+- `slippage`: Slippage tolerance (prefer bps, 50 = 0.5%)
+- `swapType`: Swap type ("EXACT_INPUT" | "EXACT_OUTPUT")
+- `sender`: Sender address (required, EVM address)
+- `recipient`: Recipient address (required, EVM address, can be same as sender)
+
+**Returns:**
+- `success`: Whether successful
+- `amountOut`: Output amount
+- `minAmountOut`: Minimum output amount (considering slippage)
+- `routerMsg`: Router message for execution (required for executeSwap)
+- `error`: Error message (if failed)
+
+#### `executeSwap(params: RecipientExecuteParams): Promise<ExecuteResult>`
+
+Execute swap method. Automatically:
+- Checks token balance (for ERC20) or native balance (for native tokens)
+- Checks and approves ERC20 token if needed (with retry mechanism)
+- Estimates gas with buffer and EIP-1559 support
+- Executes swap via Bitget aggregator
+
+**Parameters:**
+- `quote`: Quote result from `quote()` method
+- `sender`: Sender address (required, EVM address)
+- `receiveUser`: Recipient address, usually depositAddress (required, EVM address)
+- `recipient`: Optional, kept for compatibility
+
+**Returns:**
+- `success`: Whether successful
+- `txHash`: Transaction hash
+- `txHashArray`: Transaction hash array (if multiple transactions)
+- `error`: Error message (if failed)
+
+#### `getCapabilities(): RouterCapabilities`
+
+Returns router capabilities:
+- `requiresRecipient`: true
+- `requiresFinalizeQuote`: false
+- `requiresComplexRegistration`: false
+- `supportedChain`: "evm"
+
+#### `getSupportedChain(): "evm"`
+
+Returns the supported chain identifier.
+
+#### `getChainId(): number`
+
+Returns the EVM chain ID (e.g., 1 for Ethereum, 56 for BSC, 137 for Polygon, 8453 for Base).
+
 ### completeQuote
 
 Complete quote function that integrates DEX Aggregator and NearIntents.
@@ -462,20 +705,21 @@ Complete quote function that integrates DEX Aggregator and NearIntents.
 **Parameters:**
 - `sourceToken`: Source token information
 - `targetToken`: Target token information
-- `sourceChain`: Source chain identifier ("near")
-- `targetChain`: Target chain identifier (e.g., "bsc", "ethereum")
+- `sourceChain`: Source chain identifier ("near", "evm", "ethereum", "bsc", "polygon", "base", etc.)
+- `targetChain`: Target chain identifier (e.g., "bsc", "ethereum", "near")
 - `amountIn`: Input amount (string format)
 - `slippage`: Slippage tolerance (prefer bps, 50 = 0.5%)
 - `recipient`: Recipient address on target chain
 - `refundTo`: Refund address (optional, defaults to recipient)
+- `evmChainId`: Optional EVM chain ID for precise chain identification (e.g., 1 for Ethereum, 56 for BSC)
 
 **Configuration:**
 - `intentsQuotationAdapter`: NearIntents quotation adapter
 - `dexRouter`: Single DEX Router instance (optional, use `dexRouters` for multiple)
 - `dexRouters`: Array of DEX Router instances (optional, use `dexRouter` for single)
-- `bluechipTokens`: Bluechip tokens configuration (USDT, USDC, NEAR)
-- `configAdapter`: Configuration adapter
-- `currentUserAddress`: Current user address (required for V2 Router)
+- `bluechipTokens`: Bluechip tokens configuration (USDT, USDC, NEAR for NEAR chains; USDT, USDC, ETH for EVM chains)
+- `configAdapter`: Configuration adapter (with optional `getEvmNativeWrappedTokenAddress` for EVM chains)
+- `currentUserAddress`: Current user address (required for V2 Router and EVM Router)
 
 **Returns:**
 - `intents`: NearIntents quote result with depositAddress
@@ -488,15 +732,19 @@ Complete quote function that integrates DEX Aggregator and NearIntents.
 
 ## Router Comparison
 
-| Feature | NearSmartRouter (V1) | AggregateDexRouter (V2) |
-|---------|---------------------|-------------------------|
-| API | FindPath | swapMultiDexPath |
-| Execution | REF Finance | Aggregate DEX Contract |
-| Recipient Required | No | Yes (sender + recipient) |
-| Auto Registration | Basic (recipient only) | Advanced (user, receiveUser, contract) |
-| Multi-DEX Support | Via FindPath | Native multi-DEX aggregation |
-| NEAR → wNEAR | Manual | Automatic |
-| Use Case | Simple swaps | Complex swaps, cross-chain |
+| Feature | NearSmartRouter (V1) | AggregateDexRouter (V2) | BitgetRouter (EVM) |
+|---------|---------------------|-------------------------|-------------------|
+| Chain | NEAR | NEAR | EVM (Ethereum, BSC, Polygon, Base, etc.) |
+| API | FindPath | swapMultiDexPath | Bitget DEX Aggregator |
+| Execution | REF Finance | Aggregate DEX Contract | Direct EVM Transaction |
+| Recipient Required | No | Yes (sender + recipient) | Yes (sender + recipient) |
+| Auto Registration | Basic (recipient only) | Advanced (user, receiveUser, contract) | N/A (EVM) |
+| Auto Approval | N/A (NEAR) | N/A (NEAR) | Yes (ERC20 with retry) |
+| Balance Check | No | No | Yes (automatic) |
+| Gas Optimization | N/A (NEAR) | N/A (NEAR) | Yes (EIP-1559 support) |
+| Multi-DEX Support | Via FindPath | Native multi-DEX aggregation | Via Bitget Aggregator |
+| NEAR → wNEAR | Manual | Automatic | N/A (EVM) |
+| Use Case | Simple swaps on NEAR | Complex swaps on NEAR, cross-chain | EVM chain swaps, cross-chain |
 
 ## Utility Functions
 
@@ -543,7 +791,7 @@ const bestToken = findBestBluechipToken(bluechipTokens);
 
 ### `isNearIntentsSupportedToken(token: TokenInfo, bluechipTokens?: BluechipTokensConfig): boolean`
 
-Check if a token is supported by NearIntents (matches bluechip token configuration).
+Check if a token is supported by NearIntents on NEAR chains (matches bluechip token configuration).
 
 ```typescript
 import { isNearIntentsSupportedToken } from "@rhea-finance/cross-chain-aggregation-dex";
@@ -551,6 +799,43 @@ import { isNearIntentsSupportedToken } from "@rhea-finance/cross-chain-aggregati
 const isSupported = isNearIntentsSupportedToken(tokenIn, bluechipTokens);
 ```
 
+### `normalizeEvmAddress(address: string): string`
+
+Normalize EVM address to lowercase format for comparison.
+
+```typescript
+import { normalizeEvmAddress } from "@rhea-finance/cross-chain-aggregation-dex";
+
+normalizeEvmAddress("0xABC..."); // "0xabc..." (lowercase)
+```
+
+### `isEvmIntentsSupportedToken(token: TokenInfo, bluechipTokens?: BluechipTokensConfig): boolean`
+
+Check if a token is supported by NearIntents on EVM chains (matches bluechip token configuration).
+
+```typescript
+import { isEvmIntentsSupportedToken } from "@rhea-finance/cross-chain-aggregation-dex";
+
+const isSupported = isEvmIntentsSupportedToken(evmTokenIn, evmBluechipTokens);
+```
+
+### `findBestEvmBluechipToken(bluechipTokens: BluechipTokensConfig, nativeTokenAddress?: string): TokenInfo`
+
+Find the best bluechip token for EVM chains (priority order: USDT > USDC > ETH/WETH).
+
+```typescript
+import { findBestEvmBluechipToken } from "@rhea-finance/cross-chain-aggregation-dex";
+
+const evmBluechipTokens = {
+  USDT: { address: "0x...", symbol: "USDT", decimals: 6 },
+  USDC: { address: "0x...", symbol: "USDC", decimals: 6 },
+  ETH: { address: "0x...", symbol: "WETH", decimals: 18 },
+};
+
+const bestToken = findBestEvmBluechipToken(evmBluechipTokens, "0x..."); // Optional WETH address
+// Returns USDT if available, otherwise USDC, otherwise ETH/WETH
+```
+
 ### `formatGasToTgas(gasInYoctoNEAR: string | number): string`
 
 Format gas value from yoctoNEAR to Tgas string, avoiding scientific notation.
@@ -622,7 +907,9 @@ import type {
 - `QuoteResult`: Quote result with routes, amounts, and optional router-specific fields
 - `ExecuteParams`: Union type supporting both simple and recipient execution modes
 - `RouterCapabilities`: Router feature flags
-- `BluechipTokensConfig`: Configuration for bluechip tokens (USDT, USDC, NEAR)
+- `BluechipTokensConfig`: Configuration for bluechip tokens (USDT, USDC, NEAR for NEAR chains; USDT, USDC, ETH for EVM chains)
+- `BitgetAdapter`: Adapter interface for Bitget DEX aggregator API
+- `EvmChainAdapter`: Adapter interface for EVM chain interactions (sendTransaction, getBalance, approve, etc.)
 
 ## Development