@tetherto/wdk-protocol-bridge-usdt0-evm

Note: This package is currently in beta. Please test thoroughly in development environments before using in production.

A simple and secure package that lets EVM wallet accounts bridge USDT0 tokens across different blockchains. This package provides a clean SDK for moving tokens between EVM-compatible chains using the LayerZero protocol and USDT0 bridge system with support for both standard wallets and ERC-4337 smart accounts.

This module can be managed by the @tetherto/wdk package, which provides a unified interface for managing multiple WDK wallet and protocol modules across different blockchains.

🔍 About WDK

This module is part of the WDK (Wallet Development Kit) project, which empowers developers to build secure, non-custodial wallets with unified blockchain access, stateless architecture, and complete user control.

For detailed documentation about the complete WDK ecosystem, visit docs.wallet.tether.io.

🌟 Features

Cross-Chain Bridge: Move USDT0 and XAUt0 tokens between supported blockchains
LayerZero Integration: Uses LayerZero protocol for secure cross-chain transfers
Multi-Chain Support: Bridge across 25+ networks including Ethereum, Arbitrum, Optimism, Polygon, Berachain, Monad, and more
Non-EVM Destinations: Bridge to Solana, TON, and TRON from any supported EVM source chain
Account Abstraction: Works with both standard EVM wallets and ERC-4337 smart accounts
Fee Management: Built-in fee calculation and bridge cost estimation
Token Support: Supports USDT0 and XAUt0 (Tether Gold) across supported networks
TypeScript Support: Full TypeScript definitions included
Memory Safety: Secure transaction handling with proper error management
Provider Flexibility: Works with JSON-RPC URLs and EIP-1193 browser providers

⬇️ Installation

To install the @tetherto/wdk-protocol-bridge-usdt0-evm package, follow these instructions:

You can install it using npm:

npm install @tetherto/wdk-protocol-bridge-usdt0-evm

🚀 Quick Start

Option 1: Using with WDK Core (Recommended)

import WDK from '@tetherto/wdk'
import Usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm'

// Create WDK instance with EVM wallet support
const wdk = new WDK(seedPhrase)
  .registerWallet('ethereum', WalletManagerEvm, {
    provider: 'https://ethereum-rpc.publicnode.com'
  })
  .registerWallet('arbitrum', WalletManagerEvm, {
    provider: 'https://arb1.arbitrum.io/rpc'
  })
  .registerProtocol('ethereum', 'usdt0', Usdt0ProtocolEvm, {
    bridgeMaxFee: 100000000000000 // 0.0001 ETH in wei
  })

// Get account with bridge protocol
const account = await wdk.getAccount('ethereum', 0)
const usdt0Bridge = account.getBridgeProtocol('usdt0')

// Perform bridge
const result = await usdt0Bridge.bridge({
  targetChain: 'arbitrum',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n // 1 USDT (6 decimals)
})

Option 2: Direct Usage

Creating a New Bridge Service

import Usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm'
import { WalletAccountEvm } from '@tetherto/wdk-wallet-evm'

// Use a BIP-39 seed phrase (replace with your own secure phrase)
const seedPhrase = 'test only example nut use this real life secret phrase must random'

// Create wallet account with provider config
const account = new WalletAccountEvm(seedPhrase, "0'/0/0", {
  provider: 'https://ethereum-rpc.publicnode.com'
})

// Create bridge service with configuration
const bridgeProtocol = new Usdt0ProtocolEvm(account, {
  bridgeMaxFee: 100000000000000n // Optional: Maximum bridge fee in wei
})

// OR for ERC-4337 smart accounts

import { WalletAccountEvmErc4337 } from '@tetherto/wdk-wallet-evm-erc-4337'

// Create ERC-4337 account
const smartAccount = new WalletAccountEvmErc4337(seedPhrase, "0'/0/0", {
  provider: 'https://arb1.arbitrum.io/rpc',
  bundlerUrl: 'YOUR_BUNDLER_URL',
  paymasterUrl: 'YOUR_PAYMASTER_URL'
})

// Create bridge service for smart account
const smartBridgeProtocol = new Usdt0ProtocolEvm(smartAccount, {
  bridgeMaxFee: 100000000000000n
})

Basic Cross-Chain Bridging

// Bridge USDT from Ethereum to Arbitrum
const result = await bridgeProtocol.bridge({
  targetChain: 'arbitrum', // Where to send tokens
  recipient: 'RECIPIENT_ADDRESS', // Who gets the tokens on target chain
  token: 'USDT_TOKEN_ADDRESS', // USDT token address on source chain
  amount: 1000000n // Amount to bridge (1 USDT with 6 decimals)
})

console.log('Bridge transaction hash:', result.hash)
console.log('Total fee:', result.fee, 'wei')
console.log('Bridge fee:', result.bridgeFee, 'wei')

// Bridge from Arbitrum to Ethereum
const reverseResult = await bridgeProtocol.bridge({
  targetChain: 'ethereum',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 5000000n // 5 USDT
})

// Bridge to Polygon
const polygonResult = await bridgeProtocol.bridge({
  targetChain: 'polygon',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 10000000n // 10 USDT
})

Getting Bridge Quotes

// Get bridge cost estimate before executing
const quote = await bridgeProtocol.quoteBridge({
  targetChain: 'arbitrum',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n
})

console.log('Estimated gas fee:', quote.fee, 'wei')
console.log('Estimated bridge fee:', quote.bridgeFee, 'wei')
console.log('Total cost:', Number(quote.fee + quote.bridgeFee) / 1e18, 'ETH')

// Check if bridge is cost-effective
if (quote.fee + quote.bridgeFee > 100000000000000n) { // More than 0.0001 ETH
  console.log('Bridge fees too high, consider waiting for lower gas prices')
} else {
  // Execute the bridge
  const result = await bridgeProtocol.bridge({
    targetChain: 'arbitrum',
    recipient: 'RECIPIENT_ADDRESS',
    token: 'USDT_TOKEN_ADDRESS',
    amount: 1000000n
  })
}

ERC-4337 Smart Account Bridging

// Bridge using ERC-4337 smart account with sponsored transactions
const smartAccountResult = await smartBridgeProtocol.bridge({
  targetChain: 'ethereum',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n
}, {
  paymasterToken: 'USDT', // Use USDT to pay gas fees
  bridgeMaxFee: 100000000000000n // Override max fee
})

console.log('Smart account bridge hash:', smartAccountResult.hash)
console.log('Gas fee paid in USDT:', smartAccountResult.fee)
console.log('Bridge service fee:', smartAccountResult.bridgeFee)

Multi-Token Bridging

// Bridge different USDT0 ecosystem tokens
const tokens = [
  { address: 'USDT_TOKEN_ADDRESS', amount: 1000000n, name: 'USDT' },
  { address: 'XAUT_TOKEN_ADDRESS', amount: 1000000000000000000n, name: 'XAUT' }, // 18 decimals
]

for (const token of tokens) {
  try {
    // Get quote first
    const quote = await bridgeProtocol.quoteBridge({
      targetChain: 'arbitrum',
      recipient: 'RECIPIENT_ADDRESS',
      token: token.address,
      amount: token.amount
    })
    
    console.log(`Bridge ${token.name} quote:`)
    console.log(`  Gas fee: ${quote.fee} wei`)
    console.log(`  Bridge fee: ${quote.bridgeFee} wei`)
    
    // Execute bridge
    const result = await bridgeProtocol.bridge({
      targetChain: 'arbitrum',
      recipient: 'RECIPIENT_ADDRESS',
      token: token.address,
      amount: token.amount
    })
    
    console.log(`${token.name} bridge successful: ${result.hash}`)
    
  } catch (error) {
    console.error(`${token.name} bridge failed:`, error.message)
  }
}

Bridging to Non-EVM Chains

// Bridge USDT0 from Ethereum to Solana
const solanaResult = await bridgeProtocol.bridge({
  targetChain: 'solana',
  recipient: 'HyXJcgYpURfDhgzuyRL7zxP4FhLg7LZQMeDrR4MXZcMN', // Solana base58 address
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n
})

// Bridge USDT0 from Ethereum to TON
const tonResult = await bridgeProtocol.bridge({
  targetChain: 'ton',
  recipient: 'EQAd31gAUhdO0d0NZsNb_cGl_Maa9PSuNhVLE9z8bBSjX6Gq', // TON address
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n
})

// Bridge USDT0 from Ethereum to TRON
const tronResult = await bridgeProtocol.bridge({
  targetChain: 'tron',
  recipient: 'TFG4wBaDQ8sHWWP1ACeSGnoNR6RRzevLPt', // TRON address
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n
})

Custom Contract Address and Destination EID Overrides

// Use a custom OFT contract address (bypasses auto-resolution)
const result = await bridgeProtocol.bridge({
  targetChain: 'arbitrum',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n,
  oftContractAddress: '0xYourCustomOftContractAddress'
})

// Override the destination endpoint ID
const result2 = await bridgeProtocol.bridge({
  targetChain: 'arbitrum',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n,
  dstEid: 30110 // Custom LayerZero endpoint ID
})

// Both overrides work with quoteBridge too
const quote = await bridgeProtocol.quoteBridge({
  targetChain: 'arbitrum',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n,
  oftContractAddress: '0xYourCustomOftContractAddress',
  dstEid: 30110
})

Advanced Bridge Operations

// Compare bridge costs across different target chains
const sourceChain = 'ethereum'
const targetChains = ['arbitrum', 'optimism', 'polygon']
const amount = 1000000n
const token = 'USDT_TOKEN_ADDRESS'
const recipient = 'RECIPIENT_ADDRESS'

const quotes = await Promise.allSettled(
  targetChains.map(async (chain) => {
    const quote = await bridgeProtocol.quoteBridge({
      targetChain: chain,
      recipient,
      token,
      amount
    })
    return { chain, ...quote }
  })
)

quotes.forEach((result, index) => {
  if (result.status === 'fulfilled') {
    const { chain, fee, bridgeFee } = result.value
    console.log(`Bridge to ${chain}:`)
    console.log(`  Total cost: ${Number(fee + bridgeFee) / 1e18} ETH`)
  } else {
    console.error(`Bridge to ${targetChains[index]} failed:`, result.reason.message)
  }
})

📚 API Reference

Class	Description	Methods
Usdt0ProtocolEvm	Main class for bridging USDT0 tokens between EVM chains. Extends `BridgeProtocol` from `@tetherto/wdk-wallet/protocols`.	Constructor, Methods

Usdt0ProtocolEvm

The main class for bridging USDT0 tokens between EVM-compatible blockchains using the LayerZero protocol.
Extends BridgeProtocol from @tetherto/wdk-wallet/protocols.

Constructor

new Usdt0ProtocolEvm(account, config)

Parameters:

account (WalletAccountEvm | WalletAccountEvmErc4337 | WalletAccountReadOnlyEvm | WalletAccountReadOnlyEvmErc4337): The wallet account to use for bridge operations
config (object, optional): Configuration object
- bridgeMaxFee (bigint, optional): Maximum total bridge cost in wei

Example:

const bridgeProtocol = new Usdt0ProtocolEvm(account, {
  bridgeMaxFee: 100000000000000n // Maximum bridge fee in wei (0.0001 ETH)
})

Methods

Method	Description	Returns
`bridge(options, config?)`	Bridges tokens between EVM chains	`Promise<BridgeResult>`
`quoteBridge(options, config?)`	Gets the cost of a bridge operation	`Promise<Omit<BridgeResult, 'hash'>>`

`bridge(options, config?)`

Bridges tokens between blockchains using the USDT0 protocol.

Parameters:

options (BridgeOptions): Bridge operation options
- targetChain (string): Where to send tokens (e.g. 'ethereum', 'arbitrum', 'polygon', 'solana', 'ton', 'tron', etc.)
- recipient (string): Address that will get the bridged tokens (EVM hex address, Solana base58, TON, or TRON address)
- token (string): Token address on source chain
- amount (bigint): Amount to bridge in token base units
- oftContractAddress (string, optional): Custom OFT contract address to use instead of auto-resolving from the source chain
- dstEid (number, optional): Custom LayerZero destination endpoint ID to override the default for the target chain
config (Pick<EvmErc4337WalletConfig, 'paymasterToken'> & Pick<BridgeProtocolConfig, 'bridgeMaxFee'>, optional): Override settings for ERC-4337 accounts
- paymasterToken ({ address: string }, optional): Paymaster token configuration
- bridgeMaxFee (bigint, optional): Override maximum bridge fee

Returns: Promise<BridgeResult> - Bridge operation result

Example:

const result = await bridgeProtocol.bridge({
  targetChain: 'arbitrum',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n // 1 USDT (6 decimals)
})

`quoteBridge(options, config?)`

Gets the cost of a bridge operation without executing it.

Parameters:

options (BridgeOptions): Same as bridge method (including optional oftContractAddress and dstEid overrides)
config (Pick<EvmErc4337WalletConfig, 'paymasterToken'>, optional): Override settings for ERC-4337 accounts

Returns: Promise<Omit<BridgeResult, 'hash'>> - Bridge cost estimate

Example:

const quote = await bridgeProtocol.quoteBridge({
  targetChain: 'arbitrum',
  recipient: 'RECIPIENT_ADDRESS',
  token: 'USDT_TOKEN_ADDRESS',
  amount: 1000000n
})

🌐 Supported Networks

This package supports bridging from EVM source chains to both EVM and non-EVM destination chains.

EVM Source/Destination Chains (USDT0):

Chain	Chain ID	EID
Ethereum	1	30101
Arbitrum	42161	30110
Berachain	80094	30362
Conflux eSpace	1030	30212
Corn	21000000	30331
Flare	14	30295
HyperEVM	999	30367
Ink	57073	30339
Mantle	5000	30181
MegaETH	4326	30398
Monad	143	30390
Morph	2818	30322
Optimism	10	30111
Plasma	9745	30383
Polygon	137	30109
Rootstock	30	30333
Sei	1329	30280
Stable	988	30396
Unichain	130	30320
XLayer	196	30274

Legacy Mesh Chains (USDT0):

Chain	EID
Ethereum	30101
Arbitrum	30110
Celo	30125
Solana	30168
TON	30343
TRON	30420

Non-EVM Destination Chains:

Solana (EID: 30168) - base58 address format
TON (EID: 30343) - TON address format
TRON (EID: 30420) - TRON address format

XAUt0 (Tether Gold) Support:

Chain	EID
Ethereum	30101
Arbitrum	30110
Avalanche	30106
Celo	30125
HyperEVM	30367
Ink	30339
Monad	30390
Plasma	30383
Polygon	30109
Stable	30396

Account Types:

Standard EVM Wallets: @tetherto/wdk-wallet-evm accounts
ERC-4337 Smart Accounts: @tetherto/wdk-wallet-evm-erc-4337 accounts with sponsored transactions
Read-Only Accounts: For querying bridge costs without transaction capabilities

Note: Token support is determined by the contracts deployed on each chain. The protocol checks for oftContract, legacyMeshContract, and xautOftContract to determine available tokens.

🔒 Security Considerations

Seed Phrase Security: Always store your seed phrase securely and never share it
Private Key Management: The package handles private keys internally with memory safety features
RPC Provider Security: Use trusted RPC endpoints and consider running your own node
Transaction Validation: Always validate bridge details before signing
Gas Price Management: Monitor gas prices and set appropriate bridgeMaxFee limits
Quote Validation: Always get quotes before executing bridges to avoid unexpected costs
Token Verification: Verify token contract addresses before bridging
Chain Verification: Ensure target chain supports the token being bridged
Recipient Validation: Double-check recipient addresses for target chains
LayerZero Security: Trust LayerZero protocol for cross-chain message delivery
Smart Contract Risk: Understand the risks of interacting with bridge smart contracts
ERC-4337 Considerations: Be aware of paymaster and bundler dependencies for smart accounts
Slippage Protection: Consider price impact for large bridge amounts
MEV Protection: Be aware of potential MEV risks on public mempools

🛠️ Development

Building

# Install dependencies
npm install

# Build TypeScript definitions
npm run build:types

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🆘 Support

For support, please open an issue on the GitHub repository.

@tetherto/wdk-protocol-bridge-usdt0-evm

1.0.0-beta.3

@subash.77

@tetherto/wdk-protocol-bridge-usdt0-evm

🔍 About WDK

🌟 Features

⬇️ Installation

🚀 Quick Start

Option 1: Using with WDK Core (Recommended)

Option 2: Direct Usage

Creating a New Bridge Service

Basic Cross-Chain Bridging

Getting Bridge Quotes

ERC-4337 Smart Account Bridging

Multi-Token Bridging

Bridging to Non-EVM Chains

Custom Contract Address and Destination EID Overrides

Advanced Bridge Operations

📚 API Reference

Table of Contents

Usdt0ProtocolEvm

Constructor

Methods

`bridge(options, config?)`

`quoteBridge(options, config?)`

🌐 Supported Networks

🔒 Security Considerations

🛠️ Development

Building

Testing

📜 License

🤝 Contributing

🆘 Support