onekey-balance-kit/.cursor/rules/blockchain-providers.mdc at main · sd0xdev/onekey-balance-kit · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
---
description: Blockchain Provider
globs:
alwaysApply: false
---
# 區塊鏈提供者架構

該規則描述了我們的區塊鏈提供者架構，特別是使用 Strategy 和 Adapter 設計模式重構後的多鏈支援實現。

## 架構概述

我們使用三層設計來實現多鏈支援：

1. **Strategy 層**：負責與區塊鏈節點通訊（如 EVM SDK、Solana RPC 等）
2. **Adapter 層**：將不同鏈的原始回應轉換為統一的 DTO 格式
3. **Facade 層**：根據鏈類型選擇適當的策略並調用適配器

## 主要組件

### 策略介面與實現

- [BalanceStrategy 介面](mdc:src/providers/strategies/balance-strategy.interface.ts) - 定義所有策略必須實現的方法
- [EvmAlchemyStrategy](mdc:src/providers/strategies/implementations/evm-alchemy.strategy.ts) - 基於 Alchemy SDK 的 EVM 策略實現
- [EvmQuickNodeStrategy](mdc:src/providers/strategies/implementations/evm-quicknode.strategy.ts) - 基於 QuickNode SDK 的 EVM 策略實現
- [SolanaAlchemyStrategy](mdc:src/providers/strategies/implementations/solana-alchemy.strategy.ts) - Solana 鏈策略實現，使用 Alchemy RPC 和 Portfolio API
- [BalanceStrategyFactory](mdc:src/providers/strategies/balance-strategy.factory.ts) - 策略工廠，用於創建和管理策略實例

### 適配器介面與實現

- [BalanceAdapter 介面](mdc:src/providers/adapters/balance-adapter.interface.ts) - 定義所有適配器的方法
- [EvmBalanceAdapter](mdc:src/providers/adapters/implementations/evm-balance.adapter.ts) - EVM 鏈的適配器實現
- [EvmQuickNodeAdapter](mdc:src/providers/adapters/implementations/evm-quicknode.adapter.ts) - QuickNode EVM 回應的適配器實現
- [SolanaBalanceAdapter](mdc:src/providers/adapters/implementations/solana-balance.adapter.ts) - Solana 鏈的適配器實現
- [BalanceAdapterFactory](mdc:src/providers/adapters/balance-adapter.factory.ts) - 適配器工廠，創建和管理適配器實例

### 提供者實現

- [AlchemyProviderFacade](mdc:src/providers/implementations/multi-chain/alchemy-provider.facade.ts) - Alchemy 多鏈提供者門面，使用策略和適配器處理不同鏈的請求
- [EthereumQuickNodeProvider](mdc:src/providers/implementations/ethereum/ethereum-quicknode.provider.ts) - QuickNode 以太坊提供者門面，使用策略和適配器處理請求
- [Provider 裝飾器](mdc:src/providers/decorators/provider.decorator.ts) - 用於標記和註冊提供者
- [ProvidersModule](mdc:src/providers/providers.module.ts) - 提供者模組配置

## 模組配置

[providers.module.ts](mdc:src/providers/providers.module.ts) 中註冊了所有提供者，包括重構後的 `AlchemyProviderFacade` 和 `EthereumQuickNodeProvider`。

## 使用範例

獲取任意鏈的餘額：

```typescript
// 注入 AlchemyProviderFacade
constructor(private readonly alchemyProvider: AlchemyProviderFacade) {}

// 獲取 EVM 鏈餘額
const ethBalances = await this.alchemyProvider.getBalances(
  '0x123...',
  NetworkType.MAINNET,
  ChainName.ETHEREUM
);

// 獲取 Solana 鏈餘額
const solBalances = await this.alchemyProvider.getBalances(
  'Bx4KqEq1...',
  NetworkType.MAINNET,
  ChainName.SOLANA
);

// 使用 QuickNode 提供者
constructor(private readonly quickNodeProvider: EthereumQuickNodeProvider) {}

const ethBalancesQuickNode = await this.quickNodeProvider.getBalances(
  '0x123...',
  NetworkType.MAINNET
);
```

## 擴展指南

### 添加新的鏈支援

1. 為新鏈創建適配器實現（繼承 `BalanceAdapter`）
2. 在 `BalanceAdapterFactory` 中添加新鏈的映射
3. 創建新鏈的策略實現（實現 `BalanceStrategy`）
4. 在 `AlchemyProviderFacade` 中的 `initializeStrategies` 方法中添加新鏈支援

### 添加新的提供者

1. 為每個需要支援的鏈創建策略實現（實現 `BalanceStrategy`）
2. 創建適當的適配器或使用現有適配器
3. 創建新的提供者門面（繼承 `AbstractProviderService`）
4. 在提供者門面中使用策略工廠和適配器工廠獲取相應實例

### QuickNode 提供者實現範例

QuickNode 提供者使用三層架構：
- **策略層**: `EvmQuickNodeStrategy` 負責與 QuickNode API 通訊
- **適配器層**: `EvmQuickNodeAdapter` 將原始資料轉換為統一格式
- **外觀層**: `EthereumQuickNodeProvider` 作為前端，協調策略和適配器

## 注意事項

- 使用 EIP-1559 gas 費用模型，優先從 `maxFeePerGas` 獲取
- Solana 公共 RPC 有請求限制，實際應用中應實現指數退避重試和缓存
- 添加新鏈時需在多個位置更新，包括 ChainName 常量、策略列表和適配器工廠
- QuickNode 提供者目前支援以太坊及其測試網，可擴展到 Polygon、BSC 等其他 EVM 鏈