How it works
Your users hold USDT.
That should be enough.
Every Tron integration eventually builds the same unhappy machine: TRX on every address, energy leases to track, dust to reconcile. TronMaster deletes that machine. Funds sit at addresses whose code can only move them by rules fixed before deployment, and whoever moves them pays the energy.
No TRX on every address
Deposit addresses hold the token and nothing else.
No energy leases to track
No per-address delegation, no lag, no expiry calendar.
No dust to reconcile
Sweeps move the entire balance. Nothing is stranded.
No TRX on your balance sheet
Fees settle in the token you were already moving.
The tax you're paying now
On Tron, every address you create is a TRX liability.
Every transaction burns bandwidth, and every contract call burns energy. An address with no TRX and no staked or delegated energy cannot send USDT at all — a fresh one cannot even be activated. There are two standard workarounds, and both scale badly in exactly the place it hurts: per address.
Rent or delegate energy, per address
The address has to be activated first. Delegation lags. And you now run a leasing desk nobody asked you to run — one row per customer, forever.
Sprinkle TRX on every address
One TRX transfer per address before it can move a cent, dust left behind at every one, and your unit economics now float on the TRX chart.
TronMaster moves the cost to whoever moves the funds. Your users and deposit addresses hold only the token. Your sweeper or a relayer pays the energy — and where a fee applies, it settles in the token being moved, never in TRX.
Pick your integration
You already know which one you are.
Two modes, one factory, both with addresses you can derive offline before anything exists on chain. The only question is who holds the key.
You run an exchange, a processor, or custody
Deposit addresses that can only pay you
Mint unlimited deposit addresses offline. Your treasury is part of every one of them, so a sweep physically cannot land anywhere else — whoever triggers it.
- Who holds the key
- you
- Who can move funds
- your sweeper — or anyone
- Where funds can land
- only your treasury
- On-chain fee
- none
You build a wallet or an app
Gasless sends your users just… do
Your user signs a permit. Any relayer submits it and eats the energy. No onboarding step where you explain what TRX is and why they need some.
- Who holds the key
- your user
- Who can move funds
- any relayer, on a signed permit
- Where funds can land
- wherever the owner signs
- On-chain fee
- capped by the signed maxFee
The shape of it
One immutable factory. Addresses that outlive your code.
Every clone delegates to a router, and the router reads the current implementation from the factory. That one indirection is why shipping new code never migrates a single customer address.
A clone's address depends on its router and its args — never on which implementation happens to be current.
PaymasterFactory
Deploys clones, holds the current implementation per kind, and owns governance. The factory itself is immutable — a new factory is a new deployment, never a surprise.
ImplementationRouter
A tiny immutable contract, one per kind. On every call it reads factory.implementation(KIND) and delegatecalls it.
Clones
EIP-1167 minimal proxies with immutable args appended to their runtime code. Those args are part of the CREATE2 init code, so they are part of the address. No initializer means nothing to front-run or hijack.
Implementations
DepositForwarder (stateless) and PermitAccount (ERC-7201 namespaced storage). Both refuse to run when called directly.
relayer ──tx──▶ clone ──delegatecall──▶ router ──staticcall──▶ factory.implementation(Account)
└──delegatecall──▶ PermitAccount code
address(this) = clone, storage = clone'sDeterministic addresses
The address is the policy.
Addresses come from TVM CREATE2 — identical to the EVM except the prefix byte is 0x41 rather than 0xff. Change any argument and you get a different address. That is what turns your custody rules from something you enforce into something the chain enforces for you.
address = last20( keccak256( 0x41 ‖ factory ‖ salt ‖ keccak256(initCode) ) )
initCode = 0x61 ‖ uint16(len(args)+0x2d) ‖ 3d81600a3d39f3363d3d373d3d3d363d73
‖ router ‖ 5af43d82803e903d91602b57fd5bf3 ‖ args| Kind | Salt | Args |
|---|---|---|
| Forwarder | your own 32 bytes — the SDK derives HMAC-SHA256(secret, id) | treasury ‖ sweeper |
| Account | keccak256(abi.encode(owner, index)) | owner |
Hand them out before they exist
Deposits land at an address with no code, and the chain credits them anyway. Generate a million up front.
Derive them offline
No network call — just (factory, router, args, salt), cross-checked against the factory to catch drift.
A changed arg is a changed address
A forwarder for your treasury can never pay someone else's, because that would simply be a different address.
Upgrades never move them
The init code commits to the router, which is immutable — never to the implementation behind it.
Custodial mode
A deposit address with your treasury baked in.
Not a policy you configure and hope holds — the treasury is literally part of the address. For every caller and every calldata, value only reaches you. It is fuzzed as an invariant, not merely intended.
- 01
Derive the address offline
salt = HMAC(secret, userId), then predict the forwarder from your treasury, your sweeper and that salt. No gas, no deployment, no rate limit, no API. - 02
Your user sends USDT
There is no contract there yet. It does not matter — the chain credits the balance all the same.
- 03
Your sweeper sweeps
One ordinary transaction deploys the clone and empties it to your treasury. Deploy and sweep are the same transaction, so the first deposit costs one transaction, not two.
- 04
Every deposit after that is cheaper
The clone already exists, so later sweeps skip deployment entirely.
Why your security team will like it
- Sweeps always move the entire balance, and always to your treasury.
- Leave the sweeper unset and anyone can sweep for you — a third party who pays the energy gains nothing, since the funds still land with you.
- Set a sweeper and only it can trigger. That gates when deposits move, never where.
- A leaked sweeper credential moves your deposits into your own treasury. That is the worst case.
A sweep is a single parseable transaction, so a policy engine can pin the contract, the selector and the treasury argument. For the treasury itself, use a Tron multi-signature account — keys rotate while every forwarder bound to it keeps its address.
Non-custodial mode
Your user signs. Someone else pays.
The owner signs a TIP-712 permit naming the token, recipient, amount, max fee, relayer, deadline and nonce. Any relayer can submit it and burn its own energy. The recipient receives exactly what was signed — fees never come out of the transfer.
owner (no TRX) relayer chain
│ quote(owner,to,value) │ │
│───────────────────────▶│ prices energy, binds itself │
│◀────── unsigned permit │ (relayer, maxFee, nonce, ttl) │
│ sign TIP-712 digest │ │
│──── permit + (r,vs) ──▶│ verify locally, simulate │
│ │──── permitTransfer ─────────────▶│ checks → effects → transfer
│ │ │ recipient += value
│◀──────────── txid ─────│ │ fees accrue in storage
│ │──── claimMany (batched) ────────▶│ relayer's accrual paid outEight checks before anything moves
Ordered cheapest first, so a bad permit dies before it costs anyone energy.
- 1
block.timestamp <= deadlinethe permit has not expired - 2
nonce == account.noncesequential, so each executes at most once - 3
permit.owner == OWNERthe permit belongs to this account - 4
permit.relayer == 0 || feeRecipient == permit.relayera front-runner cannot steal the fee - 5
relayerFee != 0 ⇒ feeRecipient != 0no fee without a recipient - 6
to ∉ {0, this} and value > 0no burns, no self-sends, no no-ops - 7
recover(digest, r, vs) == signerthe rotated signer or the owner key; high-s rejected - 8
relayerFee + protocolFee <= maxFeeread live from the factory; reverts while paused
Then the effects: the nonce increments, fees are credited, the transfer goes out, and a final balance check keeps accrued fees backed. Your user's recipient receives exactly the value signed, to the cent.
One permit, one transfer
Fees are recorded in storage rather than moved on every permit, so a send costs one token transfer instead of three. Relayers sweep up their earnings later in a single batched claimMany— and that call pays only the caller's own accrual.
Your users are never locked in
- withdraw
- exit any time, up to the available balance
- setSigner
- rotate the permit key; follows Tron account permissions
- invalidateNonces
- cancel every outstanding permit below n
None of these can be paused — by us, by you, or by anyone. An owner with no TRX can still leave by signing a permit to themselves.
Governance
Upgrades you can see coming.
Every account and forwarder is a clone of a fixed router, so addresses survive upgrades. The code behind them changes only through a public timelock — and you get alerts while the clock runs.
Queue
The admin queues an implementation. The event is public the moment it lands.
Wait
At least 48 hours, fixed at deploy. Your users can withdraw for the whole window.
Veto or lapse
The guardian can veto, and anything unexecuted lapses after 7 days.
Execute
Every clone of that kind runs the new code. Not one address moves.
A pause cannot become a freeze
Pauses stop permits and sweeps only. They expire on their own, and a guardian cooldown stops anyone holding the protocol down.
Never pausable, by anyone
withdraw · withdrawTRX · setSigner · invalidateNonces · claimFees
Trust summary
What you can promise your users.
Written plainly, including the part we cannot engineer away: after the delay, an executed upgrade can change the code behind every clone. That is why the queue is public, the guardian can veto, and owners can always leave inside the window.
| Who | Can | Cannot |
|---|---|---|
| Your user | withdraw available funds any time; rotate the signer; cancel permits | spend accrued fees |
| A relayer | submit valid signed permits; claim its own accrued fees | change the recipient or amount; exceed maxFee; take another relayer's fee |
| Your sweeper | trigger forwarder sweeps | send funds anywhere but your treasury |
| The admin | queue upgrades and role changes (delayed); set fees within the caps; pause | upgrade instantly; exceed the fee caps; move funds |
| The guardian | veto upgrades; pause (bounded, with cooldown); unpause | upgrade; change fees; pause indefinitely; block its own replacement |
Sharp edges
We already hit the potholes.
Tron has a few behaviours that quietly ruin integrations. These are handled, tested against a real TVM and real USDT on Nile, and documented rather than buried.
USDT returns false on success
Tron's USDT returns falsefrom a transfer that worked, which makes OpenZeppelin's SafeERC20 revert. Ignoring the return value is just as unsafe. So we require the call not to revert, ignore the bool, then verify the balance actually moved.
The caller pays, and we prove it
The factory ships with consume_user_resource_percent = 100, so the relayer or sweeper pays all execution energy and nobody is quietly subsidising anybody. End-to-end tests assert origin_energy_usage == 0 on real receipts.
Left out on purpose
No generic execute — one owner approval would let accrued fees be drained through transferFrom. TRC-10 is a documented gap, and fee-on-transfer and rebasing tokens are unsupported rather than half-supported.
Derive your first deposit address in 60 seconds.
Read-only, no keys, no account, nothing to fund — against the public Nile test factory.