@rhea-finance/cross-chain-aggregation-dex 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,465 @@
+/**
+ * Cross-chain DEX aggregation SDK core type definitions
+ */
+interface TokenInfo {
+    address: string;
+    symbol: string;
+    decimals: number;
+    chain: string;
+}
+interface Route {
+    pools: PoolInfo[];
+    amountIn: string;
+    amountOut: string;
+}
+interface PoolInfo {
+    pool_id: number;
+    token_in: string;
+    token_out: string;
+    amount_in?: string;
+    amount_out?: string;
+    fee?: number;
+}
+/**
+ * Base quote parameters (common to all routers)
+ */
+interface BaseQuoteParams {
+    tokenIn: TokenInfo;
+    tokenOut: TokenInfo;
+    amountIn: string;
+    /** Slippage tolerance in bps (e.g. 50 = 0.5%). */
+    slippage: number;
+    swapType?: "EXACT_INPUT" | "EXACT_OUTPUT";
+    recipient?: string;
+}
+/**
+ * Simple quote parameters (V1 NEAR, etc., no recipient required)
+ */
+interface SimpleQuoteParams extends BaseQuoteParams {
+}
+/**
+ * Recipient quote parameters (V2 NEAR, EVM, etc., recipient required)
+ */
+interface RecipientQuoteParams extends BaseQuoteParams {
+    /** Sender address (current user) */
+    sender: string;
+    /** Recipient address (equals sender during quote, equals depositAddress during execution) */
+    recipient: string;
+}
+/**
+ * Unified quote parameters (union type)
+ * Supports both simple and recipient modes
+ */
+type QuoteParams = SimpleQuoteParams | RecipientQuoteParams;
+/**
+ * Type guard: check if recipient parameters are required
+ */
+declare function requiresRecipient(params: QuoteParams): params is RecipientQuoteParams;
+interface QuoteResult {
+    success: boolean;
+    tokenIn: TokenInfo;
+    tokenOut: TokenInfo;
+    amountIn: string;
+    amountOut: string;
+    minAmountOut: string;
+    routes: Route[];
+    /**
+     * Optional: Raw route data returned by chain router/aggregator
+     * - Used for scenarios where aggregator-specific fields need to be passed through in executeSwap
+     * - Kept optional to avoid tightly coupling implementation details into core logic
+     */
+    rawRoutes?: any[];
+    priceImpact?: number;
+    avgFee?: number;
+    estimatedGas?: string;
+    error?: string;
+    routerMsg?: string;
+    signature?: string;
+    tokens?: string[];
+    dexs?: string[];
+    recipient?: string;
+    slippage?: number;
+    transactionData?: string;
+    gasEstimate?: string;
+}
+/**
+ * Base execute parameters (common to all routers)
+ */
+interface BaseExecuteParams {
+    quote: QuoteResult;
+    recipient: string;
+    depositAddress?: string;
+    deadline?: number;
+}
+/**
+ * Recipient execute parameters (V2 NEAR, EVM, etc.)
+ */
+interface RecipientExecuteParams extends BaseExecuteParams {
+    /** Sender address (current user) */
+    sender: string;
+    /** Recipient address (usually depositAddress) */
+    receiveUser: string;
+}
+/**
+ * Unified execute parameters (union type)
+ * Supports both simple and recipient modes
+ */
+type ExecuteParams = BaseExecuteParams | RecipientExecuteParams;
+/**
+ * Type guard: check if execute parameters require recipient
+ */
+declare function requiresRecipientInExecute(params: ExecuteParams): params is RecipientExecuteParams;
+interface ExecuteResult {
+    success: boolean;
+    txHash?: string;
+    txHashArray?: string[];
+    error?: string;
+}
+type SupportedChain = "near" | "evm" | "solana";
+/**
+ * Router capabilities
+ * Used to declare router features and requirements
+ */
+interface RouterCapabilities {
+    /** Whether recipient parameters (sender/recipient) are required */
+    requiresRecipient: boolean;
+    /** Whether two API calls are needed (quote + finalize) */
+    requiresFinalizeQuote: boolean;
+    /** Whether complex token registration is required */
+    requiresComplexRegistration: boolean;
+    /** Supported chain */
+    supportedChain: SupportedChain | string;
+}
+/**
+ * DEX aggregator router abstract interface
+ * Each chain/aggregator implements its own quote/executeSwap
+ *
+ * Extended to support common architecture:
+ * - Capabilities (RouterCapabilities)
+ * - Optional finalize quote method (finalizeQuote)
+ * - Unified parameter interface (supports both simple and recipient modes)
+ */
+interface DexRouter {
+    getCapabilities(): RouterCapabilities;
+    getSupportedChain(): SupportedChain | string;
+    /**
+     * Quote method
+     * - Simple router: only needs BaseQuoteParams
+     * - Recipient router: needs RecipientQuoteParams
+     */
+    quote(params: QuoteParams): Promise<QuoteResult>;
+    /**
+     * Execute swap
+     * - Simple router: only needs BaseExecuteParams
+     * - Recipient router: needs RecipientExecuteParams
+     */
+    executeSwap(params: ExecuteParams): Promise<ExecuteResult>;
+    /**
+     * Finalize quote (if two API calls are needed)
+     * - Only implemented when requiresFinalizeQuote = true
+     * - Used to call API again after getting depositAddress
+     */
+    finalizeQuote?(params: QuoteParams, depositAddress: string): Promise<QuoteResult>;
+}
+/**
+ * Bluechip token configuration
+ */
+interface BluechipTokenConfig {
+    address: string;
+    symbol: string;
+    decimals: number;
+    assetId?: string;
+}
+/**
+ * Bluechip tokens list configuration
+ */
+interface BluechipTokensConfig {
+    USDT?: BluechipTokenConfig;
+    USDC?: BluechipTokenConfig;
+    NEAR?: BluechipTokenConfig;
+    [key: string]: BluechipTokenConfig | undefined;
+}
+
+/** FindPath API response. */
+interface FindPathResponse {
+    result_code: number;
+    result_msg?: string;
+    result_message?: string;
+    result_data: {
+        routes: any[];
+        amount_out: string;
+    } | null;
+}
+/** Adapter for querying DEX routes (FindPath). */
+interface FindPathAdapter {
+    findPath(params: {
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        slippage: number;
+        supportLedger?: boolean;
+    }): Promise<FindPathResponse>;
+}
+/** NearIntents quote result. */
+interface IntentsQuoteResult {
+    quoteStatus: "success" | "error";
+    message?: string;
+    quoteSuccessResult?: {
+        quote: {
+            amountOut: string;
+            depositAddress: string;
+            [key: string]: any;
+        };
+        [key: string]: any;
+    };
+    [key: string]: any;
+}
+/** Adapter for fetching NearIntents quotes. */
+interface IntentsQuotationAdapter {
+    quote(params: {
+        originAsset: string;
+        destinationAsset: string;
+        amount: string;
+        refundTo: string;
+        recipient: string;
+        slippageTolerance: number;
+        swapType?: "EXACT_INPUT" | "EXACT_OUTPUT" | "FLEX_INPUT";
+        [key: string]: any;
+    }): Promise<IntentsQuoteResult>;
+}
+/** Adapter for interacting with NEAR (call/view). */
+interface NearChainAdapter {
+    call(params: {
+        transactions: Array<{
+            contractId: string;
+            methodName: string;
+            args: any;
+            gas?: string;
+            expandDeposit?: string;
+        }>;
+    }): Promise<{
+        status: "success" | "error";
+        txHash?: string;
+        txHashArr?: string[];
+        message?: string;
+    }>;
+    view(params: {
+        contractId: string;
+        methodName: string;
+        args?: any;
+    }): Promise<any>;
+}
+/** V2 Router API response. */
+interface SwapMultiDexPathResponse {
+    result_code: number;
+    result_message?: string;
+    result_data: {
+        amount_in: string;
+        amount_out: string;
+        min_amount_out: string;
+        msg: string;
+        signature: string;
+        tokens: string[];
+        dexs: string[];
+    } | null;
+}
+/** Adapter for V2 Router API (swapMultiDexPath). */
+interface SwapMultiDexPathAdapter {
+    swapMultiDexPath(params: {
+        amountIn: string;
+        tokenIn: string;
+        tokenOut: string;
+        slippage: number;
+        pathDeep?: number;
+        chainId?: number;
+        routerCount?: number;
+        user: string;
+        receiveUser: string;
+        skipUnwrapNativeToken?: boolean;
+    }): Promise<SwapMultiDexPathResponse>;
+}
+/** Chain-specific configuration provider. */
+interface ConfigAdapter {
+    getRefExchangeId(): string;
+    getWrapNearContractId(): string;
+    getFindPathUrl(): string;
+    /** Storage deposit amount (yoctoNEAR) for `storage_deposit` when needed. */
+    getTokenStorageDepositRead?(): string;
+    getAggregateDexContractId?(): string;
+    getSmartxUrl?(): string;
+}
+
+declare const logger: {
+    debug: (...args: any[]) => void;
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+};
+
+/** Set the SDK-wide bluechip token config used for NearIntents compatibility and intermediate routing. */
+declare function setBluechipTokensConfig(config: BluechipTokensConfig): void;
+/** Get the bluechip token config; returns an empty object (and warns) if unset. */
+declare function getBluechipTokensConfig(): BluechipTokensConfig;
+/**
+ * Normalize a NEAR asset id:
+ * - strip `nep141:` prefix (if present)
+ * - map `near` -> `wrap.near` (overridable via `wrapNearContractId`)
+ */
+declare function normalizeTokenId(tokenId: string | undefined | null, wrapNearContractId?: string): string;
+/** True if the token matches a NearIntents-supported bluechip token (by symbol + address/assetId). */
+declare function isNearIntentsSupportedToken(token: TokenInfo, bluechipTokens?: BluechipTokensConfig): boolean;
+/** Pick an intermediate bluechip token (priority: USDT > USDC > wNEAR; fallback to `wrapNearContractId`). */
+declare function findBestBluechipToken(bluechipTokens: BluechipTokensConfig, wrapNearContractId?: string): TokenInfo;
+/**
+ * Convert slippage input into bps (1 bps = 0.01%).
+ * - `>= 1`: bps (e.g. 50 = 0.5%)
+ * - `[0.01, 1)`: percent (e.g. 0.5 = 0.5%)
+ * - `(0, 0.01)`: decimal (e.g. 0.005 = 0.5%)
+ */
+declare function convertSlippageToBasisPoints(slippage: number): number;
+/** Normalize NearIntents `destinationAsset` (prefix + `near` -> `wrap.near`). */
+declare function normalizeDestinationAsset(assetId: string, wrapNearContractId?: string): string;
+/**
+ * Format gas value from yoctoNEAR to Tgas string, avoiding scientific notation.
+ * @param gasInYoctoNEAR Gas value in yoctoNEAR (string or number)
+ * @returns Formatted gas string in Tgas units (e.g., "795" for 795 Tgas)
+ */
+declare function formatGasToTgas(gasInYoctoNEAR: string | number): string;
+/**
+ * Ensure gas value is a string without scientific notation.
+ * This is used to format gas values before passing to wallet selector.
+ * @param gas Gas value (string, number, or BigInt)
+ * @returns Formatted gas string in yoctoNEAR
+ */
+declare function formatGasString(gas: string | number | bigint): string;
+
+/** NEAR DEX router implementation (FindPath for routing + REF for execution). */
+
+interface NearSmartRouterConfig {
+    findPathAdapter: FindPathAdapter;
+    nearChainAdapter: NearChainAdapter;
+    configAdapter: ConfigAdapter;
+}
+declare class NearSmartRouter implements DexRouter {
+    private findPathAdapter;
+    private nearChainAdapter;
+    private configAdapter;
+    private wrapNearContractId;
+    private refExchangeId;
+    private tokenStorageDepositRead;
+    constructor(config: NearSmartRouterConfig);
+    /**
+     * Get a swap quote (normalizes token ids and queries FindPath for routes).
+     */
+    quote(params: QuoteParams): Promise<QuoteResult>;
+    /**
+     * Execute a swap: optionally adds `storage_deposit` for the recipient, then calls REF via `ft_transfer_call`.
+     */
+    executeSwap(params: ExecuteParams): Promise<ExecuteResult>;
+    /**
+     * Get Router capabilities
+     */
+    getCapabilities(): RouterCapabilities;
+    /**
+     * Get supported chain
+     */
+    getSupportedChain(): "near";
+}
+
+/** V2 Router implementation (Aggregate DEX Router). */
+
+interface AggregateDexRouterConfig {
+    swapMultiDexPathAdapter: SwapMultiDexPathAdapter;
+    nearChainAdapter: NearChainAdapter;
+    configAdapter: ConfigAdapter;
+}
+/**
+ * V2 Router implementation for NEAR
+ * Uses Aggregate DEX contract for routing
+ */
+declare class AggregateDexRouter implements DexRouter {
+    private swapMultiDexPathAdapter;
+    private nearChainAdapter;
+    private configAdapter;
+    private aggregateDexContractId;
+    private wrapNearContractId;
+    private readonly NEW_ACCOUNT_STORAGE_COST;
+    private readonly ONE_YOCTO_NEAR;
+    constructor(config: AggregateDexRouterConfig);
+    /**
+     * Get Router capabilities
+     */
+    getCapabilities(): RouterCapabilities;
+    getSupportedChain(): "near";
+    /**
+     * Get a swap quote from V2 Router API
+     */
+    quote(params: QuoteParams): Promise<QuoteResult>;
+    /**
+     * Finalize quote with depositAddress (deprecated)
+     *
+     * @deprecated No longer needed. executeSwap automatically fetches final quote using receiveUser (depositAddress).
+     * Kept for interface compatibility only.
+     */
+    finalizeQuote(params: QuoteParams, depositAddress: string): Promise<QuoteResult>;
+    /**
+     * Execute swap with V2 Router
+     * Automatically fetches final quote using receiveUser (depositAddress) to ensure correct routerMsg and signature.
+     */
+    executeSwap(params: ExecuteParams): Promise<ExecuteResult>;
+    /**
+     * Query user token registration status in AGGREGATE_DEX contract
+     */
+    private queryUserTokensRegistered;
+}
+
+/** Composite quote: optional NEAR DEX pre-swap + NearIntents quote. */
+
+interface CompleteQuoteParams {
+    sourceToken: TokenInfo;
+    targetToken: TokenInfo;
+    sourceChain: string;
+    targetChain: string;
+    amountIn: string;
+    slippage: number;
+    recipient: string;
+    refundTo?: string;
+}
+interface CompleteQuoteResult {
+    intents: {
+        /** Raw NearIntents response (passed through). */
+        quote: any;
+        depositAddress: string;
+    };
+    preSwap?: {
+        quote: QuoteResult;
+        tokenIn: TokenInfo;
+        tokenOut: TokenInfo;
+        executor: DexRouter;
+    };
+    finalAmountOut: string;
+    totalPriceImpact?: number;
+    totalFee?: number;
+}
+interface CompleteQuoteConfig {
+    intentsQuotationAdapter: IntentsQuotationAdapter;
+    dexRouters?: DexRouter[];
+    dexRouter?: DexRouter;
+    bluechipTokens: BluechipTokensConfig;
+    configAdapter: {
+        getWrapNearContractId(): string;
+    };
+    currentUserAddress?: string;
+}
+/**
+ * Build a "complete quote":
+ * - If `sourceToken` is not NearIntents-supported, pre-swap to a bluechip token on NEAR DEX.
+ * - Quote NearIntents using (pre-swap output) or `amountIn`.
+ *
+ * Notes:
+ * - Prefer `slippage` in bps (e.g. 50 = 0.5%); we also accept percent/decimal inputs.
+ * - `targetChain` is currently reserved for future use.
+ */
+declare function completeQuote(params: CompleteQuoteParams, config: CompleteQuoteConfig): Promise<CompleteQuoteResult>;
+
+export { AggregateDexRouter, type AggregateDexRouterConfig, type BaseExecuteParams, type BaseQuoteParams, type BluechipTokenConfig, type BluechipTokensConfig, type CompleteQuoteConfig, type CompleteQuoteParams, type CompleteQuoteResult, type ConfigAdapter, type DexRouter, type ExecuteParams, type ExecuteResult, type FindPathAdapter, type FindPathResponse, type IntentsQuotationAdapter, type IntentsQuoteResult, type NearChainAdapter, NearSmartRouter, type NearSmartRouterConfig, type PoolInfo, type QuoteParams, type QuoteResult, type RecipientExecuteParams, type RecipientQuoteParams, type Route, type RouterCapabilities, type SimpleQuoteParams, type SupportedChain, type SwapMultiDexPathAdapter, type SwapMultiDexPathResponse, type TokenInfo, completeQuote, convertSlippageToBasisPoints, findBestBluechipToken, formatGasString, formatGasToTgas, getBluechipTokensConfig, isNearIntentsSupportedToken, logger, normalizeDestinationAsset, normalizeTokenId, requiresRecipient, requiresRecipientInExecute, setBluechipTokensConfig };