@peachprojects/aggregator-sdk 0.0.0-experimental-20260324105259

package/dist/index.d.ts

@@ -0,0 +1,681 @@
+import { ethers } from 'ethers';
+
+export declare interface AdapterConfig {
+    protocol: ProtocolType;
+    address: string;
+}
+
+/**
+ * Default values for API parameters
+ */
+export declare const API_DEFAULTS: {
+    /** Default route search depth */
+    readonly depth: 3;
+    /** Default trade split count */
+    readonly splitCount: 20;
+    /** Default DEX providers */
+    readonly providers: Provider[];
+    /** Default client version for V3 API */
+    readonly clientVersion: 1001500;
+};
+
+export declare class ApiClient {
+    private baseUrl;
+    private timeout;
+    constructor(config: ApiClientConfig);
+    /**
+     * Find optimal routes via API
+     */
+    findRoutes(params: {
+        from: string;
+        target: string;
+        amount: bigint;
+        byAmountIn?: boolean;
+        depth?: number;
+        splitCount?: number;
+        providers?: Provider[];
+    }): Promise<ApiFindRouteData>;
+    /**
+     * Get service status including available providers
+     */
+    getStatus(): Promise<ApiStatusData>;
+    /**
+     * Get list of available providers
+     */
+    getAvailableProviders(): Promise<string[]>;
+    /**
+     * Update API base URL
+     */
+    setBaseUrl(url: string): void;
+    /**
+     * Get current API base URL
+     */
+    getBaseUrl(): string;
+}
+
+export declare interface ApiClientConfig {
+    /** API base URL (required) */
+    baseUrl: string;
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+}
+
+/**
+ * Contract addresses for EVM
+ */
+export declare interface ApiContractAddresses {
+    /** PeachAggregator router address */
+    router: string;
+    /** Adapter addresses by provider name */
+    adapters: Record<string, string>;
+}
+
+/**
+ * API error class
+ */
+export declare class ApiError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+
+/**
+ * Find route response data
+ */
+export declare interface ApiFindRouteData {
+    request_id: string;
+    /** Total input amount (string to support u128) */
+    amount_in: string;
+    /** Total output amount (string to support u128) */
+    amount_out: string;
+    deviation_ratio: string;
+    paths: ApiRoutePath[];
+    /** Contract addresses for building transactions */
+    contracts: ApiContractAddresses;
+    /** Estimated gas */
+    gas: number;
+}
+
+/**
+ * API request parameters for find_routes
+ * Note: The following parameters are ignored by SDK:
+ * - liquidity_change
+ * - apikey
+ * - gas
+ * - with_sign
+ * - cal_path_limit
+ */
+export declare interface ApiFindRouteRequest {
+    /** Input token address (required) */
+    from: string;
+    /** Output token address (required) */
+    target: string;
+    /** Trade amount, cannot be 0 (required) */
+    amount: string;
+    /** true: calculate output from input; false: calculate input from output (default: true) */
+    by_amount_in?: boolean;
+    /** Route search depth / max hops (default: 3) */
+    depth?: number;
+    /** Trade split count for large trades optimization (default: 20) */
+    split_count?: number;
+    /** DEX providers, comma-separated (default: "PANCAKEV2,PANCAKEV3") */
+    providers?: string;
+    /** Client version (required >= 1001500 for V3) */
+    v?: number;
+}
+
+/**
+ * Full find route response
+ */
+export declare type ApiFindRouteResponse = ApiResponse<ApiFindRouteData>;
+
+/**
+ * Aggregator API response wrapper
+ */
+export declare interface ApiResponse<T> {
+    code: number;
+    msg: string;
+    data: T;
+}
+
+/**
+ * Route path from aggregator API (EVM format)
+ */
+export declare interface ApiRoutePath {
+    /** Pool contract address */
+    pool: string;
+    /** Provider name (e.g., "PANCAKEV3") */
+    provider: Provider;
+    /** Adapter contract address */
+    adapter: string;
+    /** Input token address */
+    token_in: string;
+    /** Output token address */
+    token_out: string;
+    /** Swap direction (true = token0 -> token1) */
+    direction: boolean;
+    /** Fee rate (e.g., "0.0005" for 0.05%) */
+    fee_rate: string;
+    /** Input amount (string to support u128) */
+    amount_in: string;
+    /** Output amount (string to support u128) */
+    amount_out: string;
+    /** Extra data for adapter (hex encoded) */
+    extra_data?: string;
+}
+
+/**
+ * Status API response data
+ */
+export declare interface ApiStatusData {
+    /** Available liquidity providers */
+    providers: string[];
+    /** Chain sync status for each provider */
+    chainflows: ChainflowStatus[];
+}
+
+/**
+ * Full status response
+ */
+export declare type ApiStatusResponse = ApiResponse<ApiStatusData>;
+
+export declare const BPS_DENOMINATOR = 10000n;
+
+export declare const BSC_MAINNET_CONFIG: PeachConfig;
+
+export declare const BSC_TESTNET_CONFIG: PeachConfig;
+
+/**
+ * Chainflow sync status for a provider
+ */
+export declare interface ChainflowStatus {
+    /** Provider name (e.g., "PANCAKEV3") */
+    provider: string;
+    /** Current sync transaction cursor (tx hash) */
+    tx_cursor: string | null;
+    /** Sync version info */
+    version: {
+        /** Latest synced block number */
+        latest_block_number: number;
+        /** Latest synced transaction index in that block */
+        latest_transaction_index: number;
+    };
+    /** Last update timestamp in milliseconds */
+    update_at: number;
+}
+
+export declare const DEFAULT_DEADLINE_SECONDS = 1200;
+
+export declare const DEFAULT_EXECUTE_TIMEOUT_MS = 60000;
+
+/**
+ * Peach Aggregator SDK Types
+ *
+ * Simplified design: only supports linear execution + topological sort + pool merging
+ */
+export declare const DEFAULT_SLIPPAGE_BPS = 50;
+
+export declare const DEFAULT_TRANSACTION_RESPONSE_POLL_INTERVALS_MS: readonly [50, 100, 200, 400, 800, 1200];
+
+/** API returned route paths where all paths have zero amounts */
+export declare const ERR_ZERO_AMOUNT_PATHS = 4001;
+
+export declare interface ExecuteOptions extends SwapOptions {
+    /** Skip the preflight eth_call simulation before sending (default: false).
+     *  Set to true only if you've already called simulate() and confirmed the route is valid. */
+    skipPreflight?: boolean;
+    /** Timeout in milliseconds for the wallet to sign & broadcast the transaction.
+     *  If the wallet does not settle the Promise within this duration, execute() rejects
+     *  with a timeout error so the caller is not stuck on "Pending Wallet Signature" forever.
+     *  Default: 60_000 (60 seconds). Set to 0 to disable. */
+    timeoutMs?: number;
+    /** Polling intervals for getTransaction(hash) after the wallet returns a tx hash.
+     *  Defaults to [50, 100, 200, 400, 800, 1200]ms and then repeats the last value. */
+    transactionResponsePollingIntervalsMs?: readonly number[];
+}
+
+export declare class ExecuteTimeoutError extends Error {
+    readonly txHash?: string;
+    readonly stage: ExecuteTimeoutStage;
+    constructor(message: string, stage: ExecuteTimeoutStage, txHash?: string);
+}
+
+export declare type ExecuteTimeoutStage = "wallet_send" | "provider_index";
+
+/** Result of findFailingStep: which step index and step caused the revert */
+export declare interface FindFailingStepResult {
+    stepIndex: number;
+    step: SwapStep;
+    error: unknown;
+    /** Revert reason when simulating only up to this step (may differ from full route) */
+    revertMessage?: string;
+    /** Revert reason from the full-route simulation, if fullRouteError was passed */
+    fullRouteRevertMessage?: string;
+}
+
+/**
+ * Check if an address is the native token sentinel address.
+ */
+export declare function isNativeTokenAddress(address: string): boolean;
+
+/**
+ * Known DEX providers supported by the SDK.
+ */
+export declare type KnownProvider = "PANCAKEV2" | "PANCAKEV3" | "UNISWAPV3" | "DODO" | "THENA";
+
+/**
+ * Sentinel address indicating native token (e.g. BNB on BSC).
+ * Pass this as srcToken/dstToken to distinguish native BNB from WBNB ERC20.
+ */
+export declare const NATIVE_TOKEN_ADDRESS = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+
+export declare class PeachClient {
+    private provider;
+    private config;
+    private routerContract;
+    private apiClient;
+    constructor(config: PeachConfig, provider?: ethers.Provider, options?: PeachClientOptions);
+    /**
+     * Get the effective router address for a quote.
+     */
+    private getRouterAddress;
+    /**
+     * Apply slippage to swap params, returning a new SwapParams with adjusted amountOutMin
+     */
+    private applySlippage;
+    /**
+     * Build transaction requests for an approval (if needed) and the swap itself.
+     */
+    swap(quote: Quote, ownerAddress: string, options: SwapOptions): Promise<SwapRequest>;
+    /**
+     * Execute swap using the legacy signer-managed flow.
+     *
+     * @deprecated Prefer swap(), then send the returned tx request with your wallet/client.
+     */
+    execute(quote: Quote, signer: ethers.Signer, options: ExecuteOptions): Promise<ethers.TransactionResponse>;
+    /**
+     * Encode parameters to contract format
+     */
+    private encodeParams;
+    private getProtocolForProvider;
+    /**
+     * Encode swap calldata for the Peach Aggregator contract
+     * Useful for simulation or building custom transactions
+     *
+     * @param quote - Quote object from getQuote
+     * @param slippageBps - Slippage tolerance in basis points (e.g. 50 = 0.5%). Required.
+     * @returns Encoded calldata and transaction info (to address, value)
+     */
+    encodeSwapCalldata(quote: Quote, slippageBps: number): {
+        to: string;
+        data: string;
+        value: bigint;
+        method: 'swap' | 'swapETH';
+    };
+    private buildSwapTransactionRequest;
+    private buildApprovalRequest;
+    private buildApprovalTransactionRequest;
+    private getAllowance;
+    private applyTxOverrides;
+    private sendTransactionWithTimeout;
+    private waitForTransactionResponse;
+    private delay;
+    private getNextPollingDelay;
+    /**
+     * Get token metadata and, optionally, the balance for a specific owner.
+     */
+    getTokenInfo(tokenAddress: string, ownerAddress?: string): Promise<{
+        symbol: string;
+        decimals: number;
+        balance?: bigint;
+    }>;
+    /**
+     * Get user token balance
+     */
+    getBalance(tokenAddress: string, userAddress: string): Promise<bigint>;
+    /**
+     * Get quote via API
+     * @throws Error if API client is not configured
+     */
+    getQuote(params: {
+        srcToken: string;
+        dstToken: string;
+        amountIn: bigint;
+        options?: QuoteOptions;
+    }): Promise<Quote>;
+    /**
+     * Filter paths by allowed providers, removing paths with disallowed providers
+     * and cascade-removing orphaned paths that depend on removed paths.
+     */
+    private filterPathsByProviders;
+    /**
+     * Build Quote from route data (e.g. from JSON file or API response).
+     * Use this to simulate a swap from a pre-computed route without calling the API.
+     *
+     * @param data - Route data with paths, amount_in, amount_out, contracts, gas
+     * @param srcToken - Source token address (first path token_in)
+     * @param dstToken - Destination token address (last path token_out)
+     * @param deadlineSeconds - Optional deadline in seconds from now (default: 20 min)
+     */
+    buildQuoteFromRouteData(data: ApiFindRouteData, srcToken: string, dstToken: string, deadlineSeconds?: number, options?: {
+        srcNative?: boolean;
+        dstNative?: boolean;
+    }): Quote;
+    /**
+     * Build Quote from API response
+     */
+    private buildQuoteFromApi;
+    private buildQuoteFromRouteDataInternal;
+    /**
+     * Get available providers from the API
+     * @throws Error if API client is not configured
+     */
+    getAvailableProviders(): Promise<string[]>;
+    /**
+     * Simulate swap via eth_call (no gas, no state change)
+     * Useful for testing and verifying quote accuracy
+     *
+     * @param quote - Quote object from getQuote
+     * @param slippageBps - Slippage tolerance in basis points (e.g. 50 = 0.5%). Required.
+     * @param fromAddress - Optional caller address for simulation (default: zero address)
+     * @param stateOverrides - Optional state overrides for ERC20 balance/allowance
+     * @returns Simulated amountOut and method used
+     */
+    simulate(quote: Quote, slippageBps: number, fromAddress?: string, stateOverrides?: Record<string, {
+        stateDiff: Record<string, string>;
+    }>): Promise<{
+        amountOut: bigint;
+        method: 'swap' | 'swapETH';
+    }>;
+    private getJsonRpcProviderForStateOverrides;
+    /**
+     * Format simulate error with human-readable details
+     */
+    private formatSimulateError;
+    /**
+     * Find which step in the route causes the same revert as the full route (e.g. MUL_ERROR).
+     * Simulates with steps [0..1], [0..2], ... and returns the first step whose revert
+     * matches fullRouteError. Ignores steps that revert with a different reason (e.g. unknown custom error).
+     *
+     * @param quote - Full quote from getQuote (the one that fails when simulated)
+     * @param slippageBps - Same as for simulate
+     * @param fromAddress - Same as for simulate
+     * @param stateOverrides - Same as for simulate (use when simulating ERC20 sell with arbitrary address)
+     * @param fullRouteError - The error from simulating the full route. Required so we match by revert reason (e.g. "MUL_ERROR"); only the step that produces the same reason is returned.
+     * @returns The step index and step details whose revert matches fullRouteError, or null if none match or full route succeeds
+     */
+    findFailingStep(quote: Quote, slippageBps: number, fromAddress?: string, stateOverrides?: Record<string, {
+        stateDiff: Record<string, string>;
+    }>, fullRouteError?: unknown): Promise<FindFailingStepResult | null>;
+    /** Extract a comparable revert reason (e.g. "MUL_ERROR") from an error for findFailingStep matching. */
+    private normalizeRevertReason;
+    /** Build a quote that only includes the first stepCount steps (for findFailingStep). */
+    private quoteWithFirstNSteps;
+    /**
+     * Build state overrides for ERC20 token balance and allowance.
+     * Useful for simulating swaps without actual on-chain token balance/approval.
+     *
+     * Automatically covers multiple storage slot layouts (slots 0-2 for balance,
+     * slots 0-7 for allowance) to handle OZ ERC20 (slot 0/1), Ownable+ERC20 (slot 1/2),
+     * and other common BSC token implementations.
+     *
+     * WBNB (native wrap) is skipped automatically — swapETH wraps msg.value
+     * internally so no ERC20 approval from the sender is needed.
+     *
+     * @param tokenAddress - ERC20 token address (WBNB returns empty overrides)
+     * @param owner - Address that needs the balance and allowance
+     * @param routerAddress - Router address (used as fallback spender)
+     * @param balance - Balance to inject (default: 1M tokens with 18 decimals)
+     * @param spenderAddress - Spender to approve (default: routerAddress). Pass quote.routerAddress when simulating API quotes.
+     */
+    buildStateOverrides(tokenAddress: string, owner: string, routerAddress: string, balance?: bigint, spenderAddress?: string, options?: {
+        isNative?: boolean;
+    }): Record<string, {
+        stateDiff: Record<string, string>;
+    }>;
+}
+
+export declare interface PeachClientOptions {
+    /** API client configuration. Required for getQuote(). */
+    api?: ApiClientConfig;
+}
+
+export declare interface PeachConfig {
+    chainId: number;
+    rpcUrl: string;
+    /** Router address override. If not provided, uses the address from API response. */
+    routerAddress?: string;
+    weth: string;
+    adapters: AdapterConfig[];
+}
+
+export declare interface PoolInfo {
+    address: string;
+    token0: string;
+    token1: string;
+    protocol: ProtocolType;
+    reserve0?: bigint;
+    reserve1?: bigint;
+    fee?: number;
+    liquidity?: bigint;
+    sqrtPriceX96?: bigint;
+    tick?: number;
+}
+
+export declare enum ProtocolType {
+    PancakeV2 = "PancakeV2",
+    PancakeV3 = "PancakeV3",
+    UniswapV3 = "UniswapV3",
+    Dodo = "Dodo",
+    Thena = "Thena"
+}
+
+/**
+ * Supported DEX providers.
+ * Use getAvailableProviders() to get the list dynamically.
+ */
+export declare type Provider = KnownProvider | (string & {});
+
+export declare interface Quote {
+    srcToken: string;
+    dstToken: string;
+    amountIn: bigint;
+    amountOut: bigint;
+    priceImpact: number;
+    route: SplitRoute;
+    params: SwapParams;
+    gasEstimate: bigint;
+    /** Router contract address from quote API (contracts.router). When set, simulate/execute use this instead of config.routerAddress. */
+    routerAddress?: string;
+    /** True when the original srcToken was the native token sentinel address */
+    srcNative?: boolean;
+    /** True when the original dstToken was the native token sentinel address */
+    dstNative?: boolean;
+}
+
+/**
+ * SDK-level quote request options
+ */
+export declare interface QuoteOptions {
+    /** true: calculate output from input; false: calculate input from output (default: true) */
+    byAmountIn?: boolean;
+    /** Route search depth / max hops (default: 3) */
+    depth?: number;
+    /** Trade split count for large trades optimization (default: 20) */
+    splitCount?: number;
+    /** DEX providers to use (default: ["PANCAKEV2", "PANCAKEV3"]) */
+    providers?: Provider[];
+    /** Transaction deadline in seconds from now (default: 1200 = 20 min) */
+    deadlineSeconds?: number;
+}
+
+export declare interface Route {
+    steps: RouteStep[];
+    amountIn: bigint;
+    amountOut: bigint;
+    gasEstimate: bigint;
+}
+
+export declare class RouteDiscovery {
+    private provider;
+    private config;
+    private v2Factory;
+    private v3Factory;
+    private poolCache;
+    constructor(provider: ethers.Provider, config: PeachConfig);
+    /**
+     * Discover optimal route
+     */
+    findBestRoute(srcToken: string, dstToken: string, amountIn: bigint): Promise<SplitRoute>;
+    /**
+     * Discover available pools (direct path)
+     */
+    private discoverPools;
+    /**
+     * Find V2 pool
+     */
+    private findV2Pool;
+    /**
+     * Find V3 pool
+     */
+    private findV3Pool;
+    /**
+     * Calculate route quotes
+     */
+    private calculateRoutes;
+    /**
+     * Get output for a single pool
+     */
+    private getAmountOut;
+    /**
+     * V2 output calculation
+     */
+    private getV2AmountOut;
+    /**
+     * V3 output estimation (simplified)
+     */
+    private estimateV3AmountOut;
+    /**
+     * Clear cache
+     */
+    clearCache(): void;
+}
+
+export declare interface RouteStep {
+    pool: PoolInfo;
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: bigint;
+    amountOut: bigint;
+}
+
+export declare interface SplitRoute {
+    routes: Route[];
+    percentages: number[];
+    totalAmountIn: bigint;
+    totalAmountOut: bigint;
+    totalGasEstimate: bigint;
+}
+
+export declare interface SwapApprovalRequest {
+    token: string;
+    owner: string;
+    spender: string;
+    currentAllowance: bigint;
+    requiredAmount: bigint;
+    approveAmount: bigint;
+    tx: SwapTxRequest;
+}
+
+export declare class SwapBuilder {
+    private adapters;
+    constructor(adapters: Map<ProtocolType, string>);
+    /**
+     * Build SwapParams from split route
+     */
+    build(splitRoute: SplitRoute, srcToken: string, dstToken: string, amountOutMin: bigint, deadlineSeconds?: number): SwapParams;
+    /**
+     * Flatten split route
+     */
+    private flattenRoutes;
+    /**
+     * Merge identical pools
+     * Key: pool + tokenIn + tokenOut
+     */
+    private mergeIdenticalPools;
+    /**
+     * Topological sort (Kahn's Algorithm)
+     */
+    private topologicalSort;
+    /**
+     * Convert to contract SwapStep format
+     */
+    private convertToSwapSteps;
+    /**
+     * Encode protocol-specific parameters
+     */
+    private encodeExtraData;
+    /**
+     * Extract intermediate tokens
+     */
+    private extractIntermediates;
+    /**
+     * Generate unique step key
+     */
+    private stepKey;
+}
+
+export declare interface SwapOptions {
+    /** Slippage tolerance in basis points (e.g. 50 = 0.5%). Required. */
+    slippageBps: number;
+    /** Gas price in wei. Applied to the swap tx and, if present, the approval tx. */
+    gasPrice?: bigint;
+    /** Gas limit for the swap tx. */
+    gasLimit?: bigint;
+}
+
+export declare interface SwapParams {
+    srcToken: string;
+    dstToken: string;
+    amountIn: bigint;
+    amountOutMin: bigint;
+    steps: SwapStep[];
+    intermediateTokens: string[];
+    deadline: bigint;
+    quoteId: string;
+    expectAmountOut: bigint;
+}
+
+export declare interface SwapRequest {
+    routerAddress: string;
+    method: "swap" | "swapETH";
+    tx: SwapTxRequest;
+    approval?: SwapApprovalRequest;
+}
+
+export declare interface SwapResult {
+    txHash: string;
+    amountIn: bigint;
+    amountOut: bigint;
+    gasUsed: bigint;
+}
+
+export declare interface SwapStep {
+    adapter: string;
+    pool: string;
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: bigint;
+    extraData: string;
+}
+
+export declare interface SwapTxRequest {
+    to: string;
+    data: string;
+    value: bigint;
+    gasPrice?: bigint;
+    gasLimit?: bigint;
+}
+
+export declare function withWalletSendTimeout<T>(promise: Promise<T>, timeoutMs?: number): Promise<T>;
+
+export { }