anchor-sdk 0.1.36

package/README.md

@@ -0,0 +1,735 @@
+# Anchor SDK
+
+[![npm version](https://badge.fury.io/js/%40keccak256-evg%2Fanchor-sdk.svg)](https://badge.fury.io/js/%40keccak256-evg%2Fanchor-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+
+Anchor SDK 是一个用于与 Anchor 生态系统交互的 TypeScript 开发工具包，支持徽章铸造、支付处理和 ERC1155 代币管理。
+
+## ✨ 特性
+
+- 🌐 **多网络支持** - 支持以太坊主网、Saigon、Ronin、Base Sepolia、Bera 等多个网络
+- 🔐 **双模式支持** - 同时支持账户抽象（AA）和外部拥有账户（EOA）模式
+- 🎯 **简单易用** - 提供直观的 API 接口进行徽章铸造和查询
+- 💰 **多种支付方式** - 支持使用 ETH 或 ERC20 代币购买徽章
+- ✍️ **自定义签名** - 支持使用自定义签名购买徽章
+- 🆓 **免费铸造** - 支持铸造免费徽章
+- 📝 **完全类型化** - 提供完整的 TypeScript 类型支持，确保良好的开发体验
+- ⚡ **批量操作** - 支持批量铸造和 multicall 操作
+- 🔄 **React 支持** - 提供 React Hook 和组件
+
+## 📦 安装
+
+### 使用 npm
+
+```bash
+npm install anchor-sdk
+```
+
+### 使用 yarn
+
+```bash
+yarn add anchor-sdk
+```
+
+### 使用 pnpm
+
+```bash
+pnpm add anchor-sdk
+```
+
+## 📋 依赖要求
+
+Anchor SDK 需要以下依赖：
+
+- **Node.js**: >= 16.0.0
+- **TypeScript**: >= 4.5.0 (如果使用 TypeScript)
+- **viem**: ^2.23.9
+- **ethers**: ^6.15.0
+
+### 可选依赖
+
+- **React**: ^19.0.0 (如果使用 React 组件)
+- **@types/react**: ^19.0.10 (如果使用 TypeScript 和 React)
+
+## 🚀 快速开始
+
+### 1. 初始化 SDK
+
+```typescript
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { mainnet } from "viem/chains";
+import { AnchorSDK, NETWORKS, Environment } from "anchor-sdk";
+
+// 创建客户端
+const rpcUrl = "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY";
+const privateKey = "0xYOUR_PRIVATE_KEY";
+
+const publicClient = createPublicClient({
+  chain: mainnet,
+  transport: http(rpcUrl),
+});
+
+const account = privateKeyToAccount(
+  `0x${
+    privateKey.startsWith("0x") ? privateKey.slice(2) : privateKey
+  }` as `0x${string}`
+);
+
+const walletClient = createWalletClient({
+  account,
+  chain: mainnet,
+  transport: http(rpcUrl),
+});
+
+// 创建 SDK 实例
+const sdk = new AnchorSDK({
+  publicClient,
+  walletClient,
+  network: NETWORKS.mainnet,
+  // 可以指定环境，支持 DEV、BETA 和 PROD
+  env: Environment.DEV,
+  // 也可以直接指定 API URL，这将覆盖环境配置
+  // apiBaseUrl: "https://api.example.com",
+  authToken: "YOUR_JWT_TOKEN",
+  clientId: "YOUR_CLIENT_ID",
+});
+```
+
+### 2. 使用 ETH 购买徽章（EOA 模式）
+
+```typescript
+// 直接发送交易
+const txHash = await sdk.buyBadgeWithETH(
+  "0xRECIPIENT_ADDRESS", // 接收徽章的地址
+  "0xCONTRACT_ADDRESS", // 合约地址
+  1, // Badge ID
+  1, // 数量
+  "0xRECEIPT_ADDRESS", // 接收支付的地址
+  {
+    value: "0.1", // 支付金额（ETH）
+    gas: 300000n, // 可选：指定 gas 限制
+    sendTransaction: true, // 明确指定直接发送交易
+  }
+);
+
+console.log(`交易已发送: ${txHash}`);
+```
+
+### 3. 使用 ETH 购买徽章（AA 模式）
+
+```typescript
+// 只返回交易数据，不发送交易
+const txData = await sdk.buyBadgeWithETH(
+  "0xRECIPIENT_ADDRESS", // 接收徽章的地址
+  "0xCONTRACT_ADDRESS", // 合约地址
+  1, // Badge ID
+  1, // 数量
+  "0xRECEIPT_ADDRESS", // 接收支付的地址
+  {
+    value: "0.1", // 支付金额（ETH）
+    sendTransaction: false, // 指定不发送交易，只返回交易数据
+  }
+);
+
+console.log(`交易数据: ${txData}`);
+// 使用你的 AA 钱包发送此交易数据
+```
+
+### 4. 铸造免费徽章
+
+```typescript
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { saigon, baseSepolia } from "viem/chains";
+import { AnchorSDK, NETWORKS, Environment } from "anchor-sdk";
+
+// 创建客户端
+const privateKey = "0xYOUR_PRIVATE_KEY";
+
+// 这里使用 saigon 测试网，也可以使用 baseSepolia 或其他支持的网络
+const publicClient = createPublicClient({
+  chain: saigon,
+  transport: http(),
+});
+
+const account = privateKeyToAccount(
+  `0x${
+    privateKey.startsWith("0x") ? privateKey.slice(2) : privateKey
+  }` as `0x${string}`
+);
+
+const walletClient = createWalletClient({
+  account,
+  chain: saigon,
+  transport: http(),
+});
+
+// 创建 SDK 实例
+const sdk = new AnchorSDK({
+  publicClient,
+  walletClient,
+  env: Environment.DEV,
+  network: NETWORKS.saigon,
+  authToken: "YOUR_JWT_TOKEN",
+  clientId: "YOUR_CLIENT_ID",
+});
+
+try {
+  // 使用封装的 mintFreeBadge 方法（推荐）
+  // 这个方法会自动从后端获取签名请求并执行铸造
+  const customerAddress = account.address;
+  const contractAddress =
+    "0x23Da7778F6152D7B91C20808bEF7163c5EC2C470" as `0x${string}`; // 替换为合约地址
+  const claimableIds = ["CLAIMABLE_ID"]; // 替换为实际的可领取 ID
+
+  const txHash = await sdk.mintFreeBadge(
+    customerAddress,
+    contractAddress,
+    claimableIds,
+    { sendTransaction: true } // 明确指定直接发送交易
+  );
+
+  console.log(`免费徽章铸造交易已提交：${txHash}`);
+
+  // 检查铸造结果
+  const receipt = await publicClient.waitForTransactionReceipt({
+    hash: txHash,
+  });
+  console.log(`铸造成功: ${receipt.status === "success"}`);
+} catch (error) {
+  console.error("铸造免费徽章失败:", error);
+}
+```
+
+### 5. 使用纯支付功能
+
+```typescript
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { saigon } from "viem/chains";
+import { AnchorSDK, Environment } from "anchor-sdk";
+
+// 创建客户端
+const privateKey = "0xYOUR_PRIVATE_KEY";
+
+const publicClient = createPublicClient({
+  chain: saigon,
+  transport: http(),
+});
+
+const account = privateKeyToAccount(
+  `0x${
+    privateKey.startsWith("0x") ? privateKey.slice(2) : privateKey
+  }` as `0x${string}`
+);
+
+const walletClient = createWalletClient({
+  account,
+  chain: saigon,
+  transport: http(),
+});
+
+// 创建 SDK 实例
+const sdk = new AnchorSDK({
+  publicClient,
+  walletClient,
+  env: Environment.DEV,
+  network: NETWORKS.saigon,
+});
+
+try {
+  // EOA 模式 - 直接发送交易
+  const txHash = await sdk.pay(
+    "order-123", // 订单 ID
+    "0.01", // 支付金额（ETH）
+    "0xRECEIPT_ADDRESS", // 接收地址
+    { sendTransaction: true } // 明确指定直接发送交易
+  );
+
+  console.log(`交易已提交：${txHash}`);
+
+  // AA 模式 - 只返回交易数据，不发送交易
+  const txData = await sdk.pay(
+    "order-456", // 订单 ID
+    "0.05", // 支付金额（ETH）
+    "0xRECEIPT_ADDRESS", // 接收地址
+    { sendTransaction: false } // 指定不发送交易，只返回交易数据
+  );
+
+  console.log("交易数据:", txData);
+  // 使用你的 AA 钱包发送此交易数据
+} catch (error) {
+  console.error("支付失败:", error);
+}
+```
+
+### 6. 使用自定义签名购买徽章
+
+```typescript
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { mainnet, saigon } from "viem/chains";
+import { AnchorSDK, NETWORKS, Environment } from "anchor-sdk";
+import MugenApiClient from "./MugenApiClient";
+
+// 创建客户端
+const rpcUrl = "https://saigon-testnet.roninchain.com/rpc";
+const privateKey = "0xYOUR_PRIVATE_KEY";
+
+const publicClient = createPublicClient({
+  chain: saigon,
+  transport: http(rpcUrl),
+});
+
+const account = privateKeyToAccount(
+  `0x${
+    privateKey.startsWith("0x") ? privateKey.slice(2) : privateKey
+  }` as `0x${string}`
+);
+const userAddress = account.address;
+
+const walletClient = createWalletClient({
+  account,
+  chain: saigon,
+  transport: http(rpcUrl),
+});
+
+// 创建 SDK 实例
+const sdk = new AnchorSDK({
+  publicClient,
+  walletClient,
+  network: NETWORKS.saigon,
+  env: Environment.BETA,
+});
+
+// 从 Mugen API 获取签名数据
+const mugenApiClient = new MugenApiClient(
+  "https://api.mugen.com/",
+  "YOUR_JWT_TOKEN"
+);
+
+try {
+  // 创建订单
+  const orderResult = await mugenApiClient.orderCreate(
+    "PRODUCT_CODE",
+    "PRODUCT_ID",
+    userAddress
+  );
+
+  console.log("创建订单结果:", orderResult);
+
+  if (orderResult.success && orderResult.obj) {
+    // 使用 SDK 的自定义签名方法购买徽章
+    const signedRequest = {
+      request: {
+        to: userAddress,
+        tokenId: "TOKEN_ID",
+        amount: 1,
+        price: "0.01",
+        currency: "0x0000000000000000000000000000000000000000", // ETH的地址是零地址
+        deadline: Math.floor(Date.now() / 1000) + 3600, // 1小时后过期
+        quantity: 1,
+      },
+      signature: orderResult.obj.signature,
+    };
+
+    const txHash = await sdk.buyBadgeWithETHWithSignedRequest(
+      signedRequest,
+      userAddress, // 接收地址
+      { value: "0.01", sendTransaction: true }
+    );
+
+    console.log("交易已发送:", txHash);
+  } else {
+    console.error("创建订单失败:", orderResult);
+  }
+} catch (error) {
+  console.error("购买徽章失败:", error);
+}
+```
+
+## 🎯 DApp 函数调用场景
+
+在 dApp 中，您可以在以下特定情况下调用这些函数来与 Anchor SDK 交互：
+
+- **buyBadgeWithETH**: 当用户想要使用 ETH 购买徽章时调用此函数，在 EOA 模式下直接发送交易，或在 AA 模式下获取交易数据而不发送。
+- **buyBadgeWithETHWithSignedRequest**: 用于使用预签名请求购买徽章，通常在集成外部 API 进行自定义签名时使用。
+- **buyBadgeWithERC20**: 当用户使用 ERC20 代币购买徽章时调用此函数，处理代币批准和转账。
+- **buyBadgeWithERC20WithCustomSignature**: 用于需要签名请求的 ERC20 购买，例如来自后端的验证订单场景。
+- **pay**: 用于一般支付，如使用 ETH 处理订单或为 AA 钱包获取交易数据。
+- **mintFreeBadge**: 为符合条件的用户铸造免费徽章时调用此函数，通常在从 API 获取可领取 ID 后使用。
+- **其他函数**: 对于批量操作或高级交互，请参考 batchMintBadge 等方法在单个交易中进行多次铸造。
+
+## 🌐 支持的网络
+
+SDK 支持多种网络，包括：
+
+| 网络               | 类型   | 链 ID | 说明                |
+| ------------------ | ------ | ----- | ------------------- |
+| `mainnet`          | 主网   | 1     | 以太坊主网          |
+| `saigon`           | 测试网 | 2021  | Saigon 测试网       |
+| `ronin`            | 主网   | 2020  | Ronin 网络          |
+| `baseSepolia`      | 测试网 | 84532 | Base Sepolia 测试网 |
+| `berachain`        | 主网   | 80094 | Bera 主网           |
+| `berachainBepolia` | 测试网 | 80085 | Bera 测试网         |
+| `abstractTestnet`  | 测试网 | 11124 | Abstract 测试网     |
+| `base`             | 主网   | 8453  | Base 主网           |
+| `abstract`         | 主网   | 11111 | Abstract 主网       |
+
+## 🔐 API 认证
+
+使用 Anchor API 功能时，需要提供以下认证参数：
+
+- `authToken` - JWT 令牌，格式为 "your-jwt-token"
+- `clientId` - 客户端标识
+
+您可以在初始化 SDK 时提供这些参数，也可以在运行时更新：
+
+```typescript
+// 初始化时设置
+const sdk = new AnchorSDK({
+  // 其他配置...
+  apiBaseUrl: "https://api.example.com",
+  authToken: "YOUR_JWT_TOKEN",
+  clientId: "YOUR_CLIENT_ID",
+});
+
+// 运行时更新
+sdk.anchorApi.setAuthToken("NEW_JWT_TOKEN");
+sdk.anchorApi.setClientId("NEW_CLIENT_ID");
+```
+
+### Token 过期处理
+
+SDK 提供了 token 过期回调机制，当 API 调用遇到 token 过期错误时，会自动调用回调函数：
+
+```typescript
+// 初始化时设置 token 过期回调
+const sdk = new AnchorSDK({
+  // 其他配置...
+  apiBaseUrl: "https://api.example.com",
+  authToken: "YOUR_JWT_TOKEN",
+  clientId: "YOUR_CLIENT_ID",
+  onTokenExpired: (error: Error) => {
+    console.log("Token 已过期:", error.message);
+
+    // 处理 token 过期逻辑
+    // 例如：刷新 token、重新登录、通知用户等
+    refreshToken().then((newToken) => {
+      sdk.anchorApi?.setAuthToken(newToken);
+      console.log("Token 已刷新");
+    });
+  },
+});
+
+// 运行时设置 token 过期回调
+sdk.setTokenExpiredCallback((error: Error) => {
+  console.log("Token 已过期:", error.message);
+  // 处理 token 过期逻辑
+});
+```
+
+回调函数会在以下情况下触发：
+
+- 响应体中的 `code` 字段为 `params.jwt.check.invalid`（即使 HTTP 状态码为 200）
+
+### 错误码说明
+
+当 API 返回 `code: "params.jwt.check.invalid"` 时，表示 JWT token 验证失败，可能的原因包括：
+
+- Token 已过期
+- Token 格式不正确
+- Token 签名无效
+- Token 被撤销
+
+**注意**：即使 token 过期，API 也可能返回 HTTP 状态码 200，SDK 会检查响应体中的错误码来判断 token 是否有效。
+
+SDK 会自动检测这种错误码并调用回调函数，让您可以执行相应的处理逻辑。
+
+## 📚 API 文档
+
+### 核心类
+
+#### `AnchorSDK`
+
+主要的 SDK 类，提供与 Anchor 生态系统交互的所有功能。
+
+```typescript
+class AnchorSDK {
+  constructor(config: AnchorSDKConfig);
+
+  // 徽章购买方法
+  buyBadgeWithETH(
+    customerAddress: string,
+    contractAddress: string,
+    tokenId: string | number | bigint,
+    quantity: string | number | bigint,
+    receiptAddress: string,
+    options?: PaymentOptions
+  ): Promise<TransactionReceipt | { to: string; data: string; value: bigint }>;
+
+  buyBadgeWithETHWithSignedRequest(
+    signedRequest: SignedMintRequest,
+    receiptAddress: string,
+    options?: PaymentOptions
+  ): Promise<TransactionReceipt | { to: string; data: string; value: bigint }>;
+
+  buyBadgeWithERC20(
+    customerAddress: string,
+    contractAddress: string,
+    tokenId: string | number | bigint,
+    quantity: string | number | bigint,
+    currency: string,
+    receiptAddress: string,
+    options?: PaymentOptions
+  ): Promise<TransactionReceipt | { to: string; data: string; value: bigint }>;
+
+  // 免费铸造方法
+  mintFreeBadge(
+    customerAddress: string,
+    contractAddress: string,
+    tokenIds: string[],
+    options?: { sendTransaction?: boolean }
+  ): Promise<
+    | TransactionReceipt
+    | { to: string; data: string; value: bigint }
+    | { to: string; data: string; value: bigint }[]
+  >;
+
+  // 批量操作
+  batchMintBadge(
+    customerAddress: string,
+    contractAddress: string,
+    tokenIds: string[],
+    options?: { sendTransaction?: boolean }
+  ): Promise<
+    TransactionReceipt | { to: string; data: string; value: bigint }[]
+  >;
+
+  batchMintBadgeWithMulticall(
+    customerAddress: string,
+    contractAddress: string,
+    tokenIds: string[],
+    options?: { sendTransaction?: boolean }
+  ): Promise<TransactionReceipt | { to: string; data: string; value: bigint }>;
+
+  // 支付方法
+  pay(
+    orderId: string,
+    amount: string | number | bigint,
+    receiptAddress: string,
+    options?: PaymentOptions
+  ): Promise<TransactionReceipt | { to: string; data: string; value: bigint }>;
+
+  sendPaymentWithNativeToken(params: {
+    callData: `0x${string}`;
+    amount: string | number | bigint;
+    receiptAddress: string;
+    contractName?: string;
+    options?: PaymentOptions;
+  }): Promise<TransactionReceipt | { to: string; data: string; value: bigint }>;
+
+  sendPaymentWithERC20(params: {
+    callData: `0x${string}`;
+    amount: string | number | bigint;
+    receiptAddress: string;
+    tokenAddress: string;
+    contractName?: string;
+    options?: PaymentOptions;
+  }): Promise<TransactionReceipt | { to: string; data: string; value: bigint }>;
+
+  // 工具方法
+  setWalletClient(signerOrWalletClient: any): AnchorSDK;
+  setTokenExpiredCallback(callback: (error: Error) => void): void;
+  processTransactionHash(txHash: string): Promise<any>;
+  getERC20ApprovalData(
+    tokenAddress: Address,
+    amount: bigint,
+    spender?: Address
+  ): { to: string; data: string; value: bigint };
+}
+```
+
+### 类型定义
+
+#### `AnchorSDKConfig`
+
+SDK 配置接口：
+
+```typescript
+interface AnchorSDKConfig {
+  provider?: string | any; // Provider URL 或 Web3 Provider
+  signer?: any; // 可选的签名者或钱包
+  network: {
+    // 网络信息
+    id: number;
+    name: string;
+    [key: string]: any;
+  };
+  env: Environment; // 环境枚举
+  apiBaseUrl?: string; // API 基础 URL
+  authToken?: string; // 认证令牌
+  projectId?: string; // 项目 ID
+  anchorPayAddress?: string; // AnchorPay 合约地址
+  anchorERC1155Address?: string; // AnchorERC1155 合约地址
+  publicClient?: PublicClient; // 公共客户端
+  walletClient?: WalletClient; // 钱包客户端
+  account?: Account; // 账户信息
+  onTokenExpired?: (error: Error) => void; // Token 过期回调
+}
+```
+
+#### `PaymentOptions`
+
+支付选项接口：
+
+```typescript
+interface PaymentOptions {
+  autoApprove?: boolean; // 是否自动批准 ERC20 代币
+  gas?: bigint; // Gas 限制
+  maxFeePerGas?: bigint; // 最大 Gas 费用
+  maxPriorityFeePerGas?: bigint; // 最大优先费用
+  value?: bigint; // 交易值
+  nonce?: number; // 交易 nonce
+  sendTransaction?: boolean; // 是否直接发送交易
+}
+```
+
+#### `SignedMintRequest`
+
+签名铸造请求接口：
+
+```typescript
+interface SignedMintRequest {
+  request: IMintRequest; // 铸造请求
+  signature: string; // 签名
+}
+
+interface IMintRequest {
+  to: Address; // 接收者地址
+  tokenId: number | bigint; // 代币 ID
+  quantity: number | bigint; // 数量
+  price: bigint; // 价格
+  currency: Address; // 货币地址
+  validityStartTimestamp?: number | bigint; // 有效期开始时间戳
+  validityEndTimestamp?: number | bigint; // 有效期结束时间戳
+  uid: Hex; // 唯一 ID
+  chainId: bigint; // 链 ID
+  contractAddress?: string; // 合约地址
+  projectHandle?: string; // 项目句柄
+}
+```
+
+### 环境配置
+
+#### `Environment`
+
+环境枚举：
+
+```typescript
+enum Environment {
+  DEV = "dev", // 开发环境
+  BETA = "beta", // 测试环境
+  PROD = "prod", // 生产环境
+}
+```
+
+### React 支持
+
+SDK 还提供了 React Hook 和组件支持：
+
+```typescript
+import { useAnchorSDK, AnchorProvider } from "anchor-sdk/react";
+
+// 使用 Hook
+const { sdk, loading, error } = useAnchorSDK();
+
+// 使用 Provider
+<AnchorProvider config={sdkConfig}>
+  <YourApp />
+</AnchorProvider>;
+```
+
+## 🛠️ 开发指南
+
+### 本地开发
+
+1. 克隆仓库：
+
+```bash
+git clone https://github.com/keccak256-evg/anchor-sdk.git
+cd anchor-sdk
+```
+
+2. 安装依赖：
+
+```bash
+npm install
+```
+
+3. 构建项目：
+
+```bash
+npm run build
+```
+
+4. 运行测试：
+
+```bash
+npm test
+```
+
+### 项目结构
+
+```
+src/
+├── index.ts                 # 主入口文件
+├── AnchorSDK.ts            # 核心 SDK 类
+├── AnchorPayClient.ts      # AnchorPay 客户端
+├── AnchorERC1155Client.ts  # AnchorERC1155 客户端
+├── AnchorApiClientV2.ts    # API 客户端
+├── constants.ts            # 常量定义
+├── types.ts               # 类型定义
+├── abi/                   # 合约 ABI
+├── generated/             # 生成的 API 代码
+├── react/                 # React 组件和 Hook
+└── utils/                 # 工具函数
+```
+
+## 🤝 贡献
+
+我们欢迎社区贡献！请遵循以下步骤：
+
+1. Fork 这个仓库
+2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 打开一个 Pull Request
+
+### 贡献指南
+
+- 请确保您的代码遵循项目的 TypeScript 配置
+- 添加适当的测试覆盖
+- 更新相关文档
+- 遵循现有的代码风格
+
+## 📄 许可证
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
+
+## 🔗 相关链接
+
+- [项目主页](https://github.com/keccak256-evg/anchor-sdk)
+- [npm 包](https://www.npmjs.com/package/anchor-sdk)
+- [文档](https://github.com/keccak256-evg/anchor-sdk/tree/main/docs)
+- [示例代码](https://github.com/keccak256-evg/anchor-sdk/tree/main/examples)
+
+## 📞 支持
+
+如果您遇到任何问题或有疑问，请：
+
+1. 查看 [文档](https://github.com/keccak256-evg/anchor-sdk/tree/main/docs)
+2. 搜索 [Issues](https://github.com/keccak256-evg/anchor-sdk/issues)
+3. 创建新的 [Issue](https://github.com/keccak256-evg/anchor-sdk/issues/new)