feat(protocol): add protoLint script for enum validation

Author: 0xbigapple

gradle/verification-metadata.xml

@@ -26,6 +26,29 @@
             <sha256 value="26e82330157d6b844b67a8064945e206581e772977183e3e31fec6058aa9a59b" origin="Generated by Gradle"/>
          </artifact>
       </component>
+      <component group="build.buf" name="buf" version="1.61.0">
+         <artifact name="buf-1.61.0-linux-aarch_64.exe">
+            <sha256 value="37bfa47e6ede6ac1b78b3e3c93a0911b7c71d5bb9ed9c684dfc0164167619bc1" origin="Generated by Gradle"/>
+         </artifact>
+         <artifact name="buf-1.61.0-linux-x86_64.exe">
+            <sha256 value="d82849eca790bacb5b8885a027f31bbfbfdf72b2d93bc82bda8cb2ca20e4faca" origin="Generated by Gradle"/>
+         </artifact>
+         <artifact name="buf-1.61.0-osx-aarch_64.exe">
+            <sha256 value="b7878d0c88673e067c3a5ac60fabf133b29be71ae3a37598f2e99ee5d3c5fd22" origin="Generated by Gradle"/>
+         </artifact>
+         <artifact name="buf-1.61.0-osx-x86_64.exe">
+            <sha256 value="20323fa889d55893b67d402b714b04efe8916358ab29ccd2f70203439dc67b42" origin="Generated by Gradle"/>
+         </artifact>
+         <artifact name="buf-1.61.0-windows-aarch_64.exe">
+            <sha256 value="467eec551d3a6f7c4a2a10cbfde8fe4635353035753cc0f8b9eec1a32d2c97e8" origin="Generated by Gradle"/>
+         </artifact>
+         <artifact name="buf-1.61.0-windows-x86_64.exe">
+            <sha256 value="38bdff1ef30a9f97355df1c5377acad90b3b91355c9cafd0bf1c6d65c8172dd6" origin="Generated by Gradle"/>
+         </artifact>
+         <artifact name="buf-1.61.0.pom">
+            <sha256 value="917774d5994717ae1bdb6dc731b9190f19d79465396262e3c44430c91f628e11" origin="Generated by Gradle"/>
+         </artifact>
+      </component>
       <component group="ch.qos.logback" name="logback-classic" version="1.2.13">
          <artifact name="logback-classic-1.2.13.jar">
             <sha256 value="937afb220b91d8a394d78befdbf587c71aeed289d582e2a91e72a7d92172371d" origin="Generated by Gradle"/>

protocol/build.gradle

@@ -1,4 +1,5 @@
 apply plugin: 'com.google.protobuf'
+apply from: 'protoLint.gradle'
 
 def protobufVersion = '3.25.8'
 def grpcVersion = '1.75.0'

protocol/protoLint.gradle

@@ -0,0 +1,167 @@
+/**
+ * This is a Gradle script for proto linting.
+ *
+ * Implementation:
+ * 1. Integrates the 'buf' CLI tool to compile .proto files and generate a JSON AST (Abstract Syntax Tree) image.
+ * 2. Uses Groovy's JsonSlurper to parse the AST image.
+ * 3. Traverses all Enum definitions and validates them against preset rules.
+ *
+ * Current Validation:
+ * Enforces the java-tron API evolution standard (see https://github.com/tronprotocol/java-tron/issues/6515).
+ * Except for legacy enums in the 'legacyEnums' whitelist, all newly defined Enums MUST reserve index 0 for a field starting with 'UNKNOWN_'.
+ * This ensures robust forward/backward compatibility during proto3 JSON serialization.
+ */
+import groovy.json.JsonSlurper
+import org.gradle.internal.os.OperatingSystem
+
+// Define the required buf CLI version
+def bufVersion = "1.61.0"
+def currentOs = OperatingSystem.current()
+def platform = currentOs.isMacOsX() ? "osx" : (currentOs.isWindows() ? "windows" : "linux")
+def machine = rootProject.archInfo.isArm64 ? "aarch_64" : "x86_64"
+
+// Create a custom configuration for the buf CLI tool to keep it isolated from the classpath
+configurations {
+    bufTool
+}
+
+// Depend on the buf executable published on Maven Central
+dependencies {
+    bufTool "build.buf:buf:${bufVersion}:${platform}-${machine}@exe"
+}
+
+task protoLint {
+    group = "verification"
+    description = "Validate Protobuf Enums using buf generated JSON AST. Enforces 'UNKNOWN_' prefix for index 0 to ensure JSON serialization backward compatibility."
+    
+    // Explicitly declare dependency to avoid Gradle implicit dependency warnings 
+    // because generateProto outputs to the parent 'src' directory.
+    dependsOn 'generateProto'
+
+    // Incremental build support: Only run if proto files or the script itself changes
+    inputs.dir('src/main/protos')
+    inputs.file('protoLint.gradle')
+    
+    def markerFile = file("${buildDir}/tmp/protoLint.done")
+    outputs.file(markerFile)
+
+    doLast {
+        def bufExe = configurations.bufTool.singleFile
+        if (!bufExe.exists() || !bufExe.canExecute()) {
+            bufExe.setExecutable(true)
+        }
+
+        // 1. Legacy Whitelist
+        // Contains enums that existed before the 'UNKNOWN_' standard was enforced.
+        // Format: "filename.proto:EnumName" or "filename.proto:MessageName.EnumName"
+        def legacyEnums = [
+            "core/contract/common.proto:ResourceCode",
+            "core/contract/smart_contract.proto:SmartContract.ABI.Entry.EntryType",
+            "core/contract/smart_contract.proto:SmartContract.ABI.Entry.StateMutabilityType",
+            "core/Tron.proto:AccountType",
+            "core/Tron.proto:ReasonCode",
+            "core/Tron.proto:Proposal.State",
+            "core/Tron.proto:MarketOrder.State",
+            "core/Tron.proto:Permission.PermissionType",
+            "core/Tron.proto:Transaction.Contract.ContractType",
+            "core/Tron.proto:Transaction.Result.code",
+            "core/Tron.proto:Transaction.Result.contractResult",
+            "core/Tron.proto:TransactionInfo.code",
+            "core/Tron.proto:BlockInventory.Type",
+            "core/Tron.proto:Inventory.InventoryType",
+            "core/Tron.proto:Items.ItemType",
+            "core/Tron.proto:PBFTMessage.MsgType",
+            "core/Tron.proto:PBFTMessage.DataType",
+            "api/api.proto:Return.response_code",
+            "api/api.proto:TransactionSignWeight.Result.response_code",
+            "api/api.proto:TransactionApprovedList.Result.response_code",
+            "api/zksnark.proto:ZksnarkResponse.Code"
+        ].collect { it.toString() } as Set
+
+        // 2. Build JSON AST Image using buf CLI
+        def imageDir = file("${buildDir}/tmp/buf")
+        def imageFile = file("${imageDir}/proto-ast.json")
+        imageDir.mkdirs()
+        
+        println "🔍 Generating Proto AST image using buf CLI..."
+        
+        def bufConfig = '{"version":"v1beta1","build":{"roots":["src/main/protos","build/extracted-include-protos/main"]}}'
+        
+        def execResult = exec {
+            commandLine bufExe.absolutePath, 'build', '.', '--config', bufConfig, '-o', "${imageFile.absolutePath}#format=json"
+            ignoreExitValue = true
+        }
+
+        if (execResult.exitValue != 0) {
+            throw new GradleException("Failed to generate AST image. Ensure your .proto files are valid. Buf exited with code ${execResult.exitValue}")
+        }
+
+        if (!imageFile.exists()) {
+            throw new GradleException("Failed to locate generated buf image at ${imageFile.absolutePath}")
+        }
+
+        // 3. Parse AST and Validate Enums
+        def descriptorSet
+        try {
+            descriptorSet = new JsonSlurper().parse(imageFile)
+        } catch (Exception e) {
+            throw new GradleException("Failed to parse buf generated JSON AST: ${e.message}", e)
+        }
+
+        def errors = []
+
+        descriptorSet.file?.each { protoFile ->
+            // Skip Google's and gRPC's internal protos as they are outside our control
+            if (protoFile.name?.startsWith("google/") || protoFile.name?.startsWith("grpc/")) {
+                return
+            }
+
+            // A queue-based (BFS) approach to safely traverse all nested messages and enums
+            // without using recursion, ensuring support for any nesting depth.
+            def queue = []
+            
+            // Initial seed: top-level enums and messages
+            protoFile.enumType?.each { queue << [def: it, parentName: ""] }
+            protoFile.messageType?.each { queue << [def: it, parentName: ""] }
+
+            while (!queue.isEmpty()) {
+                def item = queue.remove(0)
+                def definition = item.def
+                def parentName = item.parentName
+
+                if (definition.value != null) { 
+                    // This is an Enum definition
+                    def fullName = parentName ? "${parentName}.${definition.name}" : definition.name
+                    def identifier = "${protoFile.name}:${fullName}".toString()
+                    
+                    if (!legacyEnums.contains(identifier)) {
+                        def zeroValue = definition.value?.find { it.number == 0 }
+                        if (zeroValue && !zeroValue.name?.startsWith("UNKNOWN_")) {
+                            errors << "[${protoFile.name}] Enum \"${fullName}\" has index 0: \"${zeroValue.name}\". It MUST start with \"UNKNOWN_\"."
+                        }
+                    }
+                } else {
+                    // This is a Message definition, look for nested enums and nested messages
+                    def currentMsgName = parentName ? "${parentName}.${definition.name}" : definition.name
+                    
+                    definition.enumType?.each { queue << [def: it, parentName: currentMsgName] }
+                    definition.nestedType?.each { queue << [def: it, parentName: currentMsgName] }
+                }
+            }
+        }
+
+        // 4. Report Results
+        if (!errors.isEmpty()) {
+            println "\n🚨 [Protocol Design Violation] The following enums violate the java-tron API evolution standard (Issue #6515):"
+            errors.each { println "  - $it" }
+            println "\n💡 Recommendation: To ensure proto3 JSON serialization backward compatibility, newly defined enums MUST reserve index 0 for an 'UNKNOWN_XXX' field.\n"
+            throw new GradleException("Proto Enum validation failed. See above for details.")
+        } else {
+            println "✅ Proto Enum validation passed!"
+            // Update marker file for Gradle incremental build cache
+            markerFile.text = "Success: " + new Date().toString()
+        }
+    }
+}
+
+check.dependsOn protoLint