four-flap-meme-sdk 2.2.18 → 2.2.20

package/dist/shared/flap/vault.d.ts

@@ -1,12 +1,20 @@
 /**
  * Flap Tax Vaults（税收金库）
  *
+ * ⚠️ 重要：基于 flap.sh/launch 实际源码分析，金库模式架构如下：
+ *
  * 1. 金库代币通过 VaultPortal 合约创建（不是普通 Portal）
- * 2. 调用函数：VaultPortal.newTokenV6WithVault(params) + tokenVersion = TOKEN_TAXED_V3
- * 3. newTaxTokenWithVault 已在链上废弃，请勿再使用
- * 4. 金库配置通过 vaultFactory + vaultData 传递；extensionID/extensionData 始终为零
+ * 2. 调用函数：VaultPortal.newTaxTokenWithVault(params)
+ * 3. 参数中 extensionID/extensionData 始终为零值
+ * 4. 真正的金库配置通过 vaultFactory（工厂地址）和 vaultData（ABI 编码数据）传递
+ * 5. 每种金库类型对应一个具体的 VaultFactory 合约地址
  *
- * @see https://docs.flap.sh/flap/developers/token-launcher-developers/launch-token-through-vaultportal
+ * VaultPortal.newTaxTokenWithVault 参数结构：
+ *   - 基础参数（与 Portal.newTokenV5 相同）：name, symbol, meta, dexThresh, salt, taxRate,
+ *     migratorType, quoteToken, quoteAmt, permitData, extensionID(全零), extensionData("0x"),
+ *     dexId, lpFeeProfile, taxDuration, antiFarmerDuration, mktBps, deflationBps, dividendBps,
+ *     lpBps, minimumShareBalance
+ *   - 金库专属参数：vaultFactory(address), vaultData(bytes)
  *
  * 金库分类（来自 flap.sh 源码）：
  *   官方金库 (official)：
@@ -20,8 +28,6 @@
  * @module vault
  */
 import { type JsonRpcProvider } from 'ethers';
-import { TokenVersion } from './portal.js';
-import type { TaxV2Config } from './portal-bundle-merkle/types.js';
 /**
  * FieldDescriptor — 字段描述符
  * 对应 Solidity 结构体 IVaultSchemasV1.FieldDescriptor
@@ -111,18 +117,19 @@ export declare const VAULT_EXTRA_CONFIG: Record<string, Record<string, Record<st
 export declare const FLAP_GUARDIAN_ADDRESSES: {
     readonly BSC: "0x9e27098dcD8844bcc6287a557E0b4D09C86B8a4b";
 };
-/** VaultPortal 金库发射必须使用 TOKEN_TAXED_V3（enum = 6） */
-export declare const TOKEN_TAXED_V3_VERSION = TokenVersion.TOKEN_TAXED_V3;
 /**
- * VaultPortal ABI — newTokenV6WithVault（当前唯一支持的金库发射入口）
+ * VaultPortal ABI — newTaxTokenWithVault
+ *
+ * ⚠️ 从 flap.sh 前端 JS 源码提取的真实 ABI
+ * 来源：flap.sh/_next/static/chunks/6288-*.js（VaultPortal 合约 ABI）
  */
 export declare const VAULT_PORTAL_ABI: readonly [{
     readonly type: "function";
-    readonly name: "newTokenV6WithVault";
+    readonly name: "newTaxTokenWithVault";
     readonly inputs: readonly [{
         readonly name: "params";
         readonly type: "tuple";
-        readonly internalType: "struct IVaultPortalTypes.NewTokenV6WithVaultParams";
+        readonly internalType: "struct IVaultPortalTypes.NewTaxTokenWithVaultParams";
         readonly components: readonly [{
             readonly name: "name";
             readonly type: "string";
@@ -138,11 +145,15 @@ export declare const VAULT_PORTAL_ABI: readonly [{
         }, {
             readonly name: "dexThresh";
             readonly type: "uint8";
-            readonly internalType: "enum IPortalTypes.DexThreshType";
+            readonly internalType: "enum IPortalCommonTypes.DexThreshType";
         }, {
             readonly name: "salt";
             readonly type: "bytes32";
             readonly internalType: "bytes32";
+        }, {
+            readonly name: "taxRate";
+            readonly type: "uint16";
+            readonly internalType: "uint16";
         }, {
             readonly name: "migratorType";
             readonly type: "uint8";
@@ -175,14 +186,6 @@ export declare const VAULT_PORTAL_ABI: readonly [{
             readonly name: "lpFeeProfile";
             readonly type: "uint8";
             readonly internalType: "enum IPortalTypes.V3LPFeeProfile";
-        }, {
-            readonly name: "buyTaxRate";
-            readonly type: "uint16";
-            readonly internalType: "uint16";
-        }, {
-            readonly name: "sellTaxRate";
-            readonly type: "uint16";
-            readonly internalType: "uint16";
         }, {
             readonly name: "taxDuration";
             readonly type: "uint64";
@@ -211,18 +214,6 @@ export declare const VAULT_PORTAL_ABI: readonly [{
             readonly name: "minimumShareBalance";
             readonly type: "uint256";
             readonly internalType: "uint256";
-        }, {
-            readonly name: "dividendToken";
-            readonly type: "address";
-            readonly internalType: "address";
-        }, {
-            readonly name: "commissionReceiver";
-            readonly type: "address";
-            readonly internalType: "address";
-        }, {
-            readonly name: "tokenVersion";
-            readonly type: "uint8";
-            readonly internalType: "enum IPortalTypes.TokenVersion";
         }, {
             readonly name: "vaultFactory";
             readonly type: "address";
@@ -351,67 +342,8 @@ export declare function getVaultFactoryAddress(chain: string, vaultType: VaultTy
  * 获取指定链的 VaultPortal 合约地址
  */
 export declare function getVaultPortalAddress(chain: string): string | null;
-export type BuildNewTokenV6WithVaultInput = {
-    tokenInfo: {
-        name: string;
-        symbol: string;
-        meta: string;
-    };
-    taxV2: TaxV2Config;
-    chain: string;
-    salt?: string;
-    taxRate?: number;
-    buyTaxRate?: number;
-    sellTaxRate?: number;
-    dexThresh?: number;
-    migratorType?: number;
-    quoteToken?: string;
-    quoteAmt?: bigint;
-    dexId?: number;
-    lpFeeProfile?: number;
-};
-/**
- * 构建 VaultPortal.newTokenV6WithVault 参数（TOKEN_TAXED_V3）
- */
-export declare function buildNewTokenV6WithVaultParams(input: BuildNewTokenV6WithVaultInput): {
-    name: string;
-    symbol: string;
-    meta: string;
-    dexThresh: number;
-    salt: string;
-    migratorType: number;
-    quoteToken: string;
-    quoteAmt: bigint;
-    permitData: string;
-    extensionID: string;
-    extensionData: string;
-    dexId: number;
-    lpFeeProfile: number;
-    buyTaxRate: number;
-    sellTaxRate: number;
-    taxDuration: bigint;
-    antiFarmerDuration: bigint;
-    mktBps: number;
-    deflationBps: number;
-    dividendBps: number;
-    lpBps: number;
-    minimumShareBalance: bigint;
-    dividendToken: string;
-    commissionReceiver: string;
-    tokenVersion: TokenVersion;
-    vaultFactory: string;
-    vaultData: string;
-};
-/** 金库发射 Vanity：TOKEN_TAXED_V3 + 后缀 7777 */
-export declare function getVaultLaunchVanityOptions(chain: string): {
-    taxed: boolean;
-    taxedV3: boolean;
-    taxedV5: boolean;
-    suffix: string;
-    chain: "BSC" | "XLAYER" | "MONAD" | "BASE" | "MORPH";
-};
 /**
- * 构建金库参数（用于 VaultPortal.newTokenV6WithVault）
+ * 构建金库参数（用于 VaultPortal.newTaxTokenWithVault）
  *
  * ⚠️ 重要：返回的是 vaultFactory 和 vaultData，不是 extensionID/extensionData
  * extensionID/extensionData 在金库模式下始终为零值
@@ -429,7 +361,7 @@ export declare function buildVaultParams(config?: TaxVaultConfig, chain?: string
  * 金库参数通过 VaultPortal 的 vaultFactory/vaultData 传递
  * 此函数仅用于向后兼容
  */
-export declare function buildVaultExtensionParams(config?: TaxVaultConfig): {
+export declare function buildVaultExtensionParams(): {
     extensionID: string;
     extensionData: string;
 };

package/dist/shared/flap/vault.js

@@ -1,12 +1,20 @@
 /**
  * Flap Tax Vaults（税收金库）
  *
+ * ⚠️ 重要：基于 flap.sh/launch 实际源码分析，金库模式架构如下：
+ *
  * 1. 金库代币通过 VaultPortal 合约创建（不是普通 Portal）
- * 2. 调用函数：VaultPortal.newTokenV6WithVault(params) + tokenVersion = TOKEN_TAXED_V3
- * 3. newTaxTokenWithVault 已在链上废弃，请勿再使用
- * 4. 金库配置通过 vaultFactory + vaultData 传递；extensionID/extensionData 始终为零
+ * 2. 调用函数：VaultPortal.newTaxTokenWithVault(params)
+ * 3. 参数中 extensionID/extensionData 始终为零值
+ * 4. 真正的金库配置通过 vaultFactory（工厂地址）和 vaultData（ABI 编码数据）传递
+ * 5. 每种金库类型对应一个具体的 VaultFactory 合约地址
  *
- * @see https://docs.flap.sh/flap/developers/token-launcher-developers/launch-token-through-vaultportal
+ * VaultPortal.newTaxTokenWithVault 参数结构：
+ *   - 基础参数（与 Portal.newTokenV5 相同）：name, symbol, meta, dexThresh, salt, taxRate,
+ *     migratorType, quoteToken, quoteAmt, permitData, extensionID(全零), extensionData("0x"),
+ *     dexId, lpFeeProfile, taxDuration, antiFarmerDuration, mktBps, deflationBps, dividendBps,
+ *     lpBps, minimumShareBalance
+ *   - 金库专属参数：vaultFactory(address), vaultData(bytes)
  *
  * 金库分类（来自 flap.sh 源码）：
  *   官方金库 (official)：
@@ -20,9 +28,33 @@
  * @module vault
  */
 import { Contract, AbiCoder, ZeroAddress } from 'ethers';
-import { TokenVersion } from './portal.js';
-import { getVanitySuffix } from './constants.js';
-import { normalizeTaxV2Fields, resolveDividendTokenForQuote } from './launch-v6.js';
+import { getErrorMessageFromUnknown } from '../foundation/index.js';
+function mapFieldDescriptor(f) {
+    return {
+        name: f.name,
+        fieldType: f.fieldType,
+        description: f.description,
+        decimals: Number(f.decimals),
+    };
+}
+function mapApproveAction(a) {
+    return {
+        tokenType: a.tokenType,
+        amountFieldName: a.amountFieldName,
+    };
+}
+function mapVaultMethodSchema(m) {
+    return {
+        name: m.name,
+        description: m.description,
+        inputs: m.inputs.map(mapFieldDescriptor),
+        outputs: m.outputs.map(mapFieldDescriptor),
+        approvals: m.approvals.map(mapApproveAction),
+        isInputArray: m.isInputArray,
+        isOutputArray: m.isOutputArray,
+        isWriteMethod: m.isWriteMethod,
+    };
+}
 /**
  * 金库类型显示标签
  */
@@ -100,25 +132,28 @@ export const FLAP_GUARDIAN_ADDRESSES = {
 // ============================================================================
 // ABI 定义
 // ============================================================================
-/** VaultPortal 金库发射必须使用 TOKEN_TAXED_V3（enum = 6） */
-export const TOKEN_TAXED_V3_VERSION = TokenVersion.TOKEN_TAXED_V3;
 /**
- * VaultPortal ABI — newTokenV6WithVault（当前唯一支持的金库发射入口）
+ * VaultPortal ABI — newTaxTokenWithVault
+ *
+ * ⚠️ 从 flap.sh 前端 JS 源码提取的真实 ABI
+ * 来源：flap.sh/_next/static/chunks/6288-*.js（VaultPortal 合约 ABI）
  */
 export const VAULT_PORTAL_ABI = [
     {
         type: 'function',
-        name: 'newTokenV6WithVault',
-        inputs: [{
+        name: 'newTaxTokenWithVault',
+        inputs: [
+            {
                 name: 'params',
                 type: 'tuple',
-                internalType: 'struct IVaultPortalTypes.NewTokenV6WithVaultParams',
+                internalType: 'struct IVaultPortalTypes.NewTaxTokenWithVaultParams',
                 components: [
                     { name: 'name', type: 'string', internalType: 'string' },
                     { name: 'symbol', type: 'string', internalType: 'string' },
                     { name: 'meta', type: 'string', internalType: 'string' },
-                    { name: 'dexThresh', type: 'uint8', internalType: 'enum IPortalTypes.DexThreshType' },
+                    { name: 'dexThresh', type: 'uint8', internalType: 'enum IPortalCommonTypes.DexThreshType' },
                     { name: 'salt', type: 'bytes32', internalType: 'bytes32' },
+                    { name: 'taxRate', type: 'uint16', internalType: 'uint16' },
                     { name: 'migratorType', type: 'uint8', internalType: 'enum IPortalTypes.MigratorType' },
                     { name: 'quoteToken', type: 'address', internalType: 'address' },
                     { name: 'quoteAmt', type: 'uint256', internalType: 'uint256' },
@@ -127,8 +162,6 @@ export const VAULT_PORTAL_ABI = [
                     { name: 'extensionData', type: 'bytes', internalType: 'bytes' },
                     { name: 'dexId', type: 'uint8', internalType: 'enum IPortalTypes.DEXId' },
                     { name: 'lpFeeProfile', type: 'uint8', internalType: 'enum IPortalTypes.V3LPFeeProfile' },
-                    { name: 'buyTaxRate', type: 'uint16', internalType: 'uint16' },
-                    { name: 'sellTaxRate', type: 'uint16', internalType: 'uint16' },
                     { name: 'taxDuration', type: 'uint64', internalType: 'uint64' },
                     { name: 'antiFarmerDuration', type: 'uint64', internalType: 'uint64' },
                     { name: 'mktBps', type: 'uint16', internalType: 'uint16' },
@@ -136,13 +169,11 @@ export const VAULT_PORTAL_ABI = [
                     { name: 'dividendBps', type: 'uint16', internalType: 'uint16' },
                     { name: 'lpBps', type: 'uint16', internalType: 'uint16' },
                     { name: 'minimumShareBalance', type: 'uint256', internalType: 'uint256' },
-                    { name: 'dividendToken', type: 'address', internalType: 'address' },
-                    { name: 'commissionReceiver', type: 'address', internalType: 'address' },
-                    { name: 'tokenVersion', type: 'uint8', internalType: 'enum IPortalTypes.TokenVersion' },
                     { name: 'vaultFactory', type: 'address', internalType: 'address' },
                     { name: 'vaultData', type: 'bytes', internalType: 'bytes' },
-                ]
-            }],
+                ],
+            },
+        ],
         outputs: [{ name: 'token', type: 'address', internalType: 'address' }],
         stateMutability: 'payable',
     },
@@ -150,7 +181,8 @@ export const VAULT_PORTAL_ABI = [
         type: 'function',
         name: 'getVault',
         inputs: [{ name: 'taxToken', type: 'address', internalType: 'address' }],
-        outputs: [{
+        outputs: [
+            {
                 name: 'info',
                 type: 'tuple',
                 internalType: 'struct IVaultPortalTypes.VaultInfo',
@@ -160,8 +192,9 @@ export const VAULT_PORTAL_ABI = [
                     { name: 'description', type: 'string', internalType: 'string' },
                     { name: 'isOfficial', type: 'bool', internalType: 'bool' },
                     { name: 'riskLevel', type: 'uint8', internalType: 'enum IVaultPortalTypes.RiskLevel' },
-                ]
-            }],
+                ],
+            },
+        ],
         stateMutability: 'view',
     },
     {
@@ -188,9 +221,7 @@ export const VAULT_FACTORY_V2_ABI = [
 /**
  * VaultBase ABI（V1）
  */
-export const VAULT_BASE_ABI = [
-    'function description() public view returns (string)',
-];
+export const VAULT_BASE_ABI = ['function description() public view returns (string)'];
 /**
  * VaultBaseV2 ABI
  */
@@ -239,16 +270,21 @@ function mapFieldTypeToAbiType(fieldType) {
 function processFieldValue(field, rawValue) {
     if (rawValue === undefined || rawValue === null) {
         switch (field.fieldType) {
-            case 'address': return ZeroAddress;
-            case 'bool': return false;
-            case 'string': return '';
+            case 'address':
+                return ZeroAddress;
+            case 'bool':
+                return false;
+            case 'string':
+                return '';
             case 'bytes':
-            case 'bytes32': return '0x' + '00'.repeat(32);
-            default: return 0;
+            case 'bytes32':
+                return '0x' + '00'.repeat(32);
+            default:
+                return 0;
         }
     }
     if (field.decimals > 0 && typeof rawValue === 'number') {
-        return BigInt(Math.round(rawValue * (10 ** field.decimals)));
+        return BigInt(Math.round(rawValue * 10 ** field.decimals));
     }
     if (field.fieldType === 'bool') {
         return Boolean(rawValue);
@@ -273,66 +309,7 @@ export function getVaultPortalAddress(chain) {
     return VAULT_PORTAL_ADDRESSES[chainKey] || null;
 }
 /**
- * 构建 VaultPortal.newTokenV6WithVault 参数（TOKEN_TAXED_V3）
- */
-export function buildNewTokenV6WithVaultParams(input) {
-    const tv2 = normalizeTaxV2Fields(input.taxV2);
-    const total = tv2.mktBps + tv2.deflationBps + tv2.dividendBps + tv2.lpBps;
-    if (total !== 10000) {
-        throw new Error(`Tax distribution must sum to 10000 (100%), got ${total}`);
-    }
-    if (tv2.mktBps <= 0) {
-        throw new Error('Vault launch requires mktBps > 0');
-    }
-    const buyTaxRate = (input.buyTaxRate ?? input.taxRate ?? 0) & 0xffff;
-    const sellTaxRate = (input.sellTaxRate ?? input.taxRate ?? 0) & 0xffff;
-    if (buyTaxRate <= 0 || sellTaxRate <= 0) {
-        throw new Error('Vault launch requires buyTaxRate and sellTaxRate > 0');
-    }
-    const { vaultFactory, vaultData } = buildVaultParams(tv2.vaultConfig, input.chain);
-    return {
-        name: input.tokenInfo.name,
-        symbol: input.tokenInfo.symbol,
-        meta: input.tokenInfo.meta,
-        dexThresh: (input.dexThresh ?? 1) & 0xff,
-        salt: input.salt ?? ('0x' + '00'.repeat(32)),
-        migratorType: (input.migratorType ?? 0) & 0xff,
-        quoteToken: input.quoteToken || ZeroAddress,
-        quoteAmt: input.quoteAmt ?? 0n,
-        permitData: '0x',
-        extensionID: NONE_EXTENSION_ID,
-        extensionData: '0x',
-        dexId: (input.dexId ?? 0) & 0xff,
-        lpFeeProfile: (input.lpFeeProfile ?? 0) & 0xff,
-        buyTaxRate,
-        sellTaxRate,
-        taxDuration: BigInt(tv2.taxDuration),
-        antiFarmerDuration: BigInt(tv2.antiFarmerDuration),
-        mktBps: tv2.mktBps & 0xffff,
-        deflationBps: tv2.deflationBps & 0xffff,
-        dividendBps: tv2.dividendBps & 0xffff,
-        lpBps: tv2.lpBps & 0xffff,
-        minimumShareBalance: BigInt(tv2.minimumShareBalance ?? 10000) * (10n ** 18n),
-        dividendToken: resolveDividendTokenForQuote(input.quoteToken),
-        commissionReceiver: ZeroAddress,
-        tokenVersion: TOKEN_TAXED_V3_VERSION,
-        vaultFactory,
-        vaultData,
-    };
-}
-/** 金库发射 Vanity：TOKEN_TAXED_V3 + 后缀 7777 */
-export function getVaultLaunchVanityOptions(chain) {
-    const c = chain.toUpperCase();
-    return {
-        taxed: true,
-        taxedV3: true,
-        taxedV5: false,
-        suffix: getVanitySuffix(c, true),
-        chain: c,
-    };
-}
-/**
- * 构建金库参数（用于 VaultPortal.newTokenV6WithVault）
+ * 构建金库参数（用于 VaultPortal.newTaxTokenWithVault）
  *
  * ⚠️ 重要：返回的是 vaultFactory 和 vaultData，不是 extensionID/extensionData
  * extensionID/extensionData 在金库模式下始终为零值
@@ -385,7 +362,7 @@ export function buildVaultParams(config, chain) {
  * 金库参数通过 VaultPortal 的 vaultFactory/vaultData 传递
  * 此函数仅用于向后兼容
  */
-export function buildVaultExtensionParams(config) {
+export function buildVaultExtensionParams() {
     // 金库模式下 extensionID/extensionData 始终为零值
     return {
         extensionID: NONE_EXTENSION_ID,
@@ -401,15 +378,10 @@ export function buildVaultExtensionParams(config) {
 export async function queryVaultDataSchema(provider, factoryAddress) {
     try {
         const factory = new Contract(factoryAddress, VAULT_FACTORY_V2_ABI, provider);
-        const raw = await factory.vaultDataSchema();
+        const raw = (await factory.vaultDataSchema());
         return {
             description: raw.description,
-            fields: raw.fields.map((f) => ({
-                name: f.name,
-                fieldType: f.fieldType,
-                description: f.description,
-                decimals: Number(f.decimals),
-            })),
+            fields: raw.fields.map(mapFieldDescriptor),
             isArray: raw.isArray,
         };
     }
@@ -423,33 +395,11 @@ export async function queryVaultDataSchema(provider, factoryAddress) {
 export async function queryVaultUISchema(provider, vaultAddress) {
     try {
         const vault = new Contract(vaultAddress, VAULT_BASE_V2_ABI, provider);
-        const raw = await vault.vaultUISchema();
+        const raw = (await vault.vaultUISchema());
         return {
             vaultType: raw.vaultType,
             description: raw.description,
-            methods: raw.methods.map((m) => ({
-                name: m.name,
-                description: m.description,
-                inputs: m.inputs.map((f) => ({
-                    name: f.name,
-                    fieldType: f.fieldType,
-                    description: f.description,
-                    decimals: Number(f.decimals),
-                })),
-                outputs: m.outputs.map((f) => ({
-                    name: f.name,
-                    fieldType: f.fieldType,
-                    description: f.description,
-                    decimals: Number(f.decimals),
-                })),
-                approvals: m.approvals.map((a) => ({
-                    tokenType: a.tokenType,
-                    amountFieldName: a.amountFieldName,
-                })),
-                isInputArray: m.isInputArray,
-                isOutputArray: m.isOutputArray,
-                isWriteMethod: m.isWriteMethod,
-            })),
+            methods: raw.methods.map(mapVaultMethodSchema),
         };
     }
     catch {
@@ -485,7 +435,7 @@ export async function validateVaultFactory(provider, factoryAddress) {
         };
     }
     catch (e) {
-        return { isValid: false, isV2: false, schema: null, error: String(e) };
+        return { isValid: false, isV2: false, schema: null, error: getErrorMessageFromUnknown(e) };
     }
 }
 /**
@@ -494,7 +444,7 @@ export async function validateVaultFactory(provider, factoryAddress) {
 export async function getVaultInfo(provider, vaultPortalAddress, taxTokenAddress) {
     try {
         const portal = new Contract(vaultPortalAddress, VAULT_PORTAL_ABI, provider);
-        const info = await portal.getVault(taxTokenAddress);
+        const info = (await portal.getVault(taxTokenAddress));
         return {
             vault: info.vault,
             vaultFactory: info.vaultFactory,

package/dist/shared/foundation/amount/split-by-weight.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 将 bigint 金额按随机权重拆分为多份，末份取 remainder，保证总和精确。
+ * 权重范围 500_000–1_500_000（与 dex-helpers 一致），全程 bigint 运算。
+ */
+export declare function splitAmountByWeight(totalAmount: bigint, count: number): bigint[];

package/dist/shared/foundation/amount/split-by-weight.js

@@ -0,0 +1,35 @@
+function shuffle(arr) {
+    const a = arr.slice();
+    for (let i = a.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [a[i], a[j]] = [a[j], a[i]];
+    }
+    return a;
+}
+/**
+ * 将 bigint 金额按随机权重拆分为多份，末份取 remainder，保证总和精确。
+ * 权重范围 500_000–1_500_000（与 dex-helpers 一致），全程 bigint 运算。
+ */
+export function splitAmountByWeight(totalAmount, count) {
+    if (count <= 0)
+        throw new Error('拆分份数必须大于 0');
+    if (count === 1)
+        return [totalAmount];
+    if (totalAmount <= 0n)
+        return new Array(count).fill(0n);
+    const weights = [];
+    for (let i = 0; i < count; i++) {
+        const w = BigInt(500_000 + Math.floor(Math.random() * 1_000_000));
+        weights.push(w);
+    }
+    const totalWeight = weights.reduce((a, b) => a + b, 0n);
+    const amounts = [];
+    let allocated = 0n;
+    for (let i = 0; i < count - 1; i++) {
+        const amt = (totalAmount * weights[i]) / totalWeight;
+        amounts.push(amt);
+        allocated += amt;
+    }
+    amounts.push(totalAmount - allocated);
+    return shuffle(amounts);
+}

package/dist/shared/foundation/dex/v3-path.d.ts

@@ -0,0 +1,6 @@
+export declare function getDeadline(minutes?: number): number;
+export declare function encodeV3Path(tokens: string[], fees: number[]): string;
+export declare function decodeV3Path(path: string): {
+    tokens: string[];
+    fees: number[];
+};

package/dist/shared/foundation/dex/v3-path.js

@@ -0,0 +1,35 @@
+import { GAS_CONFIG } from '../../constants/gas.js';
+export function getDeadline(minutes = GAS_CONFIG.DEFAULT_DEADLINE_MINUTES) {
+    return Math.floor(Date.now() / 1000) + 60 * minutes;
+}
+export function encodeV3Path(tokens, fees) {
+    if (tokens.length < 2) {
+        throw new Error('V3 path 需要至少 2 个代币');
+    }
+    if (fees.length !== tokens.length - 1) {
+        throw new Error(`费率数量 (${fees.length}) 必须等于代币数量 - 1 (${tokens.length - 1})`);
+    }
+    let path = '0x';
+    for (let i = 0; i < tokens.length; i++) {
+        path += tokens[i].slice(2).toLowerCase().padStart(40, '0');
+        if (i < fees.length) {
+            path += fees[i].toString(16).padStart(6, '0');
+        }
+    }
+    return path;
+}
+export function decodeV3Path(path) {
+    const cleanPath = path.startsWith('0x') ? path.slice(2) : path;
+    const tokens = [];
+    const fees = [];
+    let offset = 0;
+    while (offset < cleanPath.length) {
+        tokens.push('0x' + cleanPath.slice(offset, offset + 40));
+        offset += 40;
+        if (offset < cleanPath.length) {
+            fees.push(parseInt(cleanPath.slice(offset, offset + 6), 16));
+            offset += 6;
+        }
+    }
+    return { tokens, fees };
+}

package/dist/shared/foundation/erc20/decimals.d.ts

@@ -0,0 +1,7 @@
+import { JsonRpcProvider } from 'ethers';
+/**
+ * 获取 ERC20 代币精度（带缓存）
+ */
+export declare function getErc20Decimals(provider: JsonRpcProvider, token: string, chainId?: number): Promise<number>;
+/** @deprecated 使用 getErc20Decimals */
+export declare const getErc20DecimalsMerkle: typeof getErc20Decimals;

package/dist/shared/foundation/erc20/decimals.js

@@ -0,0 +1,24 @@
+import { ethers } from 'ethers';
+const decimalsCache = new Map();
+/**
+ * 获取 ERC20 代币精度（带缓存）
+ */
+export async function getErc20Decimals(provider, token, chainId) {
+    const resolvedChainId = chainId ?? Number((await provider.getNetwork()).chainId);
+    const key = `${resolvedChainId}_${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;
+    }
+}
+/** @deprecated 使用 getErc20Decimals */
+export const getErc20DecimalsMerkle = getErc20Decimals;