@keccak256-evg/passport-sdk/UNIFIED_SDK_GUIDE.md

T-REX Passport SDK for interacting with Passport and Registry contracts

# 🚀 统一 Passport SDK 使用指南

基于 **EIP-1193** 标准的统一 SDK，支持所有主流 Web3 钱包和库！

## ✨ 主要优势

- **🔄 通用兼容**: 支持 MetaMask、WalletConnect、Coinbase Wallet 等所有 EIP-1193 兼容钱包
- **📦 统一API**: 一套 API 适配所有钱包，无需针对不同库编写不同代码
- **⚡ 简单配置**: 只需传入 provider，自动处理底层差异
- **🎯 类型安全**: 完整的 TypeScript 支持

## 🔧 基础使用

### 安装

```bash
npm install @keccak256-evg/passport-sdk
```

### 快速开始

```typescript
import { UnifiedPassportSDK } from '@keccak256-evg/passport-sdk';

// 使用 MetaMask
const sdk = new UnifiedPassportSDK({
  provider: window.ethereum, // EIP-1193 provider
  chain: {
    id: 1962,
    name: 'T-Rex Testnet',
    rpcUrls: { default: { http: ['https://testnetrpc.trex.xyz'] } }
  },
  env: 'dev'
});

// 连接钱包并检查 Passport
const accounts = await sdk.connectWallet();
const result = await sdk.checkWalletHasPassport(accounts[0]);
```

## 📱 支持的钱包

| 钱包 | Provider 获取方式 | 状态 |
|------|------------------|------|
| MetaMask | `window.ethereum` | ✅ 完全支持 |
| Coinbase Wallet | `window.coinbaseWalletExtension?.ethereum` | ✅ 完全支持 |
| WalletConnect | `provider` from WC SDK | ✅ 完全支持 |
| Trust Wallet | `window.trustWallet` | ✅ 完全支持 |
| 其他 EIP-1193 钱包 | 按钱包文档获取 | ✅ 理论支持 |

## 🎯 核心功能

### 1. 钱包管理

```typescript
// 连接钱包
const accounts = await sdk.connectWallet();

// 获取账户信息
const accounts = await sdk.getAccounts();

// 切换网络
await sdk.switchChain();

// 获取 provider 信息
const info = sdk.getProviderInfo();
console.log(info.isMetaMask, info.isCoinbaseWallet);
```

### 2. Passport 操作

```typescript
// 创建 Passport
const txHash = await sdk.createPassport();

// 检查钱包是否有 Passport
const result = await sdk.checkWalletHasPassport(userAddress);

// 获取 Passport 详细信息
const info = await sdk.getPassportInfo(passportAddress);

// 绑定钱包
await sdk.requestBindWallet(passportAddress, targetWallet);
await sdk.acceptBindRequest(passportAddress);

// 解绑钱包
await sdk.unbindWallet(passportAddress);
```

### 3. 事件监听

```typescript
// 监听账户变化
sdk.onAccountsChanged((accounts) => {
  console.log('账户已更改:', accounts);
});

// 监听网络变化
sdk.onChainChanged((chainId) => {
  console.log('网络已更改:', chainId);
});
```

## 🔄 与不同库的兼容性对比

### 传统方式（需要针对每个库单独配置）

```typescript
// Viem 方式
const viemSDK = new ViemPassportSDK({
  publicClient: createPublicClient({...}),
  walletClient: createWalletClient({...}),
  // ...复杂配置
});

// Thirdweb 方式  
const thirdwebSDK = new PassportSDK({
  client: createThirdwebClient({...}),
  chain: defineChain({...}),
  // ...不同的配置
});
```

### 统一方式（一套代码适配所有）

```typescript
// 统一方式 - 任何钱包都用同样的代码
const sdk = new UnifiedPassportSDK({
  provider: anyEIP1193Provider, // 可以是任何兼容钱包
  chain: chainConfig,
  env: 'dev'
});
```

## 🛠️ 高级用法

### 错误处理和重试

```typescript
async function robustOperation() {
  const maxRetries = 3;
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await sdk.createPassport();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }
}
```

### 类型安全配置

```typescript
import { UnifiedPassportSDKConfig } from '@keccak256-evg/passport-sdk';

function createSDK(config: UnifiedPassportSDKConfig) {
  // 配置验证
  if (!config.provider.request) {
    throw new Error('Provider 必须实现 EIP-1193 标准');
  }
  
  return new UnifiedPassportSDK(config);
}
```

### 多钱包支持

```typescript
// 检测并使用可用的钱包
async function detectAndUseWallet() {
  let provider;
  
  if (window.ethereum?.isMetaMask) {
    provider = window.ethereum;
    console.log('使用 MetaMask');
  } else if (window.coinbaseWalletExtension) {
    provider = window.coinbaseWalletExtension.ethereum;
    console.log('使用 Coinbase Wallet');
  } else {
    throw new Error('未检测到支持的钱包');
  }
  
  return new UnifiedPassportSDK({
    provider,
    chain: chainConfig
  });
}
```

## 🔄 迁移指南

### 从 ViemPassportSDK 迁移

```typescript
// 旧方式
const oldSDK = new ViemPassportSDK({
  publicClient: createPublicClient({
    transport: custom(window.ethereum)
  }),
  // ...其他配置
});

// 新方式
const newSDK = new UnifiedPassportSDK({
  provider: window.ethereum, // 直接使用 provider
  chain: chainConfig
});
```

### 从 PassportSDK 迁移

```typescript
// 旧方式
const oldSDK = new PassportSDK({
  client: thirdwebClient,
  chain: thirdwebChain,
  // ...
});

// 新方式  
const newSDK = new UnifiedPassportSDK({
  provider: window.ethereum, // 使用钱包 provider 而不是库 client
  chain: standardChainConfig
});
```

## ❓ 常见问题

### Q: 为什么选择 EIP-1193？
A: EIP-1193 是以太坊钱包的标准接口，所有主流钱包都支持，使用它可以实现最大的兼容性。

### Q: 是否支持服务器端？
A: 统一SDK主要面向浏览器环境。服务器端请继续使用 ViemPassportSDK 配合私钥。

### Q: 如何处理不同钱包的特殊功能？
A: 通过 `getProviderInfo()` 检测钱包类型，然后使用钱包特定的功能。

### Q: 性能如何？
A: 统一SDK底层使用 Viem，性能与直接使用 Viem 基本一致。

## 🔗 相关链接

- [EIP-1193 标准](https://eips.ethereum.org/EIPS/eip-1193)
- [示例代码](./examples/unified-provider-example.ts)
- [完整 API 文档](./README.md)

---

**建议**: 新项目直接使用 `UnifiedPassportSDK`，现有项目可以逐步迁移。这样可以让您的 dApp 支持更多钱包，提供更好的用户体验！