wdk

# Tether WDK Multi-chain wallet SDK. All modules share common interfaces from `@tetherto/wdk-wallet`. ## Documentation **Official Docs**: https://docs.wallet.tether.io ### URL Fetching Workflow When working with WDK tasks, follow this workflow to access documentation: Identify relevant URLs - Based on the task, determine which module documentation pages are needed (see Module Documentation Links below) Attempt to fetch - Try web_fetch on the URL directly If fetch fails - Search for the exact URL: web_search("https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage") This makes the URL appear in search results, which unlocks fetching. Fetch after search - Now web_fetch will work on that URL Example workflow: Task: Build a Spark wallet app 1. Relevant URLs identified: - https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage - https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/configuration 2. web_fetch("https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage") → If permission error, proceed to step 3 3. web_search("https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage") → URL now appears in results 4. web_fetch("https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage") → Success - full page content retrieved For each module, documentation is organized into subpages: /usage - Example usage and patterns /configuration - Configuration options and settings /api-reference - Complete API documentation ## Architecture ``` @tetherto/wdk-core # Orchestrator - registers wallets + protocols ├── @tetherto/wdk-wallet # Base classes (WalletManager, IWalletAccount) │ ├── wdk-wallet-btc # Bitcoin (BIP-84, SegWit) │ ├── wdk-wallet-evm # Ethereum & EVM chains │ ├── wdk-wallet-evm-erc-4337 # EVM with Account Abstraction │ ├── wdk-wallet-solana # Solana │ ├── wdk-wallet-spark # Spark/Lightning │ ├── wdk-wallet-ton # TON │ ├── wdk-wallet-ton-gasless # TON gasless │ ├── wdk-wallet-tron # TRON │ └── wdk-wallet-tron-gasfree # TRON gas-free └── Protocol Modules ├── wdk-protocol-swap-velora-evm # DEX swaps on EVM ├── wdk-protocol-bridge-usdt0-evm # Cross-chain USDT0 bridge └── wdk-protocol-lending-aave-evm # Aave V3 lending ``` ## Quick Start **Docs**: https://docs.wallet.tether.io/sdk/get-started ### With WDK Core (Multi-chain) ```javascript import WDK from '@tetherto/wdk' import WalletManagerEvm from '@tetherto/wdk-wallet-evm' import WalletManagerBtc from '@tetherto/wdk-wallet-btc' const wdk = new WDK(seedPhrase) .registerWallet('ethereum', WalletManagerEvm, { provider: 'https://eth.drpc.org' }) .registerWallet('bitcoin', WalletManagerBtc, { host: 'electrum.blockstream.info', port: 50001 }) const ethAccount = await wdk.getAccount('ethereum', 0) const btcAccount = await wdk.getAccount('bitcoin', 0) ``` ### Single Chain (Direct) ```javascript import WalletManagerBtc from '@tetherto/wdk-wallet-btc' const wallet = new WalletManagerBtc(seedPhrase, { host: 'electrum.blockstream.info', port: 50001, network: 'bitcoin' }) const account = await wallet.getAccount(0) ``` ## Common Interface (All Wallets) All wallet accounts implement `IWalletAccount`: | Method | Returns | Description | |--------|---------|-------------| | `getAddress()` | `Promise<string>` | Account address | | `getBalance()` | `Promise<bigint>` | Native token balance (base units) | | `getTokenBalance(addr)` | `Promise<bigint>` | Token balance | | `sendTransaction({to, value})` | `Promise<{hash, fee}>` | Send native tokens | | `quoteSendTransaction({to, value})` | `Promise<{fee}>` | Estimate tx fee | | `transfer({token, recipient, amount})` | `Promise<{hash, fee}>` | Transfer tokens | | `quoteTransfer(opts)` | `Promise<{fee}>` | Estimate transfer fee | | `sign(message)` | `Promise<string>` | Sign message | | `verify(message, signature)` | `Promise<boolean>` | Verify signature | | `dispose()` | `void` | Clear private keys from memory | Properties: `index`, `path`, `keyPair` (⚠️ sensitive) ## Module Documentation Links ### Core Module | Resource | URL | |----------|-----| | Overview | https://docs.wallet.tether.io/sdk/core-module | | Usage | https://docs.wallet.tether.io/sdk/core-module/usage | | Configuration | https://docs.wallet.tether.io/sdk/core-module/configuration | | API Reference | https://docs.wallet.tether.io/sdk/core-module/api-reference | ### Wallet Modules | Module | Docs | |--------|------| | **Bitcoin** | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-btc | | **EVM** | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-evm | | **EVM ERC-4337** | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-evm-erc-4337 | | **Solana** | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-solana | | **Spark** | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark | | **TON** | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-ton | | **TON Gasless** | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-ton-gasless | | **TRON** | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-tron | | **TRON Gasfree** | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-tron-gasfree | Each wallet module has `/usage`, `/configuration`, and `/api-reference` subpages. ### Protocol Modules | Module | Docs | |--------|------| | **Swap (Velora EVM)** | https://docs.wallet.tether.io/sdk/swap-modules/swap-velora-evm | | **Bridge (USDT0 EVM)** | https://docs.wallet.tether.io/sdk/bridge-modules/bridge-usdt0-evm | | **Lending (Aave EVM)** | https://docs.wallet.tether.io/sdk/lending-modules/lending-aave-evm | Each protocol module has `/usage`, `/configuration`, and `/api-reference` subpages. ### UI Kits & Examples | Resource | URL | |----------|-----| | React Native UI Kit | https://docs.wallet.tether.io/ui-kits/react-native-ui-kit/get-started | | Theming | https://docs.wallet.tether.io/ui-kits/react-native-ui-kit/theming | | UI Kit API Reference | https://docs.wallet.tether.io/ui-kits/react-native-ui-kit/api-reference | | React Native Starter | https://docs.wallet.tether.io/examples-and-starters/react-native-starter | ## Chain-Specific Notes ### Bitcoin - BIP-84 (Native SegWit only, `bc1...` addresses) - Uses Electrum servers, fees in sat/vB - No token support (`getTokenBalance`, `transfer` throw) - `getTransfers({direction, limit, skip})` for history ### EVM - BIP-44 (`m/44'/60'`), EIP-1559 fee model - Supports ERC20 via `transfer()` - Fee rates: `normal` = base×1.1, `fast` = base×2.0 ### ERC-4337 (Account Abstraction) - Gasless via UserOperations + Paymaster - Fees paid in paymaster token (e.g., USDT) - `getPaymasterTokenBalance()` for fee balance - Batch transactions: `sendTransaction([tx1, tx2])` ### Solana - BIP-44 (`m/44'/501'`), Ed25519 - Fees in lamports (1 SOL = 1B lamports) - SPL tokens via `transfer()` ### Spark - Bitcoin L2 with Lightning support - Zero fees for Spark txs - `getSingleUseDepositAddress()`, `claimDeposit(txId)` - `createLightningInvoice({value, memo})`, `payLightningInvoice({invoice, maxFeeSats})` - `withdraw({to, value})` for L1 withdrawal ### TON - BIP-44 (`m/44'/607'`), Ed25519 - Fees in nanotons (1 TON = 1B nanotons) - Jettons via `transfer()` ### TRON - BIP-44 (`m/44'/195'`), secp256k1 - Fees in sun (1 TRX = 1M sun) - TRC20 via `transfer()` - Energy + bandwidth costs ### Gasless Variants - **TON Gasless**: Requires `tonApiClient`, `paymasterToken` config - **TRON Gasfree**: Requires `gasFreeProvider`, `gasFreeApiKey`, `serviceProvider`, `verifyingContract` - Both: `sendTransaction()` not supported, use `transfer()` only ## Protocol Quick Reference ### Swap (DEX) ```javascript // EVM (Velora) const velora = new VeloraProtocolEvm(evmAccount, { swapMaxFee: 200000000000000n }) await velora.swap({ tokenIn: '0x...', tokenOut: '0x...', tokenInAmount: 1000000n }) ``` ### Bridge ```javascript const bridge = new Usdt0ProtocolEvm(evmAccount, { bridgeMaxFee: 1000000000000000n }) await bridge.bridge({ targetChain: 'arbitrum', recipient: '0x...', token: '0x...', // USDT0 amount: 1000000n }) ``` ### Lending (Aave) ```javascript const aave = new AaveProtocolEvm(evmAccount) await aave.supply({ token: '0x...', amount: 1000000n }) await aave.borrow({ token: '0x...', amount: 500000n }) await aave.repay({ token: '0x...', amount: 500000n }) await aave.withdraw({ token: '0x...', amount: 1000000n }) const data = await aave.getAccountData() // healthFactor, ltv, etc. ``` ## Common Patterns ### Fee Estimation Before Send ```javascript const quote = await account.quoteSendTransaction({ to, value }) if (quote.fee > maxAcceptableFee) throw new Error('Fee too high') const result = await account.sendTransaction({ to, value }) ``` ### Cleanup ```javascript try { // ... wallet operations } finally { account.dispose() wallet.dispose() } ``` ### Read-Only Account ```javascript const readOnly = await account.toReadOnlyAccount() // Can query balances, estimate fees, but cannot sign ``` ## Package Versions **ALWAYS** fetch the latest version from npm before adding any package to package.json: ```bash npm view <package-name> version ``` Example workflow: ```bash # Before writing package.json, check each package you need: npm view @tetherto/wdk-core version npm view @tetherto/wdk-wallet-btc version npm view @tetherto/wdk-wallet-evm version # ... for every @tetherto package you're using ``` Never hardcode or guess versions. Always verify against npm first. ## Browser Compatibility WDK uses `sodium-universal` for secure memory handling which requires Node.js. For browser/React apps: 1. Add node polyfills (vite-plugin-node-polyfills or similar) 2. Create a shim for sodium if `dispose()` errors occur: ```javascript // sodium-shim.js - No-op for browser export function sodium_memzero() {} export default { sodium_memzero } ``` 3. Alias in bundler config: ```javascript resolve: { alias: { 'sodium-universal': './src/sodium-shim.js' } } ```