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
Integration guide

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
Integration guide

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.

PaymasterFactory
immutable
CREATE2 deployer · implementation registry · pause, fees, roles
ForwarderRouter
fixed delegate target
AccountRouter
fixed delegate target
forwarder clones
args: treasury ‖ sweeper
one per deposit
account clones
args: owner
one per user

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.

call path — account.permitTransfer(…)
relayer ──tx──▶ clone ──delegatecall──▶ router ──staticcall──▶ factory.implementation(Account)
                                          └──delegatecall──▶ PermitAccount code
                                              address(this) = clone, storage = clone's

Deterministic 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 derivation
address  = last20( keccak256( 0x41 ‖ factory ‖ salt ‖ keccak256(initCode) ) )

initCode = 0x61 ‖ uint16(len(args)+0x2d) ‖ 3d81600a3d39f3363d3d373d3d3d363d73
           ‖ router ‖ 5af43d82803e903d91602b57fd5bf3 ‖ args
KindSaltArgs
Forwarderyour own 32 bytes — the SDK derives HMAC-SHA256(secret, id)treasury ‖ sweeper
Accountkeccak256(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.

  1. 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.

  2. 02

    Your user sends USDT

    There is no contract there yet. It does not matter — the chain credits the balance all the same.

  3. 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.

  4. 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.

permit lifecycle
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 out

Eight checks before anything moves

Ordered cheapest first, so a bad permit dies before it costs anyone energy.

  1. 1
    block.timestamp <= deadlinethe permit has not expired
  2. 2
    nonce == account.noncesequential, so each executes at most once
  3. 3
    permit.owner == OWNERthe permit belongs to this account
  4. 4
    permit.relayer == 0 || feeRecipient == permit.relayera front-runner cannot steal the fee
  5. 5
    relayerFee != 0 ⇒ feeRecipient != 0no fee without a recipient
  6. 6
    to ∉ {0, this} and value > 0no burns, no self-sends, no no-ops
  7. 7
    recover(digest, r, vs) == signerthe rotated signer or the owner key; high-s rejected
  8. 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.

01

Queue

The admin queues an implementation. The event is public the moment it lands.

02

Wait

At least 48 hours, fixed at deploy. Your users can withdraw for the whole window.

03

Veto or lapse

The guardian can veto, and anything unexecuted lapses after 7 days.

04

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.

WhoCanCannot
Your userwithdraw available funds any time; rotate the signer; cancel permitsspend accrued fees
A relayersubmit valid signed permits; claim its own accrued feeschange the recipient or amount; exceed maxFee; take another relayer's fee
Your sweepertrigger forwarder sweepssend funds anywhere but your treasury
The adminqueue upgrades and role changes (delayed); set fees within the caps; pauseupgrade instantly; exceed the fee caps; move funds
The guardianveto upgrades; pause (bounded, with cooldown); unpauseupgrade; 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.