MMashDiv

Configuration reference

Every environment variable the Tron service reads, the shared Ecosystem variables that change its behaviour, the chain constants baked into the code, and the admin endpoints and permissions involved.

3 min readUpdated 6 August 2026environment, reference, trongrid, constants, endpoints

Everything the Tron addon reads, in one place. Variables live in the project root .env; none of them are present in .env.example, so all of them are added by hand.

The service is a singleton constructed on first use and nothing re-reads these values. Restart the backend after any change.

pm2 restart backend

Tron variables

Which network the service runs against. Accepts mainnet, shasta or nile and nothing else. An unrecognised value throws inside the constructor, so the singleton is never built and every Tron flow fails with "Tron service not available".
Full-host URL for mainnet — used as the TronWeb fullHost and as the base for every direct REST call. Must start with http:// or https://.
Full-host URL used when TRON_NETWORK is shasta.
Full-host URL used when TRON_NETWORK is nile.
TronGrid API key, sent as the TRON-PRO-API-KEY header on every RPC and REST call. Effectively mandatory on mainnet — without it the deposit monitor rate-limits itself into permanent shutdown.
Set to the string "true" for verbose TronWeb initialisation logging — the resolved full host and whether an API key was found.

Only the RPC variable matching the selected network is read. Setting TRON_SHASTA_RPC while TRON_NETWORK="mainnet" does nothing.

Some providers embed a token in the path rather than a header. The diagnostics console echoes only the host of a TRON_*_RPC value for that reason. Treat these variables as secrets if yours is that shape.

Shared Ecosystem variables that affect Tron

These are not Tron-specific but they change Tron behaviour directly.

Set to "false" to disable the shared background deposit scanner on every chain. Without it, a deposit arriving after the user closes the deposit page is only found the next time they open it.
Address-scan passes per second the background scanner may spend on Tron. The default is tuned to sit under TronGrid's limits; raise it only if you have quota to spend.
Default scan rate for any chain without its own override.
How often the background scanner revisits a registered address, in milliseconds.
How long an address stays in the background scanner's working set after it was last seen on a deposit page, in milliseconds. The default is 72 hours.

The vault variables — ENCRYPTED_ENCRYPTION_KEY and ENCRYPTION_KEY_PASSPHRASE — encrypt every Tron key this addon creates. They are documented in Ecosystem: master wallets and the vault; losing either makes every Tron address on the install permanently unspendable.

Chain facts

Property Value
Chain key TRON
Native symbol TRX
Decimals 6 (1 TRX = 1,000,000 sun)
Derivation path m/44'/195'/0'/0/0
Address format base58, starts with T
Explorer https://tronscan.org
Seeded product ID 54577641
Licence file lic/54577641.lic
Service module backend/src/blockchains/tron.ts
Token deployment Not supported — import only
Custodial contracts Not supported

Tron is classified as a special chain alongside Solana, TON and Monero, and as a network-agnostic chain for the purposes of the token-network check. The second classification means Ecosystem's guard against issuing an address for a token whose network disagrees with the chain's configured network never fires on Tron. Nothing warns you when they diverge.

Constants baked into the code

None of these are configurable. They are listed because they explain observed behaviour and because the numbers matter when you are reading a log.

Constant Value Where it applies
Deposit poll interval 30 s Per-session monitor, both asset types
Poll start jitter 0–5 s random Avoids a thundering herd at page open
Backoff on 429 ×2 per error, 5 min ceiling Rate limiting
Backoff on 403 ×3 per error, 5 min ceiling Bad or missing API key
Consecutive errors before shutdown 10 The monitor deletes its own loop
Native dust floor 0.001 TRX Ignored, counted and logged
TRC-20 dust floor 1 / 10^(decimals − 3) 0.001 for a 6-decimal token
Records fetched per poll 50 Both endpoints
Processed-hash memory 30 min In-process duplicate suppression
Transaction history cache 30 min Redis, per address
TRC-20 feeLimit 100 TRX Hard ceiling per transfer
Default energy estimate 65,000 Used when the simulation is unavailable
Bandwidth sizing 350 bytes A signed TRC-20 triggerSmartContract
Gas top-up headroom 20% Applied to the computed shortfall
Chain-parameter cache 10 min getEnergyFee, getTransactionFee
Fallback energy price 420 sun Only if the node cannot be read
Fallback bandwidth price 1,000 sun Only if the node cannot be read
Native bandwidth price assumption 10,000 sun per missing point Informational estimate only
Top-up confirmation window 30 × 3 s = 90 s Then the withdrawal is requeued
Receipt confirmation window 20 × 3 s = 60 s Then the row becomes TIMEOUT
New-account activation figure 1 TRX Informational metadata, never charged
Licence and toggle cache 5 min Both gates, read together

Endpoints

Tron has no routes of its own. It is driven through Ecosystem's admin and user endpoints.

Full per-chain requirements report — every variable the runtime reads, whether it is set, and every non-environment prerequisite
Runs live read-only probes against Tron and returns per-flow readiness
Enables or disables a blockchain by product ID. Returns 403 if the licence file is absent.
Reads one blockchain row
Generates, encrypts and stores a master wallet for a chain
Lists master wallets, and refreshes each balance from the chain as a side effect. This is the route that reads a Tron balance — it calls getEcosystemMasterWalletBalance in wallet/master/utils.ts, the only function with a TRON branch, and caches per wallet in Redis for one minute.
Refreshes every master wallet balance — except Tron's. Handles UTXO chains directly and sends everything else through getProvider, which is EVM-only, and caches for five minutes.

balance.get.ts has its own copy of the balance-refresh logic, and that copy knows about UTXO chains and getProvider() and nothing else. getProvider() builds an ethers JSON-RPC provider from chainConfigs, and the TRON entry there carries explorer hosts but no chainId, so the call throws "Chain ID not found for TRON on mainnet". The error is caught, written to the console, and the row keeps whatever balance it already had.

The one-minute cache belongs to the list route; this one holds its figures for five. If a Tron master wallet balance looks stale, reload the wallets list — calling this endpoint will never move it.

Registers an existing on-chain token contract as an Ecosystem token
Returns the user's ECO wallet for a currency, creating and backfilling addresses as needed

Diagnostic checks the console runs

Selecting Tron on the Requirements page and running its test performs, in order:

  1. Network configured — TRON_NETWORK resolves to a host and that host is a valid http(s) URL. A failure here short-circuits the rest, because the service cannot be constructed at all.
  2. Node liveness — POST /wallet/getnowblock, expecting a numeric block height back.
  3. TronGrid REST + API key — a one-record account-transactions read against Tron's burn address, which always exists on every network. This is the exact path deposit polling uses. It passes with a warning when no API key is set, and reports 401/403 as an invalid key and 429 as anonymous rate limiting.
  4. Chain service installed — whether @b/blockchains/tron resolves.
  5. Licence + DB toggle active — both gates.

Readiness for deposits and withdrawals is derived from node liveness plus the last two checks, and then further downgraded by signing prerequisites — a locked vault or a missing or disabled master wallet fails withdrawal readiness even though every probe above passed.