Summary
The actuator.whitelist configuration can cause node execution results to diverge from the network in a public blockchain setting, breaking consensus. This configuration and all related code should be completely removed.
Problem
Motivation
actuator.whitelist was introduced in the early stages of java-tron to support functional testing scenarios, allowing nodes to execute only specific types of transactions. However, as TRON is a public blockchain, all nodes must produce identical execution results for the same block, enable or disable specific types of transaction should be controlled by proposals. The design assumption of this configuration fundamentally conflicts with the consensus requirements of a public network.
Current State
The config.conf file allows configuring actuator.whitelist as an array of allowed transaction types:
- If the array is empty, the node executes all transaction types
- If the array is non-empty, during
TransactionRegister.registerActuator(), actuator types not in the whitelist are not instantiated (via reflection of AbstractActuator subclasses) and therefore not registered in actuatorMap
- Smart contracts (
VMActuator) follow a separate execution path and are checked independently in RuntimeImpl.execute()
Limitations or Risks
In a public blockchain context, this configuration introduces the following risks:
- Consensus breakage: Blocks on the mainnet may contain transaction types not included in the whitelist (e.g.,
FreezeBalanceActuator). Nodes with a whitelist will lack the corresponding actuator in actuatorMap, causing getActuator() to return null, leading to execution results that diverge from other nodes and resulting in state forks
- Node isolation: Nodes with divergent execution results cannot synchronize with the main network, forming private forks
- High maintenance cost: The whitelist requires hardcoding actuator class name strings without type safety, and must be updated whenever new actuator types are introduced in protocol upgrades
- Incorrect abstraction layer: This mechanism operates at the block execution layer rather than the API layer, causing far greater impact than intended
Proposed Solution
Proposed Design
Completely remove the actuator.whitelist configuration and all related code. All nodes must unconditionally register and execute all valid actuator types, eliminating the possibility of consensus divergence caused by whitelist configuration.
Key Changes
- Affected Modules:
TransactionRegister, AbstractActuator and its subclass construction logic in the framework module; whitelist-related checks for VMActuator in RuntimeImpl
- Config Changes: Remove the
actuator.whitelist configuration from config.conf
- API Changes: None
Impact
- Security: Eliminates the risk of node isolation or private forks caused by incorrect whitelist configuration
- Stability: Improves consensus stability of public nodes and prevents state divergence
- Developer Experience: Removes the need to manually maintain hardcoded actuator class names, reducing configuration overhead during protocol upgrades
Backward Compatibility
- Breaking Change: the
actuator.whitelist configuration will be removed
- Default Behavior Change: Nodes previously using a whitelist will execute all transaction types, aligning with standard public network behavior
- Migration Required: nodes using
actuator.whitelist must remove this configuration before upgrading
Additional Notes
- Do you have ideas regarding implementation?
Yes
- Are you willing to implement this feature?
Yes
Summary
The
actuator.whitelistconfiguration can cause node execution results to diverge from the network in a public blockchain setting, breaking consensus. This configuration and all related code should be completely removed.Problem
Motivation
actuator.whitelistwas introduced in the early stages of java-tron to support functional testing scenarios, allowing nodes to execute only specific types of transactions. However, as TRON is a public blockchain, all nodes must produce identical execution results for the same block, enable or disable specific types of transaction should be controlled by proposals. The design assumption of this configuration fundamentally conflicts with the consensus requirements of a public network.Current State
The
config.conffile allows configuringactuator.whitelistas an array of allowed transaction types:TransactionRegister.registerActuator(), actuator types not in the whitelist are not instantiated (via reflection ofAbstractActuatorsubclasses) and therefore not registered inactuatorMapVMActuator) follow a separate execution path and are checked independently inRuntimeImpl.execute()Limitations or Risks
In a public blockchain context, this configuration introduces the following risks:
FreezeBalanceActuator). Nodes with a whitelist will lack the corresponding actuator inactuatorMap, causinggetActuator()to returnnull, leading to execution results that diverge from other nodes and resulting in state forksProposed Solution
Proposed Design
Completely remove the
actuator.whitelistconfiguration and all related code. All nodes must unconditionally register and execute all valid actuator types, eliminating the possibility of consensus divergence caused by whitelist configuration.Key Changes
TransactionRegister,AbstractActuatorand its subclass construction logic in theframeworkmodule; whitelist-related checks forVMActuatorinRuntimeImplactuator.whitelistconfiguration fromconfig.confImpact
Backward Compatibility
actuator.whitelistconfiguration will be removedactuator.whitelistmust remove this configuration before upgradingAdditional Notes
Yes
Yes