@rhea-finance/cross-chain-aggregation-dex 1.0.6 → 2.0.1

package/README.md

@@ -1,355 +1,366 @@
 # @rhea-finance/cross-chain-aggregation-dex
 
-Cross-chain DEX Aggregation SDK is a TypeScript SDK for multi-chain DEX aggregation and routing. It supports token swaps on Near chain and can integrate with NearIntents bridge protocol to enable cross-chain swaps.
+TypeScript SDK for the unified multi-chain Swap API. It provides raw and normalized quote, build, execution, order status, report, and history interfaces without coupling the core package to a wallet or UI framework.
 
-## Features
+Supported chain families: EVM, Solana, Aptos, NEAR, Tron, Bitcoin, Zcash, and Sui.
 
-- 🔄 **DEX Aggregation Routing**: Automatically finds optimal swap paths
-- 🌉 **Cross-chain Support**: Integrates with NearIntents for cross-chain swaps
-- 🔀 **Pre-swap Handling**: Automatically handles conversion from non-bluechip tokens to bluechip tokens
-- 📦 **Type Safety**: Complete TypeScript type definitions
-- 🔌 **Adapter Pattern**: Abstracts dependencies through adapter interfaces for easy integration
-
-## Installation
+## Install
 
 ```bash
-npm install @rhea-finance/cross-chain-aggregation-dex
-# or
 pnpm add @rhea-finance/cross-chain-aggregation-dex
-# or
-yarn add @rhea-finance/cross-chain-aggregation-dex
 ```
 
-## Quick Start
+## Quick start
 
-### 1. Create Adapters
+All token amounts are base-unit decimal strings. Slippage uses basis points (`50` means 0.5%).
 
-First, you need to implement adapter interfaces to provide necessary dependencies:
+```ts
+import { SwapClient, type QuoteRequest } from "@rhea-finance/cross-chain-aggregation-dex";
 
-```typescript
-import {
-  FindPathAdapter,
-  IntentsQuotationAdapter,
-  NearChainAdapter,
-  ConfigAdapter,
-} from "@rhea-finance/cross-chain-aggregation-dex";
+const getAccessToken = async () => sessionStorage.getItem("access-token") ?? "";
 
-// FindPath API adapter
-const findPathAdapter: FindPathAdapter = {
-  async findPath(params) {
-    const response = await fetch(
-      `https://smartrouter.rhea.finance/findPath?${new URLSearchParams({
-        amountIn: params.amountIn,
-        tokenIn: params.tokenIn,
-        tokenOut: params.tokenOut,
-        pathDeep: "3",
-        slippage: String(params.slippage),
-      })}`
-    );
-    return response.json();
-  },
-};
+const client = new SwapClient({
+  baseUrl: "https://api.rhea.finance",
+  getAccessToken,
+});
 
-// SmartX swapMultiDexPath adapter (optional, used to compare and show the best quote)
-const swapMultiDexPathAdapter = {
-  async swapMultiDexPath(params: any) {
-    const response = await fetch(
-      `https://smartx.rhea.finance/swapMultiDexPath?${new URLSearchParams({
-        amountIn: params.amountIn,
-        tokenIn: params.tokenIn,
-        tokenOut: params.tokenOut,
-        slippage: String(params.slippage),
-        pathDeep: "2",
-        chainId: "0",
-        routerCount: "1",
-        skipUnwrapNativeToken: "false",
-        user: params.user,
-        receiveUser: params.receiveUser,
-      })}`
-    );
-    return response.json();
+const request: QuoteRequest = {
+  fromChain: "btc",
+  toChain: "near",
+  tokenIn: {
+    chain: "btc",
+    address: "btc",
+    symbol: "BTC",
+    decimals: 8,
+    isNative: true,
   },
-};
-
-// NearIntents quotation adapter
-const intentsQuotationAdapter: IntentsQuotationAdapter = {
-  async quote(params) {
-    // Call your NearIntents API
-    const response = await fetch("https://your-api.com/intents/quote", {
-      method: "POST",
-      body: JSON.stringify(params),
-    });
-    return response.json();
+  tokenOut: {
+    chain: "near",
+    address: "wrap.near",
+    symbol: "wNEAR",
+    decimals: 24,
   },
+  amountIn: "100000",
+  slippageBps: 50,
+  sender: "bc1...",
+  recipient: "alice.near",
 };
 
-// Near chain interaction adapter
-const nearChainAdapter: NearChainAdapter = {
-  async call({ transactions }) {
-    // Use your Near wallet or RPC to call contracts
-    // Return { status: "success", txHash: "..." }
-  },
-  async view({ contractId, methodName, args }) {
-    // Use your Near RPC to view contract state
-  },
-};
+const quote = await client.quote(request);
+const build = await client.buildSwap({ quote });
 
-// Configuration adapter
-const configAdapter: ConfigAdapter = {
-  getRefExchangeId: () => "v2.ref-finance.near",
-  getWrapNearContractId: () => "wrap.near",
-  getFindPathUrl: () => "https://smartrouter.ref.finance",
-  getTokenStorageDepositRead: () => "1250000000000000000000",
-};
+// build is safe to inspect or send to another process.
+// Register a chain executor before calling executeSwap.
 ```
 
-### 2. Create DEX Aggregator Instance
+`buildSwap()` never opens a wallet. To execute a build, inject one or more `ChainExecutor` implementations when creating the client:
 
-```typescript
-import { NearSmartRouter } from "@rhea-finance/cross-chain-aggregation-dex";
+```ts
+const clientWithExecutor = new SwapClient({
+  baseUrl: "https://api.rhea.finance",
+  getAccessToken,
+  executors: [bitcoinExecutor],
+});
 
-const router = new NearSmartRouter({
-  findPathAdapter,
-  swapMultiDexPathAdapter,
-  nearChainAdapter,
-  configAdapter,
+const result = await clientWithExecutor.executeSwap({
+  build,
+  waitFor: "submitted",
 });
 ```
 
-### 3. Get Quote
 
-```typescript
-import { TokenInfo } from "@rhea-finance/cross-chain-aggregation-dex";
 
-const tokenIn: TokenInfo = {
-  address: "token-a.near",
-  symbol: "TOKENA",
-  decimals: 18,
-  chain: "near",
-};
+### Executor adapters
+
+Each executor is imported from its own subpath and accepts a wallet-neutral adapter. The application decides whether that adapter wraps a browser wallet, server signer, RPC service, or HSM.
 
-const tokenOut: TokenInfo = {
-  address: "token-b.near",
-  symbol: "TOKENB",
-  decimals: 18,
-  chain: "near",
+```ts
+import { SwapClient } from "@rhea-finance/cross-chain-aggregation-dex";
+import {
+  createEvmExecutor,
+  type EvmWalletAdapter,
+} from "@rhea-finance/cross-chain-aggregation-dex/executors/evm";
+
+const evmWallet: EvmWalletAdapter = {
+  getIdentityKey: () => wallet.address,
+  signMessage: (message) => wallet.signMessage(message),
+  sendTransaction: async (tx) => {
+    const response = await wallet.sendTransaction({
+      to: tx.to,
+      data: tx.data,
+      value: tx.value,
+      gasLimit: tx.gasLimit,
+    });
+    return { txHash: response.hash, raw: response };
+  },
+  signTypedData: async (request) =>
+    wallet.signTypedData(
+      request.typedData.domain,
+      request.typedData.types,
+      request.typedData.message
+    ),
+  waitForTransaction: async (txHash) => provider.waitForTransaction(txHash),
 };
 
-const quote = await router.quote({
-  tokenIn,
-  tokenOut,
-  amountIn: "1000000000000000000", // 1 token (18 decimals)
-  slippage: 50, // 0.5% (50 basis points)
-  swapType: "EXACT_INPUT",
+const client = new SwapClient({
+  baseUrl: "https://api.rhea.finance",
+  getAccessToken,
+  executors: [createEvmExecutor(evmWallet)],
 });
+```
 
-if (quote.success) {
-  console.log("Amount out:", quote.amountOut);
-  console.log("Min amount out:", quote.minAmountOut);
-  console.log("Routes:", quote.routes);
-} else {
-  console.error("Quote failed:", quote.error);
-}
+Other executor subpaths follow the same pattern:
+
+```ts
+import { createSolanaExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/solana";
+import { createAptosExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/aptos";
+import { createNearExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/near";
+import { createTronExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/tron";
+import { createBitcoinExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/bitcoin";
+import { createZcashExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/zcash";
+import { createSuiExecutor } from "@rhea-finance/cross-chain-aggregation-dex/executors/sui";
 ```
 
-### 4. Execute Swap
+Bitcoin requires `feeRate` in the build or a configured fallback:
 
-```typescript
-const result = await router.executeSwap({
-  quote,
-  recipient: "user.near",
-  depositAddress: "deposit.near", // optional
+```ts
+const bitcoinExecutor = createBitcoinExecutor(bitcoinWallet, {
+  defaultFeeRate: 4,
 });
-
-if (result.success) {
-  console.log("Transaction hash:", result.txHash);
-} else {
-  console.error("Swap failed:", result.error);
-}
 ```
 
-### 5. Complete Quote (DEX Aggregator + NearIntents)
+Zcash adapters may return `{ requiresUserAction: true }` for legacy wallets that complete transfer confirmation in an external interface. The SDK returns `requires-user-action` without creating a fake transaction hash.
+
+`swap({ quote })` is the convenience form of `buildSwap({ quote })` followed by `executeSwap({ build })`. It does not request another quote.
+
+## MCA swaps
+
+MCA deposit and withdrawal are execution modes of the unified root API. Use the same `client.quote()`, `client.buildSwap()`, `client.swap()`, `client.report()`, and `client.getHistory()` methods as a regular swap. The SDK does not create MCA accounts or query lending positions.
 
-```typescript
-import { completeQuote } from "@rhea-finance/cross-chain-aggregation-dex";
+### Deposit into an MCA
 
-const bluechipTokens = {
-  USDT: {
-    address: "usdt.tether-token.near",
-    symbol: "USDT",
-    decimals: 6,
-    assetId: "nep141:usdt.tether-token.near",
+The destination asset address is the Burrow token id expected by the Swap API. Execution reuses the registered source-chain executor.
+
+```ts
+const quote = await client.quote({
+  flow: "deposit",
+  mcaAccountId: "account.near",
+  fromChain: "1",
+  toChain: "near",
+  tokenIn: ethereumUsdc,
+  tokenOut: mcaUsdc,
+  amountIn: "1000000",
+  slippageBps: 50,
+  sender: "0x...",
+  recipient: "account.near",
+  signerChain: "evm",
+  collateral: {
+    useAsCollateral: true,
   },
-  USDC: {
-    address: "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1",
-    symbol: "USDC",
-    decimals: 6,
-    assetId: "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1",
+});
+
+const result = await client.swap({ quote, waitFor: "completed" });
+```
+
+The report includes `multi_addr`. Its `tx_type` remains `same-chain` or `cross-chain`, matching the unified Swap API.
+
+### Withdraw directly to NEAR
+
+Register a NEAR executor and request the NEAR path. The SDK parses `nearMcaWithdrawTx`, builds the MCA `exec` function call, and asks the injected NEAR wallet to send it. This path does not create an additional off-chain MCA message signature.
+
+```ts
+const quote = await client.quote({
+  flow: "withdraw",
+  mcaAccountId: "account.near",
+  fromChain: "near",
+  toChain: "near",
+  tokenIn: mcaUsdc,
+  tokenOut: nearUsdc,
+  amountIn: "1000000",
+  slippageBps: 50,
+  sender: "account.near",
+  recipient: "alice.near",
+  signerChain: "near",
+  collateral: {
+    needDecrease: false,
+    decreaseAmountBurrow: "0",
   },
-  NEAR: {
-    address: "wrap.near",
-    symbol: "wNEAR",
-    decimals: 24,
-    assetId: "nep141:wrap.near",
+  executionPreference: "near",
+  boundNearAccountId: "alice.near",
+});
+
+await client.swap({ quote, waitFor: "completed" });
+```
+
+With `executionPreference: "auto"`, NEAR direct execution is selected only when the destination chain is NEAR and `recipient` exactly matches `boundNearAccountId`.
+
+### Withdraw through the multichain relayer
+
+For other destination chains, expose `getIdentityKey()` and `signMessage()` on the connected wallet adapter used by its registered executor. The SDK signs the exact `messageToSign` returned by the API, then submits `mcaRelayer` through `POST /api/swap/swap`. No source-chain executor broadcasts a transaction for this path.
+
+```ts
+const quote = await client.quote({
+  flow: "withdraw",
+  mcaAccountId: "account.near",
+  fromChain: "near",
+  toChain: "1",
+  tokenIn: mcaUsdc,
+  tokenOut: ethereumUsdc,
+  amountIn: "1000000",
+  slippageBps: 50,
+  sender: "account.near",
+  recipient: wallet.address,
+  signerChain: "evm",
+  collateral: {
+    needDecrease: true,
+    decreaseAmountBurrow: "1000000",
+    withdrawAll: true,
   },
-};
+  executionPreference: "relayer",
+});
 
-const completeQuoteResult = await completeQuote(
-  {
-    sourceToken: tokenIn,
-    targetToken: tokenOut,
-    sourceChain: "near",
-    targetChain: "bsc",
-    amountIn: "1000000000000000000",
-    slippage: 50,
-    recipient: "0x...", // Target chain address
-    refundTo: "user.near",
+await client.swap({
+  quote,
+  waitFor: "completed",
+  beforeSign(preview) {
+    showMcaSignatureConfirmation(preview);
   },
-  {
-    intentsQuotationAdapter,
-    dexRouter: router,
-    bluechipTokens,
-    configAdapter,
-  }
-);
-
-console.log("Deposit address:", completeQuoteResult.intents.depositAddress);
-console.log("Final amount out:", completeQuoteResult.finalAmountOut);
-
-if (completeQuoteResult.preSwap) {
-  console.log("Pre-swap required:", completeQuoteResult.preSwap.quote);
-}
+});
 ```
 
-## API Documentation
+Supported MCA signer identity formats are EVM, Solana, Bitcoin, NEAR, Aptos, Sui, Zcash, and Tron. Wallet implementations remain application-owned:
+
+```ts
+import {
+  formatMcaWallet,
+  selectMcaSigner,
+} from "@rhea-finance/cross-chain-aggregation-dex";
+
+formatMcaWallet("evm", "0xAbC"); // { EVM: "AbC" }
 
-### NearSmartRouter
+const signer = selectMcaSigner(boundMcaWallets, connectedSignerIdentities);
+```
 
-#### `quote(params: QuoteParams): Promise<QuoteResult>`
+The executor registered for the selected chain must expose `signMessage` when the relayer preview requests a message signature. The SDK never receives a private key or recovery phrase.
 
-Get quote method that returns optimal swap path and output amount.
+### Collateral policy
 
-**Parameters:**
-- `tokenIn`: Input token information
-- `tokenOut`: Output token information
-- `amountIn`: Input amount (string format, considering decimals)
-- `slippage`: Slippage tolerance (prefer bps, 50 = 0.5%). Percent/decimal inputs are also accepted.
-- `swapType`: Swap type ("EXACT_INPUT" | "EXACT_OUTPUT")
+The SDK does not fetch a lending portfolio. Pass collateral decisions explicitly, or calculate the API fields from data already held by the application:
 
-**Returns:**
-- `success`: Whether successful
-- `amountOut`: Output amount
-- `minAmountOut`: Minimum output amount (considering slippage)
-- `routes`: Route information
-- `error`: Error message (if failed)
+```ts
+import { resolveMcaWithdrawPolicy } from "@rhea-finance/cross-chain-aggregation-dex";
 
-#### `executeSwap(params: ExecuteParams): Promise<ExecuteResult>`
+const collateral = resolveMcaWithdrawPolicy({
+  collateralBalance: "12.5",
+  availableBalance: "1000000",
+  amountIn: "999999",
+  isMax: false,
+});
+```
 
-Execute swap method.
+`withdrawAll` becomes true for max selection, exact available balance, or a ratio of at least `0.999999`. The calculation uses decimal strings and `BigInt`, not floating-point arithmetic.
 
-**Parameters:**
-- `quote`: Quote result
-- `recipient`: Recipient address
-- `depositAddress`: Deposit address (optional, for cross-chain scenarios)
+MCA history uses the MCA account id as the server-side history search key. The backend matches this value against `sender`, `recipient`, and `multi_addr`:
 
-**Returns:**
-- `success`: Whether successful
-- `txHash`: Transaction hash
-- `txHashArray`: Transaction hash array (if multiple transactions)
-- `error`: Error message (if failed)
+```ts
+const history = await client.getHistory({
+  sender: "account.near",
+});
+```
 
-### completeQuote
+The SDK preserves the server page instead of filtering `record.multi_addr` again. Address fields may be presentation-normalized by the API, so callers should not require exact equality with the MCA account id.
 
-Complete quote function that integrates DEX Aggregator and NearIntents.
+## API surfaces
 
-**Parameters:**
-- `sourceToken`: Source token
-- `targetToken`: Target token
-- `sourceChain`: Source chain
-- `targetChain`: Target chain
-- `amountIn`: Input amount
-- `slippage`: Slippage tolerance
-- `recipient`: Recipient address
-- `refundTo`: Refund address (optional)
+Normalized methods:
 
-**Configuration:**
-- `intentsQuotationAdapter`: NearIntents quotation adapter
-- `dexRouter`: DEX Router instance
-- `bluechipTokens`: Bluechip tokens configuration
-- `configAdapter`: Configuration adapter
+- `quote()`
+- `buildSwap()`
+- `executeSwap()` and `swap()`
+- `getOrderStatus()` and `waitForOrder()`
+- `report()` and `retryReport()`
+- `getHistory()`
 
-## Utility Functions
+Raw methods preserve the unified API `data` shape:
 
-### `normalizeTokenId(tokenId: string, wrapNearContractId?: string): string`
+- `quoteRaw()`
+- `buildRaw()`
+- `submitOrderRaw()`
+- `getOrderStatusRaw()`
+- `reportRaw()`
+- `getHistoryRaw()`
 
-Normalize token ID, remove `nep141:` prefix, convert `near` to `wrap.near`.
 
-### `convertSlippageToBasisPoints(slippage: number): number`
 
-Convert slippage format to basis points (1 basis point = 0.01%).
+## Execution kinds
 
-### `findBestBluechipToken(bluechipTokens: BluechipTokensConfig, wrapNearContractId?: string): TokenInfo`
+Build responses are validated and represented as a discriminated union:
 
-Find the best bluechip token to use as intermediate token (priority order: USDT > USDC > wNEAR).
+- `evm-transaction`
+- `evm-signature`
+- `solana-transaction`
+- `aptos-entry-function`
+- `near-transaction-batch`
+- `tron-transfer`
+- `bitcoin-transfer`
+- `zcash-transfer`
+- `sui-transfer`
 
-### Logging
+The SDK core defines the executor contract and registry. Wallet-specific implementations are injected by the application, so importing the package does not access browser wallet globals.
 
-The SDK uses a simple logger with log level control. You can control logging via the `LOG_LEVEL` environment variable:
+## Runtime and credentials
 
-- `LOG_LEVEL=debug` - Show all logs (default in development)
-- `LOG_LEVEL=info` - Show info, warn, and error logs
-- `LOG_LEVEL=warn` - Show only warnings and errors (default in production)
-- `LOG_LEVEL=error` - Show only errors
-- `LOG_LEVEL=silent` - Disable all logs
+- Browsers and Node.js 18+ use the global Fetch API.
+- Node.js 16 requires a compatible `fetch` implementation through `new SwapClient({ fetch })`.
+- Supply credentials with `apiKey` or `getAccessToken`; when both are present, `getAccessToken` takes precedence.
+- The package contains no fixed API credential and never manages private keys or wallet recovery phrases.
+- Use `AbortSignal` on network, build, execute, and polling calls when cancellation is required.
 
-```typescript
-import { logger } from "@rhea-finance/cross-chain-aggregation-dex";
 
-// The logger is automatically used internally
-// You can also use it in your code if needed
-logger.debug("Debug message");
-logger.info("Info message");
-logger.warn("Warning message");
-logger.error("Error message");
-```
 
-## Type Definitions
+## Retry and logging
 
-All type definitions can be imported from the package:
+Quote, history, and order-status requests retry network errors, timeouts, HTTP 429, and retryable 5xx responses twice by default. Build, report, order submission, and wallet execution are never retried automatically.
 
-```typescript
-import type {
-  TokenInfo,
-  QuoteParams,
-  QuoteResult,
-  ExecuteParams,
-  ExecuteResult,
-  DexRouter,
-  BluechipTokensConfig,
-} from "@rhea-finance/cross-chain-aggregation-dex";
+```ts
+const client = new SwapClient({
+  baseUrl: "https://api.rhea.finance",
+  retry: {
+    maxRetries: 2,
+    baseDelayMs: 250,
+    maxDelayMs: 2_000,
+    jitter: true,
+  },
+  logger: {
+    log(entry) {
+      telemetry.emit(entry.event, entry);
+    },
+  },
+});
 ```
 
-## Development
+Log entries contain only request stage, endpoint path, attempt, response status, timing, and SDK error code. They do not include credentials, query strings, request bodies, signatures, or serialized transactions.
 
-```bash
-# Install dependencies
-pnpm install
+## Amount conversion
 
-# Build
-pnpm build
+`parseUnits` and `formatUnits` use string arithmetic and never pass token values through floating-point numbers:
 
-# Type check
-pnpm type-check
+```ts
+import {
+  formatUnits,
+  parseUnits,
+} from "@rhea-finance/cross-chain-aggregation-dex";
 
-# Development mode (watch file changes)
-pnpm dev
+parseUnits("1.25", 6); // "1250000"
+formatUnits("1250000", 6); // "1.25"
 ```
 
-## License
+Both functions reject negative values, scientific notation, malformed input, and unsupported precision. Token decimals must be an integer between 0 and 255.
 
-MIT
+## History filtering
 
-## Related Links
+The service handles sender and pagination. `getHistory({ status })` filters the current returned page locally and sets `filteredLocally: true`; server totals remain unchanged.
+
+## License
 
-- [GitHub Repository](https://github.com/rhea-finance/crossChain-aggregation-dex)
-- [Rhea Finance](https://rhea.finance)
+MIT

package/dist/executors/aptos.d.mts

@@ -0,0 +1,19 @@
+import { C as ChainRef, q as ChainExecutor } from '../registry-DRYUqs7T.mjs';
+import { E as ExecutorErrorAdapter, T as TransactionSubmission } from '../shared-BqpFeosz.mjs';
+
+interface AptosWalletAdapter extends ExecutorErrorAdapter {
+    getChain(): ChainRef | Promise<ChainRef>;
+    signAndSubmitTransaction(payload: {
+        function: string;
+        typeArguments: string[];
+        functionArguments: unknown[];
+    }, options: {
+        signal?: AbortSignal;
+    }): Promise<TransactionSubmission>;
+    waitForTransaction?(txHash: string, options: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+declare function createAptosExecutor(adapter: AptosWalletAdapter): ChainExecutor<"aptos-entry-function">;
+
+export { type AptosWalletAdapter, createAptosExecutor };