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

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

# Passport 升级功能实现

## 概述

在 Passport Information 信息框的右上角添加了自动升级检测和升级功能，确保用户的 Passport 始终使用最新版本的合约实现。

## 功能特性

### 1. 自动升级检测
- 当用户连接钱包并查询 Passport 信息时，自动调用 `requireUpgrade()` 方法
- 检查当前 Passport 的实现版本是否与 Registry 中的最新版本一致
- 实时显示升级状态

### 2. 升级状态显示
- **需要升级**: 显示橙色的 "🔄 Upgrade" 按钮
- **最新版本**: 显示绿色的 "✓ Latest Version" 标签
- **升级中**: 显示 "Upgrading..." 状态

### 3. 一键升级
- 用户点击升级按钮后，调用 Registry 合约的 `upgradeMyPassport()` 方法
- 自动处理交易确认和状态更新
- 升级成功后自动刷新 Passport 信息

## 技术实现

### SDK 新增方法

#### 1. `checkPassportUpgrade(passportAddress: string): Promise<boolean>`
```typescript
// 检查 Passport 是否需要升级
const needsUpgrade = await passportSDK.checkPassportUpgrade(passportAddress);
```

**实现细节**:
- 调用 Passport 合约的 `requireUpgrade()` 方法
- 比较当前实现版本与 Registry 中的最新版本
- 返回 `true` 表示需要升级，`false` 表示已是最新版本

#### 2. `upgradeMyPassport(): Promise<any>`
```typescript
// 升级用户的 Passport
const transaction = await passportSDK.upgradeMyPassport();
const result = await sendTransaction(transaction);
```

**实现细节**:
- 调用 Registry 合约的 `upgradeMyPassport()` 方法
- 该方法会自动升级调用者的 Passport 到最新版本
- 返回准备好的交易对象，需要用户签名确认

### ABI 更新

在 `constants.ts` 中添加了新的方法定义：

#### Passport ABI 新增
```json
{
  "inputs": [],
  "name": "requireUpgrade",
  "outputs": [{"type": "bool"}],
  "stateMutability": "view",
  "type": "function"
}
```

#### Registry ABI 新增
```json
{
  "inputs": [],
  "name": "upgradeMyPassport",
  "outputs": [],
  "stateMutability": "nonpayable",
  "type": "function"
}
```

### UI 实现

#### 状态管理
```typescript
const [upgrading, setUpgrading] = useState(false);
const [needsUpgrade, setNeedsUpgrade] = useState(false);
```

#### 自动检测逻辑
```typescript
// 在 checkPassportInfo 中添加升级检测
if (hasPassport.hasPassport && hasPassport.passportAddress) {
  const info = await passportSDK.getPassportInfo(hasPassport.passportAddress);
  setPassportInfo({
    ...hasPassport,
    ...info,
  });
  
  // 检查是否需要升级
  try {
    const upgradeNeeded = await passportSDK.checkPassportUpgrade(hasPassport.passportAddress);
    setNeedsUpgrade(upgradeNeeded);
  } catch (error) {
    console.error("Error checking upgrade status:", error);
    setNeedsUpgrade(false);
  }
}
```

#### 升级按钮实现
```typescript
{passportInfo && (
  <div className="flex items-center space-x-2">
    {needsUpgrade ? (
      <button
        onClick={handleUpgradePassport}
        disabled={upgrading || isTransactionPending}
        className={`px-3 py-1 rounded-md text-sm font-medium ${
          upgrading || isTransactionPending
            ? 'bg-zinc-700 text-zinc-400 cursor-not-allowed' 
            : 'bg-orange-600 hover:bg-orange-700 text-white'
        }`}
      >
        {upgrading || isTransactionPending ? 'Upgrading...' : '🔄 Upgrade'}
      </button>
    ) : (
      <span className="px-3 py-1 rounded-md text-sm font-medium bg-green-600 text-white">
        ✓ Latest Version
      </span>
    )}
  </div>
)}
```

## 用户体验

### 1. 自动检测
- 用户连接钱包后，系统自动检查 Passport 版本
- 无需手动操作，状态实时更新

### 2. 清晰的状态指示
- **橙色升级按钮**: 明确提示用户需要升级
- **绿色最新版本标签**: 确认用户已使用最新版本
- **升级中状态**: 防止重复操作

### 3. 一键升级
- 点击升级按钮即可完成升级
- 自动处理交易确认和状态更新
- 升级成功后自动刷新信息

### 4. 错误处理
- 升级失败时显示具体错误信息
- 网络问题或合约错误都有相应提示

## 合约方法说明

### Passport.requireUpgrade()
```solidity
function requireUpgrade() external view returns (bool) {
    address currentImpl = implementation();
    address registryImpl = PassportRegistry(registry()).getPassportImplementation();
    return currentImpl != registryImpl;
}
```

**功能**: 检查当前 Passport 的实现版本是否与 Registry 中的最新版本一致

### Registry.upgradeMyPassport()
```solidity
function upgradeMyPassport() external {
    // 验证调用者是否绑定到 Passport
    // 获取当前实现版本
    // 升级到最新版本
    // 发出升级事件
}
```

**功能**: 将调用者的 Passport 升级到最新实现版本

## 安全考虑

1. **权限验证**: 只有绑定到 Passport 的钱包才能升级
2. **版本检查**: 避免重复升级到相同版本
3. **交易确认**: 用户必须签名确认升级交易
4. **错误处理**: 完善的错误处理和用户提示

## 总结

升级功能的实现确保了：
- **自动化**: 无需用户手动检查版本
- **安全性**: 严格的权限验证和交易确认
- **用户体验**: 清晰的状态指示和简单的操作流程
- **可靠性**: 完善的错误处理和状态管理

这个功能让用户能够轻松保持 Passport 合约的最新版本，享受最新的功能和安全性改进。