Tron Java

Skill based on java-tron (TRON Protocol Java implementation), generated 2026-02-09.

java-tron is the Java node for the TRON blockchain: high-throughput, DPoS, EVM-compatible TVM. This skill covers building/running FullNode and SR, HTTP/gRPC/JSON-RPC APIs, modular architecture (framework, protocol, common, chainbase, consensus, actuator), and implementing custom transaction types via actuators.

Core References

Features

Modularization

Best Practices

Generation Info

• Source: sources/tron-java
• Git SHA: c158599c97e1a77cd4d8d903d0fc33a29d94f81b
• Generated: 2026-02-09

API Security Best Practices

When exposing java-tron APIs (HTTP, gRPC, or JSON-RPC) to a public or untrusted network, harden the node to reduce abuse and unauthorized access.

Recommendations

1. Authentication — Add authentication in front of the node (reverse proxy, API gateway, or gRPC interceptors) so only authorized clients can call the APIs. Do not rely on "internal only" if the ports are reachable from the internet.

2. Rate limiting — Apply rate limits per IP or per API key to prevent DoS and resource exhaustion. Tune limits for your capacity (e.g. RPC throughput, block sync).

3. Network access controls — Restrict who can reach the API ports (firewall, security groups, VPN). Prefer exposing APIs only to known clients or a proxy, not 0.0.0.0 to the whole internet unless necessary.

4. Use TronGrid for public access — For mainnet and testnet, TronGrid provides hosted HTTP endpoints with built-in scaling and security. Prefer TronGrid when you do not need to run your own node.

5. Minimal exposure — In config, enable only the APIs you need (node.http, node.rpc, node.jsonrpc) and use non-default ports if it helps with policy or filtering.

Config reminder

API enable/disable and ports are in config.conf under node.http, node.rpc, and node.jsonrpc. Changing ports does not replace authentication or rate limiting.

Key Points

• Do not expose API ports publicly without authentication, rate limiting, and network controls.
• For production or high-value nodes, put the node behind a reverse proxy or gateway that enforces auth and limits.

<!-- Source references:

• https://github.com/tronprotocol/java-tron (README.md — "When exposing any of these APIs to a public interface...")
• https://developers.tron.network/docs/connect-to-the-tron-network

-->

java-tron APIs

After FullNode starts, the node exposes:

• HTTP API — HTTP API reference.
• gRPC — gRPC reference; high-performance, service-to-service.
• JSON-RPC — Ethereum-compatible; JSON-RPC methods.

Config (enable/disable and ports)

In config file (e.g. config.conf):

node {
  http {
    fullNodeEnable = true
    fullNodePort   = 8090
  }

  jsonrpc {
    httpFullNodeEnable = true
    httpFullNodePort   = 8545
  }

  rpc {
    enable = true
    port   = 9090
  }
}

Usage

• Public hosted HTTP (mainnet/testnet): TronGrid.
• When exposing APIs publicly: use authentication, rate limiting, and network access controls.

Key Points

• HTTP: typical REST-style TRON endpoints (wallet, node, etc.).
• gRPC: Wallet, WalletSolidity, etc.; use for server-to-server.
• JSON-RPC: use when integrating with Ethereum-style tooling (e.g. 8545 port).

<!-- Source references:

• https://github.com/tronprotocol/java-tron (README.md)
• https://tronprotocol.github.io/documentation-en/api/

-->

Build and Run java-tron

Build

Prerequisites: Linux or macOS; JDK 8 or 17; 4+ CPU cores, 16 GB RAM, 10 GB disk. Optional: use install_dependencies.sh.

git clone https://github.com/tronprotocol/java-tron.git
cd java-tron
git checkout -t origin/master
./gradlew clean build -x test

-x test skips tests. FullNode.jar and Toolkit.jar are in build/libs/.

As dependency (no build):

Gradle (JitPack):

repositories { maven { url 'https://jitpack.io' } }
dependencies { implementation 'com.github.tronprotocol:java-tron:develop-SNAPSHOT' }

Maven: add jitpack repository and com.github.tronprotocol:java-tron with version e.g. develop-SNAPSHOT.

Run Full Node

Mainnet (default config):

java -jar ./build/libs/FullNode.jar

With config file:

java -jar ./build/libs/FullNode.jar -c config.conf

Nile testnet: use Nile config and preferably build from nile-testnet:

java -jar ./build/libs/FullNode.jar -c config-nile.conf

SR (witness) mode: add -w (or --witness) and set localwitness = [ <private_key> ] in config.

Monitor sync: tail -f ./logs/tron.log.

Hardware (Mainnet)

Testnets can use lower specs. JVM tuning: JVM Parameter Optimization.

Key Points

• Building in IntelliJ: run ./gradlew build once first; use JDK 8 for Gradle; enable Annotation Processing.
• Proto compilation: project build compiles protos; or use protoc v3.4.0 manually.

<!-- Source references:

• https://github.com/tronprotocol/java-tron (README.md, build.md)
• https://tronprotocol.github.io/documentation-en/using_javatron/installing_javatron/

-->

java-tron Configuration

FullNode and SR are configured via a single config file (e.g. config.conf). Pass it with -c config.conf or --config config.conf.

Main blocks

Network and P2P

• node.p2p.version — Mainnet: 11111; Nile: 201910292; Shasta: 1. Must match network.
• node.active / node.passive — Optional peer IP:port lists.
• node.fastForward — Fast-sync peers (sample entries in default config).
• seed.node — Genesis/seed node list for the network (required for private/test nets).
• genesis.block — Genesis block definition (witnesses, timestamp, etc.); used for private/test nets.

APIs (under node)

• node.http — fullNodeEnable, fullNodePort (8090), solidityEnable/Port, PBFTEnable/PBFTPort.
• node.rpc — enable, port (50051), solidityEnable/Port, PBFTEnable/Port; gRPC tuning (thread, maxConnectionIdleInMillis, maxMessageSize, etc.).
• node.jsonrpc — httpFullNodeEnable, httpFullNodePort (8545), etc.

Enable/disable and ports here; when exposing publicly, use authentication, rate limiting, and network controls (see best-practices-api-security).

Super Representative (SR)

• localwitness — List with the SR account private key (hex). One key when using -w/--witness.
• localwitnesskeystore — Optional: path(s) to keystore file(s) instead of raw key in config.

Fill one of these when running as SR; keep config file secure.

Storage tuning

• storage.db.engine — "LEVELDB" or "ROCKSDB". ARM supports only ROCKSDB.
• storage.properties — Optional per-database config (name required; path, LevelDB options). Used for splitting DBs across disks or tuning; see Advanced Configurations.
• storage.dbSettings — RocksDB-only (levelNumber, blockSize, maxBytesForLevelBase, etc.). Change only if understood.

Advanced LevelDB/gRPC/backup options are documented in common/src/main/java/org/tron/core/config/README.md.

Usage

• Mainnet: use bundled framework/src/main/resources/config.conf (or copy).
• Nile: use config from nile-testnet repo.
• Private net: set seed.node, genesis.block, and optionally localwitness; align p2p.version and needSyncCheck with docs.

<!-- Source references:

• sources/tron-java/framework/src/main/resources/config.conf
• sources/tron-java/common/src/main/java/org/tron/core/config/README.md
• https://github.com/tronprotocol/java-tron (README.md, run.md)

-->

java-tron Overview

java-tron is the Java implementation of the TRON Protocol: a high-throughput (2000+ TPS), scalable blockchain with DPoS consensus. TRON Virtual Machine (TVM) is EVM-compatible for smart contracts.

Key Artifacts

Networks

• Mainnet — production; config: framework/src/main/resources/config.conf.
• Nile Testnet — forward-looking testnet; config: config-nile.conf. Build from nile-testnet repo when needed.
• Shasta Testnet — mirrors Mainnet; no public node peers; use TronGrid for programmatic access.
• Private networks — Private Network guide.

Key Points

• Linux/macOS only (Windows not supported). JDK 8 or 17.
• Full node: gateway to TRON network; HTTP and RPC APIs. SR node: add --witness; fill localwitness in config with SR private key.
• Official docs: documentation-en, TRON Developer Hub.

<!-- Source references:

• https://github.com/tronprotocol/java-tron (README.md)
• https://tronprotocol.github.io/documentation-en/

-->

Super Representative (SR) Node

An SR node is a FullNode that also produces blocks. Use -w or --witness and configure the witness key.

Launch

Mainnet (recommended: JAR):

java -jar FullNode.jar -p <your_private_key> --witness -c /path/to/config.conf

Or put the private key in config (see below) and run:

java -jar FullNode.jar --witness -c config.conf

Private testnet: Same pattern; config must define genesis and seed nodes (see below).

Config: localwitness

Set the SR account private key so the node can sign blocks.

• localwitness — List of one private key (hex). Example:

localwitness = [
  <your_private_key>
]

• localwitnesskeystore — Optional: list of keystore file paths instead of raw key.

When the witness account uses witnessPermission, set localWitnessAccountAddress to the witness account address and put the witnessPermission signer key in localwitness. Otherwise, put the witness account key in localwitness.

Private testnet SR setup

For a private chain where you control genesis:

1. genesis.block — Define witnesses with the SR address(es) and initial assets / timestamp / parentHash. Replace with your SR address. 2. seed.node — Set ip.list to the peer(s) (e.g. your node IP or other testnet nodes). All members must use the same genesis and compatible p2p.version. 3. block.needSyncCheck — Set to false for the first SR that starts the chain; set to true for others that sync from it. 4. node.p2p.version — Use a distinct version for your private net (e.g. 61 in older docs) so it does not mix with mainnet/testnet.

Then start with --witness and -c your_private_config.conf.

Key Points

• One active localwitness key when running as SR; config must be kept secure.
• Mainnet SR: use official TRON config and follow Super Representative documentation for eligibility and setup.
• Test on Nile or a private network before mainnet.

<!-- Source references:

• https://github.com/tronprotocol/java-tron (README.md, run.md)
• sources/tron-java/framework/src/main/resources/config.conf, config-localtest.conf
• https://tronprotocol.github.io/documentation-en/using_javatron/installing_javatron/#starting-a-block-production-node

-->

Chainbase Module

Chainbase is the storage layer for java-tron. It defines interfaces for databases that support rollback (e.g. for reorgs or consensus switches) and allows swapping the underlying engine (LevelDB or RocksDB).

Rollback and interfaces

• RevokingDatabase — Interface for a container that manages multiple revocable (rollback-capable) databases. SnapshotManager is the default implementation.
• TronStoreWithRevoking — Abstract base for stores that support rollback: state can be reverted to a previous checkpoint.
• Chainbase — Concrete implementation of TronStoreWithRevoking used for chain data.

Requirements for a store to plug in: state rollback mechanism and checkpoint-based fault tolerance so that chainbase can revert state when the consensus layer decides to switch chain (e.g. DPoS reorg).

Storage engines

• LevelDB — Default on x86; used by many DB-related Toolkit commands (archive, convert). Not available on ARM in some setups.
• RocksDB — Supported on all platforms including ARM; config via storage.db.engine = "ROCKSDB" and optional storage.dbSettings.

Both can be used as the underlying store for chainbase; the same storage.properties (name, path) apply. LevelDB-specific options (createIfMissing, blockSize, etc.) are documented in Advanced Configurations; RocksDB uses dbSettings.

Key Points

• Chainbase abstracts rollback and checkpointing; do not assume a single linear append-only DB when writing plugins or custom actuators that persist state.
• For custom persistent data in an actuator, consider a dedicated store that follows the chainbase rollback contract or stores only after finality.
• Toolkit operations (e.g. db convert, db lite) are engine- and platform-specific; see features-toolkit.

<!-- Source references:

• sources/tron-java/docs/modular-introduction-en.md
• sources/tron-java/common/src/main/java/org/tron/core/config/README.md
• https://github.com/tronprotocol/java-tron (modularization docs)

-->

Custom Actuator (java-tron)

Actuators execute specific transaction (contract) types. To add a new type:

1. Define contract in protocol (proto). 2. Register ContractType in Tron.proto. 3. Add gRPC/HTTP in api.proto (Wallet service). 4. Implement Actuator and register in WalletApi.

1. Define contract (protocol)

Create e.g. protocol/src/main/protos/core/contract/math_contract.proto:

syntax = "proto3";
package protocol;
option java_package = "org.tron.protos.contract";
message SumContract {
    int64 param1 = 1;
    int64 param2 = 2;
    bytes owner_address = 3;
}

2. Register ContractType

In protocol/src/main/protos/core/Tron.proto, inside Transaction.Contract.ContractType:

SumContract = 52;  // pick unused enum value

3. Add API (api.proto)

In src/main/protos/api/api.proto, Wallet service:

rpc InvokeSum (SumContract) returns (Transaction) {
  option (google.api.http) = {
    post: "/wallet/invokesum"
    body: "*"
    additional_bindings { get: "/wallet/invokesum" }
  };
};

4. Implement Actuator

Create class in org.tron.core.actuator, extending AbstractActuator:

public class SumActuator extends AbstractActuator {
  public SumActuator() {
    super(ContractType.SumContract, SumContract.class);
  }

  @Override
  public boolean execute(Object object) throws ContractExeException {
    TransactionResultCapsule ret = (TransactionResultCapsule) object;
    SumContract c = any.unpack(SumContract.class);
    long sum = c.getParam1() + c.getParam2();
    // persist or log; then:
    ret.setStatus(calcFee(), code.SUCESS);
    return true;
  }

  @Override
  public boolean validate() throws ContractValidateException {
    SumContract c = any.unpack(SumContract.class);
    if (!DecodeUtil.addressValid(c.getOwnerAddress().toByteArray())) throw new ContractValidateException("Invalid ownerAddress!");
    // other checks
    return true;
  }

  @Override
  public ByteString getOwnerAddress() throws InvalidProtocolBufferException {
    return any.unpack(SumContract.class).getOwnerAddress();
  }

  @Override
  public long calcFee() { return TRANSFER_FEE; }
}

5. Wire in WalletApi

In WalletApi (extends WalletImplBase), implement the RPC handler:

@Override
public void invokeSum(MathContract.SumContract req, StreamObserver<Transaction> responseObserver) {
  try {
    responseObserver.onNext(createTransactionCapsule(req, ContractType.SumContract).getInstance());
  } catch (ContractValidateException e) {
    responseObserver.onNext(null);
  }
  responseObserver.onCompleted();
}

Build

Project build compiles protos. Use project protoc version (e.g. v3.4.0) if compiling manually:

./gradlew build -x test

Key Points

• Contract definition and enum live in protocol; API in api.proto; execution in actuator + WalletApi.
• For persistent state, add or use a chainbase; for wallet-cli support, add CLI commands.

<!-- Source references:

• https://github.com/tronprotocol/java-tron (docs/implement-a-customized-actuator-en.md)

-->

Docker for java-tron

java-tron can be run via Docker: either build an image from source or use the official image. Useful for consistent environments and quick mainnet/testnet nodes.

Build image from source

cd java-tron
cd docker
docker build -t tronprotocol/java-tron .

Use official image

docker pull tronprotocol/java-tron

Run container

Default (mainnet, built-in config):

docker run -it -d -p 8090:8090 -p 8091:8091 -p 18888:18888 -p 50051:50051 --restart always tronprotocol/java-tron

Ports: 8090 (HTTP FullNode), 8091 (HTTP Solidity), 18888 (P2P), 50051 (gRPC). Map others if you enable JSON-RPC or PBFT ports.

Custom config and data

Mount config and data directories; pass -c, -d, and optionally -jvm and -w (SR):

docker run -it -d -p 8090:8090 -p 18888:18888 -p 50051:50051 \
  -v /host/conf:/java-tron/conf \
  -v /host/datadir:/java-tron/data \
  tronprotocol/java-tron \
  -jvm "{-Xmx10g -Xms10g}" \
  -c /java-tron/conf/config.conf \
  -d /java-tron/data \
  -w

• -v — Mount host conf and data into container.
• -c — Config path inside container (e.g. /java-tron/conf/config.conf).
• -d — Data/output directory inside container.
• -jvm — JVM options; must be in double quotes and braces, e.g. "{-Xmx10g -Xms10g}".
• -w — Start as Super Representative (witness mode).

Ensure the mounted conf directory contains the referenced config file.

Third-party quickstart (docker-tron-quickstart)

For a full dev stack (Full Node, Solidity Node, Event Server, TronWeb), use docker-tron-quickstart: pull trontools/quickstart and run per that repo. It exposes a single port (e.g. 9090) and sets up accounts for testing.

Key Points

• Official image defaults to mainnet; override with -c to a Nile or custom config.
• For production SR or high-load nodes, mount persistent volumes for config and data and set JVM options with -jvm.

<!-- Source references:

• sources/tron-java/quickstart.md
• https://github.com/tronprotocol/java-tron (README.md, quickstart.md)

-->

java-tron Modular Architecture

Modularization lets developers build app-specific chains: pluggable consensus, custom actuators, replaceable storage. Six modules:

Key Interfaces

ConsensusInterface: start, stop, receiveBlock, validBlock, applyBlock.

Actuator: execute(Object resultCapsule), validate(), getOwnerAddress(), calcFee().

Chainbase: Databases implement rollback and checkpoint; any implementation of the interface can be used as storage.

When to Use

• Custom chain: Swap consensus or storage via config / implementations.
• Custom transaction type: Add a new contract (proto), implement an Actuator, register in protocol and API layer.

<!-- Source references:

• https://github.com/tronprotocol/java-tron (docs/modular-introduction-en.md)

-->

Modular Deployment (Post-modularization)

After modularization, prefer launching via the distribution script instead of java -jar FullNode.jar (the latter may be deprecated).

Build and Unzip

git clone git@github.com:tronprotocol/java-tron.git
./gradlew build
# Output: java-tron-1.0.0.zip in build/distributions
cd build/distributions
unzip -o java-tron-1.0.0.zip
# Result: bin/ (scripts), lib/ (jars)

Startup

Use OS-appropriate script (*.bat on Windows; on Linux):

# default
java-tron-1.0.0/bin/FullNode

# with config (demos in framework/build/resources)
java-tron-1.0.0/bin/FullNode -c config.conf

# SR mode
java-tron-1.0.0/bin/FullNode -c config.conf -w

JVM Options

Edit bin/java-tron.vmoptions, e.g.:

-XX:+UseConcMarkSweepGC
-XX:+PrintGCDetails
-Xloggc:./gc.log
-XX:+PrintGCDateStamps
-XX:+CMSParallelRemarkEnabled
-XX:ReservedCodeCacheSize=256m
-XX:+CMSScavengeBeforeRemark

Key Points

• Script-based launch is the recommended path for modular deployments.
• Config and demo configs live under framework/build/resources or the unpacked distribution.

<!-- Source references:

• https://github.com/tronprotocol/java-tron (docs/modular-deployment-en.md)

-->

start.sh Quick Start Script

The start.sh script in the java-tron root can run or stop FullNode, and optionally clone/build or fetch the latest release. Target: x86_64, JDK 8 (see start.sh.simple for ARM64/JDK 17).

Service operation

Build / release

Use with --run to start after obtaining or building:

sh start.sh --release --run
sh start.sh -cb --run

Manifest rebuild (LevelDB)

When using -d (or default output-directory), the script can rebuild the manifest (TIP-298 / LevelDB startup optimization). Options:

Examples:

sh start.sh --run -d /tmp/db/database -m 128 -b 64000
sh start.sh --release --run -d /tmp/db/database -m 128 -b 64000

Typical usage

• Local JAR, default config/data: sh start.sh --run
• Custom config and data: sh start.sh --run -c /path/config.conf -d /path/output-directory
• Stop: sh start.sh --stop
• Latest release and run: sh start.sh --release --run
• Clone, build, run: sh start.sh -cb --run

Key Points

• FullNode.jar, start.sh, and config.conf are usually in the same directory (or use -j/-c/-d).
• After -cb, a FullNode/ directory is created with JAR and config copied; script can run from there.
• Manifest rebuild reduces LevelDB startup time; use -m/-b when you need to tune it.

<!-- Source references:

• sources/tron-java/shell.md
• https://github.com/tronprotocol/java-tron (README.md, shell.md)

-->

Toolkit (Toolkit.jar)

Toolkit.jar is built with java-tron in build/libs/. It provides node maintenance and DB operations. Run: java -jar Toolkit.jar <command> [options].

Commands

db archive (x86 + LevelDB)

Reformat manifest for the current database. Compatible with ArchiveManifest behavior.

java -jar Toolkit.jar db archive [-h] [-b=<maxBatchSize>] [-d=<databaseDirectory>] [-m=<maxManifestSize>]

• -d — Database directory (default: output-directory/database).
• -b — Batch manifest size (default: 80000).
• -m — Minimum manifest size in MB; only optimize when manifest exceeds this (default: 0).

db convert (x86 + LevelDB)

Convert LevelDB data to RocksDB.

java -jar Toolkit.jar db convert [-h] <src> <dest>
# e.g.
java -jar Toolkit.jar db convert output-directory/database /tmp/database

db cp

Copy LevelDB or RocksDB by creating hard links (same file system). Fast clone for backups or duplicates.

java -jar Toolkit.jar db cp [-h] <src> <dest>
# e.g.
java -jar Toolkit.jar db cp output-directory/database /tmp/database

db lite (LevelDB not on ARM)

Produce or use lite (split) datasets: snapshot vs history. For Lite FullNode workflows.

• split — Split full DB into snapshot and/or history datasets.
• merge — Merge snapshot and history back.

# split: snapshot
java -jar Toolkit.jar db lite -o split -t snapshot --fn-data-path output-directory/database --dataset-path /tmp
# split: history
java -jar Toolkit.jar db lite -o split -t history --fn-data-path output-directory/database --dataset-path /tmp
# merge
java -jar Toolkit.jar db lite -o merge --fn-data-path /tmp/snapshot --dataset-path /tmp/history

• -o — operate: split | merge (default: split).
• -t — type when splitting: snapshot | history (default: snapshot).
• -fn / --fn-data-path — FullNode database path.
• -ds / --dataset-path — For split: output path for snapshot/history; for merge: path to history dataset.

db mv

Move selected DBs to new paths (e.g. move block, trans to HDD). Paths are defined in config storage.properties; then run:

java -jar Toolkit.jar db mv [-h] [-c=<config>] [-d=<database-directory>]
# e.g.
java -jar Toolkit.jar db mv -c main_net_config.conf -d /data/tron/output-directory

db root (LevelDB; large DBs may hit GC limit)

Compute Merkle root for a tiny DB. Used for verification.

java -jar Toolkit.jar db root [-h] [<src>] [--db=dbname]

Key Points

• archive and convert require x86 and LevelDB. lite is not available on ARM (LevelDB).
• Use db cp for quick copies on same filesystem; db convert when switching to RocksDB or moving across systems.
• db mv reads paths from config; set storage.properties for the DBs to move before running.

<!-- Source references:

• sources/tron-java/plugins/README.md
• https://github.com/tronprotocol/java-tron (README.md)
• https://tronprotocol.github.io/documentation-en/using_javatron/toolkit/

-->