four-flap-meme-sdk 1.9.48 → 2.0.0

package/README.en.md

@@ -29,6 +29,41 @@ Optional (use Pinata for IPFS uploads)
 npm i pinata
 ```
 
+## Package entry points (subpath imports)
+
+The library is published as **ESM** (`dist` is produced by `npm run build`). The root import remains the default for full API access. For smaller dependency graphs, Node and bundlers that honor `package.json` **`exports`** may import:
+
+**When to use which**
+
+- **Root**: default for apps and examples that touch more than one SDK area.
+- **Subpaths**: for scripts or libraries that intentionally depend on only one slice (constants, ABIs, error utilities, Merkle clients, etc.).
+
+| Subpath | Purpose |
+|---------|---------|
+| `four-flap-meme-sdk` | Main entry — full surface |
+| `four-flap-meme-sdk/chains` | Chain namespaces and helpers |
+| `four-flap-meme-sdk/shared` | Cross-cutting modules: constants, `foundation`, `clients`, `FourUtils` |
+| `four-flap-meme-sdk/clients` | HTTP / Merkle-related clients |
+| `four-flap-meme-sdk/dex` | DEX helpers |
+| `four-flap-meme-sdk/constants` | Chain config, gas, addresses, profit settings |
+| `four-flap-meme-sdk/abis` | TokenManager JSON ABIs, common fragments, Flap ABIs (same as `src/abis` barrel) |
+| `four-flap-meme-sdk/foundation` | Unknown-error normalization and optional loggers |
+| `four-flap-meme-sdk/bundle-core` | Shared bundle core: `internal`, `submit`, `config-helpers` |
+| `four-flap-meme-sdk/flows` | High-level flows (e.g. `createTokenFlow`) |
+
+> **v2.0.0**: ambiguous root exports removed — see [docs/MIGRATION_EXPORTS.zh-CN.md](./docs/MIGRATION_EXPORTS.zh-CN.md).
+
+```typescript
+import { CHAINS, GAS_LIMITS } from 'four-flap-meme-sdk/constants';
+import { TokenManager } from 'four-flap-meme-sdk/abis';
+import { normalizeUnknownError } from 'four-flap-meme-sdk/foundation';
+```
+
+### Documentation: alignment & backends
+
+- **[docs/ALIGNMENT_STATUS.zh-CN.md](./docs/ALIGNMENT_STATUS.zh-CN.md)** — audit-style checklist (language: Chinese).
+- **[docs/SUBMIT_BACKENDS.zh-CN.md](./docs/SUBMIT_BACKENDS.zh-CN.md)** — choosing Merkle, BlockRazor, direct RPC, ENI, 48.club, etc.
+
 ---
 
 ## Table of Contents
@@ -3503,7 +3538,7 @@ const permitData = await buildPermitPiggybackAuto(
 The SDK provides pre-configured addresses for all supported networks:
 
 ```typescript
-import { CHAIN } from 'four-flap-meme-sdk';
+import { CHAINS } from 'four-flap-meme-sdk';
 
 // Use chain enum when calling SDK methods (addresses are handled internally)
 // Example:
@@ -3512,11 +3547,11 @@ import { CHAIN } from 'four-flap-meme-sdk';
 // await tryBuy('BSC', rpcUrl, token, amount, funds);
 
 // Chain information
-console.log(CHAIN.BSC.chainId);         // 56
-console.log(CHAIN.BASE.chainId);        // 8453
-console.log(CHAIN.XLAYER.chainId);      // 196
-console.log(CHAIN.MORPH.chainId);       // 2818
-console.log(CHAIN.ARBITRUM_ONE.chainId); // 42161
+console.log(CHAINS.BSC.chainId);         // 56
+console.log(CHAINS.BASE.chainId);        // 8453
+console.log(CHAINS.XLAYER.chainId);      // 196
+console.log(CHAINS.MORPH.chainId);       // 2818
+console.log(CHAINS.ARBITRUM_ONE.chainId); // 42161
 ```
 
 ---

package/README.md

@@ -20,6 +20,37 @@ npm i four-flap-meme-sdk ethers
 
 **要求**：Node.js >= 18, ESM, ethers v6
 
+### Package entry points (subpath imports)
+
+The package ships **ESM** with `exports` in `package.json`. Use the default root import for full API coverage; use subpaths to narrow what your resolver loads (requires tooling that respects `exports`).
+
+**When to use which**
+
+- **Root import**: matches the docs; use when you need multiple surfaces (four.meme, Flap, bundles, several chains).
+- **Subpaths**: use in scripts, internal packages, or constrained runtimes when you only need one vertical slice (constants, ABIs, error helpers, HTTP clients, etc.).
+
+| Subpath | Purpose |
+|---------|---------|
+| `four-flap-meme-sdk` | Main entry — full surface (recommended default) |
+| `four-flap-meme-sdk/chains` | Per-chain namespaces and chain helpers |
+| `four-flap-meme-sdk/shared` | Shared layer: constants, `foundation`, `clients`, `FourUtils`, etc. |
+| `four-flap-meme-sdk/clients` | HTTP / bundle / infra clients |
+| `four-flap-meme-sdk/dex` | DEX helpers and types |
+| `four-flap-meme-sdk/constants` | Chain IDs, gas limits, addresses, profit helpers — smallest config-only slice |
+| `four-flap-meme-sdk/abis` | Compiled contract JSON ABIs, shared fragment ABIs, Flap-specific ABIs (`src/abis` entry) |
+| `four-flap-meme-sdk/foundation` | `normalizeUnknownError`, `getErrorMessageFromUnknown`, injectable `SdkLogger` — no domain logic |
+
+```typescript
+import { CHAINS, ADDRESSES } from 'four-flap-meme-sdk/constants';
+import { TokenManager } from 'four-flap-meme-sdk/abis';
+import { normalizeUnknownError } from 'four-flap-meme-sdk/foundation';
+```
+
+### Docs: architecture & submission paths
+
+- **[docs/ALIGNMENT_STATUS.zh-CN.md](./docs/ALIGNMENT_STATUS.zh-CN.md)** — audit-style checklist (what is done vs backlog).
+- **[docs/SUBMIT_BACKENDS.zh-CN.md](./docs/SUBMIT_BACKENDS.zh-CN.md)** — when to use Merkle vs BlockRazor vs direct RPC vs ENI / 48.club, etc.
+
 ## 获取 Merkle API Key
 
 从 [Merkle.io](https://merkle.io) 获取免费 API Key，用于 Bundle 服务。

package/README.zh-CN.md

@@ -29,6 +29,41 @@ npm i four-flap-meme-sdk ethers
 npm i pinata
 ```
 
+## 包入口与子路径（按需引用）
+
+发布后包内为 **ESM**，`dist` 由 `npm run build` 生成。多数场景继续使用主入口即可；若希望缩小解析范围或只做配置层依赖，可选用 `package.json` 的 **`exports`** 子路径（需 Node／打包工具识别 `exports`）。
+
+**如何选择**
+
+- **主入口**：与文档示例一致；需要 four / Flap、Bundle、多链等组合能力时优先用它。
+- **子路径**：在脚本、内部库或边缘运行时**只要某一竖切**（仅常量、仅 ABI、仅错误与日志、仅 HTTP 客户端等）时使用，以收敛依赖与解析面。
+
+| 子路径 | 说明 |
+|--------|------|
+| `four-flap-meme-sdk` | 主入口，全量导出（默认推荐） |
+| `four-flap-meme-sdk/chains` | 各链命名空间与链相关工具 |
+| `four-flap-meme-sdk/shared` | 横向能力：常量、`foundation`、`clients`、`FourUtils` 等 |
+| `four-flap-meme-sdk/clients` | Merkle / HTTP 等与 I/O 相关的客户端封装 |
+| `four-flap-meme-sdk/dex` | DEX 路由与相关类型／辅助函数 |
+| `four-flap-meme-sdk/constants` | 链 ID、Gas、常用地址、利润配置等常量（等价于深入 `shared` 中的常量模块，但更轻依赖面） |
+| `four-flap-meme-sdk/abis` | 合约 JSON ABI（TokenManager 等）、公共片段 ABI、Flap 相关 ABI（与 `src/abis` 入口一致） |
+| `four-flap-meme-sdk/foundation` | 错误规范化（`normalizeUnknownError` 等）与可选 `SdkLogger`，无业务逻辑 |
+| `four-flap-meme-sdk/bundle-core` | Bundle 共享核心：`internal`、`submit`、`config-helpers` |
+| `four-flap-meme-sdk/flows` | 高层流程（如 `createTokenFlow`） |
+
+> **v2.0.0**：包根已移除 `TradeType` / `PROFIT_CONFIG` / `CHAIN` 等歧义导出，见 [docs/MIGRATION_EXPORTS.zh-CN.md](./docs/MIGRATION_EXPORTS.zh-CN.md)。
+
+```typescript
+import { CHAINS, GAS_LIMITS } from 'four-flap-meme-sdk/constants';
+import { TokenManager } from 'four-flap-meme-sdk/abis';
+import { normalizeUnknownError } from 'four-flap-meme-sdk/foundation';
+```
+
+### 文档：架构对齐与提交路径
+
+- **[docs/ALIGNMENT_STATUS.zh-CN.md](./docs/ALIGNMENT_STATUS.zh-CN.md)** — 与审计文档对照的总表（已完成 / 待办）。
+- **[docs/SUBMIT_BACKENDS.zh-CN.md](./docs/SUBMIT_BACKENDS.zh-CN.md)** — 何时用 Merkle / BlockRazor / 直连 RPC / ENI / 48.club 等。
+
 ## 浏览器环境支持
 
 SDK 已内置 Cloudflare Workers 代理，**浏览器环境可直接使用，无需额外配置 CORS**：
@@ -4587,7 +4622,7 @@ const permitData = await buildPermitPiggybackAuto(
 SDK 提供所有支持网络的预配置地址：
 
 ```typescript
-import { CHAIN } from 'four-flap-meme-sdk';
+import { CHAINS } from 'four-flap-meme-sdk';
 
 // 使用链枚举调用 SDK 方法（地址由 SDK 内部处理）
 // 示例：
@@ -4596,11 +4631,11 @@ import { CHAIN } from 'four-flap-meme-sdk';
 // await tryBuy('BSC', rpcUrl, token, amount, funds);
 
 // 链信息
-console.log(CHAIN.BSC.chainId);         // 56
-console.log(CHAIN.BASE.chainId);        // 8453
-console.log(CHAIN.XLAYER.chainId);      // 196
-console.log(CHAIN.MORPH.chainId);       // 2818
-console.log(CHAIN.ARBITRUM_ONE.chainId); // 42161
+console.log(CHAINS.BSC.chainId);         // 56
+console.log(CHAINS.BASE.chainId);        // 8453
+console.log(CHAINS.XLAYER.chainId);      // 196
+console.log(CHAINS.MORPH.chainId);       // 2818
+console.log(CHAINS.ARBITRUM_ONE.chainId); // 42161
 ```
 
 ---

package/dist/abis/common.js

@@ -69,40 +69,44 @@ export const V2_ROUTER_QUOTE_ABI = [
 export const V3_ROUTER02_ABI = [
     // exactInputSingle - 单跳，不含 deadline
     {
-        "inputs": [{
-                "components": [
-                    { "name": "tokenIn", "type": "address" },
-                    { "name": "tokenOut", "type": "address" },
-                    { "name": "fee", "type": "uint24" },
-                    { "name": "recipient", "type": "address" },
-                    { "name": "amountIn", "type": "uint256" },
-                    { "name": "amountOutMinimum", "type": "uint256" },
-                    { "name": "sqrtPriceLimitX96", "type": "uint160" }
+        inputs: [
+            {
+                components: [
+                    { name: 'tokenIn', type: 'address' },
+                    { name: 'tokenOut', type: 'address' },
+                    { name: 'fee', type: 'uint24' },
+                    { name: 'recipient', type: 'address' },
+                    { name: 'amountIn', type: 'uint256' },
+                    { name: 'amountOutMinimum', type: 'uint256' },
+                    { name: 'sqrtPriceLimitX96', type: 'uint160' },
                 ],
-                "name": "params",
-                "type": "tuple"
-            }],
-        "name": "exactInputSingle",
-        "outputs": [{ "name": "amountOut", "type": "uint256" }],
-        "stateMutability": "payable",
-        "type": "function"
+                name: 'params',
+                type: 'tuple',
+            },
+        ],
+        name: 'exactInputSingle',
+        outputs: [{ name: 'amountOut', type: 'uint256' }],
+        stateMutability: 'payable',
+        type: 'function',
     },
     // exactInput - 多跳，不含 deadline
     {
-        "inputs": [{
-                "components": [
-                    { "name": "path", "type": "bytes" },
-                    { "name": "recipient", "type": "address" },
-                    { "name": "amountIn", "type": "uint256" },
-                    { "name": "amountOutMinimum", "type": "uint256" }
+        inputs: [
+            {
+                components: [
+                    { name: 'path', type: 'bytes' },
+                    { name: 'recipient', type: 'address' },
+                    { name: 'amountIn', type: 'uint256' },
+                    { name: 'amountOutMinimum', type: 'uint256' },
                 ],
-                "name": "params",
-                "type": "tuple"
-            }],
-        "name": "exactInput",
-        "outputs": [{ "name": "amountOut", "type": "uint256" }],
-        "stateMutability": "payable",
-        "type": "function"
+                name: 'params',
+                type: 'tuple',
+            },
+        ],
+        name: 'exactInput',
+        outputs: [{ name: 'amountOut', type: 'uint256' }],
+        stateMutability: 'payable',
+        type: 'function',
     },
     // multicall - 带 deadline 版本
     'function multicall(uint256 deadline, bytes[] calldata data) external payable returns (bytes[] memory results)',
@@ -113,24 +117,26 @@ export const V3_ROUTER02_ABI = [
 export const V3_ROUTER_LEGACY_ABI = [
     // exactInputSingle - 包含 deadline
     {
-        "inputs": [{
-                "components": [
-                    { "name": "tokenIn", "type": "address" },
-                    { "name": "tokenOut", "type": "address" },
-                    { "name": "fee", "type": "uint24" },
-                    { "name": "recipient", "type": "address" },
-                    { "name": "deadline", "type": "uint256" },
-                    { "name": "amountIn", "type": "uint256" },
-                    { "name": "amountOutMinimum", "type": "uint256" },
-                    { "name": "sqrtPriceLimitX96", "type": "uint160" }
+        inputs: [
+            {
+                components: [
+                    { name: 'tokenIn', type: 'address' },
+                    { name: 'tokenOut', type: 'address' },
+                    { name: 'fee', type: 'uint24' },
+                    { name: 'recipient', type: 'address' },
+                    { name: 'deadline', type: 'uint256' },
+                    { name: 'amountIn', type: 'uint256' },
+                    { name: 'amountOutMinimum', type: 'uint256' },
+                    { name: 'sqrtPriceLimitX96', type: 'uint160' },
                 ],
-                "name": "params",
-                "type": "tuple"
-            }],
-        "name": "exactInputSingle",
-        "outputs": [{ "name": "amountOut", "type": "uint256" }],
-        "stateMutability": "payable",
-        "type": "function"
+                name: 'params',
+                type: 'tuple',
+            },
+        ],
+        name: 'exactInputSingle',
+        outputs: [{ name: 'amountOut', type: 'uint256' }],
+        stateMutability: 'payable',
+        type: 'function',
     },
     // multicall - 不带 deadline 版本
     'function multicall(bytes[] calldata data) external payable returns (bytes[] memory results)',
@@ -171,34 +177,34 @@ export const SWAP_ROUTER02_V2_ABI = [
 /** V3 QuoterV2 ABI */
 export const V3_QUOTER_ABI = [
     {
-        "inputs": [{
-                "components": [
-                    { "name": "tokenIn", "type": "address" },
-                    { "name": "tokenOut", "type": "address" },
-                    { "name": "amountIn", "type": "uint256" },
-                    { "name": "fee", "type": "uint24" },
-                    { "name": "sqrtPriceLimitX96", "type": "uint160" }
+        inputs: [
+            {
+                components: [
+                    { name: 'tokenIn', type: 'address' },
+                    { name: 'tokenOut', type: 'address' },
+                    { name: 'amountIn', type: 'uint256' },
+                    { name: 'fee', type: 'uint24' },
+                    { name: 'sqrtPriceLimitX96', type: 'uint160' },
                 ],
-                "name": "params",
-                "type": "tuple"
-            }],
-        "name": "quoteExactInputSingle",
-        "outputs": [
-            { "name": "amountOut", "type": "uint256" },
-            { "name": "sqrtPriceX96After", "type": "uint160" },
-            { "name": "initializedTicksCrossed", "type": "uint32" },
-            { "name": "gasEstimate", "type": "uint256" }
+                name: 'params',
+                type: 'tuple',
+            },
         ],
-        "stateMutability": "nonpayable",
-        "type": "function"
-    }
+        name: 'quoteExactInputSingle',
+        outputs: [
+            { name: 'amountOut', type: 'uint256' },
+            { name: 'sqrtPriceX96After', type: 'uint160' },
+            { name: 'initializedTicksCrossed', type: 'uint32' },
+            { name: 'gasEstimate', type: 'uint256' },
+        ],
+        stateMutability: 'nonpayable',
+        type: 'function',
+    },
 ];
 // ============================================================================
 // Uniswap V2 Factory & Pair ABI
 // ============================================================================
-export const V2_FACTORY_ABI = [
-    'function getPair(address tokenA, address tokenB) external view returns (address pair)',
-];
+export const V2_FACTORY_ABI = ['function getPair(address tokenA, address tokenB) external view returns (address pair)'];
 export const V2_PAIR_ABI = [
     'function token0() external view returns (address)',
     'function token1() external view returns (address)',
@@ -226,6 +232,8 @@ export const FLAP_PORTAL_ABI = [
     'function newTokenV3((string name,string symbol,string meta,uint8 dexThresh,bytes32 salt,uint16 taxRate,uint8 migratorType,address quoteToken,uint256 quoteAmt,address beneficiary,bytes permitData,bytes32 extensionID,bytes extensionData)) external payable returns (address)',
     // ✅ V4：支持 dexId / lpFeeProfile（与 portal-bundle-merkle/core.ts 的 newTokenV4.populateTransaction 对齐）
     'function newTokenV4((string name,string symbol,string meta,uint8 dexThresh,bytes32 salt,uint16 taxRate,uint8 migratorType,address quoteToken,uint256 quoteAmt,address beneficiary,bytes permitData,bytes32 extensionID,bytes extensionData,uint8 dexId,uint8 lpFeeProfile)) external payable returns (address)',
+    // ✅ V5：Tax Token V2 高级税收分配
+    'function newTokenV5((string name,string symbol,string meta,uint8 dexThresh,bytes32 salt,uint16 taxRate,uint8 migratorType,address quoteToken,uint256 quoteAmt,address beneficiary,bytes permitData,bytes32 extensionID,bytes extensionData,uint8 dexId,uint8 lpFeeProfile,uint64 taxDuration,uint64 antiFarmerDuration,uint16 mktBps,uint16 deflationBps,uint16 dividendBps,uint16 lpBps,uint256 minimumShareBalance)) external payable returns (address)',
     // 交易
     'function swapExactInput((address inputToken,address outputToken,uint256 inputAmount,uint256 minOutputAmount,bytes permitData)) external payable returns (uint256)',
     // ✅ V3：支持 extensionData（注意：这里的 V3 指“扩展交易接口版本”，不是“外盘 V3 池子”）