| … | … | @@ -0,0 +1,759 @@ |
| 1 | # WDK Multi-Chain Implementation Plan |
| 2 | |
| 3 | **Created**: 2026-01-27 |
| 4 | **Status**: Ready for Implementation |
| 5 | **Based on**: Official WDK Documentation (https://docs.wallet.tether.io) |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## Executive Summary |
| 10 | |
| 11 | This plan systematically adds support for multiple EVM-compatible chains and non-EVM chains using Tether's WDK (Wallet Development Kit). The key insight: **one WalletManagerEvm instance per chain** with different RPC endpoints, not one instance for all EVM chains. |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | ## Current State |
| 16 | |
| 17 | ### What We Have |
| 18 | - ✅ Bitcoin support via `wdk-wallet-btc` |
| 19 | - ✅ Ethereum support via `wdk-wallet-evm` |
| 20 | - ✅ Storage layer supports multiple chains |
| 21 | - ✅ UI supports currency switching |
| 22 | - ✅ Multi-wallet support (multiple addresses per chain) |
| 23 | |
| 24 | ### What's Missing |
| 25 | - ❌ Other EVM chains (Polygon, BSC, Arbitrum, Optimism, Avalanche) |
| 26 | - ❌ Non-EVM chains (Solana, Tron, TON) |
| 27 | - ❌ Chain-specific RPC endpoint configuration |
| 28 | - ❌ Network switching for EVM chains (mainnet vs testnets) |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | ## Key WDK Insights from Documentation |
| 33 | |
| 34 | ### 1. One WalletManagerEvm Registration Per Chain |
| 35 | |
| 36 | **CRITICAL**: Each EVM chain needs its own `registerWallet()` call with unique chain name: |
| 37 | |
| 38 | ```javascript |
| 39 | const wdk = new WDK(seedPhrase) |
| 40 | .registerWallet('ethereum', WalletManagerEvm, { |
| 41 | provider: 'https://eth.drpc.org' |
| 42 | }) |
| 43 | .registerWallet('polygon', WalletManagerEvm, { |
| 44 | provider: 'https://polygon-rpc.com' |
| 45 | }) |
| 46 | .registerWallet('arbitrum', WalletManagerEvm, { |
| 47 | provider: 'https://arb1.arbitrum.io/rpc' |
| 48 | }) |
| 49 | ``` |
| 50 | |
| 51 | ### 2. Chain Name is the Identifier |
| 52 | |
| 53 | The chain name passed to `registerWallet(chainName, ...)` is used everywhere: |
| 54 | - `wdk.getAccount(chainName, index)` |
| 55 | - Storage keys: `tx:${chainName}:${txid}` |
| 56 | - UI currency selector |
| 57 | |
| 58 | ### 3. Same API Across All Chains |
| 59 | |
| 60 | All registered wallets use the same consistent API: |
| 61 | ```javascript |
| 62 | const account = await wdk.getAccount('polygon', 0) |
| 63 | const address = await account.getAddress() |
| 64 | const balance = await account.getBalance() |
| 65 | const result = await account.sendTransaction({ to, value }) |
| 66 | ``` |
| 67 | |
| 68 | ### 4. Network Support (Testnet vs Mainnet) |
| 69 | |
| 70 | **EVM Chains**: Change provider URL for testnet |
| 71 | ```javascript |
| 72 | // Mainnet |
| 73 | provider: 'https://eth.drpc.org' |
| 74 | // Testnet (Sepolia) |
| 75 | provider: 'https://sepolia.drpc.org' |
| 76 | ``` |
| 77 | |
| 78 | **Bitcoin**: Network parameter |
| 79 | ```javascript |
| 80 | // Mainnet |
| 81 | { network: 'mainnet', host: 'electrum.blockstream.info', port: 50001 } |
| 82 | // Testnet |
| 83 | { network: 'testnet', host: 'blockstream.info', port: 60001 } |
| 84 | ``` |
| 85 | |
| 86 | --- |
| 87 | |
| 88 | ## Implementation Plan |
| 89 | |
| 90 | ### Phase 1: EVM Chain Expansion |
| 91 | |
| 92 | **Goal**: Add Polygon, BSC, Arbitrum, Optimism, Avalanche |
| 93 | |
| 94 | #### 1.1 Update `lib/wdk-integration.cjs` |
| 95 | |
| 96 | **Current**: |
| 97 | ```javascript |
| 98 | async function initializeWDK(walletMnemonic, config = { testnet: true }) { |
| 99 | const wdk = new WDK.default(walletMnemonic) |
| 100 | .registerWallet('bitcoin', WalletManagerBtc.default, { ... }) |
| 101 | .registerWallet('ethereum', WalletManagerEvm.default, { ... }) |
| 102 | return { wdk } |
| 103 | } |
| 104 | ``` |
| 105 | |
| 106 | **New** (with all EVM chains): |
| 107 | ```javascript |
| 108 | // RPC endpoint configuration |
| 109 | const RPC_ENDPOINTS = { |
| 110 | ethereum: { |
| 111 | mainnet: 'https://eth.drpc.org', |
| 112 | testnet: 'https://sepolia.drpc.org' |
| 113 | }, |
| 114 | polygon: { |
| 115 | mainnet: 'https://polygon-rpc.com', |
| 116 | testnet: 'https://rpc-amoy.polygon.technology' // Amoy testnet |
| 117 | }, |
| 118 | bsc: { |
| 119 | mainnet: 'https://bsc-dataseed.binance.org', |
| 120 | testnet: 'https://data-seed-prebsc-1-s1.binance.org:8545' |
| 121 | }, |
| 122 | arbitrum: { |
| 123 | mainnet: 'https://arb1.arbitrum.io/rpc', |
| 124 | testnet: 'https://sepolia-rollup.arbitrum.io/rpc' |
| 125 | }, |
| 126 | optimism: { |
| 127 | mainnet: 'https://mainnet.optimism.io', |
| 128 | testnet: 'https://sepolia.optimism.io' |
| 129 | }, |
| 130 | avalanche: { |
| 131 | mainnet: 'https://avalanche-c-chain-rpc.publicnode.com', |
| 132 | testnet: 'https://api.avax-test.network/ext/bc/C/rpc' |
| 133 | } |
| 134 | } |
| 135 | |
| 136 | async function initializeWDK(walletMnemonic, config = { testnet: true }) { |
| 137 | const network = config.testnet ? 'testnet' : 'mainnet' |
| 138 | |
| 139 | let wdk = new WDK.default(walletMnemonic) |
| 140 | |
| 141 | // Register Bitcoin |
| 142 | wdk = wdk.registerWallet('bitcoin', WalletManagerBtc.default, { |
| 143 | network: config.testnet ? 'testnet' : 'bitcoin', |
| 144 | host: 'electrum.blockstream.info', |
| 145 | port: config.testnet ? 60001 : 50001 |
| 146 | }) |
| 147 | |
| 148 | // Register all EVM chains |
| 149 | for (const [chainName, endpoints] of Object.entries(RPC_ENDPOINTS)) { |
| 150 | wdk = wdk.registerWallet(chainName, WalletManagerEvm.default, { |
| 151 | provider: endpoints[network] |
| 152 | }) |
| 153 | } |
| 154 | |
| 155 | return { wdk } |
| 156 | } |
| 157 | ``` |
| 158 | |
| 159 | #### 1.2 Update `ui/app.js` - SUPPORTED_CHAINS |
| 160 | |
| 161 | **Add back EVM chains** with correct configuration: |
| 162 | ```javascript |
| 163 | const SUPPORTED_CHAINS = { |
| 164 | bitcoin: { ... }, // Keep existing |
| 165 | ethereum: { ... }, // Keep existing |
| 166 | polygon: { |
| 167 | name: 'Polygon', |
| 168 | icon: '🔷', |
| 169 | testnetName: 'Amoy', |
| 170 | mainnetName: 'Mainnet', |
| 171 | formatBalance: (balance) => { |
| 172 | const matic = Number(balance) / 1e18 |
| 173 | return `${matic.toFixed(18).replace(/\.?0+$/, '')} MATIC` |
| 174 | }, |
| 175 | formatSmallUnit: (balance) => { |
| 176 | return `${Number(balance).toLocaleString()} wei` |
| 177 | }, |
| 178 | priceId: 'matic-network', |
| 179 | addressPattern: { |
| 180 | testnet: /^0x[a-fA-F0-9]{40}$/, |
| 181 | mainnet: /^0x[a-fA-F0-9]{40}$/ |
| 182 | }, |
| 183 | feeReserve: 100000 |
| 184 | }, |
| 185 | bsc: { |
| 186 | name: 'BNB Chain', |
| 187 | icon: '🔶', |
| 188 | testnetName: 'Testnet', |
| 189 | mainnetName: 'Mainnet', |
| 190 | formatBalance: (balance) => { |
| 191 | const bnb = Number(balance) / 1e18 |
| 192 | return `${bnb.toFixed(18).replace(/\.?0+$/, '')} BNB` |
| 193 | }, |
| 194 | formatSmallUnit: (balance) => { |
| 195 | return `${Number(balance).toLocaleString()} wei` |
| 196 | }, |
| 197 | priceId: 'binancecoin', |
| 198 | addressPattern: { |
| 199 | testnet: /^0x[a-fA-F0-9]{40}$/, |
| 200 | mainnet: /^0x[a-fA-F0-9]{40}$/ |
| 201 | }, |
| 202 | feeReserve: 100000 |
| 203 | }, |
| 204 | arbitrum: { |
| 205 | name: 'Arbitrum', |
| 206 | icon: '🔵', |
| 207 | testnetName: 'Sepolia', |
| 208 | mainnetName: 'One', |
| 209 | formatBalance: (balance) => { |
| 210 | const eth = Number(balance) / 1e18 |
| 211 | return `${eth.toFixed(18).replace(/\.?0+$/, '')} ETH` |
| 212 | }, |
| 213 | formatSmallUnit: (balance) => { |
| 214 | return `${Number(balance).toLocaleString()} wei` |
| 215 | }, |
| 216 | priceId: 'ethereum', // Uses ETH |
| 217 | addressPattern: { |
| 218 | testnet: /^0x[a-fA-F0-9]{40}$/, |
| 219 | mainnet: /^0x[a-fA-F0-9]{40}$/ |
| 220 | }, |
| 221 | feeReserve: 100000 |
| 222 | }, |
| 223 | optimism: { |
| 224 | name: 'Optimism', |
| 225 | icon: '🔴', |
| 226 | testnetName: 'Sepolia', |
| 227 | mainnetName: 'Mainnet', |
| 228 | formatBalance: (balance) => { |
| 229 | const eth = Number(balance) / 1e18 |
| 230 | return `${eth.toFixed(18).replace(/\.?0+$/, '')} ETH` |
| 231 | }, |
| 232 | formatSmallUnit: (balance) => { |
| 233 | return `${Number(balance).toLocaleString()} wei` |
| 234 | }, |
| 235 | priceId: 'ethereum', // Uses ETH |
| 236 | addressPattern: { |
| 237 | testnet: /^0x[a-fA-F0-9]{40}$/, |
| 238 | mainnet: /^0x[a-fA-F0-9]{40}$/ |
| 239 | }, |
| 240 | feeReserve: 100000 |
| 241 | }, |
| 242 | avalanche: { |
| 243 | name: 'Avalanche C-Chain', |
| 244 | icon: '🔺', |
| 245 | testnetName: 'Fuji', |
| 246 | mainnetName: 'Mainnet', |
| 247 | formatBalance: (balance) => { |
| 248 | const avax = Number(balance) / 1e18 |
| 249 | return `${avax.toFixed(18).replace(/\.?0+$/, '')} AVAX` |
| 250 | }, |
| 251 | formatSmallUnit: (balance) => { |
| 252 | return `${Number(balance).toLocaleString()} nAVAX` |
| 253 | }, |
| 254 | priceId: 'avalanche-2', |
| 255 | addressPattern: { |
| 256 | testnet: /^0x[a-fA-F0-9]{40}$/, |
| 257 | mainnet: /^0x[a-fA-F0-9]{40}$/ |
| 258 | }, |
| 259 | feeReserve: 100000 |
| 260 | } |
| 261 | } |
| 262 | ``` |
| 263 | |
| 264 | #### 1.3 No Server Changes Needed |
| 265 | |
| 266 | **Critical insight**: `wallet-server.cjs` already uses dynamic chain names: |
| 267 | ```javascript |
| 268 | const account = await wdk.getAccount(chainName, 0) |
| 269 | ``` |
| 270 | |
| 271 | As long as the chain is registered in WDK, it works automatically! |
| 272 | |
| 273 | #### 1.4 Testing Checklist |
| 274 | |
| 275 | For EACH new chain: |
| 276 | - [ ] Derive address: `GET /api/address/testnet-polygon` |
| 277 | - [ ] Check balance: `GET /api/balance/polygon` |
| 278 | - [ ] Send transaction: `POST /api/send` (with testnet funds) |
| 279 | - [ ] Transaction history: `GET /api/transactions/polygon` |
| 280 | - [ ] Multi-wallet: Derive multiple addresses, switch between them |
| 281 | - [ ] Contact send: Add contact with Polygon address, send to them |
| 282 | |
| 283 | --- |
| 284 | |
| 285 | ### Phase 2: Non-EVM Chain Support |
| 286 | |
| 287 | **Goal**: Add Solana, Tron, TON (when needed) |
| 288 | |
| 289 | #### 2.1 Install Additional WDK Modules |
| 290 | |
| 291 | ```bash |
| 292 | npm install @tetherto/wdk-wallet-solana |
| 293 | npm install @tetherto/wdk-wallet-tron |
| 294 | npm install @tetherto/wdk-wallet-ton |
| 295 | ``` |
| 296 | |
| 297 | #### 2.2 Update `lib/wdk-integration.cjs` |
| 298 | |
| 299 | ```javascript |
| 300 | import WalletManagerSolana from '@tetherto/wdk-wallet-solana' |
| 301 | import WalletManagerTron from '@tetherto/wdk-wallet-tron' |
| 302 | import WalletManagerTon from '@tetherto/wdk-wallet-ton' |
| 303 | |
| 304 | async function initializeWDK(walletMnemonic, config = { testnet: true }) { |
| 305 | // ... existing EVM registrations ... |
| 306 | |
| 307 | // Register Solana |
| 308 | wdk = wdk.registerWallet('solana', WalletManagerSolana.default, { |
| 309 | rpcUrl: config.testnet |
| 310 | ? 'https://api.devnet.solana.com' |
| 311 | : 'https://api.mainnet-beta.solana.com', |
| 312 | wsUrl: config.testnet |
| 313 | ? 'wss://api.devnet.solana.com' |
| 314 | : 'wss://api.mainnet-beta.solana.com' |
| 315 | }) |
| 316 | |
| 317 | // Register Tron |
| 318 | wdk = wdk.registerWallet('tron', WalletManagerTron.default, { |
| 319 | provider: config.testnet |
| 320 | ? 'https://api.shasta.trongrid.io' |
| 321 | : 'https://api.trongrid.io' |
| 322 | }) |
| 323 | |
| 324 | // Register TON |
| 325 | wdk = wdk.registerWallet('ton', WalletManagerTon.default, { |
| 326 | network: config.testnet ? 'testnet' : 'mainnet' |
| 327 | }) |
| 328 | |
| 329 | return { wdk } |
| 330 | } |
| 331 | ``` |
| 332 | |
| 333 | #### 2.3 Add to SUPPORTED_CHAINS |
| 334 | |
| 335 | ```javascript |
| 336 | solana: { |
| 337 | name: 'Solana', |
| 338 | icon: '◎', |
| 339 | testnetName: 'Devnet', |
| 340 | mainnetName: 'Mainnet', |
| 341 | formatBalance: (balance) => { |
| 342 | const sol = Number(balance) / 1e9 // Lamports to SOL |
| 343 | return `${sol.toFixed(9).replace(/\.?0+$/, '')} SOL` |
| 344 | }, |
| 345 | formatSmallUnit: (balance) => { |
| 346 | return `${Number(balance).toLocaleString()} lamports` |
| 347 | }, |
| 348 | priceId: 'solana', |
| 349 | addressPattern: { |
| 350 | testnet: /^[1-9A-HJ-NP-Za-km-z]{32,44}$/, // Base58 |
| 351 | mainnet: /^[1-9A-HJ-NP-Za-km-z]{32,44}$/ |
| 352 | }, |
| 353 | feeReserve: 5000 // 0.000005 SOL |
| 354 | }, |
| 355 | tron: { |
| 356 | name: 'Tron', |
| 357 | icon: '🔺', |
| 358 | testnetName: 'Shasta', |
| 359 | mainnetName: 'Mainnet', |
| 360 | formatBalance: (balance) => { |
| 361 | const trx = Number(balance) / 1e6 // Sun to TRX |
| 362 | return `${trx.toFixed(6).replace(/\.?0+$/, '')} TRX` |
| 363 | }, |
| 364 | formatSmallUnit: (balance) => { |
| 365 | return `${Number(balance).toLocaleString()} sun` |
| 366 | }, |
| 367 | priceId: 'tron', |
| 368 | addressPattern: { |
| 369 | testnet: /^T[1-9A-HJ-NP-Za-km-z]{33}$/, |
| 370 | mainnet: /^T[1-9A-HJ-NP-Za-km-z]{33}$/ |
| 371 | }, |
| 372 | feeReserve: 1000000 // 1 TRX |
| 373 | } |
| 374 | ``` |
| 375 | |
| 376 | --- |
| 377 | |
| 378 | ### Phase 3: Advanced Features |
| 379 | |
| 380 | #### 3.1 Token Support (ERC-20, TRC-20, SPL) |
| 381 | |
| 382 | **Not implemented yet** - Future enhancement. WDK supports this via: |
| 383 | ```javascript |
| 384 | const usdtBalance = await account.getBalance('0x...usdt-contract-address') |
| 385 | ``` |
| 386 | |
| 387 | #### 3.2 DeFi Protocol Integration |
| 388 | |
| 389 | **Example**: Swap on Uniswap/Velora |
| 390 | ```bash |
| 391 | npm install @tetherto/wdk-protocol-swap-velora-evm |
| 392 | ``` |
| 393 | |
| 394 | ```javascript |
| 395 | wdk.registerProtocol('ethereum', 'swap-velora-evm', VeloraProtocolEvm, { |
| 396 | provider: 'https://eth.drpc.org' |
| 397 | }) |
| 398 | |
| 399 | const protocol = await wdk.getProtocol('ethereum', 'swap-velora-evm', 0) |
| 400 | const quote = await protocol.quoteSwap({ |
| 401 | tokenIn: '0x...', // USDT |
| 402 | tokenOut: '0x...', // USDC |
| 403 | amountIn: 1000000n |
| 404 | }) |
| 405 | ``` |
| 406 | |
| 407 | #### 3.3 Transaction Explorer Links |
| 408 | |
| 409 | Update `showTxDetails()` in `ui/app.js` to add explorer links for all chains: |
| 410 | |
| 411 | ```javascript |
| 412 | const EXPLORER_URLS = { |
| 413 | bitcoin: { |
| 414 | mainnet: 'https://blockstream.info/tx/', |
| 415 | testnet: 'https://blockstream.info/testnet/tx/' |
| 416 | }, |
| 417 | ethereum: { |
| 418 | mainnet: 'https://etherscan.io/tx/', |
| 419 | testnet: 'https://sepolia.etherscan.io/tx/' |
| 420 | }, |
| 421 | polygon: { |
| 422 | mainnet: 'https://polygonscan.com/tx/', |
| 423 | testnet: 'https://amoy.polygonscan.com/tx/' |
| 424 | }, |
| 425 | bsc: { |
| 426 | mainnet: 'https://bscscan.com/tx/', |
| 427 | testnet: 'https://testnet.bscscan.com/tx/' |
| 428 | }, |
| 429 | arbitrum: { |
| 430 | mainnet: 'https://arbiscan.io/tx/', |
| 431 | testnet: 'https://sepolia.arbiscan.io/tx/' |
| 432 | }, |
| 433 | optimism: { |
| 434 | mainnet: 'https://optimistic.etherscan.io/tx/', |
| 435 | testnet: 'https://sepolia-optimism.etherscan.io/tx/' |
| 436 | }, |
| 437 | avalanche: { |
| 438 | mainnet: 'https://snowtrace.io/tx/', |
| 439 | testnet: 'https://testnet.snowtrace.io/tx/' |
| 440 | }, |
| 441 | solana: { |
| 442 | mainnet: 'https://solscan.io/tx/', |
| 443 | testnet: 'https://solscan.io/tx/?cluster=devnet' |
| 444 | }, |
| 445 | tron: { |
| 446 | mainnet: 'https://tronscan.org/#/transaction/', |
| 447 | testnet: 'https://shasta.tronscan.org/#/transaction/' |
| 448 | } |
| 449 | } |
| 450 | ``` |
| 451 | |
| 452 | --- |
| 453 | |
| 454 | ## Migration Considerations |
| 455 | |
| 456 | ### Existing Wallets |
| 457 | |
| 458 | **No migration needed!** Chain names are just strings. Existing data: |
| 459 | - `tx:ethereum:0xabc...` - Still works |
| 460 | - `address:bitcoin:0` - Still works |
| 461 | |
| 462 | New chains just add new keys: |
| 463 | - `tx:polygon:0x123...` |
| 464 | - `address:avalanche:0` |
| 465 | |
| 466 | ### Testing Strategy |
| 467 | |
| 468 | 1. **Testnet First**: Always test on testnets with faucet funds |
| 469 | 2. **One Chain at a Time**: Add and verify each chain individually |
| 470 | 3. **Backwards Compatibility**: Ensure existing Bitcoin/Ethereum wallets still work |
| 471 | 4. **Multi-Device Sync**: Test P2P sync of new chain transactions |
| 472 | |
| 473 | --- |
| 474 | |
| 475 | ## RPC Endpoint Sources |
| 476 | |
| 477 | ### Free Public Endpoints |
| 478 | |
| 479 | **Pros**: No API key needed, quick setup |
| 480 | **Cons**: Rate limited, less reliable |
| 481 | |
| 482 | - Ethereum: `https://eth.drpc.org` |
| 483 | - Polygon: `https://polygon-rpc.com` |
| 484 | - BSC: `https://bsc-dataseed.binance.org` |
| 485 | - Arbitrum: `https://arb1.arbitrum.io/rpc` |
| 486 | - Optimism: `https://mainnet.optimism.io` |
| 487 | - Avalanche: `https://avalanche-c-chain-rpc.publicnode.com` |
| 488 | |
| 489 | ### Paid/API Key Services |
| 490 | |
| 491 | **Pros**: Higher rate limits, better reliability, analytics |
| 492 | **Cons**: Requires API key, potential costs |
| 493 | |
| 494 | - **Alchemy**: Ethereum, Polygon, Arbitrum, Optimism |
| 495 | - **Infura**: Ethereum, Polygon, Arbitrum, Optimism |
| 496 | - **QuickNode**: Most EVM chains + Solana |
| 497 | - **Ankr**: All major chains |
| 498 | |
| 499 | ### Configuration Strategy |
| 500 | |
| 501 | Store RPC endpoints in `config/default.json`: |
| 502 | ```json |
| 503 | { |
| 504 | "rpc": { |
| 505 | "ethereum": { |
| 506 | "mainnet": "https://eth.drpc.org", |
| 507 | "testnet": "https://sepolia.drpc.org" |
| 508 | }, |
| 509 | "polygon": { |
| 510 | "mainnet": "https://polygon-rpc.com", |
| 511 | "testnet": "https://rpc-amoy.polygon.technology" |
| 512 | } |
| 513 | } |
| 514 | } |
| 515 | ``` |
| 516 | |
| 517 | Allow users to override in UI settings. |
| 518 | |
| 519 | --- |
| 520 | |
| 521 | ## Files to Modify |
| 522 | |
| 523 | ### Core Files (Phase 1 - EVM Chains) |
| 524 | |
| 525 | 1. **lib/wdk-integration.cjs** |
| 526 | - Add RPC_ENDPOINTS constant |
| 527 | - Update initializeWDK() to register all EVM chains |
| 528 | - ~50 lines added |
| 529 | |
| 530 | 2. **ui/app.js** |
| 531 | - Add EVM chains back to SUPPORTED_CHAINS |
| 532 | - ~200 lines added (5 chains × 40 lines each) |
| 533 | |
| 534 | 3. **package.json** |
| 535 | - No changes needed (already have wdk-wallet-evm) |
| 536 | |
| 537 | ### Additional Files (Phase 2 - Non-EVM) |
| 538 | |
| 539 | 4. **package.json** |
| 540 | - Add: `@tetherto/wdk-wallet-solana` |
| 541 | - Add: `@tetherto/wdk-wallet-tron` |
| 542 | - Add: `@tetherto/wdk-wallet-ton` |
| 543 | |
| 544 | 5. **lib/wdk-integration.cjs** |
| 545 | - Import new wallet managers |
| 546 | - Register Solana, Tron, TON |
| 547 | |
| 548 | 6. **ui/app.js** |
| 549 | - Add non-EVM chains to SUPPORTED_CHAINS |
| 550 | |
| 551 | --- |
| 552 | |
| 553 | ## Testing Checklist |
| 554 | |
| 555 | ### Per-Chain Testing |
| 556 | |
| 557 | For EACH chain added: |
| 558 | |
| 559 | **Address Derivation**: |
| 560 | - [ ] Derive address 0 |
| 561 | - [ ] Verify address format matches chain (0x... for EVM, T... for Tron, etc.) |
| 562 | - [ ] Derive address 1, verify different from address 0 |
| 563 | |
| 564 | **Balance & Transactions**: |
| 565 | - [ ] Check balance (should be 0 for new address) |
| 566 | - [ ] Get testnet funds from faucet |
| 567 | - [ ] Check balance again (should show faucet amount) |
| 568 | - [ ] Send transaction to another address |
| 569 | - [ ] Verify transaction appears in history |
| 570 | - [ ] Verify balance decreases |
| 571 | |
| 572 | **Multi-Wallet**: |
| 573 | - [ ] Create 3 addresses for chain |
| 574 | - [ ] Give them labels: "Main", "Savings", "Trading" |
| 575 | - [ ] Switch between addresses in dropdown |
| 576 | - [ ] Verify each shows different balance/history |
| 577 | |
| 578 | **Contacts**: |
| 579 | - [ ] Add contact with address for this chain |
| 580 | - [ ] Send to contact |
| 581 | - [ ] Verify contact name appears in transaction history |
| 582 | |
| 583 | **P2P Sync**: |
| 584 | - [ ] Create transaction on device 1 |
| 585 | - [ ] Verify appears on device 2 (if multi-device setup available) |
| 586 | |
| 587 | ### Integration Testing |
| 588 | |
| 589 | **Cross-Chain**: |
| 590 | - [ ] Switch between chains in UI |
| 591 | - [ ] Verify correct addresses shown |
| 592 | - [ ] Verify correct balances shown |
| 593 | - [ ] Verify transactions filtered by chain |
| 594 | |
| 595 | **Network Switching**: |
| 596 | - [ ] Switch from testnet to mainnet |
| 597 | - [ ] Verify RPC endpoints change |
| 598 | - [ ] Verify addresses remain same (same mnemonic) |
| 599 | - [ ] Verify balances show mainnet data |
| 600 | |
| 601 | **Backwards Compatibility**: |
| 602 | - [ ] Open existing wallet |
| 603 | - [ ] Verify Bitcoin transactions still load |
| 604 | - [ ] Verify Ethereum transactions still load |
| 605 | - [ ] Create new Bitcoin transaction |
| 606 | - [ ] Verify old and new data coexist |
| 607 | |
| 608 | --- |
| 609 | |
| 610 | ## Implementation Order |
| 611 | |
| 612 | ### Week 1: EVM Chains (Phase 1) |
| 613 | |
| 614 | **Day 1-2**: Polygon |
| 615 | - Implement and test Polygon fully |
| 616 | - Validate the pattern works |
| 617 | |
| 618 | **Day 3**: BSC |
| 619 | - Apply same pattern |
| 620 | - Should be quick if Polygon worked |
| 621 | |
| 622 | **Day 4**: Arbitrum |
| 623 | - L2 testing (gas differences) |
| 624 | |
| 625 | **Day 5**: Optimism + Avalanche |
| 626 | - Complete EVM expansion |
| 627 | |
| 628 | **Day 6-7**: Testing & Fixes |
| 629 | - Integration testing |
| 630 | - Multi-device sync verification |
| 631 | - Bug fixes |
| 632 | |
| 633 | ### Week 2: Non-EVM Chains (Phase 2 - Optional) |
| 634 | |
| 635 | **Day 1-2**: Solana |
| 636 | - Different address format |
| 637 | - Different transaction model |
| 638 | - Thorough testing |
| 639 | |
| 640 | **Day 3-4**: Tron |
| 641 | - TRX and TRC-20 support |
| 642 | |
| 643 | **Day 5**: TON (if needed) |
| 644 | |
| 645 | **Day 6-7**: Final testing & documentation |
| 646 | |
| 647 | --- |
| 648 | |
| 649 | ## Success Criteria |
| 650 | |
| 651 | **Phase 1 Complete When**: |
| 652 | - [ ] All 6 EVM chains (ETH, Polygon, BSC, Arbitrum, Optimism, Avalanche) working |
| 653 | - [ ] Can derive addresses on all chains |
| 654 | - [ ] Can send/receive on all chains (testnet) |
| 655 | - [ ] Transaction history works per chain |
| 656 | - [ ] Multi-wallet works per chain |
| 657 | - [ ] P2P sync works for all chains |
| 658 | - [ ] UI shows all chains in currency selector |
| 659 | - [ ] No regressions on Bitcoin/Ethereum |
| 660 | |
| 661 | **Phase 2 Complete When**: |
| 662 | - [ ] Solana, Tron, TON (if added) working |
| 663 | - [ ] Same success criteria as Phase 1 |
| 664 | - [ ] Different address formats handled correctly |
| 665 | |
| 666 | --- |
| 667 | |
| 668 | ## Risk Mitigation |
| 669 | |
| 670 | ### High Risk Areas |
| 671 | |
| 672 | 1. **Different Transaction Models** |
| 673 | - Bitcoin: UTXO-based |
| 674 | - Ethereum/EVM: Account-based |
| 675 | - Solana: Account model with rent |
| 676 | - **Mitigation**: WDK abstracts this away |
| 677 | |
| 678 | 2. **RPC Endpoint Reliability** |
| 679 | - Free endpoints can be unreliable |
| 680 | - **Mitigation**: Allow user-configurable endpoints |
| 681 | |
| 682 | 3. **Gas/Fee Differences** |
| 683 | - Each chain has different fee mechanisms |
| 684 | - **Mitigation**: Use WDK's unified fee API |
| 685 | |
| 686 | 4. **Storage Key Conflicts** |
| 687 | - Chain names must be unique |
| 688 | - **Mitigation**: Document chain naming convention |
| 689 | |
| 690 | ### Rollback Strategy |
| 691 | |
| 692 | If a chain fails: |
| 693 | 1. Comment out registration in `lib/wdk-integration.cjs` |
| 694 | 2. Comment out from `SUPPORTED_CHAINS` in `ui/app.js` |
| 695 | 3. Chain becomes invisible but doesn't break existing chains |
| 696 | 4. User data for that chain remains in storage (future recovery) |
| 697 | |
| 698 | --- |
| 699 | |
| 700 | ## Documentation Updates Needed |
| 701 | |
| 702 | After implementation: |
| 703 | |
| 704 | 1. **README.md** |
| 705 | - Update supported chains list |
| 706 | - Add testnet faucet links for all chains |
| 707 | |
| 708 | 2. **docs/API_REFERENCE.md** |
| 709 | - Document chain names |
| 710 | - Document RPC endpoint configuration |
| 711 | |
| 712 | 3. **docs/USER_GUIDE.md** |
| 713 | - How to add custom RPC endpoints |
| 714 | - Chain-specific features (if any) |
| 715 | |
| 716 | 4. **.claude/tmux-registry.json** |
| 717 | - Update features list for new version |
| 718 | |
| 719 | --- |
| 720 | |
| 721 | ## Future Enhancements (Phase 3+) |
| 722 | |
| 723 | ### Token Support |
| 724 | - ERC-20 (Ethereum ecosystem) |
| 725 | - TRC-20 (Tron) |
| 726 | - SPL tokens (Solana) |
| 727 | - Add token balance display |
| 728 | - Add token send/receive |
| 729 | |
| 730 | ### DeFi Integration |
| 731 | - Swap protocols (Uniswap, PancakeSwap, etc.) |
| 732 | - Lending protocols (Aave, Compound) |
| 733 | - Bridge protocols (LayerZero, Wormhole) |
| 734 | |
| 735 | ### Advanced Features |
| 736 | - NFT support |
| 737 | - Staking |
| 738 | - Hardware wallet integration |
| 739 | - WalletConnect integration |
| 740 | |
| 741 | --- |
| 742 | |
| 743 | ## References |
| 744 | |
| 745 | - **Official WDK Docs**: https://docs.wallet.tether.io |
| 746 | - **WDK GitHub**: https://github.com/tetherto/wdk-core |
| 747 | - **Node.js Quickstart**: /tmp/wdk-investigation/wdk-docs/start-building/nodejs-bare-quickstart.md |
| 748 | - **EVM Configuration**: /tmp/wdk-investigation/wdk-docs/sdk/wallet-modules/wallet-evm/configuration.md |
| 749 | |
| 750 | --- |
| 751 | |
| 752 | ## Next Steps |
| 753 | |
| 754 | 1. Review this plan with user |
| 755 | 2. Get approval to proceed with Phase 1 (EVM chains) |
| 756 | 3. Start with Polygon (proof of concept) |
| 757 | 4. Iterate on remaining EVM chains |
| 758 | 5. Deploy to test channel for validation |
| 759 | 6. Deploy to production when stable |