four-flap-meme-sdk/README.md

SDK for Flap bonding curve and four.meme TokenManager

# four-flap-meme-sdk

**four.meme 和 Flap Protocol 统一 SDK - 生产环境 MEV 保护方案**

提供完整的代币发行和交易功能，所有操作均通过 **Merkle.io Bundle** 执行，确保 MEV 保护、原子性和私有性。

## 核心优势

🔐 **MEV 保护** - 防止抢跑、三明治攻击和价格操纵  
⚛️ **原子性** - 批量交易全成功或全失败  
🔒 **私有 Mempool** - 交易不在公开池暴露  
📦 **顺序保证** - 多笔交易按指定顺序执行  
🚀 **生产就绪** - 经过实战验证的 MEV 保护方案

## 安装

```bash
npm i four-flap-meme-sdk ethers
```

**要求**：Node.js >= 18, ESM, ethers v6

## 获取 Merkle API Key

从 [Merkle.io](https://merkle.io) 获取免费 API Key，用于 Bundle 服务。

## 浏览器环境 CORS 支持

SDK 已内置 Cloudflare Workers 代理，**浏览器环境可直接使用，无需额外配置**：

```typescript
import { FourClient } from 'four-flap-meme-sdk';

// 直接创建，默认使用已配置好的 CORS 代理
const fourClient = new FourClient();

// 或自定义代理地址（可选）
const fourClient = new FourClient({
  baseUrl: 'https://your-worker.workers.dev'
});
```

详见：[CLOUDFLARE_WORKER_GUIDE.md](./CLOUDFLARE_WORKER_GUIDE.md)

---

## Four.meme Bundle 方法

### 1. 创建代币 + 原子化批量买入

```typescript
import { createTokenWithBundleBuyMerkle } from 'four-flap-meme-sdk';

const result = await createTokenWithBundleBuyMerkle({
  // privateKeys[0] 是创建者/付费者，其余是买家
  privateKeys: [
    '0x...创建者私钥',
    '0x...买家1',
    '0x...买家2'
  ],
  buyAmounts: ['0.5', '1.0'],  // 对应买家1和买家2
  tokenInfo: {
    name: 'My Token',
    symbol: 'MTK',
    description: '革命性代币',
    label: 'Meme'
  },
  config: {
    apiKey: 'YOUR_MERKLE_API_KEY',
    rpcUrl: 'https://bsc-dataseed.binance.org'
  }
});

console.log('Bundle Hash:', result.bundleHash);
console.log('代币地址:', result.tokenAddress);
```

### 2. 批量买入（内盘）

```typescript
import { batchBuyWithBundleMerkle } from 'four-flap-meme-sdk';

await batchBuyWithBundleMerkle({
  privateKeys: ['0x...买家1', '0x...买家2', '0x...买家3'],
  buyAmounts: ['0.3', '0.5', '0.2'],
  tokenAddress: '0x...代币地址',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});
```

### 3. 批量卖出（内盘）

```typescript
import { batchSellWithBundleMerkle } from 'four-flap-meme-sdk';

// 需先授权
await batchSellWithBundleMerkle({
  privateKeys: ['0x...卖家1', '0x...卖家2'],
  sellAmounts: ['1000', '2000'],
  tokenAddress: '0x...代币地址',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});
```

### 4. 批量授权

```typescript
import { approveFourBatchMerkle } from 'four-flap-meme-sdk';

await approveFourBatchMerkle({
  privateKeys: ['0x...地址1', '0x...地址2'],
  tokenAddress: '0x...代币地址',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});
```

### 5. PancakeSwap V2 批量交易（外盘）

```typescript
import {
  fourPancakeProxyBatchBuyMerkle,
  fourPancakeProxyBatchSellMerkle
} from 'four-flap-meme-sdk';

// V2 批量买入
await fourPancakeProxyBatchBuyMerkle({
  privateKeys: ['0x...买家1', '0x...买家2'],
  buyAmounts: ['0.5', '1.0'],
  paths: [
    ['0x...WBNB', '0x...TOKEN'],
    ['0x...WBNB', '0x...TOKEN']
  ],
  routeType: 'v2',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});

// V2 批量卖出
await fourPancakeProxyBatchSellMerkle({
  privateKeys: ['0x...卖家1', '0x...卖家2'],
  sellAmounts: ['1000', '2000'],
  paths: [
    ['0x...TOKEN', '0x...WBNB'],
    ['0x...TOKEN', '0x...WBNB']
  ],
  routeType: 'v2',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});
```

### 6. PancakeSwap V3 批量交易（外盘）

```typescript
// V3 单跳买入
await fourPancakeProxyBatchBuyMerkle({
  privateKeys: ['0x...买家1', '0x...买家2'],
  buyAmounts: ['0.5', '1.0'],
  tokenIn: '0x...WBNB',
  tokenOut: '0x...TOKEN',
  fee: 2500,  // 0.25%
  routeType: 'v3-single',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});

// V3 多跳买入
await fourPancakeProxyBatchBuyMerkle({
  privateKeys: ['0x...买家1'],
  buyAmounts: ['0.5'],
  lpAddresses: ['0x...WBNB_USDT_LP', '0x...USDT_TOKEN_LP'],
  exactTokenIn: '0x...WBNB',
  routeType: 'v3-multi',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});
```

---

## Flap Protocol Bundle 方法

### 1. 创建代币 + 原子化批量买入

```typescript
import { flapCreateTokenWithBundleBuyMerkle } from 'four-flap-meme-sdk';

const result = await flapCreateTokenWithBundleBuyMerkle({
  chain: 'BSC',
  // privateKeys[0] 是创建者/付费者，其余是买家
  privateKeys: [
    '0x...创建者私钥',
    '0x...买家1',
    '0x...买家2'
  ],
  buyAmounts: ['0.5', '1.0'],  // 对应买家1和买家2
  tokenInfo: {
    name: 'My Flap Token',
    symbol: 'MFT',
    meta: 'QmXxx...'  // IPFS CID
  },
  config: {
    apiKey: 'YOUR_MERKLE_API_KEY',
    rpcUrl: 'https://bsc-dataseed.binance.org'
  },
  dexThresh: 1,
  migratorType: 0,
  taxRate: 0,
  salt: '0x' + '00'.repeat(32)
});

console.log('Bundle Hash:', result.bundleHash);
```

### 2. 批量买入/卖出（内盘）

```typescript
import {
  flapBatchBuyWithBundleMerkle,
  flapBatchSellWithBundleMerkle
} from 'four-flap-meme-sdk';

// 批量买入
await flapBatchBuyWithBundleMerkle({
  chain: 'BSC',
  privateKeys: ['0x...买家1', '0x...买家2'],
  buyAmounts: ['0.5', '1.0'],
  tokenAddress: '0x...代币地址',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});

// 批量卖出
await flapBatchSellWithBundleMerkle({
  chain: 'BSC',
  privateKeys: ['0x...卖家1', '0x...卖家2'],
  sellAmounts: ['1000', '2000'],
  tokenAddress: '0x...代币地址',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});
```

### 3. PancakeSwap V2/V3 批量交易（外盘）

```typescript
import {
  flapPancakeProxyBatchBuyMerkle,
  flapPancakeProxyBatchSellMerkle
} from 'four-flap-meme-sdk';

// V2 批量买入
await flapPancakeProxyBatchBuyMerkle({
  chain: 'BSC',
  privateKeys: ['0x...买家1', '0x...买家2'],
  buyAmounts: ['0.5', '1.0'],
  paths: [
    ['0x...WBNB', '0x...TOKEN'],
    ['0x...WBNB', '0x...TOKEN']
  ],
  routeType: 'v2',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});

// V3 单跳卖出
await flapPancakeProxyBatchSellMerkle({
  chain: 'BSC',
  privateKeys: ['0x...卖家1', '0x...卖家2'],
  sellAmounts: ['1000', '2000'],
  tokenIn: '0x...TOKEN',
  tokenOut: '0x...WBNB',
  fee: 2500,
  routeType: 'v3-single',
  config: { apiKey: 'YOUR_MERKLE_API_KEY' }
});
```

---

## 配置选项

```typescript
type BundleMerkleConfig = {
  apiKey: string;                    // Merkle API Key（必填）
  rpcUrl?: string;                   // RPC 节点（可选）
  bundleBlockOffset?: number;        // Bundle 有效期，默认 200 区块
  gasLimitMultiplier?: number;       // Gas limit 倍数，默认 1.2
  waitTimeoutMs?: number;            // 等待超时，默认 120000ms
  slippageBps?: number;              // 滑点基点，默认 100 (1%)
  txType?: 0 | 2;                    // 交易类型，0=Legacy, 2=EIP-1559
};
```

---

## 支持的链

- **BSC**（币安智能链）- Four.meme & Flap Protocol
- **Base** - Flap Protocol
- **X Layer** - Flap Protocol
- **Morph** - Flap Protocol
- **Arbitrum One** - Four.meme

---

## 文档

📚 **完整指南**：
- [MERKLE_BUNDLE_COMPLETE_GUIDE.md](./MERKLE_BUNDLE_COMPLETE_GUIDE.md) - 详细的 Merkle Bundle 使用指南
- [README.zh-CN.md](./README.zh-CN.md) - 完整 API 参考（包含所有方法）

📖 **示例代码**：
- [examples/](./examples/) - 完整示例代码

---

## 关键概念

### 内盘 vs 外盘

- **内盘**：代币在联合曲线上交易，价格由数学公式决定
- **外盘**：代币已迁移到 DEX（PancakeSwap），价格由市场决定

### MEV 保护

- **抢跑保护**：交易不在公开 mempool 暴露
- **三明治攻击保护**：Bundle 原子化执行
- **顺序保证**：多笔交易按指定顺序执行

### 原子性

- 批量交易全成功或全失败
- 创建 + 购买在同一 Bundle 中
- 防止部分执行导致的资金损失

---

## 常见问题

**Q: 为什么只推荐 Merkle Bundle 方法？**  
A: 生产环境必须使用 MEV 保护，防止抢跑和三明治攻击。Merkle Bundle 是目前最可靠的 MEV 保护方案。

**Q: Merkle API Key 如何获取？**  
A: 访问 [Merkle.io](https://merkle.io) 注册并获取免费 API Key。

**Q: Bundle 交易失败怎么办？**  
A: 检查配置参数（gasLimit、blockOffset、slippage），确保所有地址有足够余额，适当增大超时时间。

**Q: 支持哪些 DEX？**  
A: 目前支持 PancakeSwap V2/V3（通过自定义代理合约）。

**Q: 如何处理 nonce 冲突？**  
A: SDK 内置 NonceManager，自动管理所有地址的 nonce，避免冲突。

---

## 许可

MIT

---

**🚀 开始使用 Merkle Bundle 保护你的交易！**