Error Handling & Best Practices

This guide covers recommended patterns for error handling and security when using the WDK.

Handling Common Errors

When interacting with multiple chains and protocols, various runtime issues may occur.

Missing Registration

The most common error is attempting to access a wallet or protocol that hasn't been registered.

try {
  // This will throw if 'tron' was never registered via .registerWallet()
  const tronAccount = await wdk.getAccount('tron', 0)
} catch (error) {
  console.error('Tron wallet not available:', error.message)
}

Memory Management

For security, clear wallet state from memory when a session is complete. The WDK provides dispose() for this purpose.

Seed Lifecycle

WDK does not own the seed you pass to new WDK(seed). The seed comes from your app, so your app is responsible for storing it, decrypting it, and clearing it when it is no longer needed.

Use this lifecycle for sessions that need explicit cleanup:

1. Decrypt or load the seed into a mutable buffer.
2. Initialize and use WDK.
3. Call dispose() on the WDK instance.
4. Zero the seed buffer when no WDK instance or wallet needs it anymore.

import WDK from '@tetherto/wdk'
import WalletManagerEvm from '@tetherto/wdk-wallet-evm'

type SeedDecrypter = (encryptedSeed: Uint8Array) => Promise<Uint8Array>

async function runWalletSession(
  encryptedSeed: Uint8Array,
  decryptSeedBytes: SeedDecrypter
) {
  let seedBytes: Uint8Array | undefined
  let wdk: WDK | undefined

  try {
    seedBytes = await decryptSeedBytes(encryptedSeed)

    wdk = new WDK(seedBytes)
      .registerWallet('ethereum', WalletManagerEvm, {
        provider: 'https://eth.drpc.org'
      })

    const account = await wdk.getAccount('ethereum', 0)
    const address = await account.getAddress()
    return address
  } finally {
    wdk?.dispose()
    seedBytes?.fill(0)
  }
}

In this example, decryptSeedBytes() represents your app's secure storage or decryption layer. It should return seed bytes as a Uint8Array.

Disposing the Instance

You can dispose every registered wallet using dispose():

function endSession(wdk) {
  // 1. Dispose registered wallets and account private keys
  wdk.dispose()
  
  // 2. Modify app state to reflect logged-out status
  // ...
  
  console.log('Session ended, wallet data cleared.')
}

Disposing Specific Wallets

You can dispose only the wallets you no longer need using dispose():

// Keep the TON wallet registered, but dispose the Ethereum wallet
wdk.dispose(['ethereum'])

Security Best Practices

Environment Variables

Never hardcode API keys or seed phrases in your source code. Use environment variables (e.g., process.env.TON_API_KEY).

Secure Storage

If you persist a session, never store the raw seed phrase in local storage. Use secure operating system storage (like Keychain on macOS or Keystore on Android).