four-flap-meme-sdk 3.0.0 → 4.0.0

package/dist/chains/xlayer/eoa/eoa-types.d.ts

@@ -0,0 +1,776 @@
+/**
+ * XLayer SDK — EOA/交易参数与结果类型
+ *
+ * 包含买入/卖出/换手/刷量/DEX 交易/预授权/买到毕业等交易参数与结果类型
+ */
+import type { HandleOpsResult, XLayerConfig } from './aa-types.js';
+/**
+ * 买入参数
+ */
+export interface BuyParams {
+    /** Flap 代币地址 */
+    tokenAddress: string;
+    /** 买入金额（OKB，字符串格式） */
+    amountOkb: string;
+    /** 最小输出代币数量（默认 0） */
+    minOutputAmount?: bigint;
+    /** 滑点基点（默认 100 = 1%） */
+    slippageBps?: number;
+}
+/**
+ * 卖出参数
+ */
+export interface SellParams {
+    /** Flap 代币地址 */
+    tokenAddress: string;
+    /** 卖出代币数量（可选，默认全部） */
+    amount?: bigint;
+    /** 卖出比例（0-100，如 50 表示卖出 50%） */
+    sellPercent?: number;
+    /** 最小输出 OKB 数量（默认 0） */
+    minOutputAmount?: bigint;
+    /** 滑点基点（默认 100 = 1%） */
+    slippageBps?: number;
+}
+/**
+ * 捆绑买入参数
+ */
+export interface BundleBuyParams {
+    /** 代币地址 */
+    tokenAddress: string;
+    /** Owner 私钥列表 */
+    privateKeys: string[];
+    /** 每个 owner 的买入金额（OKB 或 quoteToken，取决于 quoteToken 参数） */
+    buyAmounts: string[];
+    /** 买入使用的代币地址（零地址表示使用原生代币 OKB，非零地址表示使用 ERC20 代币如 USDC） */
+    quoteToken?: string;
+    /** quoteToken 的精度（默认 18，如果 quoteToken 不是 18 位精度需要指定） */
+    quoteTokenDecimals?: number;
+    /** 是否将代币转回 owner EOA（默认 false） */
+    transferBackToOwner?: boolean;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+}
+/**
+ * 捆绑卖出参数
+ */
+export interface BundleSellParams {
+    /** 代币地址 */
+    tokenAddress: string;
+    /** Owner 私钥列表 */
+    privateKeys: string[];
+    /** 卖出比例（0-100，默认 100 全部卖出） */
+    sellPercent?: number;
+    /** 是否将 OKB 归集回 owner EOA（默认 true） */
+    withdrawToOwner?: boolean;
+    /** 归集时保留的最小 OKB 余额 */
+    withdrawReserve?: string;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+}
+/**
+ * 捆绑买卖参数（先买后卖）
+ */
+export interface BundleBuySellParams {
+    /** 代币地址 */
+    tokenAddress: string;
+    /** Owner 私钥列表 */
+    privateKeys: string[];
+    /** 每个 owner 的買入金额（OKB 或 quoteToken，取决于 quoteToken 参数） */
+    buyAmounts: string[];
+    /** 买入使用的代币地址（零地址表示使用原生代币 OKB，非零地址表示使用 ERC20 代币如 USDC） */
+    quoteToken?: string;
+    /** quoteToken 的精度（默认 18，如果 quoteToken 不是 18 位精度需要指定） */
+    quoteTokenDecimals?: number;
+    /** 卖出比例（0-100，默认 100 全部卖出） */
+    sellPercent?: number;
+    /** 是否将 OKB 归集回 owner EOA（默认 true） */
+    withdrawToOwner?: boolean;
+    /** 归集时保留的最小 OKB 余额 */
+    withdrawReserve?: string;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+    /** LP 费率档位 (V3 专用): 0=STANDARD, 1=LOW, 2=HIGH */
+    lpFeeProfile?: number;
+    /** DEX 类型: 'V2' | 'V3' */
+    dexType?: 'V2' | 'V3';
+}
+/**
+ * 捆绑发射签名参数
+ */
+export interface BundleCreateBuySignParams {
+    /** 代币信息 */
+    tokenInfo: {
+        name: string;
+        symbol: string;
+        meta: string;
+    };
+    /** 预测的代币地址（可选，如果不传则内盘模式会自动根据 salt 预测） */
+    tokenAddress?: string;
+    /** 每个 owner 的买入金额（OKB，字符串格式） */
+    buyAmounts: string[];
+    /** Owner 私钥列表（第一个为 Dev，后续为买方） */
+    privateKeys: string[];
+    /** V2/V3/V4 参数 */
+    salt?: string;
+    dexThresh?: number;
+    taxRate?: number;
+    migratorType?: number;
+    quoteToken?: string;
+    quoteAmt?: bigint;
+    permitData?: string;
+    extensionID?: string;
+    extensionData?: string;
+    dexId?: number;
+    lpFeeProfile?: number;
+    /** 是否将 OKB 归集回 owner EOA（默认 true） */
+    withdrawToOwner?: boolean;
+    /** 归集时保留的最小 OKB 余额 */
+    withdrawReserve?: string;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+    /** Payer 私钥（用于签 handleOps 交易）；默认 privateKeys[0] */
+    payerPrivateKey?: string;
+    /** beneficiary（默认 payer 地址） */
+    beneficiary?: string;
+    /** 可选：指定 payer 起始 nonce（不传则用 pending nonce） */
+    payerStartNonce?: number;
+}
+/**
+ * 捆绑发射签名结果
+ */
+export interface BundleCreateBuySignResult {
+    /** raw signed tx 列表 */
+    signedTransactions: string[];
+    /** 代币地址 */
+    tokenAddress: string;
+    /** 元数据 */
+    metadata: {
+        tokenAddress: string;
+        devOwner: string;
+        devSender: string;
+        buyerOwners: string[];
+        buyerSenders: string[];
+        totalBuyWei: string;
+    };
+}
+/**
+ * 一键发射到外盘签名参数（AA 模式）
+ *
+ * 交易顺序：
+ * 1. handleOps #1: 创建代币 + 内盘买入（买到毕业）
+ * 2. handleOps #2: 外盘买入（通过 PotatoSwap V2）
+ * 3. 利润提取（EOA 转账）
+ */
+export interface BundleCreateToDexSignParams {
+    /** 代币信息 */
+    tokenInfo: {
+        name: string;
+        symbol: string;
+        meta: string;
+    };
+    /** 预计算的代币地址 */
+    tokenAddress: string;
+    /** Payer 私钥（支付 Gas，同时作为发币者） */
+    payerPrivateKey: string;
+    /** 内盘买入钱包私钥列表 */
+    curveBuyerPrivateKeys: string[];
+    /** 内盘买入金额列表（OKB，按顺序对应） */
+    curveBuyAmounts: string[];
+    /** 是否启用外盘买入（默认 false） */
+    enableDexBuy?: boolean;
+    /** 外盘买入钱包私钥列表（可与内盘钱包相同或不同） */
+    dexBuyerPrivateKeys?: string[];
+    /** 外盘买入金额列表（OKB） */
+    dexBuyAmounts?: string[];
+    /** V4 发币参数 */
+    salt?: string;
+    dexThresh?: number;
+    taxRate?: number;
+    migratorType?: number;
+    quoteToken?: string;
+    quoteAmt?: bigint;
+    beneficiary?: string;
+    permitData?: string;
+    extensionID?: string;
+    extensionData?: string;
+    dexId?: number;
+    lpFeeProfile?: number;
+    /** Payer 起始 nonce（不传则用 pending nonce） */
+    payerStartNonce?: number;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+}
+/**
+ * 一键发射到外盘签名结果
+ */
+export interface BundleCreateToDexSignResult {
+    /** raw signed tx 列表 */
+    signedTransactions: string[];
+    /** 代币地址 */
+    tokenAddress: string;
+    /** 元数据 */
+    metadata?: {
+        payerOwner: string;
+        payerSender: string;
+        curveBuyerCount: number;
+        curveTotalBuyWei: string;
+        enableDexBuy: boolean;
+        dexBuyerCount: number;
+        dexTotalBuyWei: string;
+        profitAmount?: string;
+    };
+}
+/**
+ * 捆绑换手参数（AA 模式，单卖单买）
+ * - 卖方 AA 先卖出
+ * - 买方 AA 再买入
+ * - 两个 UserOp（以及可选 approve）放入同一笔 handleOps
+ */
+export interface BundleSwapParams {
+    /** 交易类型：FLAP (内盘), V2 (外盘 V2), V3 (外盘 V3) */
+    tradeType?: 'FLAP' | 'V2' | 'V3';
+    /** DEX 标识（用于选择正确的 Router） */
+    dexKey?: string;
+    /** 显式指定 Router 地址（若不传则由 SDK 根据 dexKey 自动决定） */
+    routerAddress?: string;
+    /** LP 费率档位 (V3 专用): 0=STANDARD (0.25%), 1=LOW (0.01%), 2=HIGH (1%) */
+    lpFeeProfile?: number;
+    /** 代币地址 */
+    tokenAddress: string;
+    /** 卖方 Owner 私钥 */
+    sellerPrivateKey: string;
+    /** 买方 Owner 私钥 */
+    buyerPrivateKey: string;
+    /** 卖出数量（人类可读字符串，按代币 decimals 解析）；优先于 sellPercent */
+    sellAmount?: string;
+    /** 卖出比例（0-100，默认 100） */
+    sellPercent?: number;
+    /** ✅ ERC20 稳定币支持（对齐 BSC）：输出代币地址（如 USDT/USDC/USDT0），不传则使用原生代币 OKB */
+    quoteToken?: string;
+    /** ✅ ERC20 稳定币精度（默认 6，XLayer USDT/USDC/USDT0 都是 6 位精度） */
+    quoteTokenDecimals?: number;
+    /**
+     * 买入 OKB 数量（字符串）。
+     * - 不传则默认使用 previewSell(sellAmount) 的结果，并应用 slippageBps
+     */
+    buyAmountOkb?: string;
+    /** 预估卖出滑点（基点），默认 100 = 1%（用于 buyAmountOkb 未传入时） */
+    slippageBps?: number;
+    /**
+     * ✅ 转账多跳数（AA 专用，且与 BSC 的“多跳”逻辑相互独立）
+     *
+     * 用途：当卖出与买入不是同一个 AA(Sender) 时，需要把卖出得到的 OKB 先转到买方 AA(Sender) 才能执行 buy。
+     * - 0：卖方 AA(Sender) 直接转给买方 AA(Sender)
+     * - >0：按“多跳”方式转账（实现位于 xlayer/*，不会影响 BSC bundle/merkle）
+     */
+    disperseHopCount?: number;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+}
+/**
+ * 捆绑换手执行结果（链上执行 handleOps）
+ */
+export interface BundleSwapResult {
+    /** handleOps 交易结果 */
+    swapResult: HandleOpsResult;
+    /** 元数据（便于前端显示） */
+    metadata: {
+        sellerOwner: string;
+        sellerSender: string;
+        buyerOwner: string;
+        buyerSender: string;
+        sellAmountWei: string;
+        buyAmountWei: string;
+        hasApprove: boolean;
+        routeAddress?: string;
+        /** 是否提取利润 */
+        extractProfit?: boolean;
+        /** 利润比例 bps */
+        profitBps?: number;
+        /** 利润接收地址 */
+        profitRecipient?: string;
+        /** 预估利润（OKB wei） */
+        profitWei?: string;
+        /** 预估卖出输出（OKB wei） */
+        quotedSellOutWei?: string;
+        /** ✅ AA：转账多跳数（仅 xlayer AA 使用；不影响 BSC） */
+        disperseHopCount?: string;
+    };
+}
+/**
+ * 捆绑换手签名参数（仅签名 handleOps 交易；可选追加 route 尾交易）
+ * - 返回 raw signed tx，可按“BSC 捆绑”模式交给后端/Builder 提交
+ */
+export interface BundleSwapSignParams extends BundleSwapParams {
+    /** Payer 私钥（用于签 handleOps 交易）；默认 sellerPrivateKey */
+    payerPrivateKey?: string;
+    /** beneficiary（默认 payer 地址） */
+    beneficiary?: string;
+    /** 可选：指定 payer 起始 nonce（不传则用 pending nonce） */
+    payerStartNonce?: number;
+    /** 可选：覆盖 handleOps gasLimit（不传则自动 estimate，失败回退） */
+    handleOpsGasLimit?: bigint;
+    /**
+     * 可选：routeAddress（如果你的后端要求“route 尾交易”，则传入）
+     * - SDK 会自动构造 nonce+1 的空转账 tailTx
+     */
+    routeAddress?: string;
+}
+/**
+ * 捆绑换手签名结果
+ */
+export interface BundleSwapSignResult {
+    /** raw signed tx 列表（handleOps 在前；如果有 routeAddress 则 tailTx 在后） */
+    signedTransactions: string[];
+    /** 元数据（便于前端显示） */
+    metadata: {
+        payer: string;
+        beneficiary: string;
+        sellerOwner: string;
+        sellerSender: string;
+        buyerOwner: string;
+        buyerSender: string;
+        sellAmountWei: string;
+        buyAmountWei: string;
+        hasApprove: boolean;
+        routeAddress?: string;
+        /** 是否提取利润 */
+        extractProfit?: boolean;
+        /** 利润比例 bps */
+        profitBps?: number;
+        /** 利润接收地址 */
+        profitRecipient?: string;
+        /** 预估利润（OKB wei） */
+        profitWei?: string;
+        /** 预估卖出输出（OKB wei） */
+        quotedSellOutWei?: string;
+        /** ✅ AA：转账多跳数（仅 xlayer AA 使用；不影响 BSC） */
+        disperseHopCount?: string;
+    };
+}
+/**
+ * 批量捆绑换手参数（一卖多买）
+ */
+export interface BundleBatchSwapParams {
+    /** 交易类型：FLAP (内盘), V2 (外盘 V2), V3 (外盘 V3) */
+    tradeType?: 'FLAP' | 'V2' | 'V3';
+    /** DEX 标识（用于选择正确的 Router） */
+    dexKey?: string;
+    /** 显式指定 Router 地址（若不传则由 SDK 根据 dexKey 自动决定） */
+    routerAddress?: string;
+    /** LP 费率档位 (V3 专用): 0=STANDARD (0.25%), 1=LOW (0.01%), 2=HIGH (1%) */
+    lpFeeProfile?: number;
+    /** 代币地址 */
+    tokenAddress: string;
+    /** 卖方 Owner 私钥 */
+    sellerPrivateKey: string;
+    /** 买方 Owner 私钥列表 */
+    buyerPrivateKeys: string[];
+    /** 每个买方的买入 OKB 数量（字符串，长度必须与 buyerPrivateKeys 一致） */
+    buyAmountsOkb: string[];
+    /** 卖出数量（人类可读字符串，按代币 decimals 解析）；优先于 sellPercent */
+    sellAmount?: string;
+    /** 卖出比例（0-100，默认 100） */
+    sellPercent?: number;
+    /** ✅ ERC20 稳定币支持（对齐 BSC）：输出代币地址（如 USDT/USDC/USDT0），不传则使用原生代币 OKB */
+    quoteToken?: string;
+    /** ✅ ERC20 稳定币精度（默认 6，XLayer USDT/USDC/USDT0 都是 6 位精度） */
+    quoteTokenDecimals?: number;
+    /**
+     * ✅ 资金利用率模式（对齐 BSC）
+     * - true（默认）：卖出 → 分发 → 买入（资金来自卖出所得，对应 BSC flapQuickBatchSwapMerkle）
+     * - false：卖出 → 买入（买方自带资金，对应 BSC flapBatchSwapMerkle）
+     */
+    capitalMode?: boolean;
+    /**
+     * ✅ 转账多跳数（AA 专用，仅 capitalMode=true 时生效）
+     *
+     * 用途：卖出所得 OKB 需要在同一笔 handleOps 内分发给多个买方 AA(Sender)。
+     * - 0：卖方 AA(Sender) 直接分发给所有买方 AA(Sender)
+     * - >0：按"多跳"方式分发（实现位于 xlayer/*，不会影响 BSC bundle/merkle）
+     */
+    disperseHopCount?: number;
+    /**
+     * ✅ 前端传入的 gasPrice（Gwei）
+     * - 如果不传，SDK 会调用 getFeeData 获取当前 gas 价格
+     * - 建议：前端获取当前 gas 价格后传入，确保 prefund 计算一致
+     */
+    gasPriceGwei?: number;
+    /**
+     * ✅ 买入操作的 callGasLimit
+     * - DEX 买入默认 650,000
+     * - Portal 买入默认 450,000
+     * - 前端可根据实际情况调整
+     */
+    buyerCallGasLimit?: bigint;
+    /**
+     * ✅ 多跳转账的 callGasLimit
+     * - 默认 150,000
+     * - 前端可根据实际情况调整
+     */
+    hopCallGasLimit?: bigint;
+    /**
+     * ✅ 买入模式（V3 交易专用）
+     * - 'exactInput'（默认）：花费固定 OKB，买尽可能多的代币（保证交易成功，但代币数量不确定）
+     * - 'exactOutput'：买固定数量代币，花尽可能少的 OKB（保证买到预期数量，但可能失败）
+     *
+     * 注意：
+     * - exactOutput 需要配合 buyAmountsToken 使用
+     * - 如果 OKB 不足以买到预期数量，交易会失败
+     * - V2 交易不支持 exactOutput，会自动回退到 exactInput
+     */
+    buyMode?: 'exactInput' | 'exactOutput';
+    /**
+     * ✅ 每个买方要买入的代币数量（字符串，用于 exactOutput 模式）
+     * - 长度必须与 buyerPrivateKeys 一致
+     * - 仅在 buyMode = 'exactOutput' 时使用
+     * - 代币数量会按代币的 decimals 解析
+     */
+    buyAmountsToken?: string[];
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+}
+export interface BundleBatchSwapResult {
+    swapResult: HandleOpsResult;
+    metadata: {
+        sellerOwner: string;
+        sellerSender: string;
+        buyerOwners: string[];
+        buyerSenders: string[];
+        sellAmountWei: string;
+        buyAmountsWei: string[];
+        hasApprove: boolean;
+        routeAddress?: string;
+        /** 是否提取利润 */
+        extractProfit?: boolean;
+        /** 利润比例 bps */
+        profitBps?: number;
+        /** 利润接收地址 */
+        profitRecipient?: string;
+        /** 预估利润（OKB wei） */
+        profitWei?: string;
+        /** 预估卖出输出（OKB wei） */
+        quotedSellOutWei?: string;
+        /** ✅ AA：转账多跳数（仅 xlayer AA 使用；不影响 BSC） */
+        disperseHopCount?: string;
+    };
+}
+export interface BundleBatchSwapSignParams extends BundleBatchSwapParams {
+    payerPrivateKey?: string;
+    beneficiary?: string;
+    payerStartNonce?: number;
+    handleOpsGasLimit?: bigint;
+    routeAddress?: string;
+}
+export interface BundleBatchSwapSignResult {
+    signedTransactions: string[];
+    /** ✅ 多跳中转钱包列表（用作资金中转的买方钱包，交易失败时可找回资金） */
+    hopWallets?: Array<{
+        address: string;
+        privateKey: string;
+    }>;
+    metadata: {
+        payer: string;
+        beneficiary: string;
+        sellerOwner: string;
+        sellerSender: string;
+        buyerOwners: string[];
+        buyerSenders: string[];
+        sellAmountWei: string;
+        buyAmountsWei: string[];
+        hasApprove: boolean;
+        routeAddress?: string;
+        /** 是否提取利润 */
+        extractProfit?: boolean;
+        /** 利润比例 bps */
+        profitBps?: number;
+        /** 利润接收地址 */
+        profitRecipient?: string;
+        /** 预估利润（OKB wei） */
+        profitWei?: string;
+        /** 预估卖出输出（OKB wei） */
+        quotedSellOutWei?: string;
+        /** ✅ AA：转账多跳数（仅 xlayer AA 使用；不影响 BSC） */
+        disperseHopCount?: string;
+        /** ✅ 利润刮取模式：payer-eoa=由Payer EOA独立刮取，seller-aa=由Seller AA在分发中刮取 */
+        profitMode?: 'payer-eoa' | 'seller-aa';
+    };
+}
+/**
+ * 刷量参数
+ */
+export interface VolumeParams {
+    /** 代币地址 */
+    tokenAddress: string;
+    /** Owner 私钥列表 */
+    privateKeys: string[];
+    /** 每轮买入金额（OKB） */
+    buyAmountPerRound: string;
+    /** 刷量轮数 */
+    rounds: number;
+    /** 每轮间隔时间（毫秒，默认 3000） */
+    intervalMs?: number;
+    /** 每轮是否立即卖出（默认 true） */
+    sellImmediately?: boolean;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+}
+/**
+ * 捆绑买入结果
+ */
+export interface BundleBuyResult {
+    /** 买入交易结果 */
+    buyResult: HandleOpsResult;
+    /** 转账交易结果（如果 transferBackToOwner） */
+    transferResult?: HandleOpsResult;
+    /** 各 sender 的代币余额 */
+    tokenBalances: Map<string, bigint>;
+}
+/**
+ * 捆绑卖出结果
+ */
+export interface BundleSellResult {
+    /** 卖出交易结果 */
+    sellResult: HandleOpsResult;
+    /** 归集交易结果（如果 withdrawToOwner） */
+    withdrawResult?: HandleOpsResult;
+    /**
+     * 利润汇总（如果 withdrawToOwner=true 且实际归集金额>0）
+     * - 注意：AA 的 handleOps tx.value 永远是 0；利润是“从 AA Sender 余额里拆分转走”的金额
+     */
+    profit?: {
+        extractProfit: boolean;
+        profitBps: number;
+        profitRecipient: string;
+        totalProfitWei: string;
+    };
+}
+/**
+ * 捆绑买卖结果
+ */
+export interface BundleBuySellResult {
+    /** 买入阶段结果 */
+    buyResult: HandleOpsResult;
+    /** 卖出阶段结果 */
+    sellResult: HandleOpsResult;
+    /** 归集阶段结果（如果 withdrawToOwner） */
+    withdrawResult?: HandleOpsResult;
+    /** 各 sender 的最终 OKB 余额 */
+    finalBalances: Map<string, bigint>;
+    /** 利润汇总（如果 withdrawToOwner=true 且实际归集金额>0） */
+    profit?: {
+        extractProfit: boolean;
+        profitBps: number;
+        profitRecipient: string;
+        totalProfitWei: string;
+    };
+}
+/**
+ * 刷量结果
+ */
+export interface VolumeResult {
+    /** 成功轮数 */
+    successRounds: number;
+    /** 失败轮数 */
+    failedRounds: number;
+    /** 每轮结果 */
+    roundResults: BundleBuySellResult[];
+    /** 总交易量（OKB） */
+    totalVolume: bigint;
+}
+export type BuyFirstTradeType = 'FLAP' | 'V2';
+/** ✅ Router 版本类型 */
+export type RouterVersion = 'V2' | 'V3';
+/** ✅ 授权目标类型 */
+export type ApprovalTarget = 'FLAP_PORTAL' | 'V2_ROUTER' | 'V3_ROUTER';
+export interface BuyFirstParams {
+    tradeType?: BuyFirstTradeType;
+    /** ✅ 新增：Router 版本（V2 或 V3，默认 V2） */
+    routerVersion?: RouterVersion;
+    /** DEX 标识（仅 V2 时使用，用于选择 Router） */
+    dexKey?: string;
+    /** 显式指定 Router 地址（仅 V2 时使用） */
+    routerAddress?: string;
+    /** DEX deadline 分钟数（仅 V2 时使用） */
+    deadlineMinutes?: number;
+    tokenAddress: string;
+    buyerPrivateKeys: string[];
+    sellerPrivateKeys: string[];
+    /** 本轮总买入资金（OKB 或 quoteToken） */
+    buyerFunds: string;
+    buyCount?: number;
+    sellCount?: number;
+    /** ✅ 新增：买入使用的代币地址（零地址或不传表示使用 OKB，非零地址表示使用 ERC20 如 USDT） */
+    quoteToken?: string;
+    /** ✅ 新增：quoteToken 的精度（默认 18，USDT 在 XLayer 上是 6 位） */
+    quoteTokenDecimals?: number;
+    /** 报价滑点（仅用于估算 sellAmount），默认 0 */
+    slippageBps?: number;
+    withdrawToOwner?: boolean;
+    withdrawReserve?: string;
+    config?: Partial<XLayerConfig>;
+}
+export interface BuyFirstResult {
+    buySellResult: HandleOpsResult;
+    withdrawResult?: HandleOpsResult;
+    finalSellerBalances?: Map<string, bigint>;
+    profit?: {
+        extractProfit: boolean;
+        profitBps: number;
+        profitRecipient: string;
+        totalProfitWei: string;
+    };
+    metadata: {
+        tradeType: BuyFirstTradeType;
+        tokenAddress: string;
+        buyerOwners: string[];
+        buyerSenders: string[];
+        sellerOwners: string[];
+        sellerSenders: string[];
+        buyAmountsWei: string[];
+        sellAmountsWei: string[];
+        totalBuyWei: string;
+        estimatedTokenOutWei: string;
+        slippageBps: number;
+    };
+}
+export interface BuyFirstVolumeParams extends Omit<BuyFirstParams, 'buyerFunds'> {
+    buyerFundsPerRound: string;
+    rounds: number;
+    intervalMs?: number;
+}
+export interface BuyFirstVolumeResult {
+    successRounds: number;
+    failedRounds: number;
+    roundResults: BuyFirstResult[];
+    /** 总交易量（OKB wei，按“买入资金*2”统计） */
+    totalVolume: bigint;
+}
+/**
+ * 外盘（PotatoSwap）交易参数
+ */
+export interface DexSwapParams {
+    /** 输入代币地址（零地址表示 OKB） */
+    inputToken: string;
+    /** 输出代币地址（零地址表示 OKB） */
+    outputToken: string;
+    /** 输入金额 */
+    inputAmount: bigint;
+    /** 最小输出金额 */
+    minOutputAmount: bigint;
+    /** 交易截止时间（默认 20 分钟） */
+    deadline?: number;
+}
+/**
+ * 外盘交易结果
+ */
+export interface DexSwapResult {
+    txHash: string;
+    inputAmount: bigint;
+    outputAmount: bigint;
+    gasUsed: bigint;
+}
+/**
+ * 预授权参数
+ * 用于提前授权代币，避免在交易时等待授权确认
+ */
+export interface BundlePreApproveParams {
+    /** 代币地址 */
+    tokenAddress: string;
+    /** Owner 私钥列表 */
+    privateKeys: string[];
+    /** 授权目标（默认 FLAP_PORTAL，可传 Router 地址用于外盘交易） */
+    spender?: string;
+    /**
+     * 是否仅签名（不执行）
+     * - true: 返回签名后的 handleOps 交易，由前端发送到服务端广播
+     * - false（默认）: 直接执行 handleOps
+     */
+    signOnly?: boolean;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+    /** Payer 私钥（signOnly=true 时必传，用于支付 gas） */
+    payerPrivateKey?: string;
+}
+/**
+ * 预授权结果
+ */
+export interface BundlePreApproveResult {
+    /** 发送授权交易的数量 */
+    approvedCount: number;
+    /** 已经授权无需操作的数量 */
+    alreadyApprovedCount: number;
+    /** 授权交易结果（signOnly=false 时有值） */
+    approveResult?: HandleOpsResult;
+    /** 每个地址的授权状态详情 */
+    details: ApprovalStatusResult[];
+    /** signOnly=true 时：签名后的 handleOps 交易（raw signed tx） */
+    signedTransactions?: string[];
+}
+/**
+ * 授权状态检查结果
+ */
+export interface ApprovalStatusResult {
+    /** Owner EOA 地址 */
+    owner: string;
+    /** AA Sender 地址 */
+    sender: string;
+    /** 是否已授权（授权额度 >= 代币余额） */
+    isApproved: boolean;
+    /** 当前授权额度 */
+    currentAllowance: bigint;
+    /** 当前代币余额 */
+    tokenBalance: bigint;
+}
+/**
+ * 捆绑买到毕业签名参数
+ */
+export interface BundleGraduateBuyParams {
+    /** 代位地址 */
+    tokenAddress: string;
+    /** 买入钱包私钥数组 */
+    privateKeys: string[];
+    /** AA Payer 私钥 */
+    payerPrivateKey: string;
+    /** 分配模式 */
+    amountMode: 'average' | 'random' | 'custom';
+    /** 平均模式：总买入金额 */
+    totalBuyAmount?: number;
+    /** 随机模式：最小金额 / 最大金额 */
+    minAmount?: number;
+    maxAmount?: number;
+    /** 自定义模式：地址 -> 金额 */
+    walletAmounts?: Record<string, number>;
+    /** 是否启用外盘买入（默认 false） */
+    enableDexBuy?: boolean;
+    /** 内盘钱包地址列表（可选，传入则使用前端分组，不传则 SDK 自动分组） */
+    curveAddresses?: string[];
+    /** 外盘钱包地址列表（可选） */
+    dexAddresses?: string[];
+    /** 动态毕业阈值（可选，不传则使用默认 73.38 OKB） */
+    graduationAmount?: number;
+    /** 配置覆盖 */
+    config?: Partial<XLayerConfig>;
+    /** 扩展数据（传递给 swapExactInputV3，默认 0x） */
+    extensionData?: string;
+    /** Payer 起始 nonce */
+    payerStartNonce?: number;
+    /** beneficiary（默认 payer 地址） */
+    beneficiary?: string;
+}
+/**
+ * 捆绑买到毕业签名结果
+ */
+export interface BundleGraduateBuyResult {
+    /** raw signed tx 列表 */
+    signedTransactions: string[];
+    /** 元数据 */
+    metadata: {
+        curveCount: number;
+        dexCount: number;
+        curveTotalAmount: string;
+        dexTotalAmount: string;
+        tokenAddress: string;
+    };
+}