Tron Goblin Node

A Rust implementation of the TRON full-node protocol — the same role java-tron plays, written from scratch in Rust with byte-exact database and wire compatibility as a stated goal.

Status: pre-release, experimental. Pointed at public mainnet from a java-tron RocksDB snapshot, it catches up a multi-day backlog, holds the live tip, and applies real blocks into RocksDB chainbase state — and the block hashes it computes from its own executed state match the canonical chain block-for-block. Transactions run through an optional Block-STM parallel executor that stays byte-identical to the serial path, and it rebuilds head state on a fork-switch (reorg-driven rollback). Still open: full state-exactness across every edge case (block headers carry no state root, so that's verified separately by RPC reads — see below), long-running mainnet soak, and assorted polish. See Status for specifics. This is not a drop-in production replacement for java-tron today — though that is the goal.

What this is

tron-goblin-node is a workspace of small, focused crates that reproduce java-tron's behaviour piece by piece. The goal is one binary you can point at a peer and have it stay in lockstep with the java-tron reference implementation — same hashes, same state, same RPC responses.

Concretely, this means:

• Byte-exact RocksDB compatibility. A java-tron snapshot can be planted under data_dir/db/ with tron-node import-snapshot, and the daemon picks up where the java node left off.
• Wire-compatible P2P. The TRON adv-broadcast protocol (HelloMessage, BlockInventory, Inventory, FetchInvData, Block, Trx) is implemented at the byte level. A tron-goblin-node instance hand-shakes with a java-tron mainnet peer and pulls real blocks.
• java-tron API surface. JSON-RPC (eth_* + wallet/*) and gRPC (Wallet / WalletSolidity / Database / Monitor / Network) are both served. TronWeb, the Java SDK, and TronGrid clients can point at this node without modification.

See it for yourself

A block hash commits to the full header and the transaction Merkle root — so if a node's block hash matches the network's, every transaction in that block executed to the same result. Sync this node against mainnet, then compare its own independently-computed block hashes against the official trongrid.io API for the most recent blocks:

CT='-H Content-Type:application/json'
H=$(curl -s $CT -X POST http://127.0.0.1:8090/wallet/getnowblock -d '{}' | jq .block_header.raw_data.number)
for N in $(seq $((H-6)) $((H-2))); do
  O=$(curl -s $CT -X POST http://127.0.0.1:8090/wallet/getblockbynum -d "{\"num\":$N}" | jq -r .blockID)
  T=$(curl -s $CT -X POST https://api.trongrid.io/wallet/getblockbynum  -d "{\"num\":$N}" | jq -r .blockID)
  [ "$O" = "$T" ] && echo "✔ #$N  $O" || echo "✘ #$N  MISMATCH"
done

✔ #83425584  0000000004f8f930899faeaa52baa520eded6c93d36fb9a384d77f978817664f
✔ #83425585  0000000004f8f93133171bdd150fab96f1fffc78894c4c21d25b1d39d491e158
✔ #83425586  0000000004f8f932d13f30de9fc5856ca13ca21d34ef7080ac5195fdce0c9c5d
✔ #83425587  0000000004f8f9339d1953474fac8c5fb3ce6fd7c9d31dba40ce05eb7830792a
✔ #83425588  0000000004f8f934a8d80f6d0164af2e9c2086e2af088e09a378a4cfa9238ebd

Matching the header and tx-merkle root is only half the story, though — TRON headers commit to no state root, so the resulting state is verified separately (see Compatibility notes). That distinction is the whole reason this project is careful about the word "parity."

Motivation

This node exists because of trongoblin.com.

Running production infrastructure on TRON means living downstream of java-tron — its release cadence, its operational quirks, its resource profile. A second independent implementation in a different language is the cheapest way to harden the ecosystem: divergences get surfaced as bugs instead of silently propagating, snapshot and RPC paths get a second set of eyes, and operators get a node they can actually profile, debug, and tune without fighting a JVM.

Status

What works today:

• ✅ Crypto vertical slice: secp256k1, SM2 (via pure-Rust sm2 crate), keccak256, ripemd160, sha256, base58check.
• ✅ Proto / wire / types layer — produces hashes identical to java-tron for blocks and transactions across the live chain.
• ✅ Block import: decode + validate + execute live mainnet blocks into per-store RocksDB state.
• ✅ Block-STM parallel execution (optional, vm.parallel_exec). Within a block, transactions execute optimistically across cores with MVCC read/write-set tracking and re-execute only the ones that conflict, producing a result byte-identical to the serial loop — pinned by parallel-vs-serial equivalence tests, since TRON's absent state root means a silent divergence would otherwise be invisible. On a many-core machine, transaction-heavy mainnet blocks apply roughly 2× faster (more on the densest, contract-heavy blocks); light blocks skip the machinery and run serially.
• ✅ Actuator dispatch: full coverage of java-tron's contract types (Transfer, AssetTransfer, Exchange*, FreezeBalance*, Witness*, Proposal*, TriggerSmartContract, CreateSmartContract, …).
• ✅ TVM: smart-contract execution on a revm-based interpreter with TRON's energy schedule, the TRC-10 transfer fields + TRON-extended opcodes (0xd0..0xd4), the per-contract dynamic-energy model, and Sapling shielded-TRC-20 (Groth16) proving. Real mainnet contracts execute against snapshot state; read-only (triggerconstantcontract) return data for tested TRC-20s (USDT and others) matches java-tron byte-for-byte. Energy-accounting parity is close, with known residual gaps still being chased.
• ✅ JSON-RPC + REST: the eth_* surface that java-tron exposes plus the /wallet/* REST endpoints, backed by chainbase reads.
• ✅ gRPC server on the Wallet / WalletSolidity / Database / Monitor / Network services — no Status::unimplemented stubs left.
• ✅ Mempool with signer recovery + dedup + expiration eviction + on-disk persistence (java-tron's pending queue is volatile; tron-goblin-node reloads pending txs across restarts), plus state-aware admission validation — the same precondition checks a peer runs on receive (fee / permission / balance / ref-block, and smart-contract Trigger/Create preconditions) so we don't relay transactions a peer would reject.
• ✅ Snapshot import / export (import-snapshot, import-live, export-snapshot, verify-snapshot) for moving state to and from a java-tron data directory.
• ✅ Multi-peer sync from public mainnet: a java-tron-style block-chain locator (SyncBlockChain → drain queue → re-request → live-tip BlockInventory advertise at head), pipelined with rate-limit + keepalive parity. A single active syncer is elected across the per-peer driver fleet (the rest stay connected as standby and fail over if it stalls), inbound SyncBlockChain is served so peers can sync from us, and the Hello advertises a truthful solid/lowest block. Fetch is cooperative across the peer fleet — many peers download the backlog into a shared pool in parallel while one driver applies in chain order. Live-validated catching up a multi-day backlog off public mainnet and holding the tip, not just against a local reference node.
• ✅ SR block production: when [witness] is configured, the daemon runs java-tron's DposTask loop — slot ownership check, drain mempool, produce + sign + apply + broadcast.
• ✅ PBFT vote runtime: Prepare → Commit → solidify state machine driven off the SR runtime; signatures persist to PbftSignDataStore and LATEST_SOLIDIFIED_BLOCK_NUM advances.
• ✅ Reorg-driven state rollback in the sync path. On a sibling-fork overtake the driver rolls the losing branch's state back (per-block undo records restore every mutated store, incl. head pointers), re-applies the winning branch, re-pushes reverted txs to the mempool, and recovers atomically if a re-apply fails. Two backends: BlockUndoStore (default) and a SnapshotManager-style overlay stack (--snapshot-reorg). The solidified/irreversible block is never crossed (forks diverging below it are rejected).
• ✅ Prometheus /metrics endpoint (--metrics-port, default 9090) exposes ~29 metrics across chain head, sync flow, reorg / fork-tree outcomes, SR block production, PBFT message traffic, mempool (size + accepted + evicted + rejected-by-reason labels), active peers, and per-method RPC counters.

What doesn't work yet (real, currently-open gaps):

• ❌ Long-running mainnet soak / endurance. Short live sessions pass; multi-hour, multi-day stability under realistic peer churn hasn't been characterized.
• ❌ A couple of delegated-resource (Stake 2.0) refinements. The locked-delegation lifecycle is correct (delegate-with-lock, lock expiry, undelegate-after-expiry), but two java-tron behaviours aren't ported yet: the receiver bandwidth/energy usage-transfer on undelegate (a transient gap — the usage counters self-heal over the ~1-day decay window), and on-write maintenance of the DelegatedResourceAccountIndex lookup that backs getdelegatedresourceaccountindex (the store methods exist but aren't wired into the actuators).
• ❌ Probably a number of other things. java-tron is large and old; some quirks will only surface when a specific client or workload hits them. This list will be updated as new items are discovered.

Tests & metrics

Parity work that doesn't have a test pinning it isn't real parity — java-tron's behaviour is too nuanced to maintain by inspection alone. So coverage is dense: every actuator branch, every RPC shape, every chainbase encoding has at least one test that fails if the byte layout drifts.

Metric	Count
Workspace tests passing	1883
Ignored (gated on Sapling proving, ~50 MB params + 1–2 s each)	9
Integration test files (crates/*/tests/)	109
Source modules with #[cfg(test)] blocks	94

Per-crate breakdown of the test surface (where coverage lives is where parity risk lives):

Crate	Tests	Crate	Tests
tron-actuator	317	tron-net	56
tron-rpc	289	tron-types	46
tron-tvm	280	tron-crypto	34
tron-node	308	tron-mempool	25
tron-chainbase	207	tron-wallet	22
tron-executor	121	tron-eventer	14
tron-consensus	87	tron-replay	6
tron-grpc	63	tron-proto	8

Notable test categories:

• Behaviour-pinned against java-tron: actuator validate/execute paths, hash and signing vectors, RocksDB key encodings, RPC response shapes, energy / bandwidth accounting.
• Live mainnet observation: peer handshake, adv-broadcast framing, and block-application tests run against captured live fixtures (see crates/tron-net/tests/live_mainnet.rs, crates/tron-node/tests/live_tip_observation.rs).
• Shielded proving: #[ignore]-gated Groth16 round-trips for mint / transfer / burn under crates/tron-grpc/tests/create_shielded_*.rs. Run with cargo test --release -- --ignored.
• Deliberate java-tron deviations: each of the ~handful of intentional behaviour gaps (e.g. createtransaction permissiveness, getaccount unknown-address shape) has a test that asserts our shape and references the java-tron site it diverges from.

What coverage doesn't include yet:

• Reorg-driven state rollback is unit-tested at the sync-driver level (fork-switch head move, per-block state rollback, mempool re-push, mid-reorg failure recovery, both undo-store and snapshot-stack backends), but not yet exercised under a live sibling-fork overtake on mainnet.
• Long-running soak / load tests against mainnet snapshots. Manual for now; CI integration is on the observability backlog.

The whole sweep (default + ignored) finishes in under 90 s on a modern laptop:

cargo test --workspace --release -- --include-ignored

Layout

The workspace is split into one crate per concern. java-tron's modules are big, monolithic Java packages; this repo flattens them out so each crate is something you can hold in your head.

Crate	Role
tron-crypto	secp256k1 / SM2 / keccak / ripemd / sha256 / base58check.
tron-proto	Protobuf message types. Wire-compatible with java-tron.
tron-types	Capsule wrappers over tron-proto — hash, id, merkle-root conventions.
tron-chainbase	Storage: per-store key/value codecs over a pluggable KV backend.
tron-net	Wire framing + message types for the TRON P2P protocol.
tron-mempool	Validating mempool: decode + signer recovery + dedup + expiration.
tron-actuator	Per-contract (validate, execute) pairs — reproduces java-tron actuator semantics.
tron-executor	Block-level orchestrator. Validates structure, applies txs via the actuator dispatch table — serial or Block-STM parallel.
tron-consensus	DPoS slot scheduling, witness validation, maintenance period, fork choice.
tron-tvm	TRON precompiles + energy model + revm-based contract execution.
tron-rpc	Ethereum-compatible JSON-RPC server backed by chainbase.
tron-grpc	gRPC (Wallet / WalletSolidity / Database / Monitor / Network). Wraps tron-rpc.
tron-eventer	Event subscribe / logsfilter — per-block, per-tx, per-contract-event/log triggers.
tron-wallet	Key management + transaction signing CLI. Reads java-tron-compatible v3 keystores.
tron-replay	CLI for generating + validating length-delimited TRON block streams.
tron-node	Full-node daemon binary — opens stores, runs RPC, syncs blocks.

Four revm-* crates are vendored forks needed to plug TRON's TRC-10 transfer fields and the five TRON-extended opcodes (0xd0..0xd4) into revm's CALL machinery without re-implementing gas accounting and journal logic. All other revm crates come from crates.io unchanged.

Build

Prerequisites:

• Rust 1.80+. Stable toolchain is fine.

• Protoc. Used by tron-proto's build script. protoc --version should print 3.x or 5.x.

• libclang. Pulled in transitively by rocksdb → librocksdb-sys → bindgen. On Fedora / RHEL / Arch without the clang meta-package you'll need to create a libclang.so symlink — run the shim script once after cloning:

  ./scripts/setup-libclang.sh

  The script is idempotent and auto-detects the highest-versioned libclang on the host (Debian / Ubuntu / macOS paths included). .cargo/config.toml points LIBCLANG_PATH at the shim directory it creates.

Then:

cargo build --release

The full workspace compiles in ~3–5 minutes on a modern machine. Tests:

cargo test --workspace            # 1800+ tests, all defaults
cargo test --workspace --release -- --ignored
                                  # adds 9 Sapling-proving tests
                                  # (~50 MB Groth16 params + 1-2s each)

Run

Initialise a data directory:

./target/release/tron-node init --data-dir ./mainnet-data

Start the daemon against the mainnet seed peers:

./target/release/tron-node start \
    --data-dir ./mainnet-data \
    --rpc-port 8545

Or against a specific peer:

./target/release/tron-node start \
    --data-dir ./mainnet-data \
    --peer 18.221.130.41:18888

If you have your own java-tron node on the LAN and want a clean sync-from-genesis test against just that peer (no public-mainnet noise), there's a wrapper script that handles fresh-data-dir setup, TCP reachability pre-flight, log capture, and a post-run summary:

./scripts/sync-from-peer.sh <your-node-host>:18888 --max-blocks 100000

Run with --help for all options.

To plant a java-tron snapshot first (skip the genesis-walk and start from a recent state):

./target/release/tron-node import-snapshot \
    --from ./path/to/java-tron-snapshot.tar.gz \
    --data-dir ./mainnet-data

The snapshot must be RocksDB. This node is RocksDB-only — there is no LevelDB backend. A java-tron LevelDB snapshot (db.engine = LEVELDB, the older default) will not open: RocksDB reads LevelDB SSTs only partially (you'll see Cannot find Properties block from file in the logs) and can crash trying to rewrite them. Use a RocksDB snapshot (db.engine = ROCKSDB — java-tron's recommended engine), or convert a LevelDB one first with java-tron's Toolkit db convert.

tron-node --help lists every subcommand with its flags.

Configuration is TOML, not java-tron's HOCON — config files are intentionally not drop-in. State directories are byte-exact compatible; runtime config is its own surface. A fully-annotated starting point ships at config.example.toml (every key set to its built-in default); copy it and pass it with --config.

Compatibility notes

• Database: byte-exact, per-store RocksDB layout — RocksDB-only, no LevelDB backend. A java-tron snapshot is a tron-node data directory after import-snapshot, provided it was written with db.engine = ROCKSDB; LevelDB snapshots are not supported.
• P2P: byte-exact handshake + adv-broadcast. The node identifies itself on the wire as tron-goblin/0.0.1.
• JSON-RPC + gRPC: response shapes match java-tron's. Deliberate deviations (e.g. createtransaction permissiveness, getaccount on unknown addresses) are pinned in tests and documented at the call site.
• Config: TOML, not HOCON. Pull settings explicitly when porting from a java-tron config.conf.
• State parity is verified by reads, not by block hashes. TRON block headers commit to the transaction Merkle root but not to an enforced state root, so a state-computation bug can hide behind block hashes that are byte-for-byte identical to the reference chain. Parity of the resulting state is therefore checked by comparing RPC reads (getaccount, delegated-resource queries, …) against a java-tron node — not by hash equality alone. (This is exactly how the delegated-resource divergence in Status was found.)

Reference implementation

The .proto definitions needed to build are vendored at crates/tron-proto/vendored/java-tron/, so a fresh clone builds without needing the full java-tron repo on disk.

Parity work is still grounded in side-by-side reading of the java-tron source. If you want to run that comparison yourself, clone java-tron and tronprotocol/documentation-en next to this checkout — they're gitignored on purpose so this repo stays small:

git clone https://github.com/tronprotocol/java-tron.git
git clone https://github.com/tronprotocol/documentation-en.git tronprotocol/documentation-en

If you want the build to consume .proto files from a parallel java-tron clone instead of the vendored copy (useful when chasing a wire-format change before re-vendoring), point both build.rs scripts at it via:

export JAVA_TRON_PROTO_ROOT=$PWD/java-tron/protocol/src/main/protos
cargo build --release

Acknowledgements

This project stands on a stack of other people's hard work. Thanks in particular to:

• java-tron — the reference implementation. Every parity decision in this repo was grounded by reading the Java source. Without it there is no spec to mirror.
• revm — Dragan Rakita and the revm contributors. We use revm as a library and vendored four of its crates as forks to slot in TRON's TRC-10 transfer fields and the five TRON-extended opcodes (0xd0..0xd4) without reimplementing CALL's gas + journal logic.
• RustCrypto — k256 (the secp256k1 path), sm2 (the SM2 signature path), sha2, sha3, ripemd, ecdsa, elliptic-curve. The whole crypto stack underneath tron-crypto is RustCrypto crates plus a thin TRON shim.
• Zcash / Sapling crates — sapling-crypto, bls12_381, jubjub, plus wagyu-zcash-parameters for the embedded ~50 MB Groth16 MPC parameters. Without these, the shielded TRC-20 (mint / transfer / burn) prover would have been a multi-month project on its own.
• RocksDB and the rust-rocksdb bindings — the storage substrate every chainbase store opens against. java-tron's on-disk format is RocksDB; reusing the same engine is what makes byte-exact DB compatibility tractable.
• Tokio, axum, tonic, and prost — the async runtime, HTTP server, gRPC + Protobuf stack underneath every network surface in the node.
• eth_trie — Ethereum Merkle-Patricia-Trie semantics for the account-state-root path TRON inherits from Ethereum.
• tracing — structured logging across every crate.

If you maintain a crate we depend on and you're not listed here, that's an oversight — please open an issue and we'll fix it.

License

LGPL-3.0-or-later. See LICENSE.

This matches java-tron's license. If you redistribute a modified version, the LGPL's source-availability terms apply to the modified crates.