four-flap-meme-sdk 4.1.0 → 4.2.0

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

@@ -0,0 +1,196 @@
+import type { HandleOpsResult, XLayerConfig } from './aa-types.js';
+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;
+    };
+}

package/dist/chains/xlayer/eoa/eoa-dex-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,283 @@
+import type { HandleOpsResult, XLayerConfig } from './aa-types.js';
+import type { BundleSwapParams } from './eoa-trade-types.js';
+/**
+ * 捆绑换手签名参数（仅签名 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;
+}

package/dist/chains/xlayer/eoa/eoa-swap-types.js

@@ -0,0 +1 @@
+export {};