FAQ

This FAQ is the entry point for common questions about building on and operating TRON. Reference-style questions — "how do I calculate X", "where is the syntax for Y" — are answered in full below. Troubleshooting questions — "why does X fail" — give a brief summary and link to the dedicated diagnostic page where the full diagnostic flow lives.

Should beginners choose Shasta or Nile?

For first-time learning, choose Shasta. Shasta is a better fit for tutorials, wallet debugging, standard contract deployment tests, and final pre-production validation. Most quick examples in these docs also use the Shasta endpoint by default.

Nile is better for previewing upcoming features, parameter changes, and governance proposals. If you only want to complete your first transfer, deploy a standard test contract, or validate a DApp flow, start with Shasta.

Why do I need to submit the fee_limit field when calling a smart contract?

fee_limit is the maximum Energy this transaction is allowed to consume, denominated in TRX (sun, technically). The default is 0, which fails immediately — you must set it. The current Mainnet maximum is 15,000 TRX (chain parameter #47, API key getMaxFeeLimit).

If execution consumes more Energy than fee_limit / EnergyPrice allows, the VM stops with OUT_OF_ENERGY rather than silently overdrawing your TRX balance. So fee_limit plays two roles: a safety cap against runaway Energy (a buggy loop, an attack), and a per-transaction Energy budget priced in TRX.

For the full math, origin_energy_limit interaction, and three calibration strategies, see FeeLimit & Energy cost.

For the list of exceptions that consume the entire fee_limit (rather than just the Energy used so far), see VM exception handling — assert-style failures, timeouts, overflows, illegal opcodes, and so on.

Why does my contract trigger OUT_OF_TIME?

Your function ran longer than the per-transaction 80 ms execution budget (chain parameter #13, getMaxCpuTimeOfOneTx). The full fee_limit is consumed — OUT_OF_TIME is treated as an assert-style failure.

→ Smart contract errors — OUT_OF_TIME for the full diagnostic flow and fixes.

Common token destruction (burn) addresses

By industry convention, addresses derived from "0", "1", "2", and "dead" function as null / burn addresses. They are not owned by any user, and tokens sent to them become permanently inaccessible.

Use these for token burn (reducing total supply) and as the from address in mint events.

How do I troubleshoot a REVERT error?

The contract intentionally aborted. Only Energy used so far is consumed; the rest of fee_limit is returned. The actual revert reason is in contractResult returned by wallet/gettransactioninfobyid, hex-encoded behind the 08c379a0 Error(string) selector.

→ Smart contract errors — REVERT for the decode procedure with worked example.

How do I calculate Bandwidth and Energy for a contract call or deployment?

Bandwidth

A transaction's Bandwidth equals the number of bytes its on-chain representation occupies, which is the protobuf-serialized total of:

• raw_data
• the transaction signature(s)
• the transaction result

You can estimate before broadcasting.

Trident — estimateBandwidth takes a signed transaction:

public long estimateBandwidth(Transaction txn) {
    long byteSize = txn.toBuilder().clearRet().build().getSerializedSize() + 64;
    return byteSize;
}

The + 64 accounts for the fixed bytes occupied by the transaction result.

TronWeb — equivalent JavaScript:

function estimateBandwidth(signedTxn) {
    const DATA_HEX_PROTOBUF_EXTRA = 3;
    const MAX_RESULT_SIZE_IN_TX = 64;
    const A_SIGNATURE = 67;

    let len = signedTxn.raw_data_hex.length / 2
            + DATA_HEX_PROTOBUF_EXTRA
            + MAX_RESULT_SIZE_IN_TX;

    for (let i = 0; i < signedTxn.signature.length; i++) {
        len += A_SIGNATURE;
    }
    return len;
}

Energy

Energy is deducted based on the opcodes the contract executes. Different instructions have different costs (see Opcodes for the full table). Estimate by:

• wallet/triggerconstantcontract — simulates the call without broadcasting and returns energy_used. See FeeLimit & Energy cost — Strategy 3.
• wallet/estimateenergy — slightly more accurate for some edge cases (java-tron 4.7.0.1+).
• Test on Shasta or Nile before deploying to Mainnet, or inspect historical transactions on TRONSCAN.

For the full estimation flow and fee_limit calibration strategies, see FeeLimit & Energy cost.

My broadcast succeeded but the transaction never appears on chain

The node accepted the transaction into its mempool, but it never reached a producing SR. This is usually a network-propagation issue rather than a transaction problem.

→ Broadcast and RPC errors — Broadcast succeeded but transaction never on chain for the wait-or-rebroadcast decision tree.

How do I solve OUT_OF_ENERGY?

The transaction consumed all the Energy allowed by fee_limit before completing. Energy already spent is not refunded. Re-estimate, raise fee_limit, or address the contract's consume_user_resource_percent settings.

→ Smart contract errors — OUT_OF_ENERGY for the five-step fix list.

How do I solve slow or stopped node block sync?

Usually one of: under-spec hardware, too-low vm.maxTimeRatio, or a JVM heap that's too small / too large.

→ Node operations issues — slow or stopped block sync for the three-step diagnostic.

How do I solve SERVER_BUSY?

The node's pending transaction pool is full. Raise node.maxTransactionPendingSize (self-hosted nodes) or retry against a different endpoint (hosted services).

→ Broadcast and RPC errors — SERVER_BUSY.

How do I solve TronGrid 503 errors?

You're hitting TronGrid's per-IP rate limit. Always send the TRON-PRO-API-KEY header; reduce request frequency; respect Retry-After headers.

→ Broadcast and RPC errors — TronGrid 503 for the full rate-limit guidance.

Why is constant_result empty when I trigger a view or pure method?

The node was downgraded from GreatVoyage-v4.2.2 or later to v4.2.1 or v4.2.0; the downgraded database is missing fields the constant-call path expects.

→ Smart contract errors — empty constant_result for the repair procedure.

What does each broadcast response code mean?

The node returns a code like SIGERROR, BANDWITH_ERROR, TAPOS_ERROR, TRANSACTION_EXPIRATION_ERROR, CONTRACT_VALIDATE_ERROR, etc. on failed broadcasts. The full table with causes and fixes is on the dedicated diagnostic page.

→ Broadcast and RPC errors — Broadcast response codes.

How do I speed up node startup?

For LevelDB nodes, the LevelDB Startup Optimization Tool (part of the Toolkit JAR) pre-warms LevelDB metadata.

→ Node operations issues — speed up node startup plus the Toolkit User Guide for the CLI.

How do I use TronWeb to invoke a contract whose ABI is not on chain?

Some contracts have their ABI cleared (via the deprecated clearAbi API) or were created internally by another contract and never had an ABI registered. TronWeb supports passing the ABI explicitly when constructing the contract instance.

See the TronWeb contract documentation for the constructor signature and a worked example.

How do I scan blocks to identify funds moving in and out of an address?

For exchange and custodial workloads, walk each new solidified block, dispatch by contract[0].type, and inspect the relevant fields. Internal transactions need special handling.

For the full block-parsing pipeline (with code), see Exchange wallet integration — parsing blocks for deposit detection.

Why do two transfers of the same TRC-20 token consume different Energy?

The recipient's storage state (SSTORE cost differs for a zero vs. non-zero slot) and the Dynamic Energy Model (a per-contract penalty multiplier recalculated every maintenance cycle).

→ Smart contract errors — TRC-20 Energy variance for the breakdown with worked examples (USDT vs. BTT).

Why does Account Permission Management fail with "permission denied" for Stake 2.0?

The account was activated before Stake 2.0 took effect. Its Active Permission operations bitmap does not include the Stake 2.0 contract type IDs (54–59).

→ Smart contract errors — Stake 2.0 permission denied for the contract-type-ID table and the fix procedure.

How do I parse raw_data_hex from a transaction?

raw_data_hex is the protobuf-serialized form of raw_data. The structure:

{
  "raw_data": {
    "contract": [{
      "parameter": {
        "value": {
          "data": "a9059cbb000000000000000000000000...",
          "owner_address": "41b3dcf27c251da9363f1a4888257c16676cf54edf",
          "contract_address": "41eca9bc828a3005b9a3b909f2cc5c2a54794de05f"
        },
        "type_url": "type.googleapis.com/protocol.TriggerSmartContract"
      },
      "type": "TriggerSmartContract"
    }],
    "ref_block_bytes": "1b98",
    "ref_block_hash": "4e1c1e7428d1d7a4",
    "expiration": 1719223548000,
    "fee_limit": 30000000,
    "timestamp": 1719223489371
  },
  "raw_data_hex": "0a021b98..."
}

Example parser using Trident:

import com.google.protobuf.Any;
import com.google.protobuf.InvalidProtocolBufferException;
import org.tron.trident.abi.TypeDecoder;
import org.tron.trident.abi.datatypes.Address;
import org.tron.trident.abi.datatypes.generated.Uint256;
import org.tron.trident.core.utils.ByteArray;
import org.tron.trident.crypto.Hash;
import org.tron.trident.proto.Chain.Transaction;
import org.tron.trident.proto.Contract;
import org.tron.trident.proto.Contract.TriggerSmartContract;
import java.math.BigInteger;

public class Demo {
    public void parseRawDataHex() throws InvalidProtocolBufferException {
        ApiWrapper client = ApiWrapper.ofNile("3333333333333333333333333333333333333333333333333333333333333333");

        String rawDataHexString = "0a021b98...";   // truncated for brevity

        Transaction.raw rawData = Transaction.raw.parseFrom(ByteArray.fromHexString(rawDataHexString));
        System.out.println("ref_block_bytes: " + ApiWrapper.toHex(rawData.getRefBlockBytes())
            + "\nref_block_hash: " + ApiWrapper.toHex(rawData.getRefBlockHash())
            + "\nexpiration: " + rawData.getExpiration()
            + "\ntimestamp: " + rawData.getTimestamp()
            + "\nfee_limit: " + rawData.getFeeLimit()
            + "\ncontract.type: " + rawData.getContract(0).getType());

        Transaction.Contract contract = rawData.getContract(0);
        Any contractParameter = contract.getParameter();
        switch (contract.getType()) {
            case TriggerSmartContract:
                TriggerSmartContract triggerSmartContract = contractParameter.unpack(TriggerSmartContract.class);
                System.out.println("contract_address: " + ApiWrapper.toHex(triggerSmartContract.getContractAddress())
                    + "\nowner_address: " + ApiWrapper.toHex(triggerSmartContract.getOwnerAddress())
                    + "\ndata: " + ApiWrapper.toHex(triggerSmartContract.getData()));
                dataDecodingTutorial(ApiWrapper.toHex(triggerSmartContract.getData()));
                break;
            case TransferContract:
                Contract.TransferContract transferContract = contractParameter.unpack(Contract.TransferContract.class);
                break;
            default:
                break;
        }
    }

    public void dataDecodingTutorial(String DATA) {
        String rawSignature = DATA.substring(0, 8);
        String functionSignatureExample = "transfer(address,uint256)";
        String functionSelectorExample = Hash.sha3String(functionSignatureExample).substring(2, 10);
        if (rawSignature.equals(functionSelectorExample)) {
            Address rawRecipient = TypeDecoder.decodeAddress(DATA.substring(8, 72));
            Uint256 rawAmount = TypeDecoder.decodeNumeric(DATA.substring(72, 136), Uint256.class);
            BigInteger amount = rawAmount.getValue();
            System.out.println("Called function: " + functionSignatureExample);
            System.out.println("Transfer " + amount + " to " + rawRecipient.toString());
        }
    }
}

For the encoding side (constructing data from a function signature), see Parameter encoding and decoding.

How do I set reference-block information on a locally-constructed transaction?

The TAPOS reference block must be within the latest 65,536 blocks of the chain head. By convention, use the latest solidified block as the reference.

Example using Trident:

public void setReference(long blockNum, byte[] blockHash) {
    byte[] refBlockNum = ByteArray.fromLong(blockNum);
    Transaction.raw rawData = this.transaction.getRawData().toBuilder()
        .setRefBlockHash(ByteString.copyFrom(ByteArray.subArray(blockHash, 8, 16)))
        .setRefBlockBytes(ByteString.copyFrom(ByteArray.subArray(refBlockNum, 6, 8)))
        .build();
    setRawData(rawData);
}

The TAPOS expiration default is 60 seconds (TRANSACTION_DEFAULT_EXPIRATION_TIME in Constant.java). Construct as late as possible, sign quickly, broadcast immediately. See API workflow — common pitfalls.

Can I temporarily bypass the 80 ms execution time limit for testing?

Yes — start the node with --debug. Only safe on a private chain.

→ Node operations issues — bypass 80 ms execution time limit for the procedure and the warning about Mainnet sync.

How do I stop a node at a specific block height?

Configure one of BlockTime, BlockHeight, or BlockCount in config.conf under node.shutdown. The node will stop syncing and exit automatically when the condition is met.

→ Node operations issues — stop the node at a specific block height.

How do I improve node network stability and bound resource usage?

Two levers: cap JVM direct memory with -XX:MaxDirectMemorySize, and throttle TCP traffic with iptables --hashlimit rules.

→ Node operations issues — network stability and resource usage control for example commands.

My node stopped syncing with different resultCode in the log

The local node executed a transaction and produced a result different from what the block records. Three common patterns: hardware-induced timeout, database corruption, or running under --debug.

→ Node operations issues — different resultCode for the per-pattern diagnosis.

Related resources

• Smart contract errors — runtime errors when contracts execute (REVERT, OUT_OF_ENERGY, OUT_OF_TIME, etc.)
• Broadcast and RPC errors — broadcast response codes, SERVER_BUSY, TronGrid 503
• Node operations issues — sync, startup, stability, debug bypass
• FeeLimit & Energy cost — fee_limit calibration
• VM exception handling — exception types at the protocol layer
• Errors and debugging — API-level error categories and decode procedure