four-flap-meme-sdk 1.9.49 → 2.0.0

package/dist/shared/flap/portal-bundle-merkle/types.d.ts

@@ -85,6 +85,10 @@ export type MerkleBundleStatus = {
     totalGasUsed: bigint;
     targetBlock: number;
 };
+/** Merkle 结果 metadata 字段值（各方法返回的键不固定，值类型统一收窄） */
+export type MerkleResultMetadataValue = string | number | boolean | string[] | undefined;
+/** Merkle 结果 metadata */
+export type MerkleResultMetadata = Record<string, MerkleResultMetadataValue>;
 /**
  * 统一的 Merkle 方法返回类型
  * SDK 不再内部提交，只返回签名交易和元数据
@@ -97,9 +101,7 @@ export type MerkleSignedResult = {
     /** ✅ 利润多跳钱包（用于导出私钥） */
     profitHopWallets?: GeneratedWallet[];
     /** 元数据（如利润信息等） */
-    metadata?: {
-        [key: string]: any;
-    };
+    metadata?: MerkleResultMetadata;
 };
 /** ✅ Flap 创建代币 + 购买参数（Merkle 版本 - 完整） */
 export type FlapCreateWithBundleBuyMerkleParams = {
@@ -356,3 +358,71 @@ export type PancakeProxyApprovalBatchResult = {
     bundleHash?: string;
     message: string;
 };
+export type FlapDisperseSignParams = {
+    chain: 'BSC' | 'MONAD' | 'XLAYER';
+    fromPrivateKey: string;
+    recipients: string[];
+    amount?: string;
+    amounts?: string[];
+    tokenAddress?: string;
+    tokenDecimals?: number;
+    hopCount?: number | number[];
+    hopPrivateKeys?: string[][];
+    items?: {
+        recipient: string;
+        amount: string | bigint;
+        hopCount?: number;
+        hopPrivateKeys?: string[];
+    }[];
+    config: FlapSignConfig;
+    startNonce?: number;
+};
+export type FlapDisperseMerkleResult = {
+    signedTransactions: string[];
+    hopWallets?: (string | GeneratedWallet)[][];
+    profitHopWallets?: GeneratedWallet[];
+    metadata?: {
+        totalAmount: string;
+        profitAmount: string;
+        profitRecipient: string;
+        recipientCount: number;
+        isNative: boolean;
+        tokenAddress?: string;
+    };
+};
+export type FlapSweepSignParams = {
+    chain: 'BSC' | 'MONAD' | 'XLAYER';
+    sourcePrivateKeys: string[];
+    target: string;
+    ratioPct?: number;
+    ratios?: number[];
+    amount?: string;
+    amounts?: string[];
+    tokenAddress?: string;
+    tokenDecimals?: number;
+    skipIfInsufficient?: boolean;
+    hopCount?: number | number[];
+    hopPrivateKeys?: string[][];
+    sources?: {
+        privateKey: string;
+        ratioPct?: number;
+        amount?: string;
+        hopCount?: number;
+        hopPrivateKeys?: string[];
+    }[];
+    config: FlapSignConfig;
+    startNonce?: number;
+};
+export type FlapSweepMerkleResult = {
+    signedTransactions: string[];
+    hopWallets?: (string | GeneratedWallet)[][];
+    profitHopWallets?: GeneratedWallet[];
+    metadata?: {
+        totalAmount: string;
+        profitAmount: string;
+        profitRecipient: string;
+        sourceCount: number;
+        isNative: boolean;
+        tokenAddress?: string;
+    };
+};

package/dist/shared/flap/portal-bundle-merkle/utils-helpers.d.ts

@@ -0,0 +1,100 @@
+import { JsonRpcProvider } from 'ethers';
+import type { FlapSignConfig } from './types.js';
+import type { GeneratedWallet } from '../../../utils/wallet.js';
+/** 分散参数 */
+export type FlapDisperseSignParams = {
+    chain: 'BSC' | 'MONAD' | 'XLAYER';
+    fromPrivateKey: string;
+    recipients: string[];
+    amount?: string;
+    amounts?: string[];
+    tokenAddress?: string;
+    tokenDecimals?: number;
+    hopCount?: number | number[];
+    hopPrivateKeys?: string[][];
+    items?: {
+        recipient: string;
+        amount: string | bigint;
+        hopCount?: number;
+        hopPrivateKeys?: string[];
+    }[];
+    config: FlapSignConfig;
+    startNonce?: number;
+};
+/** 分散结果 */
+export type FlapDisperseMerkleResult = {
+    signedTransactions: string[];
+    hopWallets?: (string | GeneratedWallet)[][];
+    profitHopWallets?: GeneratedWallet[];
+    metadata?: {
+        totalAmount: string;
+        profitAmount: string;
+        profitRecipient: string;
+        recipientCount: number;
+        isNative: boolean;
+        tokenAddress?: string;
+    };
+};
+/** 归集参数 */
+export type FlapSweepSignParams = {
+    chain: 'BSC' | 'MONAD' | 'XLAYER';
+    sourcePrivateKeys: string[];
+    target: string;
+    ratioPct?: number;
+    ratios?: number[];
+    amount?: string;
+    amounts?: string[];
+    tokenAddress?: string;
+    tokenDecimals?: number;
+    skipIfInsufficient?: boolean;
+    hopCount?: number | number[];
+    hopPrivateKeys?: string[][];
+    sources?: {
+        privateKey: string;
+        ratioPct?: number;
+        amount?: string;
+        hopCount?: number;
+        hopPrivateKeys?: string[];
+    }[];
+    config: FlapSignConfig;
+    startNonce?: number;
+};
+/** 归集结果 */
+export type FlapSweepMerkleResult = {
+    signedTransactions: string[];
+    hopWallets?: (string | GeneratedWallet)[][];
+    profitHopWallets?: GeneratedWallet[];
+    metadata?: {
+        totalAmount: string;
+        profitAmount: string;
+        profitRecipient: string;
+        sourceCount: number;
+        isNative: boolean;
+        tokenAddress?: string;
+    };
+};
+export declare const CHAIN_ID_MAP: Record<string, number>;
+export declare const MULTICALL3_ADDRESS: "0xcA11bde05977b3631167028862bE2a173976CA11";
+export declare const decimalsCache: Map<string, number>;
+export declare function getErc20Decimals(provider: JsonRpcProvider, token: string): Promise<number>;
+/**
+ * ✅ 生成多跳中间钱包（返回完整钱包信息：地址 + 私钥）
+ */
+export declare function generateHopWallets(recipientCount: number, hopCount: number | number[]): GeneratedWallet[][] | null;
+export declare function normalizeAmounts(recipients: string[], amount?: string, amounts?: string[]): string[];
+export declare function batchGetBalances(provider: JsonRpcProvider, addresses: string[], tokenAddress?: string): Promise<bigint[]>;
+/**
+ * 计算 Gas Limit
+ * - 原生代币转账：21000 gas（固定）
+ * - ERC20 标准 transfer：约 45000-55000 gas，使用 55000 作为安全值
+ *
+ * ✅ 优化：降低 ERC20 gas limit，减少中转钱包 BNB 残留
+ */
+export declare function calculateGasLimit(config: FlapSignConfig, isNative: boolean, hasHops: boolean, _hopCount?: number): bigint;
+export declare function isNativeTokenAddress(tokenAddress?: string): boolean;
+/**
+ * Flap Protocol: 分散（仅签名版本）
+ * ✅ 支持利润提取（按地址数量收取固定费用）
+ * ✅ 支持多跳
+ * ✅ 支持 Multicall3 批量获取余额
+ */

package/dist/shared/flap/portal-bundle-merkle/utils-helpers.js

@@ -0,0 +1,133 @@
+import { ethers, Wallet } from 'ethers';
+import { ADDRESSES } from '../../../utils/constants.js';
+import { MULTICALL3_ABI, ERC20_BALANCE_ABI } from '../../abis/common.js';
+// ==================== 链配置 ====================
+export const CHAIN_ID_MAP = {
+    'BSC': 56,
+    'MONAD': 143,
+    'XLAYER': 196
+};
+// ==================== 链常量 ====================
+// ✅ 使用公共模块
+export const MULTICALL3_ADDRESS = ADDRESSES.BSC.Multicall3;
+// ==================== 内部辅助函数 ====================
+export const decimalsCache = new Map();
+export async function getErc20Decimals(provider, token) {
+    const network = await provider.getNetwork();
+    const key = `${network.chainId}_${token.toLowerCase()}`;
+    if (decimalsCache.has(key))
+        return decimalsCache.get(key);
+    try {
+        const erc20 = new ethers.Contract(token, ['function decimals() view returns (uint8)'], provider);
+        const d = await erc20.decimals();
+        if (!Number.isFinite(d) || d < 0 || d > 36)
+            return 18;
+        decimalsCache.set(key, d);
+        return d;
+    }
+    catch {
+        return 18;
+    }
+}
+/**
+ * ✅ 生成多跳中间钱包（返回完整钱包信息：地址 + 私钥）
+ */
+export function generateHopWallets(recipientCount, hopCount) {
+    const hopCounts = Array.isArray(hopCount) ? hopCount : new Array(recipientCount).fill(hopCount);
+    if (hopCounts.every(h => h <= 0))
+        return null;
+    const result = [];
+    for (let i = 0; i < recipientCount; i++) {
+        const chain = [];
+        for (let j = 0; j < hopCounts[i]; j++) {
+            const wallet = Wallet.createRandom();
+            chain.push({
+                address: wallet.address,
+                privateKey: wallet.privateKey
+            });
+        }
+        result.push(chain);
+    }
+    return result;
+}
+export function normalizeAmounts(recipients, amount, amounts) {
+    if (amounts && amounts.length > 0) {
+        if (amounts.length !== recipients.length) {
+            throw new Error(`amounts length (${amounts.length}) must match recipients length (${recipients.length})`);
+        }
+        return amounts;
+    }
+    if (amount !== undefined && amount.trim().length > 0) {
+        return new Array(recipients.length).fill(amount);
+    }
+    throw new Error('Either amount or amounts must be provided');
+}
+export async function batchGetBalances(provider, addresses, tokenAddress) {
+    if (addresses.length === 0)
+        return [];
+    if (!tokenAddress) {
+        return Promise.all(addresses.map(addr => provider.getBalance(addr).catch(() => 0n)));
+    }
+    else {
+        // ✅ 使用公共模块
+        const multicall = new ethers.Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, provider);
+        const iface = new ethers.Interface(ERC20_BALANCE_ABI);
+        const calls = addresses.map(addr => ({
+            target: tokenAddress,
+            allowFailure: true,
+            callData: iface.encodeFunctionData('balanceOf', [addr])
+        }));
+        try {
+            const results = await multicall.aggregate3(calls);
+            return results.map((result) => {
+                if (result.success) {
+                    return iface.decodeFunctionResult('balanceOf', result.returnData)[0];
+                }
+                return 0n;
+            });
+        }
+        catch {
+            const fallbackCalls = addresses.map(addr => provider
+                .call({ to: tokenAddress, data: iface.encodeFunctionData('balanceOf', [addr]) })
+                .then(raw => iface.decodeFunctionResult('balanceOf', raw)[0])
+                .catch(() => 0n));
+            return Promise.all(fallbackCalls);
+        }
+    }
+}
+/**
+ * 计算 Gas Limit
+ * - 原生代币转账：21000 gas（固定）
+ * - ERC20 标准 transfer：约 45000-55000 gas，使用 55000 作为安全值
+ *
+ * ✅ 优化：降低 ERC20 gas limit，减少中转钱包 BNB 残留
+ */
+export function calculateGasLimit(config, isNative, hasHops, _hopCount = 0) {
+    if (config.gasLimit !== undefined) {
+        return BigInt(config.gasLimit);
+    }
+    // ✅ 原生代币: 21000, ERC20 标准 transfer: 48000（USDT 最低约 46815）
+    const baseGas = isNative ? 21000 : 48000;
+    // ✅ 多跳时每个中转钱包只执行一笔 transfer，使用较小的安全系数
+    const multiplier = config.gasLimitMultiplier ?? 1.1;
+    return BigInt(Math.ceil(baseGas * multiplier));
+}
+export function isNativeTokenAddress(tokenAddress) {
+    if (!tokenAddress)
+        return true;
+    const v = tokenAddress.trim().toLowerCase();
+    if (!v)
+        return true;
+    if (v === 'native')
+        return true;
+    if (v === '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee')
+        return true;
+    return false;
+}
+// ==================== 分散函数 ====================
+/**
+ * Flap Protocol: 分散（仅签名版本）
+ * ✅ 支持利润提取（按地址数量收取固定费用）
+ * ✅ 支持多跳
+ * ✅ 支持 Multicall3 批量获取余额
+ */

package/dist/shared/flap/portal-bundle-merkle/utils.d.ts

@@ -1,83 +1,4 @@
-import type { FlapSignConfig } from './types.js';
-import type { GeneratedWallet } from '../../../utils/wallet.js';
-/** 分散参数 */
-export type FlapDisperseSignParams = {
-    chain: 'BSC' | 'MONAD' | 'XLAYER';
-    fromPrivateKey: string;
-    recipients: string[];
-    amount?: string;
-    amounts?: string[];
-    tokenAddress?: string;
-    tokenDecimals?: number;
-    hopCount?: number | number[];
-    hopPrivateKeys?: string[][];
-    items?: {
-        recipient: string;
-        amount: string | bigint;
-        hopCount?: number;
-        hopPrivateKeys?: string[];
-    }[];
-    config: FlapSignConfig;
-    startNonce?: number;
-};
-/** 分散结果 */
-export type FlapDisperseMerkleResult = {
-    signedTransactions: string[];
-    hopWallets?: (string | GeneratedWallet)[][];
-    profitHopWallets?: GeneratedWallet[];
-    metadata?: {
-        totalAmount: string;
-        profitAmount: string;
-        profitRecipient: string;
-        recipientCount: number;
-        isNative: boolean;
-        tokenAddress?: string;
-    };
-};
-/** 归集参数 */
-export type FlapSweepSignParams = {
-    chain: 'BSC' | 'MONAD' | 'XLAYER';
-    sourcePrivateKeys: string[];
-    target: string;
-    ratioPct?: number;
-    ratios?: number[];
-    amount?: string;
-    amounts?: string[];
-    tokenAddress?: string;
-    tokenDecimals?: number;
-    skipIfInsufficient?: boolean;
-    hopCount?: number | number[];
-    hopPrivateKeys?: string[][];
-    sources?: {
-        privateKey: string;
-        ratioPct?: number;
-        amount?: string;
-        hopCount?: number;
-        hopPrivateKeys?: string[];
-    }[];
-    config: FlapSignConfig;
-    startNonce?: number;
-};
-/** 归集结果 */
-export type FlapSweepMerkleResult = {
-    signedTransactions: string[];
-    hopWallets?: (string | GeneratedWallet)[][];
-    profitHopWallets?: GeneratedWallet[];
-    metadata?: {
-        totalAmount: string;
-        profitAmount: string;
-        profitRecipient: string;
-        sourceCount: number;
-        isNative: boolean;
-        tokenAddress?: string;
-    };
-};
-/**
- * Flap Protocol: 分散（仅签名版本）
- * ✅ 支持利润提取（按地址数量收取固定费用）
- * ✅ 支持多跳
- * ✅ 支持 Multicall3 批量获取余额
- */
+import type { FlapDisperseMerkleResult, FlapDisperseSignParams, FlapSweepMerkleResult, FlapSweepSignParams } from './types.js';
 export declare function flapDisperseWithBundleMerkle(params: FlapDisperseSignParams): Promise<FlapDisperseMerkleResult>;
 /**
  * Flap Protocol: 归集（仅签名版本）