four-flap-meme-sdk 2.2.19 → 3.0.0

package/dist/utils/constants.js

@@ -1,84 +1,9 @@
 /**
- * 公共常量 - 向后兼容层
+ * 公共常量 - 向后兼容 re-export 层
  *
- * ⚠️ 此文件为向后兼容保留，新代码请使用 shared/constants
+ * 新代码请直接使用 `shared/constants`：
+ * `import { CHAINS, ADDRESSES, getProfitRateBps } from '../core/constants/index.js'`
  *
- * 推荐用法：
- * import { CHAINS, GAS_LIMITS, ADDRESSES } from '../shared/constants';
+ * v2：不再导出 `CHAIN` / `DEFAULT_DEADLINE_MINUTES` / `PROFIT_CONFIG` / 报价 `V3_FEE_TIERS`。
  */
-// ============================================================================
-// 从 shared/constants 重新导出（新的标准入口）
-// ============================================================================
-export { 
-// 链配置
-CHAINS, CHAIN_ID_MAP, getChainById, getChainName, getDefaultRpcUrl, isKnownChain, isBscChain, isXLayerChain, isMonadChain, getConfirmationTimeout, 
-// Gas 常量
-GAS_LIMITS, GAS_CONFIG, V3_FEE_TIERS, calculateGasLimit, getTransferGasLimit, 
-// 合约地址
-ZERO_ADDRESS, BLOCKRAZOR_BUILDER_EOA, ADDRESSES, getAddress, getWrappedNativeAddress, getMulticall3Address, getFlapPortalAddress, isZeroAddress, isNativeToken, 
-// 利润配置
-PROFIT_CONFIG as PROFIT_CONFIG_NEW, getProfitRecipient, getAllProfitRecipients, getProfitRateBps, calculateProfitAmount, calculateProfitHopGasCost, 
-// ✅ 钱包转账按地址收费
-TRANSFER_FEE_PER_ADDRESS, getTransferFeePerAddress, calculateTransferFee, } from '../shared/constants/index.js';
-import { CHAINS, PROFIT_CONFIG as PROFIT_CONFIG_NEW } from '../shared/constants/index.js';
-// ============================================================================
-// 向后兼容：旧格式常量（标记为 @deprecated）
-// ============================================================================
-/**
- * @deprecated 使用 GAS_CONFIG.DEFAULT_DEADLINE_MINUTES 替代
- */
-export const DEFAULT_DEADLINE_MINUTES = 20;
-/**
- * @deprecated 使用 CHAINS 替代
- *
- * 旧格式的链配置，仅包含 chainId 和 name
- */
-export const CHAIN = {
-    BSC: {
-        chainId: CHAINS.BSC.chainId,
-        name: CHAINS.BSC.name,
-    },
-    BASE: {
-        chainId: CHAINS.BASE.chainId,
-        name: CHAINS.BASE.name
-    },
-    XLAYER: {
-        chainId: CHAINS.XLAYER.chainId,
-        name: CHAINS.XLAYER.name
-    },
-    MORPH: {
-        chainId: CHAINS.MORPH.chainId,
-        name: CHAINS.MORPH.name
-    },
-    ARBITRUM_ONE: {
-        chainId: CHAINS.ARBITRUM_ONE.chainId,
-        name: CHAINS.ARBITRUM_ONE.name
-    },
-    MONAD: {
-        chainId: CHAINS.MONAD.chainId,
-        name: CHAINS.MONAD.name
-    },
-};
-/**
- * @deprecated 使用 PROFIT_CONFIG_NEW 替代
- *
- * 旧格式的利润配置（扁平结构）
- */
-export const PROFIT_CONFIG = {
-    /** @deprecated 使用 getProfitRecipient() 随机获取 */
-    get RECIPIENT() {
-        return PROFIT_CONFIG_NEW.RECIPIENTS[Math.floor(Math.random() * PROFIT_CONFIG_NEW.RECIPIENTS.length)];
-    },
-    /** 利润比例（基点）：40 bps = 0.4%（普通模式） */
-    RATE_BPS: PROFIT_CONFIG_NEW.RATES.NORMAL,
-    /** 利润比例（基点）：6 bps = 0.06%（捆绑换手模式） */
-    RATE_BPS_SWAP: PROFIT_CONFIG_NEW.RATES.BUNDLE_SWAP,
-    /** 利润比例（单边基点）：8 bps = 0.08%（用户类型 v0） */
-    RATE_BPS_V0: PROFIT_CONFIG_NEW.RATES.V0_SINGLE,
-    /** 利润比例（双边基点）：4 bps = 0.04%（用户类型 v0） */
-    RATE_BPS_V0_DOUBLE: PROFIT_CONFIG_NEW.RATES.V0_DOUBLE,
-    /** 利润比例（单边基点）：10 bps = 0.10%（用户类型 v1） */
-    RATE_BPS_V1: PROFIT_CONFIG_NEW.RATES.V1_SINGLE,
-    /** 利润比例（双边基点）：5 bps = 0.05%（用户类型 v1） */
-    RATE_BPS_V1_DOUBLE: PROFIT_CONFIG_NEW.RATES.V1_DOUBLE,
-};
+export { CHAINS, CHAIN_ID_MAP, getChainById, getChainName, getDefaultRpcUrl, isKnownChain, isBscChain, isXLayerChain, isMonadChain, isEniChain, getConfirmationTimeout, GAS_LIMITS, GAS_CONFIG, calculateGasLimit, getTransferGasLimit, ZERO_ADDRESS, BLOCKRAZOR_BUILDER_EOA, ADDRESSES, getAddress, getWrappedNativeAddress, getMulticall3Address, getFlapPortalAddress, isZeroAddress, isNativeToken, getProfitRecipient, getAllProfitRecipients, getProfitRateBps, calculateProfitAmount, calculateProfitHopGasCost, TRANSFER_FEE_PER_ADDRESS, getTransferFeePerAddress, calculateTransferFee, QUOTE_CONFIG, QUOTE_V3_FEE_TIERS, } from '../core/constants/index.js';

package/dist/utils/contract-factory.d.ts

@@ -1,8 +1,6 @@
 import { Contract } from 'ethers';
-/**
- * 支持的链类型
- */
-export type ChainName = 'BSC' | 'BASE' | 'ARBITRUM_ONE';
+import type { ChainName } from './types/contract-factory.js';
+export type { ChainName } from './types/contract-factory.js';
 /**
  * 创建 TokenManager V1 合约实例（只读）
  * 自动使用正确的代理合约地址

package/dist/utils/contract-factory.js

@@ -1,84 +1,91 @@
-import { Contract, JsonRpcProvider, Wallet } from 'ethers';
-import { TokenManager, TokenManager2, TokenManagerHelper3 } from '../shared/abis/index.js';
-import { ADDRESSES } from './constants.js';
+import { Contract, Wallet } from 'ethers';
+import { TokenManager, TokenManager2, TokenManagerHelper3 } from '../abis/index.js';
+import { ADDRESSES } from '../core/constants/index.js';
+import { createProvider } from './provider-factory.js';
+const TOKEN_MANAGER_ABI = TokenManager;
+const TOKEN_MANAGER2_ABI = TokenManager2;
+const TOKEN_MANAGER_HELPER3_ABI = TokenManagerHelper3;
+function readOnlyProvider(rpcUrl) {
+    return createProvider(rpcUrl);
+}
+function writableProvider(rpcUrl, privateKey) {
+    return new Wallet(privateKey, createProvider(rpcUrl));
+}
 /**
  * 创建 TokenManager V1 合约实例（只读）
  * 自动使用正确的代理合约地址
  */
 export function getTokenManagerV1(chain, rpcUrl) {
-    const provider = new JsonRpcProvider(rpcUrl, undefined); // ✅ 禁用 ENS
+    const provider = readOnlyProvider(rpcUrl);
     const chainAddresses = ADDRESSES[chain];
     const address = 'TokenManagerV1' in chainAddresses ? chainAddresses.TokenManagerV1 : undefined;
     if (!address) {
         throw new Error(`TokenManager V1 not deployed on ${chain}`);
     }
-    return new Contract(address, TokenManager, provider);
+    return new Contract(address, TOKEN_MANAGER_ABI, provider);
 }
 /**
  * 创建 TokenManager V2 合约实例（只读）
  * 自动使用正确的代理合约地址
  */
 export function getTokenManagerV2(chain, rpcUrl) {
-    const provider = new JsonRpcProvider(rpcUrl, undefined); // ✅ 禁用 ENS
+    const provider = readOnlyProvider(rpcUrl);
     const chainAddresses = ADDRESSES[chain];
     const address = 'TokenManagerV2' in chainAddresses ? chainAddresses.TokenManagerV2 : undefined;
     if (!address) {
         throw new Error(`TokenManager V2 not deployed on ${chain}`);
     }
-    return new Contract(address, TokenManager2, provider);
+    return new Contract(address, TOKEN_MANAGER2_ABI, provider);
 }
 /**
  * 创建 TokenManagerHelper3 合约实例（只读）
  * 自动使用正确的代理合约地址
  */
 export function getTokenManagerHelper3(chain, rpcUrl) {
-    const provider = new JsonRpcProvider(rpcUrl, undefined); // ✅ 禁用 ENS
+    const provider = readOnlyProvider(rpcUrl);
     const address = ADDRESSES[chain].TokenManagerHelper3;
     if (!address) {
         throw new Error(`TokenManagerHelper3 not deployed on ${chain}`);
     }
-    return new Contract(address, TokenManagerHelper3, provider);
+    return new Contract(address, TOKEN_MANAGER_HELPER3_ABI, provider);
 }
 /**
  * 创建 TokenManager V1 合约实例（可写）
  * 自动使用正确的代理合约地址
  */
 export function getTokenManagerV1Writer(chain, rpcUrl, privateKey) {
-    const provider = new JsonRpcProvider(rpcUrl, undefined); // ✅ 禁用 ENS
-    const signer = new Wallet(privateKey, provider);
+    const signer = writableProvider(rpcUrl, privateKey);
     const chainAddresses = ADDRESSES[chain];
     const address = 'TokenManagerV1' in chainAddresses ? chainAddresses.TokenManagerV1 : undefined;
     if (!address) {
         throw new Error(`TokenManager V1 not deployed on ${chain}`);
     }
-    return new Contract(address, TokenManager, signer);
+    return new Contract(address, TOKEN_MANAGER_ABI, signer);
 }
 /**
  * 创建 TokenManager V2 合约实例（可写）
  * 自动使用正确的代理合约地址
  */
 export function getTokenManagerV2Writer(chain, rpcUrl, privateKey) {
-    const provider = new JsonRpcProvider(rpcUrl, undefined); // ✅ 禁用 ENS
-    const signer = new Wallet(privateKey, provider);
+    const signer = writableProvider(rpcUrl, privateKey);
     const chainAddresses = ADDRESSES[chain];
     const address = 'TokenManagerV2' in chainAddresses ? chainAddresses.TokenManagerV2 : undefined;
     if (!address) {
         throw new Error(`TokenManager V2 not deployed on ${chain}`);
     }
-    return new Contract(address, TokenManager2, signer);
+    return new Contract(address, TOKEN_MANAGER2_ABI, signer);
 }
 /**
  * 创建 TokenManagerHelper3 合约实例（可写）
  * 自动使用正确的代理合约地址
  */
 export function getTokenManagerHelper3Writer(chain, rpcUrl, privateKey) {
-    const provider = new JsonRpcProvider(rpcUrl, undefined); // ✅ 禁用 ENS
-    const signer = new Wallet(privateKey, provider);
+    const signer = writableProvider(rpcUrl, privateKey);
     const address = ADDRESSES[chain].TokenManagerHelper3;
     if (!address) {
         throw new Error(`TokenManagerHelper3 not deployed on ${chain}`);
     }
-    return new Contract(address, TokenManagerHelper3, signer);
+    return new Contract(address, TOKEN_MANAGER_HELPER3_ABI, signer);
 }
 /**
  * 获取链上 TokenManager 的代理合约地址

package/dist/utils/errors.d.ts

@@ -1,5 +1,16 @@
-export type FourErrorCode = 'GW' | 'ZA' | 'TO' | 'Slippage' | 'More BNB' | 'FR' | 'SO';
+import { SdkErrorCode } from '../core/legacy-types/errors.js';
+import type { FourErrorCode } from './types/errors.js';
+export { SdkErrorCode } from '../core/legacy-types/errors.js';
+export type { FourErrorCode } from './types/errors.js';
 export declare function parseFourError(err: unknown): {
     code?: FourErrorCode;
     message: string;
 };
+/** 统一结构化错误（含错误码，便于上层分支处理） */
+export declare class SdkError extends Error {
+    readonly code: SdkErrorCode;
+    cause?: unknown;
+    constructor(code: SdkErrorCode, message: string, cause?: unknown);
+}
+/** 将任意异常归一为 SdkError */
+export declare function parseSdkError(err: unknown): SdkError;

package/dist/utils/errors.js

@@ -1,3 +1,6 @@
+import { getErrorMessageFromUnknown } from '../core/normalize-unknown.js';
+import { SdkErrorCode } from '../core/legacy-types/errors.js';
+export { SdkErrorCode } from '../core/legacy-types/errors.js';
 const MESSAGES = {
     GW: 'Amount precision is not aligned to GWEI',
     ZA: "The 'to' address should not be address(0)",
@@ -8,9 +11,65 @@ const MESSAGES = {
     SO: 'Order amount is too small',
 };
 export function parseFourError(err) {
-    const raw = String(err?.message ?? err);
+    const raw = getErrorMessageFromUnknown(err);
     const found = Object.keys(MESSAGES).find((k) => raw.includes(k));
     if (found)
         return { code: found, message: MESSAGES[found] };
     return { message: raw };
 }
+function mapFourCodeToSdk(code) {
+    switch (code) {
+        case 'GW':
+            return SdkErrorCode.FOUR_GWEI_PRECISION;
+        case 'ZA':
+            return SdkErrorCode.FOUR_ZERO_ADDRESS;
+        case 'TO':
+            return SdkErrorCode.FOUR_ZERO_ADDRESS;
+        case 'Slippage':
+            return SdkErrorCode.FOUR_SLIPPAGE;
+        case 'More BNB':
+            return SdkErrorCode.FOUR_INSUFFICIENT_FUNDS;
+        case 'FR':
+            return SdkErrorCode.FOUR_FEE_TOO_HIGH;
+        case 'SO':
+            return SdkErrorCode.FOUR_ORDER_TOO_SMALL;
+        default:
+            return SdkErrorCode.UNKNOWN_ERROR;
+    }
+}
+/** 统一结构化错误（含错误码，便于上层分支处理） */
+export class SdkError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause !== undefined ? { cause } : undefined);
+        this.name = 'SdkError';
+        this.code = code;
+    }
+}
+/** 将任意异常归一为 SdkError */
+export function parseSdkError(err) {
+    if (err instanceof SdkError)
+        return err;
+    if (err === null || err === undefined) {
+        return new SdkError(SdkErrorCode.UNKNOWN_ERROR, 'Unknown error');
+    }
+    const raw = getErrorMessageFromUnknown(err);
+    const rawLower = raw.toLowerCase();
+    const four = parseFourError(err);
+    if (four.code) {
+        return new SdkError(mapFourCodeToSdk(four.code), four.message);
+    }
+    if (rawLower.includes('token already exists')) {
+        return new SdkError(SdkErrorCode.TOKEN_ALREADY_EXISTS, raw);
+    }
+    if (rawLower.includes('slippage')) {
+        return new SdkError(SdkErrorCode.SLIPPAGE_EXCEEDED, raw);
+    }
+    if (rawLower.includes('insufficient funds') || rawLower.includes('insufficient balance')) {
+        return new SdkError(SdkErrorCode.INSUFFICIENT_BALANCE, raw);
+    }
+    if (rawLower.includes('permit expired')) {
+        return new SdkError(SdkErrorCode.PERMIT_EXPIRED, raw);
+    }
+    return new SdkError(SdkErrorCode.UNKNOWN_ERROR, raw);
+}

package/dist/utils/hop-chains.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 多跳（Hop Chain）转账链生成工具
+ *
+ * 提取自 chains/bsc/four/swap.ts、chains/bsc/pancake/bundle-swap.ts、domains/flap/portal-bundle-merkle/swap.ts
+ * 消除三个文件之间的复制代码
+ */
+import { ethers, Wallet, JsonRpcProvider } from 'ethers';
+import type { DisperseHopPath } from './types/hop-chains.js';
+export type { DisperseHopPath } from './types/hop-chains.js';
+export declare const NATIVE_TRANSFER_GAS_LIMIT: 21055n;
+export declare const ERC20_TRANSFER_GAS_LIMIT_HOP: 65000n;
+export declare const BRIBE_GAS_LIMIT: 21000n;
+/**
+
+/**
+ * 给交易对象附加 gasPrice/maxFeePerGas（根据 txType）
+ * 消除 `if (txType === 2) { ... } else { ... }` 手写重复
+ */
+export declare function applyTxTypeGas(tx: ethers.TransactionLike, gasPrice: bigint, txType: 0 | 2): void;
+/**
+ * 生成分发多跳路径
+ */
+export declare function generateDisperseHopPaths(targetAddresses: string[], hopCount: number, provider: JsonRpcProvider): DisperseHopPath[];
+/**
+ * 构建原生代币多跳转账链
+ */
+export declare function buildNativeHopChain(payer: Wallet, path: DisperseHopPath, finalAmount: bigint, gasPrice: bigint, chainId: number, txType: 0 | 2, payerNonce: number): Promise<string[]>;
+/**
+ * 构建 ERC20 多跳转账链（需要配合 BNB 多跳使用）
+ */
+export declare function buildERC20HopChain(payer: Wallet, path: DisperseHopPath, erc20Address: string, erc20Amount: bigint, gasPrice: bigint, chainId: number, txType: 0 | 2, payerNonce: number): Promise<string[]>;
+/**
+ * 构建 BNB 多跳转账链（为 ERC20 中间钱包预留 gas）
+ */
+export declare function buildBNBHopChainForERC20(payer: Wallet, path: DisperseHopPath, finalGasAmount: bigint, gasPrice: bigint, chainId: number, txType: 0 | 2, payerNonce: number): Promise<string[]>;

package/dist/utils/hop-chains.js

@@ -0,0 +1,215 @@
+/**
+ * 多跳（Hop Chain）转账链生成工具
+ *
+ * 提取自 chains/bsc/four/swap.ts、chains/bsc/pancake/bundle-swap.ts、domains/flap/portal-bundle-merkle/swap.ts
+ * 消除三个文件之间的复制代码
+ */
+import { ethers, Wallet } from 'ethers';
+import { GAS_LIMITS } from '../core/constants/index.js';
+import { ERC20_ABI } from '../abis/common.js';
+import { generateWallets } from './wallet.js';
+export const NATIVE_TRANSFER_GAS_LIMIT = GAS_LIMITS.NATIVE_TRANSFER;
+export const ERC20_TRANSFER_GAS_LIMIT_HOP = GAS_LIMITS.ERC20_TRANSFER;
+export const BRIBE_GAS_LIMIT = GAS_LIMITS.BRIBE;
+/**
+
+/**
+ * 给交易对象附加 gasPrice/maxFeePerGas（根据 txType）
+ * 消除 `if (txType === 2) { ... } else { ... }` 手写重复
+ */
+export function applyTxTypeGas(tx, gasPrice, txType) {
+    if (txType === 2) {
+        tx.maxFeePerGas = gasPrice;
+        tx.maxPriorityFeePerGas = gasPrice / 10n || 1n;
+    }
+    else {
+        tx.gasPrice = gasPrice;
+    }
+}
+// ============================================================================
+// 生成多跳路径
+// ============================================================================
+/**
+ * 生成分发多跳路径
+ */
+export function generateDisperseHopPaths(targetAddresses, hopCount, provider) {
+    if (hopCount <= 0) {
+        return targetAddresses.map((addr) => ({
+            targetAddress: addr,
+            hopWallets: [],
+            hopWalletsInfo: [],
+        }));
+    }
+    return targetAddresses.map((targetAddress) => {
+        const hopWalletsInfo = generateWallets(hopCount);
+        const hopWallets = hopWalletsInfo.map((w) => new Wallet(w.privateKey, provider));
+        return { targetAddress, hopWallets, hopWalletsInfo };
+    });
+}
+// ============================================================================
+// 原生代币多跳
+// ============================================================================
+/**
+ * 构建原生代币多跳转账链
+ */
+export async function buildNativeHopChain(payer, path, finalAmount, gasPrice, chainId, txType, payerNonce) {
+    const signedTxs = [];
+    const hopCount = path.hopWallets.length;
+    if (hopCount === 0) {
+        const tx = {
+            to: path.targetAddress,
+            value: finalAmount,
+            nonce: payerNonce,
+            gasLimit: NATIVE_TRANSFER_GAS_LIMIT,
+            chainId,
+            type: txType,
+        };
+        applyTxTypeGas(tx, gasPrice, txType);
+        signedTxs.push(await payer.signTransaction(tx));
+        return signedTxs;
+    }
+    const hopGasCost = NATIVE_TRANSFER_GAS_LIMIT * gasPrice;
+    // 计算每跳需要的金额
+    const amountsPerHop = [];
+    for (let i = 0; i < hopCount; i++) {
+        const remainingHops = hopCount - i;
+        amountsPerHop.push(finalAmount + hopGasCost * BigInt(remainingHops));
+    }
+    // payer → hop1
+    const firstTx = {
+        to: path.hopWallets[0].address,
+        value: amountsPerHop[0],
+        nonce: payerNonce,
+        gasLimit: NATIVE_TRANSFER_GAS_LIMIT,
+        chainId,
+        type: txType,
+    };
+    applyTxTypeGas(firstTx, gasPrice, txType);
+    signedTxs.push(await payer.signTransaction(firstTx));
+    // hop1 → hop2 → ... → target
+    for (let i = 0; i < hopCount; i++) {
+        const fromWallet = path.hopWallets[i];
+        const toAddress = i === hopCount - 1 ? path.targetAddress : path.hopWallets[i + 1].address;
+        const amount = i === hopCount - 1 ? finalAmount : amountsPerHop[i + 1];
+        const tx = {
+            to: toAddress,
+            value: amount,
+            nonce: 0,
+            gasLimit: NATIVE_TRANSFER_GAS_LIMIT,
+            chainId,
+            type: txType,
+        };
+        applyTxTypeGas(tx, gasPrice, txType);
+        signedTxs.push(await fromWallet.signTransaction(tx));
+    }
+    return signedTxs;
+}
+// ============================================================================
+// ERC20 多跳
+// ============================================================================
+/**
+ * 构建 ERC20 多跳转账链（需要配合 BNB 多跳使用）
+ */
+export async function buildERC20HopChain(payer, path, erc20Address, erc20Amount, gasPrice, chainId, txType, payerNonce) {
+    const signedTxs = [];
+    const hopCount = path.hopWallets.length;
+    const erc20Interface = new ethers.Interface(ERC20_ABI);
+    if (hopCount === 0) {
+        const data = erc20Interface.encodeFunctionData('transfer', [path.targetAddress, erc20Amount]);
+        const tx = {
+            to: erc20Address,
+            data,
+            value: 0n,
+            nonce: payerNonce,
+            gasLimit: ERC20_TRANSFER_GAS_LIMIT_HOP,
+            chainId,
+            type: txType,
+        };
+        applyTxTypeGas(tx, gasPrice, txType);
+        signedTxs.push(await payer.signTransaction(tx));
+        return signedTxs;
+    }
+    // payer → hop1
+    const firstData = erc20Interface.encodeFunctionData('transfer', [path.hopWallets[0].address, erc20Amount]);
+    const firstTx = {
+        to: erc20Address,
+        data: firstData,
+        value: 0n,
+        nonce: payerNonce,
+        gasLimit: ERC20_TRANSFER_GAS_LIMIT_HOP,
+        chainId,
+        type: txType,
+    };
+    applyTxTypeGas(firstTx, gasPrice, txType);
+    signedTxs.push(await payer.signTransaction(firstTx));
+    // hop1 → hop2 → ... → target (nonce=1，nonce=0 用于 BNB 转发)
+    for (let i = 0; i < hopCount; i++) {
+        const fromWallet = path.hopWallets[i];
+        const toAddress = i === hopCount - 1 ? path.targetAddress : path.hopWallets[i + 1].address;
+        const data = erc20Interface.encodeFunctionData('transfer', [toAddress, erc20Amount]);
+        const tx = {
+            to: erc20Address,
+            data,
+            value: 0n,
+            nonce: 1, // nonce=0 已用于 BNB 转发
+            gasLimit: ERC20_TRANSFER_GAS_LIMIT_HOP,
+            chainId,
+            type: txType,
+        };
+        applyTxTypeGas(tx, gasPrice, txType);
+        signedTxs.push(await fromWallet.signTransaction(tx));
+    }
+    return signedTxs;
+}
+// ============================================================================
+// BNB 多跳（为 ERC20 中间钱包预留 Gas）
+// ============================================================================
+/**
+ * 构建 BNB 多跳转账链（为 ERC20 中间钱包预留 gas）
+ */
+export async function buildBNBHopChainForERC20(payer, path, finalGasAmount, gasPrice, chainId, txType, payerNonce) {
+    const signedTxs = [];
+    const hopCount = path.hopWallets.length;
+    if (hopCount === 0) {
+        // 无多跳时不需要转 gas
+        return signedTxs;
+    }
+    const hopGasCost = NATIVE_TRANSFER_GAS_LIMIT * gasPrice;
+    const erc20GasCost = ERC20_TRANSFER_GAS_LIMIT_HOP * gasPrice;
+    // 每个中间钱包需要: BNB 转发 gas + ERC20 转发 gas
+    const gasPerHop = hopGasCost + erc20GasCost * 2n; // 2倍安全系数
+    // 计算每跳需要的金额
+    const amountsPerHop = [];
+    for (let i = 0; i < hopCount; i++) {
+        const remainingHops = hopCount - i;
+        amountsPerHop.push(finalGasAmount + gasPerHop * BigInt(remainingHops));
+    }
+    // payer → hop1
+    const firstTx = {
+        to: path.hopWallets[0].address,
+        value: amountsPerHop[0],
+        nonce: payerNonce,
+        gasLimit: NATIVE_TRANSFER_GAS_LIMIT,
+        chainId,
+        type: txType,
+    };
+    applyTxTypeGas(firstTx, gasPrice, txType);
+    signedTxs.push(await payer.signTransaction(firstTx));
+    // hop1 → hop2 → ... → target
+    for (let i = 0; i < hopCount; i++) {
+        const fromWallet = path.hopWallets[i];
+        const toAddress = i === hopCount - 1 ? path.targetAddress : path.hopWallets[i + 1].address;
+        const amount = i === hopCount - 1 ? finalGasAmount : amountsPerHop[i + 1];
+        const tx = {
+            to: toAddress,
+            value: amount,
+            nonce: 1, // nonce=0 已用于 ERC20 转发
+            gasLimit: NATIVE_TRANSFER_GAS_LIMIT,
+            chainId,
+            type: txType,
+        };
+        applyTxTypeGas(tx, gasPrice, txType);
+        signedTxs.push(await fromWallet.signTransaction(tx));
+    }
+    return signedTxs;
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+/** pure utils barrel */
+export * from './wallet.js';
+export * from './concurrency.js';
+export * from './provider-factory.js';
+export * from './bundle-helpers.js';

package/dist/utils/index.js

@@ -0,0 +1,5 @@
+/** pure utils barrel */
+export * from './wallet.js';
+export * from './concurrency.js';
+export * from './provider-factory.js';
+export * from './bundle-helpers.js';

package/dist/utils/mpcExclusive.d.ts

@@ -1,8 +1,5 @@
-export type ExclusiveCheckOnChainParams = {
-    chain: 'BSC';
-    tokenAddress: string;
-    rpcUrl: string;
-};
+import type { ExclusiveCheckOnChainParams } from './types/mpc-exclusive.js';
+export type { ExclusiveCheckOnChainParams } from './types/mpc-exclusive.js';
 export declare function isExclusiveOnChain(params: ExclusiveCheckOnChainParams): Promise<boolean>;
 export declare function isExclusiveOffChain(getTokenInfo: (token: string) => Promise<{
     version?: string;

package/dist/utils/mpcExclusive.js

@@ -1,12 +1,13 @@
 import { Contract, JsonRpcProvider } from 'ethers';
-import TokenManager2Abi from '../shared/abis/TokenManager2.json' with { type: 'json' };
-import { ADDRESSES } from './constants.js';
+import TokenManager2Abi from '../abis/contracts/TokenManager2.json' with { type: 'json' };
+import { ADDRESSES } from '../core/constants/index.js';
+const TOKEN_MANAGER2_ABI = TokenManager2Abi;
 // 链上识别：template & 0x10000 > 0
 export async function isExclusiveOnChain(params) {
     const { chain, tokenAddress, rpcUrl } = params;
     const tokenManager2Address = ADDRESSES[chain].TokenManagerV2;
     const provider = new JsonRpcProvider(rpcUrl);
-    const tm2 = new Contract(tokenManager2Address, TokenManager2Abi, provider);
+    const tm2 = new Contract(tokenManager2Address, TOKEN_MANAGER2_ABI, provider);
     const info = await tm2._tokenInfos(tokenAddress);
     const template = info.template;
     return (template & 0x10000n) > 0n;

package/dist/utils/provider-factory.d.ts

@@ -25,6 +25,10 @@ export declare function createCachedProvider(rpcUrl: string, chainId: number, ch
  * 清除 Provider 缓存
  */
 export declare function clearProviderCache(): void;
+/**
+ * ENI 专用 Provider（staticNetwork，适合批量 RPC）
+ */
+export declare function createEniProvider(rpcUrl: string, chainId?: number): JsonRpcProvider;
 /**
  * XLayer 专用 Provider 创建函数
  */

package/dist/utils/provider-factory.js

@@ -72,6 +72,16 @@ export function createCachedProvider(rpcUrl, chainId, chainName) {
 export function clearProviderCache() {
     providerCache.clear();
 }
+/**
+ * ENI 专用 Provider（staticNetwork，适合批量 RPC）
+ */
+export function createEniProvider(rpcUrl, chainId = 173) {
+    return new JsonRpcProvider(rpcUrl, chainId, {
+        staticNetwork: true,
+        batchMaxCount: 20,
+        batchStallTime: 30,
+    });
+}
 /**
  * XLayer 专用 Provider 创建函数
  */

package/dist/utils/stealth-transfer.d.ts

@@ -1,31 +1,5 @@
-import type { SoulPointSignatureMode, VNormalizationMode } from '../shared/clients/club48.js';
-export type StealthTransferResult = {
-    bundleUuid: string;
-    txs: string[];
-    hopAddresses: string[];
-};
-/**
- * 简化版隐秘转账参数
- * - 仅需人类可读金额与（可选）代币地址，其余自动处理
- * - 未提供 tokenAddress → 原生币模式；提供 tokenAddress → 自动读取 decimals 转换为 wei 的代币模式
- */
-export type StealthTransferSimpleParams = {
-    rpcUrl: string;
-    chainId: number;
-    rootPrivateKey: string;
-    finalTo: string;
-    hopCount: number;
-    amount: string;
-    tokenAddress?: string;
-    tokenHolderPrivateKey?: string;
-    bundleEndpoint?: string;
-    gasPriceGwei?: string;
-    gasLimit?: bigint;
-    blockOffset?: number;
-    spMode?: SoulPointSignatureMode;
-    spPrivateKey?: string;
-    spVMode?: VNormalizationMode;
-};
+import type { StealthTransferResult, StealthTransferSimpleParams } from './types/stealth-transfer.js';
+export type { StealthTransferResult, StealthTransferSimpleParams } from './types/stealth-transfer.js';
 /**
  * 隐秘转账（简化版）
  * - 原生模式：amount 按 parseEther 转 wei