tronbox/tre repository overview

⁠🐳 TronBox Runtime Environment

Run a single-node, isolated TRON development environment with one Docker container.

TronBox Runtime Environment (TRE) is intended for local development, automated tests, and CI. It starts a local block-producing node and exposes the APIs commonly used by TronBox, TronWeb, and TRON-compatible tooling.

⚠️ Development only

This image exposes funded test accounts and unauthenticated privileged APIs, including /admin/* and /tre. Never expose it to an untrusted network or use it with production keys or funds.

⁠✨ What's new in 2.0.0

Version 2.0.0 packages a TRE-specific java-tron 4.8.2 build and replaces the multi-process 1.x runtime with a unified service:

• One Java process replaces the legacy FullNode, Node.js proxy, Redis, PM2, Eventron, and BlockParser runtime.
• One publicly exposed HTTP endpoint on port 9090 for Wallet, Solidity, JSON-RPC, account administration, health checks, and event queries.
• Eventron-compatible legacy and /v1 APIs implemented directly against in-process chain state.
• Automatic BIP39/BIP44 test-account generation and direct funding inside the node.
• RocksDB storage with checkpoint v2 enabled.
• A jlink-trimmed Java 17 runtime on Ubuntu 22.04.
• Native multi-platform images for linux/amd64 and linux/arm64.

The private network runs with peer-to-peer networking disabled and produces blocks locally with the built-in genesis witness.

⁠🔗 TRE and java-tron versions

ℹ️ Current release: TRE 2.0.0 bundles java-tron 4.8.2, based on the TRE build GreatVoyage-v4.8.2-108-g05928c9b6d.

TRE and java-tron use independent version numbers. The image tag identifies the TRE runtime; codeVersion from /wallet/getnodeinfo identifies the bundled java-tron version. TRE builds also contain runtime-specific changes on top of the listed java-tron release, so the exact build identifier is included below.

This matrix covers the versioned tags currently published in the Docker Hub tag list⁠. The moving latest and dev tags currently resolve to the same image as 2.0.0.

⁠🏷️ Image tags

The examples below omit the tag and therefore use latest. Use the versioned tag when you need to stay on 2.0.0. For strict immutability, pin the published image digest instead of a tag.

⁠🚀 Quick start

Pull and run the current stable release:

docker pull tronbox/tre

docker run --rm \
  --name tron \
  -p 127.0.0.1:9090:9090 \
  tronbox/tre

TRE runs in the foreground and writes its logs to standard output. In another terminal, check that the HTTP service is alive:

curl -fsS http://127.0.0.1:9090/healthcheck

Expected response:

OK

To request JSON instead:

curl -fsS \
  -H 'Accept: application/json' \
  http://127.0.0.1:9090/healthcheck

{"ok":true}

/healthcheck is a liveness endpoint. Account generation and funding start asynchronously after the node launches and normally take a few more seconds. If your test needs funded accounts, wait until this command succeeds:

until curl -fsS http://127.0.0.1:9090/admin/accounts | grep -q 'Available Accounts'; do
  sleep 1
done

Follow the node logs with:

docker logs -f tron

Stop the node with:

docker stop tron

Because the startup script finalizes its configuration inside the container, create a fresh container for each run. Using --rm handles this automatically.

⁠🔄 Migrating from 1.x

The public base URL remains http://127.0.0.1:9090, so most TronBox and TronWeb configurations do not need to change. The implementation behind that endpoint is now substantially simpler:

If your scripts inspect processes or connect to old internal sidecar ports, update them to use the unified API on port 9090. Existing clients that already use fullHost on port 9090 should continue to work without routing changes.

⁠🔌 Unified API endpoint

The main HTTP routes are available through http://127.0.0.1:9090:

Examples:

# Latest block through the Wallet API
curl -fsS http://127.0.0.1:9090/wallet/getnowblock

# Node and java-tron version information
curl -fsS http://127.0.0.1:9090/wallet/getnodeinfo

# Ethereum-compatible block number
curl -fsS \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://127.0.0.1:9090/jsonrpc

# TRE v1 service information
curl -fsS http://127.0.0.1:9090/v1/info

⁠📡 gRPC

The gRPC services remain available on their native ports. Publish them only when your tooling needs direct gRPC access:

docker run --rm \
  --name tron \
  -p 127.0.0.1:9090:9090 \
  -p 127.0.0.1:50051:50051 \
  -p 127.0.0.1:50052:50052 \
  tronbox/tre

⁠👤 Test accounts

On startup, TRE generates 10 BIP39/BIP44 accounts by default and funds them with 10,000 TRX each. The generated addresses, private keys, mnemonic, and HD path are printed to the container log. When the built-in genesis private key is enabled, that account keeps its existing genesis balance instead of receiving defaultBalance.

Retrieve them at any time:

# Base58 addresses
curl -fsS http://127.0.0.1:9090/admin/accounts

# Hex addresses
curl -fsS 'http://127.0.0.1:9090/admin/accounts?format=hex'

# Base58 and hex addresses
curl -fsS 'http://127.0.0.1:9090/admin/accounts?format=all'

# Machine-readable account data
curl -fsS http://127.0.0.1:9090/admin/accounts-json

⁠🔑 Deterministic genesis account

For the same first private key on every fresh run, enable the built-in genesis key. This applies when TRE does not load an existing /config/accounts.json:

docker run --rm \
  --name tron \
  -p 127.0.0.1:9090:9090 \
  -e useDefaultPrivateKey=true \
  tronbox/tre

The first private key is then:

0000000000000000000000000000000000000000000000000000000000000001

This key is public and must only be used for local development.

⁠⚙️ Account options

Pass account settings as environment variables:

docker run --rm \
  --name tron \
  -p 127.0.0.1:9090:9090 \
  -e accounts=20 \
  -e defaultBalance=50000 \
  -e useDefaultPrivateKey=true \
  tronbox/tre

If /config/accounts.json already exists, TRE loads it before considering accounts, mnemonic, seed, hdPath, or useDefaultPrivateKey. To derive a different account set, use a new volume or remove that file before starting a fresh container.

Append and fund an additional account batch at runtime:

curl -fsS \
  'http://127.0.0.1:9090/admin/temporary-accounts-generation?accounts=5&defaultBalance=20000'

Despite the legacy endpoint name, the added keys are written to accounts.json. The requested balance is also reapplied to every known non-genesis test account, not only the newly added batch.

⁠💾 Persist account identities

TRE stores generated account metadata in /config/accounts.json. Mount /config to reuse the same mnemonic and private keys across fresh containers. This file contains private keys in plain text; do not commit it or share it.

Only account identities are persisted. Every fresh container starts a fresh chain and funds the saved accounts again; mounting /config does not preserve blocks, transactions, or contracts.

docker volume create tronbox-tre-config

docker run --rm \
  --name tron \
  -p 127.0.0.1:9090:9090 \
  -v tronbox-tre-config:/config \
  tronbox/tre

You can also use a host directory:

mkdir -p ./tre-config

docker run --rm \
  --name tron \
  -p 127.0.0.1:9090:9090 \
  -v "$PWD/tre-config:/config" \
  tronbox/tre

⁠✅ Pre-approved proposals

The preapprove environment variable accepts comma-separated key:value pairs and appends them to the genesis committee configuration before the node starts:

docker run --rm \
  --name tron \
  -p 127.0.0.1:9090:9090 \
  -e 'preapprove=multiSignFee:1,allowMultiSign:1' \
  tronbox/tre

Use proposal names supported by the bundled java-tron version.

⁠🧰 TronBox configuration

Start TRE with the deterministic genesis key:

docker run --rm \
  --name tron \
  -p 127.0.0.1:9090:9090 \
  -e useDefaultPrivateKey=true \
  tronbox/tre

Then configure tronbox.js:

module.exports = {
  networks: {
    development: {
      privateKey: '0000000000000000000000000000000000000000000000000000000000000001',
      fullHost: 'http://127.0.0.1:9090',
      network_id: '9'
    }
  }
};

⁠🌐 TronWeb configuration

const { TronWeb } = require('tronweb');

const tronWeb = new TronWeb({
  fullHost: 'http://127.0.0.1:9090',
  privateKey: '0000000000000000000000000000000000000000000000000000000000000001'
});

⁠📝 Logging options

TRE writes one concise access-log line per request by default. Additional request and response details are opt-in:

Verbose logs can contain transaction data, query parameters, and sensitive test credentials. Treat container logs as sensitive and do not publish them without review.

Example:

docker run --rm \
  --name tron \
  -p 127.0.0.1:9090:9090 \
  -e verbose=true \
  -e formatJson=true \
  -e NO_COLOR=1 \
  tronbox/tre

The request-logging options can also be changed in memory through /admin/set-env:

curl -fsS \
  'http://127.0.0.1:9090/admin/set-env?showBody=true&showQueryString=true'

⁠🛠️ Troubleshooting

⁠⏳ The liveness check fails during startup

The Java process and RocksDB need a few seconds to initialize. Follow the logs until the unified HTTP service is listening. Remember that funded accounts may take a few seconds longer than the liveness endpoint:

docker logs -f tron

⁠🚧 Port 9090 is already in use

Map the container port to another host port:

docker run --rm \
  --name tron \
  -p 127.0.0.1:19090:9090 \
  tronbox/tre

Then use http://127.0.0.1:19090 as fullHost.

⁠🔎 Show the bundled java-tron version

TRE 2.0.0 is the Docker runtime release number. The bundled java-tron software has its own version, which is reported by:

curl -fsS http://127.0.0.1:9090/wallet/getnodeinfo

⁠⚙️ Inspect the running process

Version 2.0.0 intentionally runs as a single Java process:

docker top tron

⁠📚 Related projects and license

This image packages a TRE-specific java-tron build for local development.

• TRE image on Docker Hub⁠
• java-tron upstream source⁠
• Original docker-tron-quickstart project⁠
• java-tron LGPL-3.0 license⁠