four-flap-meme-sdk 2.0.0 → 2.2.0

package/dist/chains/xlayer/eip7702/multi-hop-transfer/index.js

@@ -1,857 +0,0 @@
-/**
- * EIP-7702 转账功能
- *
- * 支持三种模式：
- * 1. 分散 (disperse): 一对多分发资金
- * 2. 归集 (sweep): 多对一收集资金
- * 3. 多对多 (pairwise): sender[i] → receiver[i] 一一对应转账
- *
- * 所有模式都支持：
- * - 原生 OKB 转账
- * - ERC20 代币转账
- * - 可选的多跳混淆
- *
- * 只生成签名，由调用方决定如何提交
- */
-import { ethers, Contract } from 'ethers';
-import { getCachedProvider, createWallet, signAuthorizationsWithNonces, batchGetNonces, buildEIP7702TransactionSync, generateRandomWallets, getProfitRecipient, } from '../utils.js';
-import { UNIFIED_DELEGATE_ADDRESS, UNIFIED_DELEGATE_ABI, ERC20_ABI, XLAYER_CHAIN_ID, } from '../constants.js';
-import { calculateTransferFee } from '../../../../shared/constants/index.js';
-// ========================================
-// 通用类型定义
-// ========================================
-// ========================================
-// 分散 (Disperse) - 一对多
-// ========================================
-/**
- * 分散资金 - 一对多分发
- *
- * 支持：原生 OKB / ERC20 代币 + 可选多跳
- *
- * 流程（无多跳）：主钱包 → 多个接收者
- * 流程（有多跳）：主钱包 → hop1 → hop2 → ... → 分发给接收者
- *
- * @example
- * // 原生 OKB 直接分发
- * const result = await disperse({
- *   mainPrivateKey: '0x...',
- *   recipients: ['0xAAA', '0xBBB', '0xCCC'],
- *   amounts: ['0.1', '0.2', '0.3'],
- * });
- *
- * @example
- * // 原生 OKB 多跳分发
- * const result = await disperse({
- *   mainPrivateKey: '0x...',
- *   recipients: ['0xAAA', '0xBBB'],
- *   amounts: ['0.5', '0.5'],
- *   hopCount: 2,
- * });
- *
- * @example
- * // ERC20 代币分发
- * const result = await disperse({
- *   mainPrivateKey: '0x...',
- *   recipients: ['0xAAA', '0xBBB'],
- *   amounts: ['100', '200'],
- *   tokenAddress: '0xTOKEN...',
- *   tokenDecimals: 18,
- *   hopCount: 2,
- * });
- */
-export async function disperse(params) {
-    const { mainPrivateKey, payerPrivateKey, recipients, amounts, tokenAddress, tokenDecimals = 18, hopCount = 0, userType, config, } = params;
-    if (recipients.length !== amounts.length) {
-        throw new Error('recipients 和 amounts 长度必须相同');
-    }
-    const provider = getCachedProvider(config?.rpcUrl);
-    const delegateAddress = (config?.delegateAddress && config.delegateAddress.trim()) || UNIFIED_DELEGATE_ADDRESS;
-    const delegateInterface = new ethers.Interface(UNIFIED_DELEGATE_ABI);
-    // ✅ mainWallet: 资金来源（Token/OKB 从这里转出）
-    const mainWallet = createWallet(mainPrivateKey, provider);
-    const isNative = !tokenAddress;
-    const profitRecipient = getProfitRecipient(config);
-    // ✅ 支持单独的 Payer 钱包（用于支付 gas）
-    const hasSeparatePayer = payerPrivateKey && payerPrivateKey !== mainPrivateKey;
-    const payerWallet = hasSeparatePayer ? createWallet(payerPrivateKey, provider) : null;
-    const txSender = payerWallet ?? mainWallet; // 交易发起者
-    console.log(`[disperse] 资金钱包: ${mainWallet.address}`);
-    console.log(`[disperse] Gas Payer: ${txSender.address}${hasSeparatePayer ? ' (独立 Payer)' : ''}`);
-    // ✅ 为每个接收者生成独立的中间钱包链
-    // 每个接收者有自己的 hopCount 个中间钱包
-    const allHopWalletInfos = [];
-    const allHopWallets = [];
-    for (let i = 0; i < recipients.length; i++) {
-        if (hopCount > 0) {
-            const hopInfos = generateRandomWallets(hopCount);
-            allHopWalletInfos.push(hopInfos);
-            allHopWallets.push(hopInfos.map(info => createWallet(info.privateKey, provider)));
-        }
-        else {
-            allHopWalletInfos.push([]);
-            allHopWallets.push([]);
-        }
-    }
-    // 解析金额
-    const amountsWei = amounts.map(amt => isNative ? ethers.parseEther(amt) : ethers.parseUnits(amt, tokenDecimals));
-    const totalAmount = amountsWei.reduce((sum, amt) => sum + amt, 0n);
-    // ✅ 按地址数量收取固定费用（原生 OKB）
-    const profitAmountOkb = calculateTransferFee(XLAYER_CHAIN_ID, recipients.length);
-    console.log(`[disperse] 按地址收费: ${recipients.length} 个地址 × ${ethers.formatEther(calculateTransferFee(XLAYER_CHAIN_ID, 1))} = ${ethers.formatEther(profitAmountOkb)} OKB`);
-    // ========================================
-    // 并行获取数据
-    // ========================================
-    const addressesToGetNonces = payerWallet
-        ? [payerWallet.address, mainWallet.address]
-        : [mainWallet.address];
-    const [allNoncesResult, feeData] = await Promise.all([
-        batchGetNonces(addressesToGetNonces, provider),
-        provider.getFeeData(),
-    ]);
-    const payerNonce = payerWallet ? allNoncesResult[0] : allNoncesResult[0];
-    const mainNonce = payerWallet ? allNoncesResult[1] : allNoncesResult[0];
-    // ========================================
-    // 同步签署授权（已有 nonce）
-    // ========================================
-    // ✅ 如果有 Payer，需要为 Payer 和 mainWallet 都生成授权
-    const allWallets = payerWallet ? [payerWallet, mainWallet] : [mainWallet];
-    const allNonces = payerWallet ? [payerNonce, mainNonce] : [mainNonce];
-    for (const hopWallets of allHopWallets) {
-        for (const hopWallet of hopWallets) {
-            allWallets.push(hopWallet);
-            allNonces.push(0);
-        }
-    }
-    const authorizations = signAuthorizationsWithNonces(allWallets, allNonces, delegateAddress, 0 // txSender（Payer 或 mainWallet）是交易发起者
-    );
-    // ========================================
-    // 同步构建调用
-    // ========================================
-    const calls = [];
-    for (let i = 0; i < recipients.length; i++) {
-        const recipient = recipients[i];
-        const amtWei = amountsWei[i];
-        const hopWallets = allHopWallets[i];
-        if (hopCount === 0 || hopWallets.length === 0) {
-            // ========================================
-            // 直接分发：主钱包 → 接收者
-            // ========================================
-            if (isNative) {
-                // ✅ Payer 模式：使用 transferAmount（从 mainWallet 余额转出）
-                // ✅ 非 Payer 模式：使用 transferTo（从 msg.value 转出）
-                if (payerWallet) {
-                    calls.push({
-                        target: mainWallet.address,
-                        allowFailure: false,
-                        value: 0n,
-                        callData: delegateInterface.encodeFunctionData('transferAmount', [recipient, amtWei]),
-                    });
-                }
-                else {
-                    calls.push({
-                        target: mainWallet.address,
-                        allowFailure: false,
-                        value: amtWei,
-                        callData: delegateInterface.encodeFunctionData('transferTo', [recipient]),
-                    });
-                }
-            }
-            else {
-                calls.push({
-                    target: mainWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('executeTransfer', [
-                        tokenAddress,
-                        recipient,
-                        amtWei,
-                    ]),
-                });
-            }
-        }
-        else {
-            // ========================================
-            // 多跳分发：主钱包 → hop1 → hop2 → ... → 接收者
-            // ========================================
-            const firstHop = hopWallets[0];
-            const lastHop = hopWallets[hopWallets.length - 1];
-            if (isNative) {
-                // 主钱包 → 第一个中间钱包
-                // ✅ Payer 模式：使用 transferAmount（从 mainWallet 余额转出）
-                if (payerWallet) {
-                    calls.push({
-                        target: mainWallet.address,
-                        allowFailure: false,
-                        value: 0n,
-                        callData: delegateInterface.encodeFunctionData('transferAmount', [firstHop.address, amtWei]),
-                    });
-                }
-                else {
-                    calls.push({
-                        target: mainWallet.address,
-                        allowFailure: false,
-                        value: amtWei,
-                        callData: delegateInterface.encodeFunctionData('transferTo', [firstHop.address]),
-                    });
-                }
-                // 中间钱包之间转账（使用全部余额）
-                for (let j = 0; j < hopWallets.length - 1; j++) {
-                    calls.push({
-                        target: hopWallets[j].address,
-                        allowFailure: false,
-                        value: 0n,
-                        callData: delegateInterface.encodeFunctionData('transferTo', [hopWallets[j + 1].address]),
-                    });
-                }
-                // 最后一个中间钱包 → 接收者（使用全部余额）
-                calls.push({
-                    target: lastHop.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('transferTo', [recipient]),
-                });
-            }
-            else {
-                // ERC20 多跳
-                // 主钱包 → 第一个中间钱包
-                calls.push({
-                    target: mainWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('executeTransfer', [
-                        tokenAddress,
-                        firstHop.address,
-                        amtWei,
-                    ]),
-                });
-                // 中间钱包之间转账
-                for (let j = 0; j < hopWallets.length - 1; j++) {
-                    calls.push({
-                        target: hopWallets[j].address,
-                        allowFailure: false,
-                        value: 0n,
-                        callData: delegateInterface.encodeFunctionData('executeTransferAll', [
-                            tokenAddress,
-                            hopWallets[j + 1].address,
-                        ]),
-                    });
-                }
-                // 最后一个中间钱包 → 接收者
-                calls.push({
-                    target: lastHop.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('executeTransferAll', [
-                        tokenAddress,
-                        recipient,
-                    ]),
-                });
-            }
-        }
-    }
-    // ========================================
-    // 添加利润转账调用（固定费用，OKB）
-    // ========================================
-    if (profitAmountOkb > 0n) {
-        calls.push({
-            target: mainWallet.address,
-            allowFailure: false,
-            value: 0n,
-            callData: delegateInterface.encodeFunctionData('transferAmount', [profitRecipient, profitAmountOkb]),
-        });
-        console.log(`[disperse] 已添加利润转账调用: ${ethers.formatEther(profitAmountOkb)} OKB → ${profitRecipient}`);
-    }
-    // ========================================
-    // 构建交易
-    // ========================================
-    // ✅ Payer 模式下 value 为 0（资金从 mainWallet 转出，不是 Payer）
-    // 无 Payer 时，原生币分发需要传递 value（资金从 txSender 转出）
-    const totalValue = (isNative && !payerWallet) ? totalAmount : 0n;
-    const signedTransaction = buildEIP7702TransactionSync(txSender, // ✅ 使用 txSender（Payer 或 mainWallet）发起交易
-    authorizations, calls, totalValue, payerNonce, // ✅ 使用 txSender 的 nonce
-    feeData, config);
-    // ✅ 返回所有中间钱包（扁平化）
-    const flatHopWallets = allHopWalletInfos.flat();
-    return {
-        signedTransaction,
-        hopWallets: flatHopWallets.length > 0 ? flatHopWallets : undefined,
-        metadata: {
-            senderAddress: mainWallet.address, // 资金来源
-            payerAddress: txSender.address, // Gas 支付者
-            recipientCount: recipients.length,
-            totalAmount: isNative ? ethers.formatEther(totalAmount) : ethers.formatUnits(totalAmount, tokenDecimals),
-            profitAmount: ethers.formatEther(profitAmountOkb), // ✅ 以 OKB 计
-            isNative,
-            tokenAddress: tokenAddress ?? null,
-            hopCount,
-            userType,
-        },
-    };
-}
-// ========================================
-// 归集 (Sweep) - 多对一
-// ========================================
-/**
- * 归集资金 - 多对一收集
- *
- * 支持：原生 OKB / ERC20 代币 + 可选多跳
- *
- * 流程（无多跳）：多个源钱包 → 目标地址
- * 流程（有多跳）：多个源钱包 → hop1 → hop2 → ... → 目标地址
- *
- * @example
- * // 原生 OKB 直接归集
- * const result = await sweep({
- *   targetAddress: '0xTARGET',
- *   sourcePrivateKeys: ['0x...', '0x...'],
- * });
- *
- * @example
- * // 原生 OKB 多跳归集
- * const result = await sweep({
- *   targetAddress: '0xTARGET',
- *   sourcePrivateKeys: ['0x...', '0x...'],
- *   hopCount: 2,
- * });
- *
- * @example
- * // ERC20 代币归集
- * const result = await sweep({
- *   targetAddress: '0xTARGET',
- *   sourcePrivateKeys: ['0x...', '0x...'],
- *   tokenAddress: '0xTOKEN...',
- *   tokenDecimals: 18,
- *   hopCount: 2,
- * });
- */
-export async function sweep(params) {
-    const { targetAddress, sourcePrivateKeys, payerPrivateKey, tokenAddress, tokenDecimals = 18, hopCount = 0, reserveGas = true, percent = 100, userType, config, } = params;
-    const provider = getCachedProvider(config?.rpcUrl);
-    const delegateAddress = (config?.delegateAddress && config.delegateAddress.trim()) || UNIFIED_DELEGATE_ADDRESS;
-    const delegateInterface = new ethers.Interface(UNIFIED_DELEGATE_ABI);
-    const sourceWallets = sourcePrivateKeys.map(pk => createWallet(pk, provider));
-    const isNative = !tokenAddress;
-    const profitRecipient = getProfitRecipient(config);
-    // ✅ 为每个源钱包生成独立的中间钱包链
-    const allHopWalletInfos = [];
-    const allHopWallets = [];
-    for (let i = 0; i < sourceWallets.length; i++) {
-        if (hopCount > 0) {
-            const hopInfos = generateRandomWallets(hopCount);
-            allHopWalletInfos.push(hopInfos);
-            allHopWallets.push(hopInfos.map(info => createWallet(info.privateKey, provider)));
-        }
-        else {
-            allHopWalletInfos.push([]);
-            allHopWallets.push([]);
-        }
-    }
-    // ✅ 支持单独的 Payer 钱包（用于支付 gas）
-    const hasSeparatePayer = payerPrivateKey && !sourcePrivateKeys.includes(payerPrivateKey);
-    const payerWallet = hasSeparatePayer ? createWallet(payerPrivateKey, provider) : null;
-    const mainWallet = payerWallet ?? sourceWallets[0];
-    // ========================================
-    // 并行获取数据
-    // ========================================
-    const sourceAddresses = sourceWallets.map(w => w.address);
-    const addressesToGetNonces = payerWallet
-        ? [payerWallet.address, ...sourceAddresses]
-        : sourceAddresses;
-    const parallelPromises = [
-        batchGetNonces(addressesToGetNonces, provider),
-        provider.getFeeData(),
-    ];
-    if (isNative) {
-        parallelPromises.push(Promise.all(sourceWallets.map(w => provider.getBalance(w.address))));
-    }
-    else {
-        const tokenContract = new Contract(tokenAddress, ERC20_ABI, provider);
-        parallelPromises.push(Promise.all(sourceWallets.map(w => tokenContract.balanceOf(w.address))));
-    }
-    const results = await Promise.all(parallelPromises);
-    const allNoncesResult = results[0];
-    const payerNonce = payerWallet ? allNoncesResult[0] : allNoncesResult[0];
-    const nonces = payerWallet ? allNoncesResult.slice(1) : allNoncesResult;
-    const feeData = results[1];
-    const balances = results[2].map(b => typeof b === 'bigint' ? b : BigInt(b.toString()));
-    // 计算转账金额
-    // ✅ 修复：当 percent=100 时，不预留 gas，归集全部余额
-    const isFullSweep = percent >= 100;
-    const gasReserve = (reserveGas && isNative && !isFullSweep) ? ethers.parseEther('0.001') : 0n;
-    const percentBigInt = BigInt(Math.min(100, Math.max(1, percent)));
-    const transferAmounts = balances.map(b => {
-        if (isFullSweep) {
-            // 100% 归集：使用全部余额
-            return b;
-        }
-        const afterReserve = b > gasReserve ? b - gasReserve : 0n;
-        return (afterReserve * percentBigInt) / 100n;
-    });
-    const totalAmount = transferAmounts.reduce((sum, amt) => sum + amt, 0n);
-    // ✅ 按地址数量收取固定费用（原生 OKB）
-    const profitAmountOkb = calculateTransferFee(XLAYER_CHAIN_ID, sourceWallets.length);
-    console.log(`[sweep] 按地址收费: ${sourceWallets.length} 个地址 × ${ethers.formatEther(calculateTransferFee(XLAYER_CHAIN_ID, 1))} = ${ethers.formatEther(profitAmountOkb)} OKB`);
-    // ✅ 找出归集金额最大的钱包（用于支付 OKB 利润）
-    let maxSweepIndex = -1;
-    let maxSweepAmount = 0n;
-    for (let i = 0; i < transferAmounts.length; i++) {
-        if (transferAmounts[i] > maxSweepAmount) {
-            maxSweepAmount = transferAmounts[i];
-            maxSweepIndex = i;
-        }
-    }
-    // ========================================
-    // 构建调用
-    // ========================================
-    const calls = [];
-    for (let i = 0; i < sourceWallets.length; i++) {
-        const sourceWallet = sourceWallets[i];
-        const amount = transferAmounts[i];
-        const hopWallets = allHopWallets[i];
-        if (amount <= 0n)
-            continue;
-        // ✅ 使用 Payer 时所有源钱包都用自己的余额（value: 0n）
-        const callValue = (payerWallet || i > 0) ? 0n : amount;
-        if (hopCount === 0 || hopWallets.length === 0) {
-            // ========================================
-            // 直接归集：源钱包 → 目标地址
-            // ========================================
-            // ✅ 最大归集钱包负责转 OKB 固定费用
-            if (profitAmountOkb > 0n && i === maxSweepIndex) {
-                calls.push({
-                    target: sourceWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('transferAmount', [profitRecipient, profitAmountOkb]),
-                });
-                console.log(`[sweep] 钱包 ${i} 转利润: ${ethers.formatEther(profitAmountOkb)} OKB → ${profitRecipient}`);
-            }
-            if (isNative) {
-                // ✅ 原生 OKB 归集
-                calls.push({
-                    target: sourceWallet.address,
-                    allowFailure: false,
-                    value: callValue,
-                    callData: delegateInterface.encodeFunctionData('transferAmount', [targetAddress, amount]),
-                });
-            }
-            else {
-                // ✅ ERC20 归集
-                calls.push({
-                    target: sourceWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('executeTransfer', [
-                        tokenAddress,
-                        targetAddress,
-                        amount,
-                    ]),
-                });
-            }
-        }
-        else {
-            // ========================================
-            // 多跳归集：源钱包 → hop1 → hop2 → ... → 目标地址
-            // ========================================
-            const firstHop = hopWallets[0];
-            const lastHop = hopWallets[hopWallets.length - 1];
-            // ✅ 最大归集钱包负责转 OKB 固定费用（在归集前）
-            if (profitAmountOkb > 0n && i === maxSweepIndex) {
-                calls.push({
-                    target: sourceWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('transferAmount', [profitRecipient, profitAmountOkb]),
-                });
-                console.log(`[sweep] 钱包 ${i} 转利润(多跳): ${ethers.formatEther(profitAmountOkb)} OKB → ${profitRecipient}`);
-            }
-            if (isNative) {
-                // 源钱包 → 第一个中间钱包
-                // ✅ 修复：使用 transferAmount 替代 transferTo，支持百分比归集
-                calls.push({
-                    target: sourceWallet.address,
-                    allowFailure: false,
-                    value: callValue,
-                    callData: delegateInterface.encodeFunctionData('transferAmount', [firstHop.address, amount]),
-                });
-                // 中间钱包之间转账
-                for (let j = 0; j < hopWallets.length - 1; j++) {
-                    calls.push({
-                        target: hopWallets[j].address,
-                        allowFailure: false,
-                        value: 0n,
-                        callData: delegateInterface.encodeFunctionData('transferTo', [hopWallets[j + 1].address]),
-                    });
-                }
-                // 最后一个中间钱包 → 目标地址
-                calls.push({
-                    target: lastHop.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('transferTo', [targetAddress]),
-                });
-            }
-            else {
-                // ERC20 多跳
-                // 源钱包 → 第一个中间钱包（ERC20 代币）
-                calls.push({
-                    target: sourceWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('executeTransfer', [
-                        tokenAddress,
-                        firstHop.address,
-                        amount,
-                    ]),
-                });
-                // 中间钱包之间转账
-                for (let j = 0; j < hopWallets.length - 1; j++) {
-                    calls.push({
-                        target: hopWallets[j].address,
-                        allowFailure: false,
-                        value: 0n,
-                        callData: delegateInterface.encodeFunctionData('executeTransferAll', [
-                            tokenAddress,
-                            hopWallets[j + 1].address,
-                        ]),
-                    });
-                }
-                // 最后一个中间钱包 → 目标地址
-                calls.push({
-                    target: lastHop.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('executeTransferAll', [
-                        tokenAddress,
-                        targetAddress,
-                    ]),
-                });
-            }
-        }
-    }
-    // ========================================
-    // 同步签署授权（已有 nonce）
-    // ========================================
-    // ✅ 收集所有需要授权的钱包
-    const allWallets = payerWallet ? [payerWallet] : [];
-    const allNonces = payerWallet ? [payerNonce] : [];
-    // 添加源钱包
-    for (let i = 0; i < sourceWallets.length; i++) {
-        allWallets.push(sourceWallets[i]);
-        allNonces.push(nonces[i]);
-    }
-    // 添加所有中间钱包
-    for (const hopWallets of allHopWallets) {
-        for (const hopWallet of hopWallets) {
-            allWallets.push(hopWallet);
-            allNonces.push(0);
-        }
-    }
-    const authorizations = signAuthorizationsWithNonces(allWallets, allNonces, delegateAddress, 0 // mainWallet 是交易发起者
-    );
-    // ========================================
-    // 同步构建交易
-    // ========================================
-    // ✅ Payer 模式下 value 为 0（资金来自源钱包）
-    const totalValue = (isNative && !payerWallet) ? transferAmounts[0] : 0n;
-    const signedTransaction = buildEIP7702TransactionSync(mainWallet, authorizations, calls, totalValue, payerWallet ? payerNonce : nonces[0], feeData, config);
-    // ✅ 返回所有中间钱包（扁平化）
-    const flatHopWallets = allHopWalletInfos.flat();
-    return {
-        signedTransaction,
-        hopWallets: flatHopWallets.length > 0 ? flatHopWallets : undefined,
-        metadata: {
-            targetAddress,
-            sourceCount: sourceWallets.length,
-            totalAmount: isNative ? ethers.formatEther(totalAmount) : ethers.formatUnits(totalAmount, tokenDecimals),
-            profitAmount: ethers.formatEther(profitAmountOkb), // ✅ 以 OKB 计
-            isNative,
-            tokenAddress: tokenAddress ?? null,
-            hopCount,
-            percent,
-            userType,
-        },
-    };
-}
-// ========================================
-// 多对多 (Pairwise) - sender[i] → receiver[i]
-// ========================================
-/**
- * 多对多转账 - sender[i] → receiver[i] 一一对应
- *
- * 支持：原生 OKB / ERC20 代币 + 可选多跳
- *
- * 每对都有独立的多跳链：sender → hop1 → hop2 → ... → receiver
- *
- * @example
- * // 原生 OKB 多对多（直接转账）
- * const result = await pairwiseTransfer({
- *   senderPrivateKeys: ['0xA...', '0xB...', '0xC...'],
- *   receiverAddresses: ['0x111', '0x222', '0x333'],
- *   amount: '0.1',
- * });
- *
- * @example
- * // 原生 OKB 多对多（带多跳）
- * const result = await pairwiseTransfer({
- *   senderPrivateKeys: ['0xA...', '0xB...'],
- *   receiverAddresses: ['0x111', '0x222'],
- *   amounts: ['0.1', '0.2'],
- *   hopCount: 2, // A → hop1 → hop2 → 111, B → hop3 → hop4 → 222
- * });
- *
- * @example
- * // ERC20 多对多（带多跳）
- * const result = await pairwiseTransfer({
- *   senderPrivateKeys: ['0xA...', '0xB...'],
- *   receiverAddresses: ['0x111', '0x222'],
- *   amount: '100',
- *   tokenAddress: '0xTOKEN...',
- *   tokenDecimals: 18,
- *   hopCount: 2,
- * });
- */
-export async function pairwiseTransfer(params) {
-    const { senderPrivateKeys, receiverAddresses, payerPrivateKey, amount, amounts, tokenAddress, tokenDecimals = 18, hopCount = 0, userType, config, } = params;
-    // 验证参数
-    if (senderPrivateKeys.length !== receiverAddresses.length) {
-        throw new Error(`senderPrivateKeys 长度 (${senderPrivateKeys.length}) 必须与 receiverAddresses 长度 (${receiverAddresses.length}) 相同`);
-    }
-    const pairCount = senderPrivateKeys.length;
-    if (pairCount === 0) {
-        throw new Error('至少需要一对发送者/接收者');
-    }
-    // 解析金额
-    const normalizedAmounts = (() => {
-        if (amounts && amounts.length > 0) {
-            if (amounts.length !== pairCount) {
-                throw new Error(`amounts 长度 (${amounts.length}) 必须与对数 (${pairCount}) 相同`);
-            }
-            return amounts;
-        }
-        if (amount !== undefined && amount.trim().length > 0) {
-            return new Array(pairCount).fill(amount);
-        }
-        throw new Error('必须提供 amount 或 amounts');
-    })();
-    const provider = getCachedProvider(config?.rpcUrl);
-    const delegateAddress = (config?.delegateAddress && config.delegateAddress.trim()) || UNIFIED_DELEGATE_ADDRESS;
-    const delegateInterface = new ethers.Interface(UNIFIED_DELEGATE_ABI);
-    const isNative = !tokenAddress;
-    const profitRecipient = getProfitRecipient(config);
-    // 创建钱包
-    const senderWallets = senderPrivateKeys.map(pk => createWallet(pk, provider));
-    // ✅ 支持单独的 Payer 钱包（用于支付 gas）
-    const hasSeparatePayer = payerPrivateKey && !senderPrivateKeys.includes(payerPrivateKey);
-    const payerWallet = hasSeparatePayer ? createWallet(payerPrivateKey, provider) : null;
-    const mainWallet = payerWallet ?? senderWallets[0];
-    // 为每对生成独立的中间钱包链
-    const allHopWalletInfos = [];
-    const allHopWallets = [];
-    for (let i = 0; i < pairCount; i++) {
-        if (hopCount > 0) {
-            const hopInfos = generateRandomWallets(hopCount);
-            allHopWalletInfos.push(hopInfos);
-            allHopWallets.push(hopInfos.map(info => createWallet(info.privateKey, provider)));
-        }
-        else {
-            allHopWalletInfos.push([]);
-            allHopWallets.push([]);
-        }
-    }
-    // 解析金额为 Wei
-    const amountsWei = normalizedAmounts.map(amt => isNative ? ethers.parseEther(amt) : ethers.parseUnits(amt, tokenDecimals));
-    const totalAmount = amountsWei.reduce((sum, amt) => sum + amt, 0n);
-    // ✅ 按地址数量收取固定费用（原生 OKB）
-    const profitAmountOkb = calculateTransferFee(XLAYER_CHAIN_ID, pairCount);
-    console.log(`[pairwiseTransfer] 按地址收费: ${pairCount} 个地址 × ${ethers.formatEther(calculateTransferFee(XLAYER_CHAIN_ID, 1))} = ${ethers.formatEther(profitAmountOkb)} OKB`);
-    // ✅ 使用第一个发送者支付 OKB 利润
-    const maxTransferIndex = 0;
-    // ========================================
-    // 并行获取数据
-    // ========================================
-    const senderAddresses = senderWallets.map(w => w.address);
-    const addressesToGetNonces = payerWallet
-        ? [payerWallet.address, ...senderAddresses]
-        : senderAddresses;
-    const [allNoncesResult, feeData] = await Promise.all([
-        batchGetNonces(addressesToGetNonces, provider),
-        provider.getFeeData(),
-    ]);
-    // 如果有单独的 Payer，第一个是 Payer 的 nonce，其余是发送者的
-    const payerNonce = payerWallet ? allNoncesResult[0] : allNoncesResult[0];
-    const nonces = payerWallet ? allNoncesResult.slice(1) : allNoncesResult;
-    // ========================================
-    // 构建调用
-    // ========================================
-    const calls = [];
-    for (let i = 0; i < pairCount; i++) {
-        const senderWallet = senderWallets[i];
-        const receiver = receiverAddresses[i];
-        const amtWei = amountsWei[i];
-        const hopWallets = allHopWallets[i];
-        // ✅ 如果有单独的 Payer，发送者使用自己的余额（value: 0n, 由 transferTo 使用 address(this).balance）
-        // ✅ 如果没有 Payer 且是第一个发送者（发起交易），需要传递 value
-        const shouldPassValue = !payerWallet && i === 0;
-        if (hopCount === 0 || hopWallets.length === 0) {
-            // ========================================
-            // 直接转账：sender → receiver
-            // ========================================
-            // ✅ 第一个发送者负责转 OKB 固定费用
-            if (profitAmountOkb > 0n && i === maxTransferIndex) {
-                calls.push({
-                    target: senderWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('transferAmount', [profitRecipient, profitAmountOkb]),
-                });
-                console.log(`[pairwiseTransfer] 发送者 ${i} 转利润: ${ethers.formatEther(profitAmountOkb)} OKB → ${profitRecipient}`);
-            }
-            if (isNative) {
-                // ✅ 使用 transferAmount 转移指定金额（而不是 transferTo 全额）
-                calls.push({
-                    target: senderWallet.address,
-                    allowFailure: false,
-                    value: shouldPassValue ? amtWei : 0n,
-                    callData: delegateInterface.encodeFunctionData('transferAmount', [receiver, amtWei]),
-                });
-            }
-            else {
-                // ERC20 代币转账
-                calls.push({
-                    target: senderWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('executeTransfer', [
-                        tokenAddress,
-                        receiver,
-                        amtWei,
-                    ]),
-                });
-            }
-        }
-        else {
-            // ========================================
-            // 多跳转账：sender → hop1 → hop2 → ... → receiver
-            // ========================================
-            const firstHop = hopWallets[0];
-            const lastHop = hopWallets[hopWallets.length - 1];
-            // ✅ 第一个发送者负责转 OKB 固定费用（在转账前）
-            if (profitAmountOkb > 0n && i === maxTransferIndex) {
-                calls.push({
-                    target: senderWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('transferAmount', [profitRecipient, profitAmountOkb]),
-                });
-                console.log(`[pairwiseTransfer] 发送者 ${i} 转利润(多跳): ${ethers.formatEther(profitAmountOkb)} OKB → ${profitRecipient}`);
-            }
-            if (isNative) {
-                // 原生 OKB 多跳
-                // ✅ sender → 第一个中间钱包（使用 transferAmount 转移指定金额）
-                calls.push({
-                    target: senderWallet.address,
-                    allowFailure: false,
-                    value: shouldPassValue ? amtWei : 0n,
-                    callData: delegateInterface.encodeFunctionData('transferAmount', [firstHop.address, amtWei]),
-                });
-                // 中间钱包之间转账（使用 transferTo，因为中间钱包只有这笔钱）
-                for (let j = 0; j < hopWallets.length - 1; j++) {
-                    calls.push({
-                        target: hopWallets[j].address,
-                        allowFailure: false,
-                        value: 0n,
-                        callData: delegateInterface.encodeFunctionData('transferTo', [hopWallets[j + 1].address]),
-                    });
-                }
-                // 最后一个中间钱包 → receiver（使用 transferTo 转移全部）
-                calls.push({
-                    target: lastHop.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('transferTo', [receiver]),
-                });
-            }
-            else {
-                // ERC20 多跳
-                // sender → 第一个中间钱包（ERC20 代币）
-                calls.push({
-                    target: senderWallet.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('executeTransfer', [
-                        tokenAddress,
-                        firstHop.address,
-                        amtWei,
-                    ]),
-                });
-                // 中间钱包之间转账
-                for (let j = 0; j < hopWallets.length - 1; j++) {
-                    calls.push({
-                        target: hopWallets[j].address,
-                        allowFailure: false,
-                        value: 0n,
-                        callData: delegateInterface.encodeFunctionData('executeTransferAll', [
-                            tokenAddress,
-                            hopWallets[j + 1].address,
-                        ]),
-                    });
-                }
-                // 最后一个中间钱包 → receiver
-                calls.push({
-                    target: lastHop.address,
-                    allowFailure: false,
-                    value: 0n,
-                    callData: delegateInterface.encodeFunctionData('executeTransferAll', [
-                        tokenAddress,
-                        receiver,
-                    ]),
-                });
-            }
-        }
-    }
-    // ========================================
-    // 同步签署授权（已有 nonce）
-    // ========================================
-    // ✅ 如果有单独的 Payer，需要为 Payer 也生成授权
-    const allWallets = payerWallet
-        ? [payerWallet, ...senderWallets]
-        : [...senderWallets];
-    const allNonces = payerWallet
-        ? [payerNonce, ...nonces]
-        : [...nonces];
-    for (const hopWallets of allHopWallets) {
-        for (const hopWallet of hopWallets) {
-            allWallets.push(hopWallet);
-            allNonces.push(0);
-        }
-    }
-    const authorizations = signAuthorizationsWithNonces(allWallets, allNonces, delegateAddress, 0 // mainWallet（可能是 Payer 或第一个发送者钱包）是交易发起者
-    );
-    // ========================================
-    // 同步构建交易
-    // ========================================
-    // ✅ Payer 模式下 value 为 0（资金来自发送者钱包）
-    const totalValue = (isNative && !payerWallet) ? totalAmount : 0n;
-    const signedTransaction = buildEIP7702TransactionSync(mainWallet, authorizations, calls, totalValue, payerWallet ? payerNonce : nonces[0], feeData, config);
-    return {
-        signedTransaction,
-        hopWallets: hopCount > 0 ? allHopWalletInfos : undefined,
-        metadata: {
-            pairCount,
-            totalAmount: isNative ? ethers.formatEther(totalAmount) : ethers.formatUnits(totalAmount, tokenDecimals),
-            profitAmount: ethers.formatEther(profitAmountOkb), // ✅ 以 OKB 计
-            isNative,
-            tokenAddress: tokenAddress ?? null,
-            hopCount,
-            userType,
-        },
-    };
-}
-// ========================================
-// 保留旧函数名的别名（向后兼容）
-// ========================================
-/** @deprecated 使用 disperse 替代 */
-export const disperseWithHops = disperse;
-/** @deprecated 使用 sweep 替代 */
-export const sweepWithHops = sweep;