@tetherto/wdk-wallet-tron-gasfree
Note: This package is currently in beta. Please test thoroughly in development environments before using in production.
A simple and secure package to manage BIP-44 wallets for the Tron blockchain with gas-free TRC20 token transfers. This package provides a clean API for creating, managing, and interacting with Tron wallets using BIP-39 seed phrases and Tron-specific derivation paths, with support for gas-free operations via a service provider.
🔍 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
- Gas-Free Transactions: Support for gas-free transactions using TRC20 tokens
- Tron Derivation Paths: Support for BIP-44 standard derivation paths for Tron
- Multi-Account Management: Create and manage multiple accounts from a single seed phrase
- TRC20 Support: Query native TRX and TRC20 token balances using smart contract interactions
- Message Signing: Sign and verify messages using Tron cryptography
⬇️ Installation
To install the @tetherto/wdk-wallet-tron-gasfree package, follow these instructions:
You can install it using npm:
🚀 Quick Start
Importing from @tetherto/wdk-wallet-tron-gasfree
Creating a New Gas-Free Wallet
Managing Multiple Accounts
Checking Balances
Owned Account
For accounts where you have the seed phrase and full access:
Read-Only Account
For addresses where you don't have the seed phrase:
Sending Transactions
⚠️ Important Note: Direct transaction sending using sendTransaction() is not supported in WalletAccountTronGasfree. This is a gas-free implementation that handles transactions through a gas-free provider instead of direct blockchain transactions.
For sending tokens, please use the transfer() method instead.
Token Transfers (Gas-Free)
Transfer TRC20 tokens and estimate fees using WalletAccountTronGasfree. Uses gas-free operations via service provider.
Message Signing and Verification
Sign and verify messages using WalletAccountTronGasfree.
Fee Management
Retrieve current fee rates using WalletManagerTronGasfree.
Memory Management
Clear sensitive data from memory using dispose methods in WalletAccountTronGasfree and WalletManagerTronGasfree.
📚 API Reference
Table of Contents
WalletManagerTronGasfree
The main class for managing Tron wallets with gas-free features.
Extends WalletManager from @tetherto/wdk-wallet.
Constructor
Parameters:
seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytesconfig (object, optional): Configuration object
chainId (string): The blockchain's idprovider (string | TronWeb): Tron RPC endpoint URL or TronWeb instance (e.g., 'https://api.trongrid.io')gasFreeProvider (string): The gasfree provider's urlgasFreeApiKey (string): The gasfree provider's api keygasFreeApiSecret (string): The gasfree provider's api secretserviceProvider (string): The address of the service providerverifyingContract (string): The address of the verifying contracttransferMaxFee (number | bigint, optional): Maximum fee amount for transfer operations (in sun)
Example:
Methods
| Method | Description | Returns |
|---|
getAccount(index) | Returns a wallet account at the specified index | Promise<WalletAccountTronGasfree> |
getAccountByPath(path) | Returns a wallet account at the specified BIP-44 derivation path | Promise<WalletAccountTronGasfree> |
getFeeRates() | Returns current fee rates for transactions | Promise<{normal: bigint, fast: bigint}> |
dispose() | Disposes all wallet accounts, clearing private keys from memory | void |
getAccount(index)
Returns a gas-free Tron wallet account at the specified index using BIP-44 derivation path m/44'/195'.
Parameters:
index (number, optional): The index of the account to get (default: 0)
Returns: Promise<WalletAccountTronGasfree> - The gas-free Tron wallet account
Example:
getAccountByPath(path)
Returns a gas-free Tron wallet account at the specified BIP-44 derivation path.
Parameters:
path (string): The derivation path (e.g., "0'/0/0", "1'/0/5")
Returns: Promise<WalletAccountTronGasfree> - The gas-free Tron wallet account
Example:
getFeeRates()
Returns current fee rates for Tron transactions (used by service provider for gas-free operations).
Returns: Promise<{normal: bigint, fast: bigint}> - Object containing fee rates in sun
normal: Standard fee rate for normal confirmation speedfast: Higher fee rate for faster confirmation
Example:
dispose()
Disposes all gas-free Tron wallet accounts and clears sensitive data from memory.
Returns: void
Example:
WalletAccountTronGasfree
Represents an individual wallet account with gas-free features. Implements IWalletAccount from @tetherto/wdk-wallet.
Constructor
Parameters:
seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytespath (string): BIP-44 derivation path (e.g., "0'/0/0")config (object, optional): Configuration object
chainId (string): The blockchain's idprovider (string | TronWeb): Tron RPC endpoint URL or TronWeb instancegasFreeProvider (string): The gasfree provider's urlgasFreeApiKey (string): The gasfree provider's api keygasFreeApiSecret (string): The gasfree provider's api secretserviceProvider (string): The address of the service providerverifyingContract (string): The address of the verifying contracttransferMaxFee (number | bigint, optional): Maximum fee amount for transfer operations (in sun)
Methods
| Method | Description | Returns |
|---|
getAddress() | Returns the account's address | Promise<string> |
sign(message) | Signs a message using the account's private key | Promise<string> |
verify(message, signature) | Verifies a message signature | Promise<boolean> |
transfer(options, config?) | Transfers TRC20 tokens to another address | Promise<{hash: string, fee: bigint}> |
quoteTransfer(options) | Estimates the fee for a TRC20 transfer | Promise<{fee: bigint}> |
getBalance() | Returns the native TRX balance (in sun) | Promise<bigint> |
getTokenBalance(tokenAddress) | Returns the balance of a specific TRC20 token | Promise<bigint> |
dispose() | Disposes the wallet account, clearing private keys from memory | void |
getAddress()
Returns the account's Tron address.
Returns: Promise<string> - The Tron address
Example:
sign(message)
Signs a message using the account's private key.
Parameters:
message (string): Message to sign
Returns: Promise<string> - Signature as hex string
Example:
verify(message, signature)
Verifies a message signature using the account's public key.
Parameters:
message (string): Original messagesignature (string): Signature as hex string
Returns: Promise<boolean> - True if signature is valid
Example:
transfer(options, config?)
Transfers TRC20 tokens to another address using gas-free operations where the service provider covers transaction fees.
Parameters:
options (object): Transfer options
token (string): TRC20 contract address (e.g., 'T...')recipient (string): Recipient Tron address (e.g., 'T...')amount (number | bigint): Amount in TRC20's base units
config (object, optional): Additional configuration
transferMaxFee (number | bigint, optional): Maximum allowed fee for this transfer
Returns: Promise<{hash: string, fee: bigint}> - Object containing hash and fee (typically 0 or covered by service provider)
Example:
quoteTransfer(options)
Estimates the fee for a TRC20 token transfer (typically covered by service provider in gas-free operations).
Parameters:
options (object): Transfer options
token (string): TRC20 contract addressrecipient (string): Recipient Tron addressamount (number | bigint): Amount in TRC20's base units
Returns: Promise<{fee: bigint, activationFee?: bigint}> - Object containing estimated fee and optional activation fee (paid in input token).
Example:
getBalance()
Returns the account's native TRX balance in sun.
Returns: Promise<bigint> - Balance in sun
Example:
getTokenBalance(tokenAddress)
Returns the balance of a specific TRC20 token.
Parameters:
tokenAddress (string): The TRC20 token contract address
Returns: Promise<bigint> - Token balance in token's smallest unit
Example:
dispose()
Disposes the wallet account, securely erasing the private key from memory.
Returns: void
Example:
Properties
| Property | Type | Description |
|---|
index | number | The derivation path's index of this account |
path | string | The full derivation path of this account |
keyPair | object | The account's key pair (⚠️ Contains sensitive data) |
⚠️ Security Note: The keyPair property contains sensitive cryptographic material. Never log, display, or expose the private key.
WalletAccountReadOnlyTronGasfree
Represents a read-only wallet account with gas-free features.
Constructor
Parameters:
address (string): The account's Tron addressconfig (object, optional): Configuration object
chainId (string): The blockchain's idprovider (string | TronWeb): Tron RPC endpoint URL or TronWeb instancegasFreeProvider (string): The gasfree provider's urlgasFreeApiKey (string): The gasfree provider's api keygasFreeApiSecret (string): The gasfree provider's api secretserviceProvider (string): The address of the service provider
Methods
| Method | Description | Returns |
|---|
getBalance() | Returns the native TRX balance (in sun) | Promise<bigint> |
getTokenBalance(tokenAddress) | Returns the balance of a specific TRC20 token | Promise<bigint> |
quoteTransfer(options) | Estimates the fee for a TRC20 transfer | Promise<{fee: bigint}> |
verify(message, signature) | Verifies a message signature | Promise<boolean> |
getBalance()
Returns the account's native TRX balance in sun.
Returns: Promise<bigint> - Balance in sun
Example:
getTokenBalance(tokenAddress)
Returns the balance of a specific TRC20 token.
Parameters:
tokenAddress (string): The TRC20 token contract address
Returns: Promise<bigint> - Token balance in token's smallest unit
Example:
quoteTransfer(options)
Estimates the fee for a TRC20 token transfer (typically covered by service provider in gas-free operations).
Parameters:
options (object): Transfer options
token (string): TRC20 contract addressrecipient (string): Recipient Tron addressamount (number | bigint): Amount in TRC20's base units
Returns: Promise<{fee: bigint, activationFee?: bigint}> - Object containing estimated fee and optional activation fee (paid in input token).
Example:
verify(message, signature)
Verifies a message signature using the account's public key.
Parameters:
message (string): Original messagesignature (string): Signature as hex string
Returns: Promise<boolean> - True if signature is valid
Example:
🌐 Supported Networks
This package works with the Tron blockchain, including:
- Tron Mainnet
- Tron Shasta Testnet
🔒 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
- Provider Security: Use trusted RPC endpoints and consider running your own node for production
- Transaction Validation: Always validate transaction details before signing
- Memory Cleanup: Use the
dispose() method to clear private keys from memory when done
- Fee Limits: Set
transferMaxFee in config to prevent excessive transaction fees
- Gas-Free Provider: Validate gas-free provider configuration and API credentials
- Service Provider: Ensure service provider address is correct and trusted
- Contract Interactions: Verify contract addresses and token decimals before transfers
🛠️ Development
Building
Testing
📜 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.
