@peachprojects/aggregator-sdk 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -22,18 +22,19 @@ export declare const API_DEFAULTS: {
 export declare class ApiClient {
     private baseUrl;
     private timeout;
+    private extraHeaders;
     constructor(config?: ApiClientConfig);
     /**
      * Find optimal routes via API
      */
-    findRoutes(params: {
-        from: string;
-        target: string;
-        amount: bigint;
-        byAmountIn?: boolean;
-        depth?: number;
-        splitCount?: number;
-        providers?: Provider[];
+    findRoutes(params: FindRoutesParams & {
+        includeResponseHeaders: true;
+    }): Promise<{
+        data: ApiFindRouteData;
+        responseHeaders: Record<string, string>;
+    }>;
+    findRoutes(params: FindRoutesParams & {
+        includeResponseHeaders?: false;
     }): Promise<ApiFindRouteData>;
     /**
      * Get service status including available providers
@@ -58,6 +59,8 @@ export declare interface ApiClientConfig {
     baseUrl?: string;
     /** Request timeout in ms (default: 10000) */
     timeout?: number;
+    /** Extra HTTP headers to send with every request (e.g. `Cookie` for gated staging environments). */
+    headers?: Record<string, string>;
 }
 
 /**
@@ -128,6 +131,20 @@ export declare interface ApiFindRouteRequest {
  */
 export declare type ApiFindRouteResponse = ApiResponse<ApiFindRouteData>;
 
+/**
+ * PeachRouter fee configuration snapshot served by the aggregator `/router/status`
+ * endpoint. Lets clients discover the router address and current fee caps without
+ * a separate on-chain read.
+ */
+export declare interface ApiPeachRouterConfig {
+    /** Deployed PeachRouter contract address the aggregator routes through. */
+    router_address: string;
+    /** Current upper bound on `CustomFee.feeBps` the router will accept (bps). */
+    max_custom_fee_bps: number;
+    /** Current upper bound on the protocol's share of the custom fee (bps of the custom fee). */
+    max_protocol_cut_bps: number;
+}
+
 /**
  * Aggregator API response wrapper
  */
@@ -171,6 +188,8 @@ export declare interface ApiStatusData {
     providers: string[];
     /** Chain sync status for each provider */
     chainflows: ChainflowStatus[];
+    /** PeachRouter address + fee-cap configuration. */
+    peach_router: ApiPeachRouterConfig;
 }
 
 /**
@@ -203,6 +222,32 @@ export declare interface ChainflowStatus {
     update_at: number;
 }
 
+/**
+ * Custom-fee configuration. Pass via `QuoteOptions.customFee` to charge an
+ * additional fee on top of the swap output, sent atomically by the on-chain router.
+ *
+ * Note: the Peach protocol takes a configurable share of this fee (owner-settable,
+ * default 20%, capped by the owner-settable `maxProtocolCutBps`). The `feeBps` you
+ * set here is the TOTAL fee charged to the user — integrator and protocol split
+ * that total according to the router's `protocolCutBps()` at execution time. Use
+ * `PeachClient.getRouterConfig()` (or `getProtocolFeeConfig()` for just the split)
+ * to read the current values so the UI can display "X bps integrator / Y bps protocol".
+ */
+export declare interface CustomFee {
+    /** Address that receives the integrator's share of the custom fee (paid in dstToken, or native BNB when dstToken is native). */
+    feeAccount: string;
+    /** Total custom fee in basis points (1 bps = 0.01%). Must be in `[1, maxCustomFeeBps]` as read from the router. */
+    feeBps: number;
+}
+
+/**
+ * Thrown when a custom-fee configuration is invalid (bad bps or feeAccount).
+ * Surfaced before any RPC round-trip so integrators get an actionable error.
+ */
+export declare class CustomFeeError extends Error {
+    constructor(message: string);
+}
+
 /**
  * Peach Aggregator SDK Types
  *
@@ -254,6 +299,17 @@ export declare interface FindFailingStepResult {
     fullRouteRevertMessage?: string;
 }
 
+export declare type FindRoutesParams = {
+    from: string;
+    target: string;
+    amount: bigint;
+    byAmountIn?: boolean;
+    depth?: number;
+    splitCount?: number;
+    providers?: Provider[];
+    includeResponseHeaders?: boolean;
+};
+
 /**
  * Check if an address is the native token sentinel address.
  */
@@ -262,7 +318,28 @@ export declare function isNativeTokenAddress(address: string): boolean;
 /**
  * Known DEX providers supported by the SDK.
  */
-export declare type KnownProvider = "PANCAKEV2" | "PANCAKEV3" | "PANCAKE_INFINITY_CL" | "UNISWAPV3" | "UNISWAPV4" | "DODO" | "THENA";
+export declare type KnownProvider = "PANCAKEV2" | "PANCAKEV3" | "PANCAKE_INFINITY_CL" | "UNISWAPV3" | "UNISWAPV4" | "DODO" | "THENA" | "NOMISWAP_STABLE" | "BISWAP" | "APESWAP" | "BABYDOGESWAP" | "BABYSWAP";
+
+/**
+ * Client-side default cap on the integrator-set custom fee. Mirrors the PeachRouter v2
+ * deploy-time initial value of `maxCustomFeeBps` (500 bps = 5%).
+ *
+ * IMPORTANT: In PeachRouter v2 the cap is an OWNER-SETTABLE state variable in [0, 10_000]
+ * bps, not a bytecode constant. This SDK constant is only a convenience default for
+ * pre-RPC validation; callers that need the live value must read it via
+ * `PeachClient.getRouterConfig()` and validate `customFee.feeBps <= maxCustomFeeBps`.
+ */
+export declare const MAX_FEE_BPS = 500;
+
+/**
+ * Client-side default cap on the protocol's share of the custom fee. Mirrors the
+ * PeachRouter v2 deploy-time initial value of `maxProtocolCutBps` (5_000 bps = 50%).
+ *
+ * IMPORTANT: In PeachRouter v2 this is an OWNER-SETTABLE state variable in [0, 10_000]
+ * bps — the owner (Safe multisig) can raise it up to 100%. UIs that want the live
+ * value must read it from the chain via `PeachClient.getRouterConfig()`.
+ */
+export declare const MAX_PLATFORM_CUT_BPS = 5000;
 
 /**
  * Sentinel address indicating native token (e.g. BNB on BSC).
@@ -337,6 +414,7 @@ export declare class PeachClient {
     /**
      * Get quote via API
      * @throws Error if API client is not configured
+     * @throws CustomFeeError if `options.customFee` is malformed
      */
     getQuote(params: {
         srcToken: string;
@@ -344,6 +422,53 @@ export declare class PeachClient {
         amountIn: bigint;
         options?: QuoteOptions;
     }): Promise<Quote>;
+    /**
+     * Validate custom-fee configuration. Pure / static so callers (tests, custom flows)
+     * can reuse it. Throws CustomFeeError on any violation; returns silently for valid input.
+     */
+    static validateCustomFee(customFee?: CustomFee): void;
+    /**
+     * Resolve the router address for read methods: argument → quote.routerAddress →
+     * config.routerAddress. Throws when none is available so callers never silently
+     * read from the zero address.
+     */
+    private resolveRouterAddress;
+    /**
+     * Read the protocol-cut configuration from a deployed PeachRouter. Useful for
+     * displaying "X bps integrator / Y bps protocol" before the user signs.
+     *
+     * Values are mutable on-chain — the router owner (Safe) can change them at any
+     * time. Re-read before each swap if your UI needs exact numbers on the signing
+     * screen.
+     *
+     * @param routerAddress Optional router address. Defaults to `config.routerAddress`.
+     *                      Pass an explicit address when reading from a different deployment.
+     */
+    getProtocolFeeConfig(routerAddress?: string): Promise<ProtocolFeeConfig>;
+    /**
+     * @deprecated Use {@link getProtocolFeeConfig}. Kept as an alias for the pre-v2 name.
+     *             The returned object now uses the `ProtocolFeeConfig` field names
+     *             (`protocolFeeReceiver` / `protocolCutBps`).
+     */
+    getPlatformConfig(routerAddress?: string): Promise<ProtocolFeeConfig>;
+    /**
+     * Read the full PeachRouter configuration in a single batched call: identity
+     * (WETH / owner / pendingOwner), emergency state (`paused`), fee caps
+     * (`maxCustomFeeBps`, `maxProtocolCutBps`), and protocol-cut split
+     * (`protocolFeeReceiver`, `protocolCutBps`).
+     *
+     * Intended for:
+     *  - Verifying a deployment before the UI surfaces swap flows.
+     *  - Pre-swap checks: reject quotes when `paused == true` or when the requested
+     *    `customFee.feeBps` exceeds the live `maxCustomFeeBps`.
+     *  - Showing the integrator / protocol fee split on the signing screen.
+     *
+     * All fields reflect on-chain state AT READ TIME — the owner (Safe) can mutate
+     * caps, the pause flag, and protocol-fee configuration at any time.
+     *
+     * @param routerAddress Optional router address. Defaults to `config.routerAddress`.
+     */
+    getRouterConfig(routerAddress?: string): Promise<RouterConfig>;
     /**
      * Filter paths by allowed providers, removing paths with disallowed providers
      * and cascade-removing orphaned paths that depend on removed paths.
@@ -450,6 +575,9 @@ export declare interface PeachConfig {
     adapters: AdapterConfig[];
 }
 
+/** @deprecated Use {@link ProtocolFeeConfig}. Kept as an alias for the pre-v2 name. */
+export declare type PlatformConfig = ProtocolFeeConfig;
+
 export declare interface PoolInfo {
     address: string;
     token0: string;
@@ -463,6 +591,18 @@ export declare interface PoolInfo {
     tick?: number;
 }
 
+/**
+ * On-chain protocol-cut configuration as read from the deployed PeachRouter.
+ * Returned by `PeachClient.getProtocolFeeConfig()` so UIs can display the integrator /
+ * protocol split of the custom fee before signing.
+ */
+export declare interface ProtocolFeeConfig {
+    /** Recipient of the protocol's portion. `ethers.ZeroAddress` means the cut is disabled and the entire custom fee flows to the integrator. */
+    protocolFeeReceiver: string;
+    /** Protocol's share of the custom fee, in basis points OF THE CUSTOM FEE (not of the swap output). */
+    protocolCutBps: number;
+}
+
 export declare enum ProtocolType {
     PancakeV2 = "PancakeV2",
     PancakeV3 = "PancakeV3",
@@ -470,7 +610,12 @@ export declare enum ProtocolType {
     UniswapV3 = "UniswapV3",
     UniswapV4 = "UniswapV4",
     Dodo = "Dodo",
-    Thena = "Thena"
+    Thena = "Thena",
+    NomiswapStable = "Nomiswap_Stable",
+    Biswap = "Biswap",
+    Apeswap = "Apeswap",
+    BabyDogeSwap = "BabyDogeSwap",
+    BabySwap = "BabySwap"
 }
 
 /**
@@ -483,6 +628,10 @@ export declare interface Quote {
     srcToken: string;
     dstToken: string;
     amountIn: bigint;
+    /**
+     * User-perceived dstToken output AFTER custom fee deduction.
+     * The gross figure (before fee) is available at `route.totalAmountOut`.
+     */
     amountOut: bigint;
     priceImpact: number;
     route: SplitRoute;
@@ -494,6 +643,21 @@ export declare interface Quote {
     srcNative?: boolean;
     /** True when the original dstToken was the native token sentinel address */
     dstNative?: boolean;
+    /**
+     * HTTP response headers from the find_routes API call.
+     * Only set when `getQuote` was called with `options.includeResponseHeaders: true`.
+     */
+    responseHeaders?: Record<string, string>;
+    /**
+     * Custom-fee summary, populated when `getQuote` was called with `options.customFee`.
+     * Surfaces what was actually requested (account/bps) and the projected feeAmount in
+     * dstToken so the UI can display "X% custom fee → Y dstToken" before signing.
+     */
+    customFee?: {
+        feeAccount: string;
+        feeBps: number;
+        feeAmount: bigint;
+    };
 }
 
 /**
@@ -510,6 +674,18 @@ export declare interface QuoteOptions {
     providers?: Provider[];
     /** Transaction deadline in seconds from now (default: 1200 = 20 min) */
     deadlineSeconds?: number;
+    /**
+     * When true, the returned `Quote` includes `responseHeaders` with all HTTP response headers from find_routes.
+     * Default false — headers are omitted to keep payloads small.
+     */
+    includeResponseHeaders?: boolean;
+    /**
+     * Optional custom-fee configuration. When set, an additional fee in basis points
+     * is taken from the dstToken output and sent atomically to `customFee.feeAccount`
+     * by the on-chain router. The user receives `amountOut * (1 - feeBps/10000)`.
+     * Capped at `MAX_FEE_BPS` (500 bps = 5%).
+     */
+    customFee?: CustomFee;
 }
 
 export declare interface Route {
@@ -521,11 +697,11 @@ export declare interface Route {
 
 export declare class RouteDiscovery {
     private provider;
-    private config;
     private v2Factory;
     private v3Factory;
+    private babySwapFactory;
     private poolCache;
-    constructor(provider: ethers.Provider, config: PeachConfig);
+    constructor(provider: ethers.Provider, _config: PeachConfig);
     /**
      * Discover optimal route
      */
@@ -542,6 +718,10 @@ export declare class RouteDiscovery {
      * Find V3 pool
      */
     private findV3Pool;
+    /**
+     * Find BabySwap pool (V2 fork, 0.2% fee)
+     */
+    private findBabySwapPool;
     /**
      * Calculate route quotes
      */
@@ -554,6 +734,10 @@ export declare class RouteDiscovery {
      * V2 output calculation
      */
     private getV2AmountOut;
+    /**
+     * BabySwap output calculation (V2 fork, 0.2% fee — coefficient 2 in 1000-scale)
+     */
+    private getBabySwapAmountOut;
     /**
      * V3 output estimation (simplified)
      */
@@ -564,6 +748,33 @@ export declare class RouteDiscovery {
     clearCache(): void;
 }
 
+/**
+ * Full PeachRouter configuration snapshot. Returned by `PeachClient.getRouterConfig()`
+ * so UIs and integrators can verify router identity, fee caps, pause status, and
+ * current protocol-fee split in a single batched read.
+ *
+ * All fields reflect on-chain state AT READ TIME — the owner (Safe multisig) can
+ * mutate caps, the pause flag, and the protocol-fee configuration at any time.
+ */
+export declare interface RouterConfig {
+    /** Router contract address this snapshot was read from. */
+    address: string;
+    /** Wrapped native-token address bound at deployment (WBNB on BSC). Immutable. */
+    weth: string;
+    /** Current owner (Ownable2Step). Typically the Peach Safe multisig. */
+    owner: string;
+    /** Pending owner from an in-flight `transferOwnership`; `ethers.ZeroAddress` when none. */
+    pendingOwner: string;
+    /** Emergency pause flag; when true `swap` / `swapETH` revert with `RouterPaused`. */
+    paused: boolean;
+    /** Active cap on `CustomFee.feeBps`. Owner-settable in [0, 10_000] bps. */
+    maxCustomFeeBps: number;
+    /** Active cap on `protocolCutBps`. Owner-settable in [0, 10_000] bps. */
+    maxProtocolCutBps: number;
+    /** Protocol-cut configuration (receiver + bps split of the custom fee). */
+    protocolFee: ProtocolFeeConfig;
+}
+
 export declare interface RouteStep {
     pool: PoolInfo;
     tokenIn: string;
@@ -641,12 +852,30 @@ export declare interface SwapParams {
     srcToken: string;
     dstToken: string;
     amountIn: bigint;
+    /**
+     * Minimum dstToken the user is willing to receive AFTER custom fee deduction.
+     * Slippage protection applies to the user-perceived amount, not the gross output.
+     */
     amountOutMin: bigint;
     steps: SwapStep[];
     intermediateTokens: string[];
     deadline: bigint;
     quoteId: string;
+    /**
+     * Off-chain pre-calculated expected output AFTER custom fee (0 if unused).
+     */
     expectAmountOut: bigint;
+    /**
+     * Custom-fee recipient address. Ignored when `feeBps == 0`.
+     * Use `ethers.ZeroAddress` when no custom fee is configured.
+     */
+    feeReceiver: string;
+    /**
+     * Custom fee in basis points, capped at `MAX_FEE_BPS` (500 = 5%).
+     * The fee is taken from dstToken output before reaching the user; the on-chain
+     * router further splits it between the integrator and the platform.
+     */
+    feeBps: number;
 }
 
 export declare interface SwapRequest {