Tron processes more USDT transfers than any other blockchain. With over $50 billion in daily TRC20-USDT volume, low transaction fees, and a three-second block time, the network has become the backbone of stablecoin payments across emerging markets. If you are building a payment platform, exchange, or any system that needs to programmatically receive and route funds, Tron is a network you cannot ignore.

This tutorial walks you through building a deterministic wallet factory on Tron: a system that pre-computes deposit addresses off-chain using CREATE2, deploys lightweight receiver contracts on demand, and sweeps incoming TRC20 tokens or TRX to one or more treasury wallets. The architecture is the same pattern used in the EVM version of this system, but adapted for the quirks of the Tron Virtual Machine (TVM).

What you will build:

• A WalletFactory contract that deploys deterministic WalletReceiver instances using CREATE2

• A WalletReceiver contract that holds funds and allows authorized sweeps with BPS-based splits

• An off-chain script that pre-computes Tron addresses before deployment

• A sweep script that triggers fund collection via TronWeb

Why deterministic wallets?

In a payment platform, each customer gets a unique deposit address. The naive approach is to deploy a contract for every customer upfront, which wastes energy and TRX. With CREATE2, you compute the address off-chain using a deterministic formula, give it to the customer, and only deploy the contract when funds actually arrive. The address is guaranteed to match because the formula is deterministic: same factory, same salt, same bytecode, same address. Every time.

Prerequisites:

• Solid understanding of Solidity (0.8.x)

• Familiarity with EVM concepts (CREATE2, ABI encoding)

• Node.js 18+ installed

• Basic understanding of the Tron network

Before diving into the code, you need to understand the fundamental differences between Tron and standard EVM chains. Tron runs a modified EVM called the TVM (Tron Virtual Machine), which is mostly compatible with Ethereum but diverges in several critical areas.

The two differences that will affect your code the most are the 0x41 prefix in CREATE2 address computation and the TRC20 transfer() return value. We will cover both in detail.

Every Tron address has an internal hex representation that starts with 0x41. When the TVM computes a CREATE2 address, it uses 0x41 as the prefix byte instead of 0xff as Ethereum does. This single byte difference means that the same factory contract, salt, and bytecode will produce a completely different address on Tron than on an EVM chain. Your off-chain address computation scripts must account for this.

Tron CREATE2 formula:

address = keccak256(0x41 ++ factory_address ++ salt ++ keccak256(init_code))[12:]

EVM CREATE2 formula:

address = keccak256(0xff ++ factory_address ++ salt ++ keccak256(init_code))[12:]

The resulting 20-byte address is then prefixed with 0x41 and encoded in base58check to produce the familiar T... Tron address.

This is the single most important Tron-specific issue you will encounter. On Ethereum and all standard EVM chains, the ERC20 transfer() function returns a bool:

// ERC20 standard
function transfer(address to, uint256 amount) external returns (bool);

On Tron, the native TRC20 tokens (including USDT, the most important one) do not return a bool:

// TRC20 on Tron — no return value
function transfer(address to, uint256 amount) external;

This means that OpenZeppelin's SafeERC20 library, which wraps transfer calls and checks the return value, will revert when used with native Tron TRC20 tokens. The safeTransfer function expects either a true return value or empty return data that it can interpret. Tron's TRC20 tokens return data that does not conform to this expectation, causing the safety check to fail.

The solution is straightforward: define a custom ITRC20 interface that matches Tron's actual behavior.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;


/// @dev Tron-compatible TRC20 interface.
///      transfer does not return a bool — compatibility with native Tron TRC20 tokens.
interface ITRC20 {
    function transfer(address to, uint256 amount) external;
    function balanceOf(address account) external view returns (uint256);
}

This interface declares transfer() as returning void. When you call ITRC20(token).transfer(to, amount), Solidity will not attempt to decode a return value, and the call will succeed as long as the token's internal logic does not revert.

The trade-off is that you lose the ability to check if a transfer succeeded via return value. In practice, this is acceptable because Tron TRC20 tokens revert on failure rather than returning false. The behavior is effectively the same as a checked transfer: if it does not revert, it succeeded.

The system follows a three-contract architecture with off-chain address pre-computation:

                    ┌─────────────────┐
                    │    Backend API   │
                    │  (Node.js)       │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  compute-wallet  │  Off-chain: pre-compute address
                    │  .js             │  using CREATE2 formula with 0x41
                    └────────┬────────┘
                             │
                             │  User sends TRC20/TRX to
                             │  pre-computed T... address
                             │
                    ┌────────▼────────┐
                    │  WalletFactory   │  On-chain: deploys receivers
                    │  (Ownable,       │  via CREATE2, triggers sweeps
                    │   Pausable)      │
                    └────────┬────────┘
                             │
                    CREATE2  │  salt = keccak256(walletId)
                             │
                    ┌────────▼────────┐
                    │  WalletReceiver  │  Minimal contract per user
                    │  (immutable      │  Receives funds, sweeps to
                    │   relayer,       │  1-5 recipients via BPS
                    │   factory,       │
                    │   walletId)      │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Treasury /      │  Final destination(s)
                    │  Recipients      │
                    └─────────────────┘

Flow:

1. Backend calls compute-wallet.js with a walletId (e.g., "user_123") to get a deterministic Tron address

2. Customer is given that T... address to deposit TRC20 tokens or TRX

3. When funds arrive, the backend calls deployAndSweep() on the factory, which deploys the receiver and immediately sweeps funds to the treasury in a single transaction

4. For subsequent deposits to the same address, sweepExisting() is called since the receiver is already deployed

mkdir wallet-factory-tron && cd wallet-factory-tron
npx tronbox init
npm install @openzeppelin/contracts@^5.0.0 dotenv minimist tronweb@^6.2.0
npm install --save-dev tronbox@^4.5.0

Replace the contents of tronbox-config.js with the full configuration:

require('dotenv').config();
module.exports = {
  networks: {
    mainnet: {
      privateKey: process.env.PRIVATE_KEY_MAINNET,
      userFeePercentage: 100,
      feeLimit: 1000 * 1e6,
      fullHost: 'https://api.trongrid.io',
      network_id: '1'
    },
    shasta: {
      privateKey: process.env.PRIVATE_KEY_SHASTA,
      userFeePercentage: 50,
      feeLimit: 1000 * 1e6,
      fullHost: 'https://api.shasta.trongrid.io',
      network_id: '2'
    },
    nile: {
      privateKey: process.env.PRIVATE_KEY_NILE,
      userFeePercentage: 100,
      feeLimit: 1000 * 1e6,
      fullHost: 'https://nile.trongrid.io',
      network_id: '3'
    },
    development: {
      privateKey: '0000000000000000000000000000000000000000000000000000000000000001',
      userFeePercentage: 0,
      feeLimit: 1000 * 1e6,
      fullHost: 'http://127.0.0.1:9090',
      network_id: '9'
    }
  },
  compilers: {
    solc: {
      version: '0.8.25',
      settings: {
        optimizer: {
          enabled: true,
          runs: 200
        },
        evmVersion: 'cancun'
      }
    }
  }
};

Network breakdown:

• mainnet — Tron production network. userFeePercentage: 100 means the caller pays 100% of the energy cost.

• shasta — Public testnet with free test TRX at shasta.tronex.io.

• nile — Another testnet, often more stable. Get test TRX at nileex.io.

• development — Local TronBox docker environment (tronbox/tre image).

Create a .env file at the project root:

# Private keys (without 0x prefix)
PRIVATE_KEY_NILE=your_private_key_here
PRIVATE_KEY_MAINNET=your_mainnet_key_here

# Relayer: the EOA authorized to trigger deploys and sweeps
RELAYER_ADDRESS=TYourRelayerBase58Address

# After deployment, set this:
WALLET_FACTORY_ADDRESS=TYourFactoryBase58Address

# Treasury: where swept funds go
TREASURY_ADDRESS=TYourTreasuryBase58Address

# Default TRC20 token for sweeps (e.g., USDT on Nile)
TRC20_TOKEN_ADDRESS=TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj

# RPC endpoint
FULL_NODE_URL_TRON=https://nile.trongrid.io

{
  "dependencies": {
    "@openzeppelin/contracts": "^5.0.0",
    "dotenv": "^17.3.1",
    "minimist": "^1.2.8",
    "tronweb": "^6.2.0"
  },
  "devDependencies": {
    "tronbox": "^4.5.0"
  }
}

Note that ethers is not listed as a direct dependency but is available transitively through TronBox. The compute-wallet.js script uses it for keccak256 hashing.

The first contract is the simplest but arguably the most important Tron-specific adaptation:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;


/// @dev Tron-compatible TRC20 interface.
///      transfer does not return a bool — compatibility with native Tron TRC20 tokens.
interface ITRC20 {
    function transfer(address to, uint256 amount) external;
    function balanceOf(address account) external view returns (uint256);
}

Why this exists:

On EVM chains, the ERC20 standard defines transfer() as returning bool. OpenZeppelin's SafeERC20 wraps calls to handle tokens that do not follow the standard (the USDT on Ethereum, for example, does not return a value on older versions). On Tron, the situation is different: the standard TRC20 implementation does not return bool on transfer(). This is not a bug in specific tokens; it is how TRC20 works on Tron.

Using OpenZeppelin's IERC20 interface would compile fine, but at runtime the ABI decoder would try to read a bool return value from the call. Since the TRC20 token does not return one, the transaction would revert with a decoding error. By declaring transfer() as external without a return type, Solidity generates a call that ignores the return data entirely.

balanceOf() returns uint256 on both ERC20 and TRC20, so it works identically.

The WalletReceiver is a minimal contract deployed via CREATE2 for each user wallet. It holds funds until the relayer or factory triggers a sweep. All configuration is stored in immutable variables, which are embedded in the contract bytecode at deploy time and cost zero storage reads at runtime.

Immutables over storage. The relayer, factory, and walletId variables are all immutable. They are set once in the constructor and embedded directly into the deployed bytecode. Reading an immutable costs 3 gas (a PUSH instruction) versus 2,100 gas for an SLOAD. Since each WalletReceiver is deployed per user, minimizing storage reads directly reduces energy costs across thousands of wallets.

ITRC20 instead of SafeERC20. As explained in the ITRC20 section, we call _token.transfer() directly without checking a return value. The comment in the code makes this explicit: native Tron TRC20 tokens do not return a bool.

BPS-based distribution. Recipients are specified as (address wallet, uint256 bps) pairs where bps stands for basis points. 10,000 BPS = 100%. The contract enforces that all BPS values sum to exactly 10,000, preventing partial distributions. The last recipient receives balance - distributed instead of a BPS calculation to avoid dust from rounding.

Dual authorization. The onlyAuthorized modifier allows both the relayer (direct EOA calls) and the factory (calls via deployAndSweep) to trigger sweeps. This dual-path design enables both atomic deploy-and-sweep flows and standalone sweeps of already-deployed receivers.

ReentrancyGuard. Both sweep() and sweepNative() are protected by OpenZeppelin's nonReentrant modifier. This is especially important for sweepNative(), which uses low-level .call{value}() to send TRX and could be vulnerable to reentrancy if a recipient is a malicious contract.

MAX_RECIPIENTS = 5. This bounds the loop iterations to prevent unbounded energy consumption. In practice, most sweeps go to a single treasury address (1 recipient, 10,000 BPS).

The WalletFactory is the central orchestrator. It deploys WalletReceiver instances via CREATE2, manages the relayer address, and provides atomic deploy-and-sweep operations.

Ownable + Pausable (not Ownable2Step). On EVM chains, we use Ownable2Step for safer ownership transfers. On Tron, Ownable2Step adds an extra transaction that consumes energy and bandwidth for the acceptance step. Since Tron transactions cost real TRX (energy is not free unless you stake), the simpler Ownable is preferred. The owner can still be transferred, but without the two-step confirmation. For production deployments where the owner is a multisig, this trade-off is acceptable.

computeWalletAddress(). This is the on-chain version of the address pre-computation. It takes a walletId (bytes32), computes the salt as keccak256(abi.encodePacked(walletId)), constructs the full init code (creation bytecode + constructor args), and applies the Tron CREATE2 formula with the 0x41 prefix. This function is view and costs no energy to call.

deployWallet(). Standalone deployment without sweeping. Uses Solidity's native new WalletReceiver{salt: salt}(...) syntax, which maps to the CREATE2 opcode. The deployed address is recorded in isDeployedReceiver and the WalletDeployed event is emitted with the hardcoded chain ID 728126428 (Tron mainnet). This chain ID is hardcoded rather than using block.chainid because TronBox environments may report different chain IDs during testing.

deployAndSweep(). The atomic operation: deploy a receiver and immediately sweep its funds in a single transaction. This is the primary function used in production. The flow is:

1. Deploy the WalletReceiver with CREATE2

2. Register it in isDeployedReceiver

3. Check if the receiver has a balance of the specified token

4. If yes, call sweep() or sweepNative() on the receiver

If token is address(0), it sweeps native TRX. Otherwise, it uses ITRC20 to check the TRC20 balance and sweep tokens. Note the use of ITRC20 instead of IERC20 in the balance check.

sweepExisting(). For receivers that are already deployed (second deposit and beyond). Validates the receiver address against isDeployedReceiver to prevent calling arbitrary contracts.

emergencySweep() and emergencySweepNative(). Owner-only functions for recovering funds in case the relayer key is compromised or lost. They bypass the relayer check and sweep 100% of funds to a single destination (10,000 BPS to one address). emergencySweep handles TRC20 tokens and explicitly rejects address(0) as the token, while emergencySweepNative handles TRX.

The CREATE2 address computation is the core of the deterministic wallet pattern. Understanding exactly how it works on Tron is critical for getting the off-chain and on-chain addresses to match.

On Ethereum and all EVM-compatible chains, CREATE2 computes the address as:

address = keccak256(0xff ++ deployer ++ salt ++ keccak256(init_code))[12:]

The 0xff prefix byte prevents collisions with the standard CREATE opcode (which uses the deployer's nonce). The result is the last 20 bytes of the keccak256 hash.

Tron replaces 0xff with 0x41:

address = keccak256(0x41 ++ deployer ++ salt ++ keccak256(init_code))[12:]

Why 0x41? Because 0x41 is the Tron address prefix byte. All Tron addresses in their hex representation start with 41. When you see a T... address, it is a base58check encoding of 41 + 20 bytes. The TVM uses this same prefix in the CREATE2 preimage to keep the address derivation consistent with Tron's address space.

Here is how the computeWalletAddress function works internally:

1. walletId        = bytes32("user_123" padded with zeros)
2. salt            = keccak256(walletId)
3. creationCode    = WalletReceiver's compiled bytecode
4. constructorArgs = abi.encode(relayer, factory, walletId)
5. initCode        = creationCode ++ constructorArgs
6. initCodeHash    = keccak256(initCode)

7. preimage = [ 0x41 ]                    // 1 byte  — Tron prefix
              ++ [ factory address ]       // 20 bytes
              ++ [ salt ]                  // 32 bytes
              ++ [ initCodeHash ]          // 32 bytes
                                           // Total: 85 bytes

8. rawHash  = keccak256(preimage)          // 32 bytes
9. address  = rawHash[12:]                 // last 20 bytes
10. tronAddr = base58check("41" ++ hex(address))  // T... format

The important detail is that the initCode includes the constructor arguments appended to the creation bytecode. If any constructor argument changes (different relayer, different factory address, different walletId), the init code hash changes, and therefore the resulting address changes. This is what makes each walletId produce a unique, deterministic address.

The migration script handles deploying the WalletFactory and converting the resulting hex address to Tron's base58check format.

require('dotenv').config();
const WalletFactory = artifacts.require("WalletFactory");
const crypto = require('crypto');

// Converts a hex Tron address (41...) to base58check format (T...)
function hexToBase58(hexAddr) {
    const BASE58_CHARS = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
    const payload = Buffer.from(hexAddr, 'hex');
    const h1 = crypto.createHash('sha256').update(payload).digest();
    const h2 = crypto.createHash('sha256').update(h1).digest();
    const checksum = h2.slice(0, 4);
    const full = Buffer.concat([payload, checksum]);

    let num = BigInt('0x' + full.toString('hex'));
    let result = '';
    const base = BigInt(58);
    while (num > 0n) {
        result = BASE58_CHARS[Number(num % base)] + result;
        num = num / base;
    }
    for (const byte of full) {
        if (byte !== 0) break;
        result = '1' + result;
    }
    return result;
}

module.exports = async function (deployer, network) {
    const relayer = process.env.RELAYER_ADDRESS;

    if (!relayer) {
        throw new Error("RELAYER_ADDRESS is not defined in .env");
    }

    console.log(">> Deploying WalletFactory with Relayer:", relayer);

    await deployer.deploy(WalletFactory, relayer);

    const instance = await WalletFactory.deployed();
    const hexAddress = instance.address;                 // 41...
    const base58Address = hexToBase58(hexAddress);       // T...

    console.log("\n╔══════════════════════════════════════════════════════╗");
    console.log("║         WalletFactory — Deploy successful            ║");
    console.log("╠══════════════════════════════════════════════════════╣");
    console.log("║ Network  :", network.padEnd(43), "║");
    console.log("║ Hex      :", hexAddress.padEnd(43), "║");
    console.log("║ Tron     :", base58Address.padEnd(43), "║");
    console.log("║ Relayer  :", relayer.padEnd(43), "║");
    console.log("╚══════════════════════════════════════════════════════╝\n");
    console.log(">> Update WALLET_FACTORY_ADDRESS in .env with:", base58Address);
};

TronBox returns contract addresses in hex format (41...). To get the human-readable T... address, you need to:

1. Take the 21-byte hex payload (41 prefix + 20 address bytes)

2. Double SHA-256 hash it: sha256(sha256(payload))

3. Take the first 4 bytes as a checksum

4. Append the checksum to the payload (25 bytes total)

5. Encode the 25 bytes in base58

This is the same encoding Bitcoin uses for addresses (base58check), just with a different version byte (0x41 for Tron instead of 0x00 for Bitcoin mainnet).

# Compile contracts
npx tronbox compile

# Deploy to Nile testnet
npx tronbox migrate --network nile

# Deploy to mainnet
npx tronbox migrate --network mainnet

After deployment, copy the Tron address from the output and set it as WALLET_FACTORY_ADDRESS in your .env file.

The compute-wallet.js script reproduces the CREATE2 formula entirely off-chain. This is the script your backend calls to generate deposit addresses for customers without making any on-chain transactions.

Step 1: Load the compiled bytecode. The script reads build/contracts/WalletReceiver.json, which TronBox generates during compilation. The bytecode field contains the creation bytecode (the code that runs during deployment and returns the runtime bytecode).

Step 2: Convert addresses. Tron addresses come in base58 format (T...). The script converts them to raw 20-byte buffers using addressToBytes20(). This function handles multiple input formats: base58 (T...), hex with Tron prefix (41...), and hex with 0x prefix.

Step 3: Encode walletId. If the walletId is a plain string like "user_123", it is converted to UTF-8 bytes and right-padded with zeros to fill 32 bytes. If it is already a 0x-prefixed hex string of 66 characters (32 bytes), it is used directly.

Step 4: ABI-encode constructor arguments. The constructor takes (address _relayer, address _factory, bytes32 _walletId). ABI encoding packs each argument into a 32-byte word: addresses are left-padded with 12 zero bytes, and bytes32 is used as-is.

Step 5: Build init code. The init code is the creation bytecode concatenated with the ABI-encoded constructor arguments. This is what the CREATE2 opcode hashes.

Step 6: Compute salt. The salt is keccak256(walletId), matching what the Solidity contract does with keccak256(abi.encodePacked(walletId)).

Step 7: Apply the Tron CREATE2 formula. Concatenate [0x41, factory(20), salt(32), keccak256(initCode)(32)] and hash with keccak256. Take the last 20 bytes as the raw address.

Step 8: Convert to Tron format. Prepend 41 to the 20-byte hex address and encode in base58check to get the final T... address.

# Pre-compute address for walletId "user_123"
node scripts/compute-wallet.js user_123

# Pre-compute address for a hex bytes32 walletId
node scripts/compute-wallet.js 0x757365725f31323300000000000000000000000000000000000000000000000000

The output will show the Tron address that will be generated when deployWallet() or deployAndSweep() is called with the same walletId on the deployed factory.

You can also call the factory's computeWalletAddress function directly via TronBox:

// compute.js — TronBox exec script
require('dotenv').config();
const WalletFactory = artifacts.require("WalletFactory");

module.exports = async function (callback) {
    try {
        const factory = await WalletFactory.deployed();
        const walletId = web3.utils.fromAscii("user_123").padEnd(66, '0');

        console.log("Computing address for walletId:", walletId);

        const predictedAddr = await factory.computeWalletAddress(walletId);

        console.log("-----------------------------------------");
        console.log("Address computed by contract:", predictedAddr);
        console.log("-----------------------------------------");

        callback();
    } catch (e) {
        console.error(e);
        callback(e);
    }
};

Run it with:

npx tronbox exec compute.js --network nile

Both methods should produce the same address. If they do not match, check that your .env has the correct factory and relayer addresses, and that the compiled bytecode has not changed since deployment.

The sweep.js script handles the complete flow of checking balances, estimating energy costs, and executing the sweep transaction. It uses TronWeb's triggerSmartContract API instead of the higher-level contract abstractions, which gives more control over parameter encoding (important for struct arrays in TronWeb v6).

triggerSmartContract — Builds and sends a state-changing transaction. This is the equivalent of calling a contract function that modifies state. The feeLimit parameter (set to 400 TRX = 400,000,000 SUN) caps the maximum energy cost. If the transaction exceeds this limit, it reverts.

triggerConstantContract — Makes a read-only call (equivalent to eth_call). Used to call computeWalletAddress() and isDeployedReceiver() without spending energy or creating a transaction. The result comes back in constant_result[0] as a hex string.

Struct encoding. TronWeb v6 expects struct arrays as nested arrays: [[address, uint256], [address, uint256]]. Each inner array represents one Recipient struct. The type is specified as (address,uint256)[].

# Sweep TRC20 tokens (uses TRC20_TOKEN_ADDRESS from .env)
node scripts/sweep.js --wallet user_123 --token trc20

# Sweep native TRX
node scripts/sweep.js --wallet user_123 --token native

# Sweep a specific TRC20 token to a custom address
node scripts/sweep.js --wallet user_123 --token TTokenBase58Address --to TCustomDestination

The script automatically determines whether to call deployAndSweep (if the receiver is not yet deployed) or sweepExisting (if it is already deployed). After the transaction confirms, it reports the actual energy, bandwidth, and TRX consumed.

Tron's resource model is fundamentally different from Ethereum's gas model. Understanding it is essential for keeping costs low in production.

Tron has two computational resources:

Energy is consumed by smart contract execution (analogous to Ethereum gas for computation). Every opcode costs a specific amount of energy. You can obtain energy in two ways:

• Staking TRX — Lock TRX to receive a daily energy allowance proportional to your stake. This is free recurring energy.

• Burning TRX — If you do not have enough staked energy, TRX is burned at the current rate (approximately 420 SUN per energy unit, though this fluctuates).

Bandwidth is consumed by the transaction data size (the raw bytes of the transaction). You get 600 free bandwidth points per day per account. Beyond that, TRX is burned. A typical contract call uses 300-500 bandwidth points.

These are approximate values. Actual costs depend on network conditions and the specific token being swept.

1. Stake TRX for energy. For a payment platform processing hundreds of sweeps per day, staking is essential. The break-even point is typically around 10-20 transactions per day. Beyond that, staking saves more TRX than it locks.

2. Batch when possible. The deployAndSweep function is cheaper than separate deployWallet + sweepExisting calls because it avoids paying bandwidth twice.

3. Use immutables. The WalletReceiver contract uses immutable variables instead of storage. Each SLOAD costs 2,100 energy; an immutable read costs 3. With three immutables per receiver, that saves 6,291 energy per sweep.

4. Set appropriate fee limits. The feeLimit caps the maximum TRX burned. Set it high enough to cover your worst-case scenario but not so high that a bug could drain your account. 400 TRX (400,000,000 SUN) is a reasonable limit for deploy+sweep operations.

5. Monitor the energy price. The burn rate (SUN per energy unit) changes based on network utilization. During high-usage periods, consider delaying non-urgent sweeps.

6. Use triggerConstantContract for estimation. Before executing a sweep, call the function as a constant (read-only) to estimate energy consumption. This is free and helps you predict costs.

The sweep script already includes energy estimation. Here is the relevant pattern:

const estimation = await tronWeb.transactionBuilder.triggerConstantContract(
    FACTORY_ADDRESS,
    'deployAndSweep(bytes32,address,(address,uint256)[])',
    {},
    params
);

if (estimation.result && estimation.result.result) {
    const energyUsed = estimation.energy_used || 0;
    const estTrx = (energyUsed * 420) / 1_000_000; // Approximate
    console.log(`Estimated energy: ${energyUsed}`);
    console.log(`Estimated cost: ~${estTrx.toFixed(2)} TRX`);
}

The energy_used field from triggerConstantContract gives you a simulation of the energy that would be consumed. Multiply by the current burn rate (check tronscan.org for the latest rate) to estimate the TRX cost.

The security model mirrors the EVM version with Tron-specific adaptations.

• Owner (deployer) — Can pause the factory, change the relayer, and trigger emergency sweeps. Should be a multisig in production.

• Relayer — An EOA authorized to deploy wallets and trigger sweeps. This is the hot key used by the backend. If compromised, the attacker can only sweep funds to the pre-specified recipients (though they could front-run legitimate sweeps).

• WalletReceiver — Accepts calls from both the relayer and the factory. This dual authorization enables atomic deploy+sweep.

Since we do not check transfer() return values, a malicious TRC20 token could silently fail transfers. In practice, the factory should maintain an allow-list of supported tokens (USDT, USDC, etc.) and reject unknown tokens at the backend level, before the on-chain call.

An attacker could send very small amounts of many different TRC20 tokens to a receiver, forcing the relayer to spend energy sweeping dust. Mitigation: the backend should check balances before triggering sweeps and only sweep above a minimum threshold.

The nonReentrant modifier on sweep() and sweepNative() prevents reentrancy attacks. This is critical for sweepNative(), which uses .call{value}() to send TRX. A malicious recipient contract could attempt to re-enter the sweep function during the TRX transfer. The ReentrancyGuard prevents this.

Since the CREATE2 address is deterministic and publicly computable, an attacker who knows the walletId could compute the address and send funds to it before the legitimate user. This is not an issue for the wallet factory pattern because:

1. Funds sent to the pre-computed address are safe: only the relayer or factory can deploy the receiver and sweep.

2. The walletId should be unpredictable (use UUIDs or database IDs, not sequential integers).

• Deploy with a multisig as the owner

• Use a dedicated relayer EOA (not the owner)

• Maintain a backend allow-list of supported TRC20 tokens

• Set minimum sweep thresholds to avoid dust griefing

• Stake TRX for energy on the relayer account

• Monitor the relayer's TRX balance for energy burns

• Set up alerts for EmergencySweep events

• Test the full flow on Nile testnet before mainnet deployment

• Verify off-chain address computation matches on-chain for multiple walletIds

• Implement rate limiting on the backend to prevent relayer key abuse

You have built a complete deterministic wallet factory for the Tron network. The system pre-computes deposit addresses off-chain, deploys lightweight receiver contracts on demand via CREATE2, and sweeps funds to configurable destinations using BPS-based splits.

What makes the Tron version different from EVM:

• 0x41 prefix in CREATE2 instead of 0xff changes address computation entirely

• ITRC20 interface instead of IERC20/SafeERC20 because TRC20 transfer() does not return a bool

• Energy + bandwidth model instead of gas requires different cost optimization strategies

• Base58check addresses (T...) instead of hex (0x...) require conversion utilities

• Ownable instead of Ownable2Step to save energy on ownership transfers

• TronBox + TronWeb instead of Hardhat + ethers.js for development and interaction

• Chain ID 728126428 hardcoded instead of using block.chainid

The architecture is production-ready for USDT payment platforms, exchange deposit systems, or any application that needs to programmatically receive and route TRC20 tokens on Tron. The same walletId-based addressing scheme allows your backend to manage deposits across EVM chains and Tron with a unified interface, differing only in the address computation prefix and token interface.

The complete source code is available in the wallet-factory-multichain repository on GitHub.

Built by Beltsys Labs. Licensed under MIT.

Originally published on beltsys.com

Tron processes more USDT transfers than any other blockchain. With over $50 billion in daily TRC20-USDT volume, low transaction fees, and a three-second block time, the network has become the backbone of stablecoin payments across emerging markets. If you are building a payment platform, exchange, or any system that needs to programmatically receive and route funds, Tron is a network you cannot ignore.

This tutorial walks you through building a deterministic wallet factory on Tron: a system that pre-computes deposit addresses off-chain using CREATE2, deploys lightweight receiver contracts on demand, and sweeps incoming TRC20 tokens or TRX to one or more treasury wallets. The architecture is the same pattern used in the EVM version of this system, but adapted for the quirks of the Tron Virtual Machine (TVM).

What you will build:

• A WalletFactory contract that deploys deterministic WalletReceiver instances using CREATE2

• A WalletReceiver contract that holds funds and allows authorized sweeps with BPS-based splits

• An off-chain script that pre-computes Tron addresses before deployment

• A sweep script that triggers fund collection via TronWeb

Why deterministic wallets?

In a payment platform, each customer gets a unique deposit address. The naive approach is to deploy a contract for every customer upfront, which wastes energy and TRX. With CREATE2, you compute the address off-chain using a deterministic formula, give it to the customer, and only deploy the contract when funds actually arrive. The address is guaranteed to match because the formula is deterministic: same factory, same salt, same bytecode, same address. Every time.

Prerequisites:

• Solid understanding of Solidity (0.8.x)

• Familiarity with EVM concepts (CREATE2, ABI encoding)

• Node.js 18+ installed

• Basic understanding of the Tron network

Before diving into the code, you need to understand the fundamental differences between Tron and standard EVM chains. Tron runs a modified EVM called the TVM (Tron Virtual Machine), which is mostly compatible with Ethereum but diverges in several critical areas.

The two differences that will affect your code the most are the 0x41 prefix in CREATE2 address computation and the TRC20 transfer() return value. We will cover both in detail.

Every Tron address has an internal hex representation that starts with 0x41. When the TVM computes a CREATE2 address, it uses 0x41 as the prefix byte instead of 0xff as Ethereum does. This single byte difference means that the same factory contract, salt, and bytecode will produce a completely different address on Tron than on an EVM chain. Your off-chain address computation scripts must account for this.

Tron CREATE2 formula:

address = keccak256(0x41 ++ factory_address ++ salt ++ keccak256(init_code))[12:]

EVM CREATE2 formula:

address = keccak256(0xff ++ factory_address ++ salt ++ keccak256(init_code))[12:]

The resulting 20-byte address is then prefixed with 0x41 and encoded in base58check to produce the familiar T... Tron address.

This is the single most important Tron-specific issue you will encounter. On Ethereum and all standard EVM chains, the ERC20 transfer() function returns a bool:

// ERC20 standard
function transfer(address to, uint256 amount) external returns (bool);

On Tron, the native TRC20 tokens (including USDT, the most important one) do not return a bool:

// TRC20 on Tron — no return value
function transfer(address to, uint256 amount) external;

This means that OpenZeppelin's SafeERC20 library, which wraps transfer calls and checks the return value, will revert when used with native Tron TRC20 tokens. The safeTransfer function expects either a true return value or empty return data that it can interpret. Tron's TRC20 tokens return data that does not conform to this expectation, causing the safety check to fail.

The solution is straightforward: define a custom ITRC20 interface that matches Tron's actual behavior.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;


/// @dev Tron-compatible TRC20 interface.
///      transfer does not return a bool — compatibility with native Tron TRC20 tokens.
interface ITRC20 {
    function transfer(address to, uint256 amount) external;
    function balanceOf(address account) external view returns (uint256);
}

This interface declares transfer() as returning void. When you call ITRC20(token).transfer(to, amount), Solidity will not attempt to decode a return value, and the call will succeed as long as the token's internal logic does not revert.

The trade-off is that you lose the ability to check if a transfer succeeded via return value. In practice, this is acceptable because Tron TRC20 tokens revert on failure rather than returning false. The behavior is effectively the same as a checked transfer: if it does not revert, it succeeded.

The system follows a three-contract architecture with off-chain address pre-computation:

                    ┌─────────────────┐
                    │    Backend API   │
                    │  (Node.js)       │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  compute-wallet  │  Off-chain: pre-compute address
                    │  .js             │  using CREATE2 formula with 0x41
                    └────────┬────────┘
                             │
                             │  User sends TRC20/TRX to
                             │  pre-computed T... address
                             │
                    ┌────────▼────────┐
                    │  WalletFactory   │  On-chain: deploys receivers
                    │  (Ownable,       │  via CREATE2, triggers sweeps
                    │   Pausable)      │
                    └────────┬────────┘
                             │
                    CREATE2  │  salt = keccak256(walletId)
                             │
                    ┌────────▼────────┐
                    │  WalletReceiver  │  Minimal contract per user
                    │  (immutable      │  Receives funds, sweeps to
                    │   relayer,       │  1-5 recipients via BPS
                    │   factory,       │
                    │   walletId)      │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Treasury /      │  Final destination(s)
                    │  Recipients      │
                    └─────────────────┘

Flow:

1. Backend calls compute-wallet.js with a walletId (e.g., "user_123") to get a deterministic Tron address

2. Customer is given that T... address to deposit TRC20 tokens or TRX

3. When funds arrive, the backend calls deployAndSweep() on the factory, which deploys the receiver and immediately sweeps funds to the treasury in a single transaction

4. For subsequent deposits to the same address, sweepExisting() is called since the receiver is already deployed

mkdir wallet-factory-tron && cd wallet-factory-tron
npx tronbox init
npm install @openzeppelin/contracts@^5.0.0 dotenv minimist tronweb@^6.2.0
npm install --save-dev tronbox@^4.5.0

Replace the contents of tronbox-config.js with the full configuration:

require('dotenv').config();
module.exports = {
  networks: {
    mainnet: {
      privateKey: process.env.PRIVATE_KEY_MAINNET,
      userFeePercentage: 100,
      feeLimit: 1000 * 1e6,
      fullHost: 'https://api.trongrid.io',
      network_id: '1'
    },
    shasta: {
      privateKey: process.env.PRIVATE_KEY_SHASTA,
      userFeePercentage: 50,
      feeLimit: 1000 * 1e6,
      fullHost: 'https://api.shasta.trongrid.io',
      network_id: '2'
    },
    nile: {
      privateKey: process.env.PRIVATE_KEY_NILE,
      userFeePercentage: 100,
      feeLimit: 1000 * 1e6,
      fullHost: 'https://nile.trongrid.io',
      network_id: '3'
    },
    development: {
      privateKey: '0000000000000000000000000000000000000000000000000000000000000001',
      userFeePercentage: 0,
      feeLimit: 1000 * 1e6,
      fullHost: 'http://127.0.0.1:9090',
      network_id: '9'
    }
  },
  compilers: {
    solc: {
      version: '0.8.25',
      settings: {
        optimizer: {
          enabled: true,
          runs: 200
        },
        evmVersion: 'cancun'
      }
    }
  }
};

Network breakdown:

• mainnet — Tron production network. userFeePercentage: 100 means the caller pays 100% of the energy cost.

• shasta — Public testnet with free test TRX at shasta.tronex.io.

• nile — Another testnet, often more stable. Get test TRX at nileex.io.

• development — Local TronBox docker environment (tronbox/tre image).

Create a .env file at the project root:

# Private keys (without 0x prefix)
PRIVATE_KEY_NILE=your_private_key_here
PRIVATE_KEY_MAINNET=your_mainnet_key_here

# Relayer: the EOA authorized to trigger deploys and sweeps
RELAYER_ADDRESS=TYourRelayerBase58Address

# After deployment, set this:
WALLET_FACTORY_ADDRESS=TYourFactoryBase58Address

# Treasury: where swept funds go
TREASURY_ADDRESS=TYourTreasuryBase58Address

# Default TRC20 token for sweeps (e.g., USDT on Nile)
TRC20_TOKEN_ADDRESS=TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj

# RPC endpoint
FULL_NODE_URL_TRON=https://nile.trongrid.io

{
  "dependencies": {
    "@openzeppelin/contracts": "^5.0.0",
    "dotenv": "^17.3.1",
    "minimist": "^1.2.8",
    "tronweb": "^6.2.0"
  },
  "devDependencies": {
    "tronbox": "^4.5.0"
  }
}

Note that ethers is not listed as a direct dependency but is available transitively through TronBox. The compute-wallet.js script uses it for keccak256 hashing.

The first contract is the simplest but arguably the most important Tron-specific adaptation:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.25;


/// @dev Tron-compatible TRC20 interface.
///      transfer does not return a bool — compatibility with native Tron TRC20 tokens.
interface ITRC20 {
    function transfer(address to, uint256 amount) external;
    function balanceOf(address account) external view returns (uint256);
}

Why this exists:

On EVM chains, the ERC20 standard defines transfer() as returning bool. OpenZeppelin's SafeERC20 wraps calls to handle tokens that do not follow the standard (the USDT on Ethereum, for example, does not return a value on older versions). On Tron, the situation is different: the standard TRC20 implementation does not return bool on transfer(). This is not a bug in specific tokens; it is how TRC20 works on Tron.

Using OpenZeppelin's IERC20 interface would compile fine, but at runtime the ABI decoder would try to read a bool return value from the call. Since the TRC20 token does not return one, the transaction would revert with a decoding error. By declaring transfer() as external without a return type, Solidity generates a call that ignores the return data entirely.

balanceOf() returns uint256 on both ERC20 and TRC20, so it works identically.

The WalletReceiver is a minimal contract deployed via CREATE2 for each user wallet. It holds funds until the relayer or factory triggers a sweep. All configuration is stored in immutable variables, which are embedded in the contract bytecode at deploy time and cost zero storage reads at runtime.

Immutables over storage. The relayer, factory, and walletId variables are all immutable. They are set once in the constructor and embedded directly into the deployed bytecode. Reading an immutable costs 3 gas (a PUSH instruction) versus 2,100 gas for an SLOAD. Since each WalletReceiver is deployed per user, minimizing storage reads directly reduces energy costs across thousands of wallets.

ITRC20 instead of SafeERC20. As explained in the ITRC20 section, we call _token.transfer() directly without checking a return value. The comment in the code makes this explicit: native Tron TRC20 tokens do not return a bool.

BPS-based distribution. Recipients are specified as (address wallet, uint256 bps) pairs where bps stands for basis points. 10,000 BPS = 100%. The contract enforces that all BPS values sum to exactly 10,000, preventing partial distributions. The last recipient receives balance - distributed instead of a BPS calculation to avoid dust from rounding.

Dual authorization. The onlyAuthorized modifier allows both the relayer (direct EOA calls) and the factory (calls via deployAndSweep) to trigger sweeps. This dual-path design enables both atomic deploy-and-sweep flows and standalone sweeps of already-deployed receivers.

ReentrancyGuard. Both sweep() and sweepNative() are protected by OpenZeppelin's nonReentrant modifier. This is especially important for sweepNative(), which uses low-level .call{value}() to send TRX and could be vulnerable to reentrancy if a recipient is a malicious contract.

MAX_RECIPIENTS = 5. This bounds the loop iterations to prevent unbounded energy consumption. In practice, most sweeps go to a single treasury address (1 recipient, 10,000 BPS).

The WalletFactory is the central orchestrator. It deploys WalletReceiver instances via CREATE2, manages the relayer address, and provides atomic deploy-and-sweep operations.

Ownable + Pausable (not Ownable2Step). On EVM chains, we use Ownable2Step for safer ownership transfers. On Tron, Ownable2Step adds an extra transaction that consumes energy and bandwidth for the acceptance step. Since Tron transactions cost real TRX (energy is not free unless you stake), the simpler Ownable is preferred. The owner can still be transferred, but without the two-step confirmation. For production deployments where the owner is a multisig, this trade-off is acceptable.

computeWalletAddress(). This is the on-chain version of the address pre-computation. It takes a walletId (bytes32), computes the salt as keccak256(abi.encodePacked(walletId)), constructs the full init code (creation bytecode + constructor args), and applies the Tron CREATE2 formula with the 0x41 prefix. This function is view and costs no energy to call.

deployWallet(). Standalone deployment without sweeping. Uses Solidity's native new WalletReceiver{salt: salt}(...) syntax, which maps to the CREATE2 opcode. The deployed address is recorded in isDeployedReceiver and the WalletDeployed event is emitted with the hardcoded chain ID 728126428 (Tron mainnet). This chain ID is hardcoded rather than using block.chainid because TronBox environments may report different chain IDs during testing.

deployAndSweep(). The atomic operation: deploy a receiver and immediately sweep its funds in a single transaction. This is the primary function used in production. The flow is:

1. Deploy the WalletReceiver with CREATE2

2. Register it in isDeployedReceiver

3. Check if the receiver has a balance of the specified token

4. If yes, call sweep() or sweepNative() on the receiver

If token is address(0), it sweeps native TRX. Otherwise, it uses ITRC20 to check the TRC20 balance and sweep tokens. Note the use of ITRC20 instead of IERC20 in the balance check.

sweepExisting(). For receivers that are already deployed (second deposit and beyond). Validates the receiver address against isDeployedReceiver to prevent calling arbitrary contracts.

emergencySweep() and emergencySweepNative(). Owner-only functions for recovering funds in case the relayer key is compromised or lost. They bypass the relayer check and sweep 100% of funds to a single destination (10,000 BPS to one address). emergencySweep handles TRC20 tokens and explicitly rejects address(0) as the token, while emergencySweepNative handles TRX.

The CREATE2 address computation is the core of the deterministic wallet pattern. Understanding exactly how it works on Tron is critical for getting the off-chain and on-chain addresses to match.

On Ethereum and all EVM-compatible chains, CREATE2 computes the address as:

address = keccak256(0xff ++ deployer ++ salt ++ keccak256(init_code))[12:]

The 0xff prefix byte prevents collisions with the standard CREATE opcode (which uses the deployer's nonce). The result is the last 20 bytes of the keccak256 hash.

Tron replaces 0xff with 0x41:

address = keccak256(0x41 ++ deployer ++ salt ++ keccak256(init_code))[12:]

Why 0x41? Because 0x41 is the Tron address prefix byte. All Tron addresses in their hex representation start with 41. When you see a T... address, it is a base58check encoding of 41 + 20 bytes. The TVM uses this same prefix in the CREATE2 preimage to keep the address derivation consistent with Tron's address space.

Here is how the computeWalletAddress function works internally:

1. walletId        = bytes32("user_123" padded with zeros)
2. salt            = keccak256(walletId)
3. creationCode    = WalletReceiver's compiled bytecode
4. constructorArgs = abi.encode(relayer, factory, walletId)
5. initCode        = creationCode ++ constructorArgs
6. initCodeHash    = keccak256(initCode)

7. preimage = [ 0x41 ]                    // 1 byte  — Tron prefix
              ++ [ factory address ]       // 20 bytes
              ++ [ salt ]                  // 32 bytes
              ++ [ initCodeHash ]          // 32 bytes
                                           // Total: 85 bytes

8. rawHash  = keccak256(preimage)          // 32 bytes
9. address  = rawHash[12:]                 // last 20 bytes
10. tronAddr = base58check("41" ++ hex(address))  // T... format

The important detail is that the initCode includes the constructor arguments appended to the creation bytecode. If any constructor argument changes (different relayer, different factory address, different walletId), the init code hash changes, and therefore the resulting address changes. This is what makes each walletId produce a unique, deterministic address.

The migration script handles deploying the WalletFactory and converting the resulting hex address to Tron's base58check format.

require('dotenv').config();
const WalletFactory = artifacts.require("WalletFactory");
const crypto = require('crypto');

// Converts a hex Tron address (41...) to base58check format (T...)
function hexToBase58(hexAddr) {
    const BASE58_CHARS = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
    const payload = Buffer.from(hexAddr, 'hex');
    const h1 = crypto.createHash('sha256').update(payload).digest();
    const h2 = crypto.createHash('sha256').update(h1).digest();
    const checksum = h2.slice(0, 4);
    const full = Buffer.concat([payload, checksum]);

    let num = BigInt('0x' + full.toString('hex'));
    let result = '';
    const base = BigInt(58);
    while (num > 0n) {
        result = BASE58_CHARS[Number(num % base)] + result;
        num = num / base;
    }
    for (const byte of full) {
        if (byte !== 0) break;
        result = '1' + result;
    }
    return result;
}

module.exports = async function (deployer, network) {
    const relayer = process.env.RELAYER_ADDRESS;

    if (!relayer) {
        throw new Error("RELAYER_ADDRESS is not defined in .env");
    }

    console.log(">> Deploying WalletFactory with Relayer:", relayer);

    await deployer.deploy(WalletFactory, relayer);

    const instance = await WalletFactory.deployed();
    const hexAddress = instance.address;                 // 41...
    const base58Address = hexToBase58(hexAddress);       // T...

    console.log("\n╔══════════════════════════════════════════════════════╗");
    console.log("║         WalletFactory — Deploy successful            ║");
    console.log("╠══════════════════════════════════════════════════════╣");
    console.log("║ Network  :", network.padEnd(43), "║");
    console.log("║ Hex      :", hexAddress.padEnd(43), "║");
    console.log("║ Tron     :", base58Address.padEnd(43), "║");
    console.log("║ Relayer  :", relayer.padEnd(43), "║");
    console.log("╚══════════════════════════════════════════════════════╝\n");
    console.log(">> Update WALLET_FACTORY_ADDRESS in .env with:", base58Address);
};

TronBox returns contract addresses in hex format (41...). To get the human-readable T... address, you need to:

1. Take the 21-byte hex payload (41 prefix + 20 address bytes)

2. Double SHA-256 hash it: sha256(sha256(payload))

3. Take the first 4 bytes as a checksum

4. Append the checksum to the payload (25 bytes total)

5. Encode the 25 bytes in base58

This is the same encoding Bitcoin uses for addresses (base58check), just with a different version byte (0x41 for Tron instead of 0x00 for Bitcoin mainnet).

# Compile contracts
npx tronbox compile

# Deploy to Nile testnet
npx tronbox migrate --network nile

# Deploy to mainnet
npx tronbox migrate --network mainnet

After deployment, copy the Tron address from the output and set it as WALLET_FACTORY_ADDRESS in your .env file.

The compute-wallet.js script reproduces the CREATE2 formula entirely off-chain. This is the script your backend calls to generate deposit addresses for customers without making any on-chain transactions.

Step 1: Load the compiled bytecode. The script reads build/contracts/WalletReceiver.json, which TronBox generates during compilation. The bytecode field contains the creation bytecode (the code that runs during deployment and returns the runtime bytecode).

Step 2: Convert addresses. Tron addresses come in base58 format (T...). The script converts them to raw 20-byte buffers using addressToBytes20(). This function handles multiple input formats: base58 (T...), hex with Tron prefix (41...), and hex with 0x prefix.

Step 3: Encode walletId. If the walletId is a plain string like "user_123", it is converted to UTF-8 bytes and right-padded with zeros to fill 32 bytes. If it is already a 0x-prefixed hex string of 66 characters (32 bytes), it is used directly.

Step 4: ABI-encode constructor arguments. The constructor takes (address _relayer, address _factory, bytes32 _walletId). ABI encoding packs each argument into a 32-byte word: addresses are left-padded with 12 zero bytes, and bytes32 is used as-is.

Step 5: Build init code. The init code is the creation bytecode concatenated with the ABI-encoded constructor arguments. This is what the CREATE2 opcode hashes.

Step 6: Compute salt. The salt is keccak256(walletId), matching what the Solidity contract does with keccak256(abi.encodePacked(walletId)).

Step 7: Apply the Tron CREATE2 formula. Concatenate [0x41, factory(20), salt(32), keccak256(initCode)(32)] and hash with keccak256. Take the last 20 bytes as the raw address.

Step 8: Convert to Tron format. Prepend 41 to the 20-byte hex address and encode in base58check to get the final T... address.

# Pre-compute address for walletId "user_123"
node scripts/compute-wallet.js user_123

# Pre-compute address for a hex bytes32 walletId
node scripts/compute-wallet.js 0x757365725f31323300000000000000000000000000000000000000000000000000

The output will show the Tron address that will be generated when deployWallet() or deployAndSweep() is called with the same walletId on the deployed factory.

You can also call the factory's computeWalletAddress function directly via TronBox:

// compute.js — TronBox exec script
require('dotenv').config();
const WalletFactory = artifacts.require("WalletFactory");

module.exports = async function (callback) {
    try {
        const factory = await WalletFactory.deployed();
        const walletId = web3.utils.fromAscii("user_123").padEnd(66, '0');

        console.log("Computing address for walletId:", walletId);

        const predictedAddr = await factory.computeWalletAddress(walletId);

        console.log("-----------------------------------------");
        console.log("Address computed by contract:", predictedAddr);
        console.log("-----------------------------------------");

        callback();
    } catch (e) {
        console.error(e);
        callback(e);
    }
};

Run it with:

npx tronbox exec compute.js --network nile

Both methods should produce the same address. If they do not match, check that your .env has the correct factory and relayer addresses, and that the compiled bytecode has not changed since deployment.

The sweep.js script handles the complete flow of checking balances, estimating energy costs, and executing the sweep transaction. It uses TronWeb's triggerSmartContract API instead of the higher-level contract abstractions, which gives more control over parameter encoding (important for struct arrays in TronWeb v6).

triggerSmartContract — Builds and sends a state-changing transaction. This is the equivalent of calling a contract function that modifies state. The feeLimit parameter (set to 400 TRX = 400,000,000 SUN) caps the maximum energy cost. If the transaction exceeds this limit, it reverts.

triggerConstantContract — Makes a read-only call (equivalent to eth_call). Used to call computeWalletAddress() and isDeployedReceiver() without spending energy or creating a transaction. The result comes back in constant_result[0] as a hex string.

Struct encoding. TronWeb v6 expects struct arrays as nested arrays: [[address, uint256], [address, uint256]]. Each inner array represents one Recipient struct. The type is specified as (address,uint256)[].

# Sweep TRC20 tokens (uses TRC20_TOKEN_ADDRESS from .env)
node scripts/sweep.js --wallet user_123 --token trc20

# Sweep native TRX
node scripts/sweep.js --wallet user_123 --token native

# Sweep a specific TRC20 token to a custom address
node scripts/sweep.js --wallet user_123 --token TTokenBase58Address --to TCustomDestination

The script automatically determines whether to call deployAndSweep (if the receiver is not yet deployed) or sweepExisting (if it is already deployed). After the transaction confirms, it reports the actual energy, bandwidth, and TRX consumed.

Tron's resource model is fundamentally different from Ethereum's gas model. Understanding it is essential for keeping costs low in production.

Tron has two computational resources:

Energy is consumed by smart contract execution (analogous to Ethereum gas for computation). Every opcode costs a specific amount of energy. You can obtain energy in two ways:

• Staking TRX — Lock TRX to receive a daily energy allowance proportional to your stake. This is free recurring energy.

• Burning TRX — If you do not have enough staked energy, TRX is burned at the current rate (approximately 420 SUN per energy unit, though this fluctuates).

Bandwidth is consumed by the transaction data size (the raw bytes of the transaction). You get 600 free bandwidth points per day per account. Beyond that, TRX is burned. A typical contract call uses 300-500 bandwidth points.

These are approximate values. Actual costs depend on network conditions and the specific token being swept.

1. Stake TRX for energy. For a payment platform processing hundreds of sweeps per day, staking is essential. The break-even point is typically around 10-20 transactions per day. Beyond that, staking saves more TRX than it locks.

2. Batch when possible. The deployAndSweep function is cheaper than separate deployWallet + sweepExisting calls because it avoids paying bandwidth twice.

3. Use immutables. The WalletReceiver contract uses immutable variables instead of storage. Each SLOAD costs 2,100 energy; an immutable read costs 3. With three immutables per receiver, that saves 6,291 energy per sweep.

4. Set appropriate fee limits. The feeLimit caps the maximum TRX burned. Set it high enough to cover your worst-case scenario but not so high that a bug could drain your account. 400 TRX (400,000,000 SUN) is a reasonable limit for deploy+sweep operations.

5. Monitor the energy price. The burn rate (SUN per energy unit) changes based on network utilization. During high-usage periods, consider delaying non-urgent sweeps.

6. Use triggerConstantContract for estimation. Before executing a sweep, call the function as a constant (read-only) to estimate energy consumption. This is free and helps you predict costs.

The sweep script already includes energy estimation. Here is the relevant pattern:

const estimation = await tronWeb.transactionBuilder.triggerConstantContract(
    FACTORY_ADDRESS,
    'deployAndSweep(bytes32,address,(address,uint256)[])',
    {},
    params
);

if (estimation.result && estimation.result.result) {
    const energyUsed = estimation.energy_used || 0;
    const estTrx = (energyUsed * 420) / 1_000_000; // Approximate
    console.log(`Estimated energy: ${energyUsed}`);
    console.log(`Estimated cost: ~${estTrx.toFixed(2)} TRX`);
}

The energy_used field from triggerConstantContract gives you a simulation of the energy that would be consumed. Multiply by the current burn rate (check tronscan.org for the latest rate) to estimate the TRX cost.

The security model mirrors the EVM version with Tron-specific adaptations.

• Owner (deployer) — Can pause the factory, change the relayer, and trigger emergency sweeps. Should be a multisig in production.

• Relayer — An EOA authorized to deploy wallets and trigger sweeps. This is the hot key used by the backend. If compromised, the attacker can only sweep funds to the pre-specified recipients (though they could front-run legitimate sweeps).

• WalletReceiver — Accepts calls from both the relayer and the factory. This dual authorization enables atomic deploy+sweep.

Since we do not check transfer() return values, a malicious TRC20 token could silently fail transfers. In practice, the factory should maintain an allow-list of supported tokens (USDT, USDC, etc.) and reject unknown tokens at the backend level, before the on-chain call.

An attacker could send very small amounts of many different TRC20 tokens to a receiver, forcing the relayer to spend energy sweeping dust. Mitigation: the backend should check balances before triggering sweeps and only sweep above a minimum threshold.

The nonReentrant modifier on sweep() and sweepNative() prevents reentrancy attacks. This is critical for sweepNative(), which uses .call{value}() to send TRX. A malicious recipient contract could attempt to re-enter the sweep function during the TRX transfer. The ReentrancyGuard prevents this.

Since the CREATE2 address is deterministic and publicly computable, an attacker who knows the walletId could compute the address and send funds to it before the legitimate user. This is not an issue for the wallet factory pattern because:

1. Funds sent to the pre-computed address are safe: only the relayer or factory can deploy the receiver and sweep.

2. The walletId should be unpredictable (use UUIDs or database IDs, not sequential integers).

• Deploy with a multisig as the owner

• Use a dedicated relayer EOA (not the owner)

• Maintain a backend allow-list of supported TRC20 tokens

• Set minimum sweep thresholds to avoid dust griefing

• Stake TRX for energy on the relayer account

• Monitor the relayer's TRX balance for energy burns

• Set up alerts for EmergencySweep events

• Test the full flow on Nile testnet before mainnet deployment

• Verify off-chain address computation matches on-chain for multiple walletIds

• Implement rate limiting on the backend to prevent relayer key abuse

You have built a complete deterministic wallet factory for the Tron network. The system pre-computes deposit addresses off-chain, deploys lightweight receiver contracts on demand via CREATE2, and sweeps funds to configurable destinations using BPS-based splits.

What makes the Tron version different from EVM:

• 0x41 prefix in CREATE2 instead of 0xff changes address computation entirely

• ITRC20 interface instead of IERC20/SafeERC20 because TRC20 transfer() does not return a bool

• Energy + bandwidth model instead of gas requires different cost optimization strategies

• Base58check addresses (T...) instead of hex (0x...) require conversion utilities

• Ownable instead of Ownable2Step to save energy on ownership transfers

• TronBox + TronWeb instead of Hardhat + ethers.js for development and interaction

• Chain ID 728126428 hardcoded instead of using block.chainid

The architecture is production-ready for USDT payment platforms, exchange deposit systems, or any application that needs to programmatically receive and route TRC20 tokens on Tron. The same walletId-based addressing scheme allows your backend to manage deposits across EVM chains and Tron with a unified interface, differing only in the address computation prefix and token interface.

The complete source code is available in the wallet-factory-multichain repository on GitHub.

Built by Beltsys Labs. Licensed under MIT.

Originally published on beltsys.com