/wdk

Name

wdk

Description

Tether Wallet Development Kit (WDK) for building non-custodial multi-chain wallets. Use when working with @tetherto/wdk-core, wallet modules (wdk-wallet-btc, wdk-wallet-evm, wdk-wallet-evm-erc-4337, wdk-wallet-solana, wdk-wallet-spark, wdk-wallet-ton, wdk-wallet-tron, ton-gasless, tron-gasfree), and protocol modules including swap (wdk-protocol-swap-velora-evm), bridge (wdk-protocol-bridge-usdt0-evm), and lending (wdk-protocol-lending-aave-evm). Covers wallet creation, transactions, token transfers, DEX swaps, cross-chain bridges, and DeFi lending/borrowing.

# 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'
  }
}
```