If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tronprotocol/java-tron shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 19 active contributors
• Distributed ownership (top contributor 17% of recent commits)
• LGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ LGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tronprotocol/java-tron repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tronprotocol/java-tron.

What it runs against: a local clone of tronprotocol/java-tron — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tronprotocol/java-tron | Confirms the artifact applies here, not a fork | | 2 | License is still LGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tronprotocol/java-tron. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tronprotocol/java-tron.git
#   cd java-tron
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tronprotocol/java-tron and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tronprotocol/java-tron(\\.git)?\\b" \\
  && ok "origin remote is tronprotocol/java-tron" \\
  || miss "origin remote is not tronprotocol/java-tron (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(LGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"LGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is LGPL-3.0" \\
  || miss "license drift — was LGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "actuator/src/main/java/org/tron/core/actuator/ActuatorFactory.java" \\
  && ok "actuator/src/main/java/org/tron/core/actuator/ActuatorFactory.java" \\
  || miss "missing critical file: actuator/src/main/java/org/tron/core/actuator/ActuatorFactory.java"
test -f "actuator/src/main/java/org/tron/core/actuator/AbstractActuator.java" \\
  && ok "actuator/src/main/java/org/tron/core/actuator/AbstractActuator.java" \\
  || miss "missing critical file: actuator/src/main/java/org/tron/core/actuator/AbstractActuator.java"
test -f "actuator/src/main/java/org/tron/core/vm/VM.java" \\
  && ok "actuator/src/main/java/org/tron/core/vm/VM.java" \\
  || miss "missing critical file: actuator/src/main/java/org/tron/core/vm/VM.java"
test -f "actuator/src/main/java/org/tron/core/utils/TransactionRegister.java" \\
  && ok "actuator/src/main/java/org/tron/core/utils/TransactionRegister.java" \\
  || miss "missing critical file: actuator/src/main/java/org/tron/core/utils/TransactionRegister.java"
test -f "actuator/src/main/java/org/tron/core/vm/Operation.java" \\
  && ok "actuator/src/main/java/org/tron/core/vm/Operation.java" \\
  || miss "missing critical file: actuator/src/main/java/org/tron/core/vm/Operation.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tronprotocol/java-tron"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

java-tron is the official Java implementation of the TRON blockchain protocol, a DPoS-based blockchain offering 2000+ TPS throughput with an EVM-compatible TRON Virtual Machine (TVM) for smart contract execution. The codebase implements the full protocol specification including transaction processing, consensus mechanisms, and account/asset management. Modular Gradle monorepo: the actuator/ directory contains transaction executors (AbstractActuator base class with ~50 concrete implementations like FreezeBalanceV2Actuator, ExchangeTransactionActuator), coordinating with dependent modules (chainbase for state storage, protocol for message definitions, crypto for cryptographic operations). Transaction processing flows through ActuatorFactory/ActuatorCreator to route transaction types to their handlers.

Blockchain developers, node operators, and protocol contributors who need to run TRON full nodes, validate transactions, or contribute to the TRON ecosystem. Also relevant for smart contract developers understanding the TVM execution layer and transaction settlement mechanics.

Production-ready. The repository shows active maintenance with CI/CD pipelines (.github/workflows including codeql.yml, system-test.yml, pr-check.yml), substantial codebase (9.8M lines of Java), and established testing infrastructure (Gradle test framework with JaCoCo coverage reporting). However, maturity depends on deployment context—this is the reference implementation used by the TRON network.

Moderate-to-low risk for a blockchain protocol implementation. Dependencies are managed via Gradle, but the large surface area (core protocol logic, cryptography, consensus) means security patches can be critical. Last visible signals (CI workflows present) suggest active maintenance. Primary risk: protocol-level changes require careful consensus coordination with the broader TRON network, making some changes non-reversible.

Active protocol development visible in the file structure: recent actuator implementations (CancelAllUnfreezeV2Actuator, DelegateResourceActuator suggesting ongoing resource delegation features), v2 staking/freezing mechanisms (FreezeBalanceV2Actuator), and market order functionality (MarketSellAssetActuator, MarketCancelOrderActuator). CI workflows (codeql.yml, math-check.yml, system-test.yml) indicate continuous security and integration testing.

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

Note: Requires JDK 8 or 17, 16 GB RAM, 10 GB disk space, Linux or macOS only.

Daily commands: This is a blockchain node, not a service. Build produces executables listed in the README under 'Executables' section. Run compiled node: java -cp [classpath] org.tron.core.FullNode (exact command in Executables section of README). Configuration via tron.conf file (not in file list but standard for TRON nodes).

• actuator/src/main/java/org/tron/core/actuator/ActuatorFactory.java — Core factory that creates and dispatches all transaction actuators; essential entry point for understanding how transactions are executed
• actuator/src/main/java/org/tron/core/actuator/AbstractActuator.java — Base abstraction for all actuator implementations; defines the contract for transaction validation and execution
• actuator/src/main/java/org/tron/core/vm/VM.java — Virtual machine implementation that executes smart contract bytecode; critical for understanding contract execution flow
• actuator/src/main/java/org/tron/core/utils/TransactionRegister.java — Transaction type registry that maps transaction types to their corresponding actuators; necessary for extending transaction support
• actuator/src/main/java/org/tron/core/vm/Operation.java — Defines VM operation interface and bytecode operation execution; fundamental to understanding contract instruction handling
• actuator/src/main/java/org/tron/core/actuator/VMActuator.java — Bridge between transaction layer and VM execution; handles smart contract invocation and state changes

Add a new transaction type actuator

1. Create a new class extending AbstractActuator in actuator/src/main/java/org/tron/core/actuator/ (actuator/src/main/java/org/tron/core/actuator/MyNewActuator.java)
2. Implement validate() method to verify transaction preconditions (actuator/src/main/java/org/tron/core/actuator/MyNewActuator.java)
3. Implement execute() method to apply state changes to the database (actuator/src/main/java/org/tron/core/actuator/MyNewActuator.java)
4. Register the transaction type in TransactionRegister by adding a mapping in the constructor or factory method (actuator/src/main/java/org/tron/core/utils/TransactionRegister.java)
5. Add transaction type enum to protocol definition (ensure protocol dependency is updated) (protocol/src/main/proto/core/Tron.proto)

Add a new EVM opcode operation

1. Add opcode enum value to Op.java (actuator/src/main/java/org/tron/core/vm/Op.java)
2. Create operation handler implementing Operation interface (actuator/src/main/java/org/tron/core/vm/program/MyOpOperation.java)
3. Register opcode in OperationRegistry during VM initialization (actuator/src/main/java/org/tron/core/vm/OperationRegistry.java)
4. Define energy cost in EnergyCost class (actuator/src/main/java/org/tron/core/vm/EnergyCost.java)

Add a new native smart contract

1. Create processor class extending native contract processor pattern (actuator/src/main/java/org/tron/core/vm/nativecontract/MyNativeContractProcessor.java)
2. Create corresponding parameter class for parsing contract call data (actuator/src/main/java/org/tron/core/vm/nativecontract/param/MyContractParam.java)
3. Register contract address mapping in PrecompiledContracts or contract registry (actuator/src/main/java/org/tron/core/vm/PrecompiledContracts.java)
4. Add processing logic in MessageCall to route contract invocations (actuator/src/main/java/org/tron/core/vm/MessageCall.java)

• Java with Protocol Buffers — Provides strong typing, cross-platform compatibility, and efficient serialization for blockchain transactions and messages
• EVM-compatible Virtual Machine — Enables Ethereum smart contract compatibility while maintaining Tron-specific extensions (energy instead of gas, resource delegation)
• Chainbase dependency — Provides persistent state storage and transaction database layer for blockchain ledger management
• Crypto dependency — Handles cryptographic operations: signature verification, hash computations, and key management

• Actuator pattern with factory dispatch

  • Why: Enables loose coupling between transaction types and their handlers, simplifying addition of new transaction types
  • Consequence: Requires careful registration of new actuators; missing registrations cause runtime failures rather than compile-time errors

• Interpreting EVM bytecode rather than JIT compilation

  • Why: Simplified implementation, deterministic behavior across nodes, easier security audits
  • Consequence: Lower performance per transaction compared to JIT-compiled execution

• Native contracts in-process rather than separate contract modules

  • Why: Better performance, direct access to blockchain state, simpler deployment
  • Consequence: Native contract changes require protocol coordination and recompilation across network

• Energy model separate from EVM gas

  • Why: Tron-specific resource pricing and bandwidth/CPU/storage resource delegation
  • Consequence: Contracts ported from Ethereum must account for different energy costs

• Does not implement transaction pool mempool management (that is in chainbase or other module)
• Does not handle P2P networking or consensus (separate consensus module handles Proof of Stake)
• Does not implement wallet or key management (delegated to crypto module)
• Does not provide REST API interface (that is in higher-level modules)

JDK version coupling: Different CPU architectures require different JDK versions (Oracle JDK 8 recommended for x86_64 production per install docs). Test heap size: Tests require -Xmx1200m; default may fail. Gradle wrapper: Must use ./gradlew, not system gradle. No Windows support: Explicitly not supported despite Java's cross-platform claims. Protobuf compilation: Changes to .proto files trigger regeneration—may cause build cache misses. Actuator registry: Adding new transaction types requires manual registration in ActuatorFactory—no auto-discovery.

• DPoS (Delegated Proof of Stake) — TRON uses DPoS consensus instead of PoW—understanding delegation, voting, and Super Representative selection is fundamental to transaction validation in this codebase
• EVM Compatibility Layer (TVM) — java-tron runs an EVM-compatible smart contract engine; developers modifying transaction execution or state handling need to understand TVM semantics differ slightly from Ethereum's EVM
• State Machine Replication (SMR) — The Actuator pattern implements state machine replication—each transaction type is a deterministic state transition; all nodes must execute identical sequences identically
• Protocol Buffers (Protobuf) — All transaction and block data is serialized using Protocol Buffers; modifying protocol requires regenerating Java classes from .proto files
• Resource System (Bandwidth/Energy/Voting Power) — TRON's unique resource model (evident in FreezeBalanceV2Actuator, DelegateResourceActuator) differs from Ethereum's gas—critical for transaction cost calculation
• Chainbase (Storage Abstraction) — State persistence is delegated to the chainbase module; understanding the abstraction boundary is critical when implementing new transaction types that modify state
• Two-Phase Commit (for Exchanges/Swaps) — Exchange transactions (ExchangeCreateActuator, ExchangeTransactionActuator, ExchangeWithdrawActuator) implement atomic multi-step operations using a commit/rollback pattern visible in AbstractExchangeActuator

• tronprotocol/protocol — Contains Protocol Buffer definitions (.proto files) that define all transaction and message structures used by java-tron
• tronprotocol/tvm — TRON Virtual Machine implementation—the EVM-compatible smart contract execution engine referenced in java-tron
• ethereum/go-ethereum — Go Ethereum reference implementation; TRON's DPoS consensus and TVM design draw architectural patterns from EVM but diverge significantly
• tronprotocol/wallet-cli — Command-line wallet for TRON—primary user-facing tool that communicates with java-tron nodes via gRPC
• tronprotocol/trident — TRON smart contract development framework—builds on top of TVM/java-tron for developers deploying contracts

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for ActuatorFactory and ActuatorCreator

The actuator module contains 30+ actuator implementations but lacks visible test coverage for the factory pattern classes (ActuatorFactory.java and ActuatorCreator.java). These are critical infrastructure components for transaction processing. Adding tests would improve reliability of transaction routing and catch regressions early.

• [ ] Create actuator/src/test/java/org/tron/core/actuator/ActuatorFactoryTest.java with tests for all actuator type mappings
• [ ] Create actuator/src/test/java/org/tron/core/actuator/ActuatorCreatorTest.java to test actuator instantiation logic
• [ ] Add parametrized tests covering each actuator type (Transfer, FreezeBalance, VoteWitness, etc.)
• [ ] Verify factory error handling for unknown transaction types
• [ ] Update jacocoTestReport to track coverage gains

Add integration tests for TransactionUtil and ProposalUtil helper classes

The actuator/src/main/java/org/tron/core/utils/ contains utility classes (TransactionUtil.java, ProposalUtil.java) that are likely used across multiple actuators but lack dedicated test files. These utilities need integration tests to ensure consistent behavior across the transaction pipeline.

• [ ] Create actuator/src/test/java/org/tron/core/utils/TransactionUtilTest.java with tests for transaction validation, parsing, and processing utilities
• [ ] Create actuator/src/test/java/org/tron/core/utils/ProposalUtilTest.java to test proposal creation, approval, and lifecycle utilities
• [ ] Add tests for edge cases (invalid inputs, boundary conditions, chainbase interactions)
• [ ] Document expected behavior in test comments referencing Tron whitepaper where applicable

Add GitHub Actions workflow for actuator module-specific testing and coverage reporting

While pr-check.yml and system-test.yml exist, there's no dedicated workflow for the actuator module's test coverage and performance validation. Given that actuator is critical infrastructure with 30+ implementations, a specialized workflow would catch module-level regressions earlier and provide visibility into coverage trends.

• [ ] Create .github/workflows/actuator-test.yml that runs on PR creation for the actuator/ directory changes only
• [ ] Configure workflow to run actuator tests with the 1200m heap size from build.gradle
• [ ] Add Jacoco coverage report generation and artifact upload for coverage trending
• [ ] Integrate with CodeClimate via .codeclimate.yml to track coverage changes per PR
• [ ] Add step to fail workflow if coverage decreases below 70% for actuator module

• Add unit tests for AbstractExchangeActuator.java—it's imported but no test file visible in the list; write comprehensive tests for exchange transaction validation edge cases
• Implement missing actuator tests: ProposalApproveActuator, ProposalDeleteActuator, SetAccountIdActuator likely lack test coverage given the pattern; add test files under actuator/src/test/ mirroring source structure
• Document the actuator registration flow: add JavaDoc to ActuatorFactory.java and ActuatorCreator.java explaining how new transaction types are registered—current code lacks developer-facing comments

The TRON java-tron codebase demonstrates a blockchain infrastructure project with moderate security posture. Primary concerns center on the VM implementation complexity, transaction validation rigor, and cryptographic operation integrity. The project includes a responsible vulnerability disclosure policy via HackerOne. Main recommendations: (1) Conduct thorough security audit of VM bytecode execution engine,

• Medium · Potential VM Code Execution Risk — actuator/src/main/java/org/tron/core/vm/. The codebase contains a VM (Virtual Machine) implementation in actuator/src/main/java/org/tron/core/vm/ with complex bytecode execution logic (VM.java, Operation.java, etc.). VM implementations handling untrusted smart contract code require rigorous security review to prevent arbitrary code execution, integer overflow, and state manipulation attacks. Fix: Conduct thorough security audit of VM implementation, implement gas metering limits, add bounds checking on all stack operations, and validate all bytecode operations against a whitelist. Ensure proper handling of stack depth, memory limits, and state transitions.
• Medium · Cryptographic Operations Without Explicit Validation — actuator/src/main/java/org/tron/core/actuator/. The actuator module depends on 'crypto' package but there is no visible evidence of cryptographic validation in transaction processors. Without proper signature verification and cryptographic validation, transactions could be forged or manipulated. Fix: Ensure all transaction actuators validate cryptographic signatures before processing. Implement comprehensive input validation for all transaction types and audit signature verification implementation in the crypto dependency.
• Medium · Missing Input Validation in Transaction Actuators — actuator/src/main/java/org/tron/core/actuator/. Multiple actuator classes (TransferActuator.java, ExchangeTransactionActuator.java, ShieldedTransferActuator.java, etc.) process financial transactions. Without visible input validation code, there is risk of processing invalid or malicious transactions that could lead to incorrect state changes. Fix: Implement comprehensive input validation in all transaction actuators. Validate: account existence, sufficient balance, valid address formats, amount ranges, and authorization before state modification. Use a validation framework to enforce consistent checks.
• Low · Privilege Escalation Risk in AccountPermissionUpdateActuator — actuator/src/main/java/org/tron/core/actuator/AccountPermissionUpdateActuator.java. AccountPermissionUpdateActuator.java manages account permissions. Improper validation could allow attackers to escalate privileges or bypass access controls, especially in multi-signature scenarios. Fix: Implement strict validation of permission changes including: verify signer has current permission to modify, validate new permission structure, enforce least privilege principle, and audit all permission state transitions.
• Low · Potential Integer Overflow in Financial Calculations — actuator/src/main/java/org/tron/core/actuator/ExchangeTransactionActuator.java, FreezeBalanceActuator.java, FreezeBalanceV2Actuator.java. Exchange and freeze balance actuators perform arithmetic operations on large numbers representing token amounts. Without explicit overflow checking, integer overflow could lead to incorrect balance calculations. Fix: Use SafeMath or explicit overflow checking for all arithmetic operations. Java's unchecked arithmetic can overflow silently. Consider using BigDecimal for financial calculations or implement explicit bounds checking before operations.
• Low · Insufficient Error Handling and Information Disclosure — actuator/build.gradle. Test configuration and logging may expose sensitive information about internal state, which could aid attackers in reconnaissance. The build.gradle shows debug logging configuration that might be overly verbose. Fix: Ensure production builds disable debug logging and sensitive information logging. Implement proper exception handling that doesn't expose internal state details to external callers. Use structured logging with appropriate log levels.
• Low · Missing Bounds Checking in Energy Cost Calculations — actuator/src/main/java/org/tron/core/vm/EnergyCost.java. EnergyCost.java manages VM operation energy consumption. Improper calculation could allow denial-of-service attacks through resource exhaustion. Fix: Validate that energy costs are properly enforced, implement reasonable upper bounds on total energy per transaction, and ensure energy calculations cannot overflow or underflow.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.