README.md

### 🤖 Assistant




# TON Connect SDK 使用文档

## 目录
- [功能概述](#功能概述)
- [主要特性](#主要特性)
- [核心导出](#核心导出)
  - [方法说明](#方法说明)
  - [数据结构](#数据结构)
- [风险提示](#风险提示)
- [使用示例](#使用示例)
- [Q&A](#qa)

## 功能概述
本SDK提供与TON区块链交互的核心功能，包括：
- 钱包连接与交易初始化
- TON代币转账
- Jetton代币（如USDT）转账
- 交易状态追踪与验证
- 主网/测试网切换支持

## 主要特性
- 支持TON主网和测试网切换
- 提供钱包连接的全生命周期管理
- 封装TON和Jetton代币的转账逻辑
- 自动处理交易载荷编码
- 交易结果轮询验证机制
- 支持交易附带文本备注

## 核心导出

### 方法说明

#### `init(isTestOnly: boolean, manifestUrl: string)`
初始化SDK实例
- `isTestOnly`: 是否使用测试网络
- `manifestUrl`: 应用配置文件URL

#### `tonPay(toAddr: string, amount: number, comment?: string)`
进行TON代币转账
- `toAddr`: 接收地址
- `amount`: 转账金额（TON单位）
- `comment`: 可选交易备注

#### `usdtPay(toAddr: string, amount: number, comment?: string)`
进行USDT（Jetton）代币转账

#### `jettonPay(jettonMasterAddr: string, toAddr: string, amount: number, comment?: string)`
通用Jetton代币转账
- `jettonMasterAddr`: Jetton主合约地址

#### `waitForTransaction(toAddr: string, amount: number, comment?: string)`
交易结果轮询验证

### 数据结构

```typescript
interface VerifyOption {
  refetchLimit: number;     // 最大重试次数
  currentRefetchCount: number;  // 当前重试计数
  toAddress: string;        // 目标地址
  amount: number;           // 转账金额
  comment?: string;         // 交易备注
  callback: Function;       // 回调函数
  interval: number;         // 轮询间隔（毫秒）
}
```

## 风险提示
1. **初始化顺序**：必须先调用`init()`方法完成初始化
2. **网络波动**：交易验证可能会因网络问题失败
3. **Gas费用**：建议保持钱包至少有0.1 TON余额
4. **连接状态**：发送交易前会自动检查钱包连接
5. **私钥安全**：SDK不存储任何私钥信息

## 使用示例

### 初始化应用
```javascript
await init(true, "https://example.com/manifest.json");
```

### TON转账
```javascript
await tonPay("EQCD...tV8", 1.5, "服务付款");
```

### USDT转账
```javascript
await usdtPay("EQCD...tV8", 100);
```

### 自定义Jetton转账
```javascript
const jettonAddr = "EQCQ...v_1";
await jettonPay(jettonAddr, "EQCD...tV8", 50);
```

### 交易验证
```javascript
await waitForTransaction("EQCD...tV8", 1.5, "tx123");
```

## Q&A

**Q1: 处理交易失败应该怎么做？**
- 检查钱包连接状态
- 确认目标地址有效性
- 检查账户余额是否充足
- 通过`waitForTransaction`验证交易状态

**Q2: 如何切换测试网络？**
在`init`方法第一个参数传入`true`

**Q3: 如何获取历史交易记录？**
使用`tonWeb.getTransactions(walletAddress, limit)`

**Q4: 交易备注最大长度限制？**
当前实现中建议不超过128字符