feat(chain-adapter): ordered apis[] fallback + walletapi providers

.env.example

@@ -2,6 +2,12 @@
 # 复制此文件为 .env.local 并填入真实值
 # .env.local 文件不会被提交到 git
 
+# ==================== API Keys ====================
+
+# TronGrid API Key（用于高频率 Tron 请求）
+# 申请地址: https://www.trongrid.io/
+# VITE_TRONGRID_API_KEY=""
+
 # ==================== E2E 测试 ====================
 
 # 资金账号助记词 - 用于提供测试资金（24个中文词，空格分隔）

docs/white-book/附录/I-外部服务提供商/index.md

@@ -12,6 +12,26 @@
 
 ---
 
+## KeyApp 配置与 Provider（重要）
+
+KeyApp 的链配置（`public/configs/*.json`）使用有序数组 `apis[]` 描述外部 Provider。
+
+- 字段：`{ type, endpoint, config? }`
+- 顺序：**从前到后**为优先级，前一个失败会自动 fallback 到下一个
+- 破坏性变更：历史的 `api`（对象/字典）已废弃，统一使用 `apis[]`
+
+常见 Provider 类型（示例）：
+
+- EVM：`blockscout-v1` / `*-rpc` / `ethwallet-v1` / `bscwallet-v1`
+- Tron：`tron-rpc` / `tron-rpc-pro` / `tronwallet-v1`
+- Bitcoin：`mempool-v1` / `btcwallet-v1`
+
+TronGrid Key：
+
+- `tron-rpc-pro` 支持在 `config.apiKeyEnv` 指定环境变量（如 `VITE_TRONGRID_API_KEY`），用于注入请求头 `TRON-PRO-API-KEY`
+
+---
+
 ## 链类型分类
 
 | 类型 | 链 | API 路径前缀 | 特点 |
@@ -112,6 +132,11 @@ src/apis/
 | POST | `/wallet/eth/account/balance/v2` | 批量查余额 |
 | GET | `/wallet/eth/getChainId` | 获取 chainId |
 
+KeyApp Provider 对应关系：
+
+- `ethwallet-v1` 以 `/wallet/eth/*` 为前缀
+- `bscwallet-v1` 以 `/wallet/bsc/*` 为前缀
+
 ---
 
 ## 三、比特币 (bitcoin)
@@ -137,6 +162,10 @@ src/apis/
 
 **注意**: Bitcoin API 使用代理模式，通过 POST 发送 `{ url, method }` 参数。
 
+KeyApp Provider 对应关系：
+
+- `btcwallet-v1` 对应 `/wallet/btc/blockbook`（代理 blockbook）
+
 ---
 
 ## 四、波场 (tron)
@@ -170,6 +199,10 @@ src/apis/
 | POST | `/wallet/tron/contract/token/detail` | 代币详情 |
 | POST | `/wallet/tron/account/balance/v2` | 批量查余额 |
 
+KeyApp Provider 对应关系：
+
+- `tronwallet-v1` 以 `/wallet/tron/*` 为前缀
+
 ---
 
 ## 响应格式

public/configs/default-chains.json

@@ -15,9 +15,7 @@
       ],
       "prefix": "b",
       "decimals": 8,
-      "api": {
-        "biowallet-v1": ["https://walletapi.bfmeta.info", { "path": "bfm" }]
-      },
+      "apis": [{ "type": "biowallet-v1", "endpoint": "https://walletapi.bfmeta.info", "config": { "path": "bfm" } }],
       "explorer": {
         "url": "https://tracker.bfmeta.org",
         "queryTx": "https://tracker.bfmeta.org/#/info/event-details/:signature",
@@ -39,9 +37,7 @@
       ],
       "prefix": "b",
       "decimals": 8,
-      "api": {
-        "biowallet-v1": ["https://walletapi.bfmeta.info", { "path": "ccchain" }]
-      }
+      "apis": [{ "type": "biowallet-v1", "endpoint": "https://walletapi.bfmeta.info", "config": { "path": "ccchain" } }]
     },
     {
       "id": "pmchain",
@@ -57,9 +53,7 @@
       ],
       "prefix": "b",
       "decimals": 8,
-      "api": {
-        "biowallet-v1": ["https://walletapi.bfmeta.info", { "path": "pmchain" }]
-      }
+      "apis": [{ "type": "biowallet-v1", "endpoint": "https://walletapi.bfmeta.info", "config": { "path": "pmchain" } }]
     },
     {
       "id": "bfchainv2",
@@ -75,9 +69,9 @@
       ],
       "prefix": "b",
       "decimals": 8,
-      "api": {
-        "biowallet-v1": ["https://walletapi.bfmeta.info", { "path": "bfchainv2" }]
-      }
+      "apis": [
+        { "type": "biowallet-v1", "endpoint": "https://walletapi.bfmeta.info", "config": { "path": "bfchainv2" } }
+      ]
     },
     {
       "id": "btgmeta",
@@ -93,9 +87,7 @@
       ],
       "prefix": "b",
       "decimals": 8,
-      "api": {
-        "biowallet-v1": ["https://walletapi.bfmeta.info", { "path": "btgmeta" }]
-      }
+      "apis": [{ "type": "biowallet-v1", "endpoint": "https://walletapi.bfmeta.info", "config": { "path": "btgmeta" } }]
     },
     {
       "id": "biwmeta",
@@ -109,9 +101,9 @@
       ],
       "prefix": "b",
       "decimals": 8,
-      "api": {
-        "biowallet-v1": ["https://walletapi.biw-meta.com", { "path": "biwmeta" }]
-      },
+      "apis": [
+        { "type": "biowallet-v1", "endpoint": "https://walletapi.biw-meta.com", "config": { "path": "biwmeta" } }
+      ],
       "explorer": {
         "url": "https://tracker.biw-meta.info",
         "queryTx": "https://tracker.biw-meta.info/#/info/event-details/:signature",
@@ -133,9 +125,7 @@
       ],
       "prefix": "b",
       "decimals": 8,
-      "api": {
-        "biowallet-v1": ["https://walletapi.bfmeta.info", { "path": "ethmeta" }]
-      }
+      "apis": [{ "type": "biowallet-v1", "endpoint": "https://walletapi.bfmeta.info", "config": { "path": "ethmeta" } }]
     },
     {
       "id": "ethereum",
@@ -150,10 +140,11 @@
         "https://raw.githubusercontent.com/BFChainMeta/fonts-cdn/main/src/meta-icon/eth"
       ],
       "decimals": 18,
-      "api": {
-        "ethereum-rpc": "https://ethereum-rpc.publicnode.com",
-        "blockscout-v1": "https://eth.blockscout.com/api"
-      },
+      "apis": [
+        { "type": "blockscout-v1", "endpoint": "https://eth.blockscout.com/api" },
+        { "type": "ethereum-rpc", "endpoint": "https://ethereum-rpc.publicnode.com" },
+        { "type": "ethwallet-v1", "endpoint": "https://walletapi.bfmeta.info/wallet/eth" }
+      ],
       "explorer": {
         "url": "https://eth.blockscout.com",
         "queryTx": "https://eth.blockscout.com/tx/:hash",
@@ -173,10 +164,10 @@
         "https://raw.githubusercontent.com/BFChainMeta/fonts-cdn/main/src/meta-icon/bsc"
       ],
       "decimals": 18,
-      "api": {
-        "bsc-rpc": "https://bsc-rpc.publicnode.com",
-        "bscwallet-v1": "https://walletapi.bfmeta.info/wallet/bsc"
-      },
+      "apis": [
+        { "type": "bsc-rpc", "endpoint": "https://bsc-rpc.publicnode.com" },
+        { "type": "bscwallet-v1", "endpoint": "https://walletapi.bfmeta.info/wallet/bsc" }
+      ],
       "explorer": {
         "url": "https://bscscan.com",
         "queryTx": "https://bscscan.com/tx/:hash",
@@ -196,9 +187,15 @@
         "https://raw.githubusercontent.com/BFChainMeta/fonts-cdn/main/src/meta-icon/tron"
       ],
       "decimals": 6,
-      "api": {
-        "tron-rpc": "https://api.trongrid.io"
-      },
+      "apis": [
+        { "type": "tron-rpc", "endpoint": "https://api.trongrid.io" },
+        {
+          "type": "tron-rpc-pro",
+          "endpoint": "https://api.trongrid.io",
+          "config": { "apiKeyEnv": "VITE_TRONGRID_API_KEY" }
+        },
+        { "type": "tronwallet-v1", "endpoint": "https://walletapi.bfmeta.info/wallet/tron" }
+      ],
       "explorer": {
         "url": "https://tronscan.org",
         "queryTx": "https://tronscan.org/#/transaction/:hash",
@@ -218,9 +215,10 @@
         "https://raw.githubusercontent.com/BFChainMeta/fonts-cdn/main/src/meta-icon/btcm"
       ],
       "decimals": 8,
-      "api": {
-        "mempool-v1": "https://mempool.space/api"
-      },
+      "apis": [
+        { "type": "mempool-v1", "endpoint": "https://mempool.space/api" },
+        { "type": "btcwallet-v1", "endpoint": "https://walletapi.bfmeta.info/wallet/btc/blockbook" }
+      ],
       "explorer": {
         "url": "https://mempool.space",
         "queryTx": "https://mempool.space/tx/:hash",

public/configs/testnet-chains.json

@@ -9,9 +9,9 @@
       "symbol": "SepoliaETH",
       "icon": "../icons/ethereum/chain.svg",
       "decimals": 18,
-      "api": {
-        "ethereum-rpc": "https://rpc.sepolia.org"
-      },
+      "apis": [
+        { "type": "ethereum-rpc", "endpoint": "https://rpc.sepolia.org" }
+      ],
       "explorer": {
         "url": "https://sepolia.etherscan.io",
         "queryTx": "https://sepolia.etherscan.io/tx/:hash",
@@ -26,9 +26,9 @@
       "symbol": "tBNB",
       "icon": "../icons/binance/chain.svg",
       "decimals": 18,
-      "api": {
-        "ethereum-rpc": "https://bsc-testnet-rpc.publicnode.com"
-      },
+      "apis": [
+        { "type": "ethereum-rpc", "endpoint": "https://bsc-testnet-rpc.publicnode.com" }
+      ],
       "explorer": {
         "url": "https://testnet.bscscan.com",
         "queryTx": "https://testnet.bscscan.com/tx/:hash",
@@ -43,9 +43,9 @@
       "symbol": "TRX",
       "icon": "../icons/tron/chain.svg",
       "decimals": 6,
-      "api": {
-        "tron-rpc": "https://nile.trongrid.io"
-      },
+      "apis": [
+        { "type": "tron-rpc", "endpoint": "https://nile.trongrid.io" }
+      ],
       "explorer": {
         "url": "https://nile.tronscan.org",
         "queryTx": "https://nile.tronscan.org/#/transaction/:hash",
@@ -60,9 +60,9 @@
       "symbol": "sBTC",
       "icon": "../icons/bitcoin/chain.svg",
       "decimals": 8,
-      "api": {
-        "mempool-v1": "https://mempool.space/signet/api"
-      },
+      "apis": [
+        { "type": "mempool-v1", "endpoint": "https://mempool.space/signet/api" }
+      ],
       "explorer": {
         "url": "https://mempool.space/signet",
         "queryTx": "https://mempool.space/signet/tx/:hash",

scripts/set-secret.ts

@@ -112,6 +112,21 @@ const SECRET_DEFINITIONS: SecretDefinition[] = [
     required: true,
     isPassword: true,
   },
+
+  // API Keys
+  {
+    key: 'VITE_TRONGRID_API_KEY',
+    description: 'TronGrid API Key（用于高频率 Tron 请求）',
+    category: 'api-keys',
+    required: false,
+    isPassword: true,
+    validate: (v) => {
+      if (v && !/^[a-f0-9-]{36}$/i.test(v)) {
+        return 'API Key 格式无效（应为 UUID）'
+      }
+      return true
+    },
+  },
 ]
 
 interface CategoryDefinition {
@@ -136,6 +151,11 @@ const CATEGORIES: CategoryDefinition[] = [
     name: 'DWEB 开发版发布',
     description: 'SFTP 开发服务器账号（用于日常 CI/CD）',
   },
+  {
+    id: 'api-keys',
+    name: 'API Keys',
+    description: '第三方 API 密钥（TronGrid 等）',
+  },
 ]
 
 // ==================== 工具函数 ====================