tron.rb 1.0.9 → 1.1.3

data/lib/tron/protobuf/transaction_raw_serializer.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+require 'google/protobuf'
+
+# This file contains proper Protocol Buffer definitions for TRON transactions
+# These would normally be generated from .proto files, but for this implementation
+# we'll define the essential structures needed for transaction serialization
+
+module Tron
+  module Protobuf
+    # We need to use the google-protobuf gem to define the classes
+    # First, let's define a basic structure for TRON transaction serialization
+    
+    # Rather than writing the complex protobuf definitions from scratch,
+    # we'll create a helper that properly serializes the transaction according to TRON specs
+    class TransactionRawSerializer
+      # Field numbers according to TRON's protocol buffer definitions
+      REF_BLOCK_BYTES = 1
+      # @return [Integer] reference block bytes field number
+      REF_BLOCK_NUM = 2
+      # @return [Integer] reference block number field number
+      REF_BLOCK_HASH = 3
+      # @return [Integer] reference block hash field number
+      EXPIRATION = 4
+      # @return [Integer] expiration field number
+      AUTHS = 5  # authority
+      # @return [Integer] authority field number
+      DATA = 6
+      # @return [Integer] data field number
+      CONTRACT = 7
+      # @return [Integer] contract field number
+      SCRIPTS = 8
+      # @return [Integer] scripts field number
+      FEE_LIMIT = 9
+      # @return [Integer] fee limit field number
+      
+      # Contract field numbers
+      CONTRACT_TYPE = 1
+      # @return [Integer] contract type field number
+      CONTRACT_PARAMETER = 2
+      # @return [Integer] contract parameter field number
+      CONTRACT_PROVIDER = 3
+      # @return [Integer] contract provider field number
+      
+      # Serializes a transaction for signing according to TRON's protocol buffer specification
+      #
+      # @param transaction [Hash] the transaction data to serialize
+      # @return [String] the serialized transaction in protocol buffer format
+      def self.serialize(transaction)
+        raw_data = transaction['raw_data']
+        result = []
+        
+        # Serialize each field in the proper order with field numbers
+        if raw_data.key?('ref_block_bytes')
+          result << encode_field(REF_BLOCK_BYTES, :bytes, convert_hex_to_bytes(raw_data['ref_block_bytes']))
+        end
+        
+        if raw_data.key?('ref_block_num')
+          result << encode_field(REF_BLOCK_NUM, :varint, raw_data['ref_block_num'])
+        end
+        
+        if raw_data.key?('ref_block_hash')
+          result << encode_field(REF_BLOCK_HASH, :bytes, convert_hex_to_bytes(raw_data['ref_block_hash']))
+        end
+        
+        if raw_data.key?('expiration')
+          result << encode_field(EXPIRATION, :varint, raw_data['expiration'])
+        end
+        
+        # Add timestamp - TRON has timestamp as part of raw_data
+        if raw_data.key?('timestamp')
+          result << encode_field(10, :varint, raw_data['timestamp'])  # timestamp field number is typically 10
+        end
+        
+        if raw_data.key?('fee_limit')
+          result << encode_field(FEE_LIMIT, :varint, raw_data['fee_limit'])
+        end
+        
+        # Handle contracts - this is more complex
+        if raw_data.key?('contract')
+          contract_data = raw_data['contract']
+          if contract_data.is_a?(Array)
+            # TRON allows multiple contracts in one transaction
+            contract_data.each do |contract|
+              result << encode_field(CONTRACT, :embedded_message, serialize_contract(contract))
+            end
+          else
+            # Single contract
+            result << encode_field(CONTRACT, :embedded_message, serialize_contract(contract_data))
+          end
+        end
+        
+        # Handle data field
+        if raw_data.key?('data')
+          result << encode_field(DATA, :bytes, convert_hex_to_bytes(raw_data['data']))
+        end
+        
+        # Handle auths (authority)
+        if raw_data.key?('authority')
+          # For now, just handle as bytes or varint depending on the structure
+        end
+        
+        result.join
+      end
+      
+      private
+      
+      # Encodes a field in protobuf wire format
+      #
+      # @param field_number [Integer] the field number
+      # @param field_type [Symbol] the type of field (:varint, :bytes, :embedded_message)
+      # @param value [Object] the value to encode
+      # @return [String] the encoded field
+      def self.encode_field(field_number, field_type, value)
+        # In protobuf, each field is encoded as (field_number << 3 | wire_type) + value
+        key = (field_number << 3) | wire_type(field_type)
+        varint_bytes = encode_varint(key)
+        
+        case field_type
+        when :varint
+          varint_bytes + encode_varint(value)
+        when :bytes
+          varint_bytes + encode_varint(value.length) + value
+        when :embedded_message
+          varint_bytes + encode_varint(value.length) + value
+        else
+          varint_bytes + value
+        end
+      end
+      
+      # Maps field types to protobuf wire types
+      #
+      # @param field_type [Symbol] the field type
+      # @return [Integer] the wire type number
+      def self.wire_type(field_type)
+        case field_type
+        when :varint
+          0  # varint wire type
+        when :bytes, :embedded_message
+          2  # length-delimited wire type
+        else
+          2  # default to length-delimited
+        end
+      end
+      
+      # Encodes an integer as a protobuf varint
+      #
+      # @param value [Integer] the integer to encode
+      # @return [String] the encoded varint
+      def self.encode_varint(value)
+        result = []
+        v = value
+        loop do
+          byte = v & 0x7F
+          v >>= 7
+          if v == 0
+            result << byte
+            break
+          else
+            result << (byte | 0x80)
+          end
+        end
+        result.pack('C*')
+      end
+      
+      # Serializes a contract according to TRON's protocol
+      #
+      # @param contract [Hash] the contract data to serialize
+      # @return [String] the serialized contract
+      def self.serialize_contract(contract)
+        result = []
+        
+        if contract.key?('type')
+          # The contract type as a varint
+          type_value = contract_type_to_int(contract['type'])
+          result << encode_field(CONTRACT_TYPE, :varint, type_value)
+        end
+        
+        if contract.key?('parameter')
+          # The parameter as embedded message
+          param_bytes = serialize_contract_parameter(contract['parameter'])
+          result << encode_field(CONTRACT_PARAMETER, :embedded_message, param_bytes)
+        end
+        
+        if contract.key?('provider')
+          # Provider address as bytes
+          result << encode_field(CONTRACT_PROVIDER, :bytes, convert_hex_to_bytes(contract['provider']))
+        end
+        
+        result.join
+      end
+      
+      # Serializes the parameter part of a contract
+      #
+      # @param parameter [Hash] the parameter data to serialize
+      # @return [String] the serialized parameter
+      def self.serialize_contract_parameter(parameter)
+        # This is simplified - a full implementation would need to serialize
+        # each specific contract type according to its protobuf definition
+        # For the triggerSmartContract, this would serialize the function_selector and call_value
+        
+        result = []
+        
+        if parameter.key?('value')
+          value = parameter['value']
+          if value.is_a?(Hash)
+            # Serialize each field in the parameter value
+            # This is where we'd need the specific protobuf definition for each contract type
+            # For now we'll serialize it in a simplified way that follows protobuf conventions
+            value.each do |field_name, field_value|
+              field_number = case field_name
+                            when 'owner_address' then 1
+                            when 'contract_address' then 2
+                            when 'data', 'function_selector' then 3
+                            when 'call_value' then 4
+                            when 'fee_limit' then 5
+                            else 1  # Default to 1
+                            end
+              
+              case field_value
+              when String
+                # If it's a hex string, convert to bytes
+                result << encode_field(field_number, :bytes, convert_hex_to_bytes(field_value))
+              when Integer
+                result << encode_field(field_number, :varint, field_value)
+              else
+                # Convert other types appropriately
+                result << encode_field(field_number, :bytes, field_value.to_s)
+              end
+            end
+          end
+        end
+        
+        # Add type_url field (field number 1 in Any type)
+        type_url = parameter['type_url'] || "type.googleapis.com/protocol.#{parameter['type'] || 'TriggerSmartContract'}"
+        result << encode_field(1, :string, type_url)
+        
+        result.join
+      end
+      
+      # Maps contract type names to their protocol buffer enum values
+      #
+      # @param type_name [String] the contract type name
+      # @return [Integer] the protocol buffer enum value
+      def self.contract_type_to_int(type_name)
+        type_map = {
+          'AccountCreateContract' => 0,
+          'TransferContract' => 1,
+          'TransferAssetContract' => 2,
+          'VoteAssetContract' => 3,
+          'VoteWitnessContract' => 4,
+          'WitnessCreateContract' => 5,
+          'AssetIssueContract' => 6,
+          'WitnessUpdateContract' => 7,
+          'ParticipateAssetIssueContract' => 8,
+          'AccountUpdateContract' => 9,
+          'FreezeBalanceContract' => 10,
+          'UnfreezeBalanceContract' => 11,
+          'WithdrawBalanceContract' => 12,
+          'UnfreezeAssetContract' => 13,
+          'UpdateAssetContract' => 14,
+          'ProposalCreateContract' => 15,
+          'ProposalApproveContract' => 16,
+          'ProposalDeleteContract' => 17,
+          'SetAccountIdContract' => 18,
+          'CustomContract' => 19,
+          'CreateSmartContract' => 30,
+          'TriggerSmartContract' => 31,
+          'GetContract' => 32,
+          'UpdateSettingContract' => 33,
+          'ExchangeCreateContract' => 41,
+          'ExchangeInjectContract' => 42,
+          'ExchangeWithdrawContract' => 43,
+          'ExchangeTransactionContract' => 44,
+          'UpdateEnergyLimitContract' => 45,
+          'AccountPermissionUpdateContract' => 46
+        }
+        
+        type_map[type_name] || 0  # Default to 0 if unknown
+      end
+      
+      # Converts a hex string to binary format
+      #
+      # @param hex_string [String] the hex string to convert
+      # @return [String] the binary representation
+      def self.convert_hex_to_bytes(hex_string)
+        # Remove '0x' prefix if present
+        hex = hex_string.to_s
+        hex = hex[2..-1] if hex.start_with?('0x', '0X')
+        # Pad with leading zero if odd length
+        hex = '0' + hex if hex.length.odd?
+        [hex].pack('H*')
+      end
+    end
+  end
+end

data/lib/tron/protobuf.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+require 'google/protobuf'
+require_relative 'protobuf/transaction_raw_serializer'
+
+module Tron
+  module Protobuf
+    # Main class to serialize TRON transactions for signing
+    class TransactionSerializer
+      # Serializes a transaction for signing
+      #
+      # @param transaction [Hash] the transaction to serialize
+      # @return [String] the serialized transaction
+      def self.serialize_for_signing(transaction)
+        TransactionRawSerializer.serialize(transaction)
+      end
+    end
+  end
+end

data/lib/tron/services/balance.rb

@@ -6,7 +6,11 @@ require_relative '../utils/rate_limiter'
 
 module Tron
   module Services
+    # The Balance service handles retrieving TRX and TRC20 token balances for TRON addresses
     class Balance
+      # Creates a new instance of the Balance service
+      #
+      # @param config [Tron::Configuration] the configuration object
       def initialize(config)
         @config = config
         @cache = Utils::Cache.new(max_age: config.cache_ttl) if config.cache_enabled
@@ -15,6 +19,11 @@ module Tron
         @cache_misses = 0
       end
 
+      # Gets the TRX balance for a given address
+      #
+      # @param address [String] the TRON address to check
+      # @return [String] the TRX balance as a formatted string
+      # @raise [ArgumentError] if the address is invalid
       def get_trx(address)
         validate_address!(address)
 
@@ -61,6 +70,12 @@ module Tron
         result
       end
 
+      # Gets all TRC20 token balances for a given address
+      #
+      # @param address [String] the TRON address to check
+      # @param strict [Boolean] whether to enable strict validation
+      # @return [Array<Hash>] an array of token information
+      # @raise [ArgumentError] if the address is invalid
       def get_trc20_tokens(address, strict: false)
         validate_address!(address)
 
@@ -105,6 +120,9 @@ module Tron
         result
       end
 
+      # Gets cache statistics for the balance service
+      #
+      # @return [Hash] a hash containing cache statistics
       def cache_stats
         total = @cache_hits + @cache_misses
         {
@@ -115,6 +133,7 @@ module Tron
         }
       end
 
+      # Clears the cache for the balance service
       def clear_cache
         @cache&.clear
         @cache_hits = 0
@@ -123,6 +142,10 @@ module Tron
 
       private
 
+      # Validates the structure of token data
+      #
+      # @param token [Hash] the token data to validate
+      # @raise [RuntimeError] if the token data is invalid
       def validate_token_data!(token)
         unless token.is_a?(Hash)
           raise "Invalid token data format: expected hash"
@@ -136,6 +159,11 @@ module Tron
         end
       end
 
+      # Gets all balance information for a given address
+      #
+      # @param address [String] the TRON address to check
+      # @param strict [Boolean] whether to enable strict validation
+      # @return [Hash] a hash containing all balance information
       def get_all(address, strict: false)
         validate_address!(address)
         
@@ -148,10 +176,19 @@ module Tron
 
       private
 
+      # Validates a TRON address
+      #
+      # @param address [String] the address to validate
+      # @raise [ArgumentError] if the address is invalid
       def validate_address!(address)
         raise ArgumentError, "Invalid TRON address: #{address}" unless Utils::Address.validate(address)
       end
 
+      # Formats a raw balance with the specified number of decimals
+      #
+      # @param raw_balance [Integer, String] the raw balance value
+      # @param decimals [Integer] the number of decimal places
+      # @return [String] the formatted balance
       def format_balance(raw_balance, decimals)
         balance = raw_balance.to_i
         divisor = 10 ** decimals
@@ -160,14 +197,18 @@ module Tron
         "#{whole}.#{fraction.to_s.rjust(decimals, '0')}"
       end
 
-
-
+      # Creates headers for the TRON API
+      #
+      # @return [Hash] the API headers
       def api_headers
         headers = { 'accept' => 'application/json' }
         headers['TRON-PRO-API-KEY'] = @config.api_key if @config.api_key
         headers
       end
 
+      # Creates headers for the Tronscan API
+      #
+      # @return [Hash] the Tronscan API headers
       def tronscan_headers
         headers = { 'accept' => 'application/json' }
         headers['TRON-PRO-API-KEY'] = @config.tronscan_api_key if @config.tronscan_api_key

data/lib/tron/services/contract.rb

@@ -0,0 +1,232 @@
+require_relative '../utils/http'
+require_relative '../utils/address'
+require_relative '../utils/abi'
+require_relative '../abi'
+require_relative 'transaction'
+
+module Tron
+  module Services
+    # The Contract service handles interactions with TRON smart contracts
+    # including both read-only calls and state-changing transactions
+    class Contract
+      # Creates a new instance of the Contract service
+      #
+      # @param configuration [Tron::Configuration] the configuration object
+      def initialize(configuration)
+        @configuration = configuration
+        @base_url = configuration.base_url
+        @transaction_service = Transaction.new(configuration)
+      end
+
+      # Triggers a smart contract (state-changing operation)
+      # This creates and broadcasts a transaction to the blockchain
+      #
+      # @param contract_address [String] the contract address to interact with
+      # @param function [String] the function to call on the contract
+      # @param parameters [Array] the parameters to pass to the function
+      # @param private_key [String] the private key to sign the transaction
+      # @param fee_limit [Integer] the maximum energy fee to pay (default: configuration default)
+      # @param call_value [Integer] the amount of TRX to send with the call (default: 0)
+      # @param owner_address [String] the address of the transaction originator (default: derived from private key)
+      # @return [Hash] the transaction result
+      def trigger_contract(
+        contract_address:,
+        function:,
+        parameters: [],
+        private_key:,
+        fee_limit: nil,
+        call_value: 0,
+        owner_address: nil
+      )
+        # Use configuration default if fee_limit not provided
+        fee_limit ||= @configuration.fee_limit
+
+        # Derive owner address from private key if not provided
+        owner_address ||= derive_address_from_private_key(private_key)
+
+        # Validate addresses
+        validate_address!(contract_address)
+        validate_address!(owner_address)
+
+        # Build transaction
+        transaction = build_trigger_transaction(
+          contract_address: contract_address,
+          function: function,
+          parameters: parameters,
+          owner_address: owner_address,
+          fee_limit: fee_limit,
+          call_value: call_value
+        )
+
+        # Sign and broadcast
+        @transaction_service.sign_and_broadcast(transaction, private_key)
+      end
+
+      # Calls a smart contract (read-only operation)
+      # This does not create a transaction and doesn't change blockchain state
+      #
+      # @param contract_address [String] the contract address to interact with
+      # @param function [String] the function to call on the contract
+      # @param parameters [Array] the parameters to pass to the function
+      # @param owner_address [String] the address of the caller (default: configuration default)
+      # @return [Hash] the result of the function call
+      def call_contract(
+        contract_address:,
+        function:,
+        parameters: [],
+        owner_address: nil
+      )
+        # Use a default address if not provided
+        owner_address ||= @configuration.default_address || 'T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb'
+
+        # Validate address
+        validate_address!(contract_address)
+
+        # Build request
+        endpoint = "#{@base_url}/wallet/triggerconstantcontract"
+
+        # Encode function call
+        encoded_data = Utils::ABI.encode_function_call(function, parameters)
+
+        # Use 'data' field instead of 'function_selector' (same as trigger_contract)
+        payload = {
+          contract_address: Utils::Address.to_hex(contract_address),
+          data: encoded_data,
+          owner_address: Utils::Address.to_hex(owner_address)
+        }
+
+        # Make API call
+        response = Utils::HTTP.post(endpoint, payload, {
+          endpoint_type: :contract_call,
+          ttl: 60  # Cache for 1 minute
+        })
+
+        # Parse response
+        parse_constant_result(response)
+      end
+
+      # Checks if a payment has been processed (example helper)
+      #
+      # @param contract_address [String] the contract address
+      # @param operator_address [String] the operator's address
+      # @param payment_id [String] the payment ID
+      # @return [Boolean] true if the payment is processed, false otherwise
+      def payment_processed?(contract_address, operator_address, payment_id)
+        result = call_contract(
+          contract_address: contract_address,
+          function: 'isPaymentProcessed(address,bytes16)',
+          parameters: [operator_address, payment_id]
+        )
+
+        Utils::ABI.decode_output('bool', result)
+      end
+
+      # Gets the fee destination (example helper)
+      #
+      # @param contract_address [String] the contract address
+      # @param operator_address [String] the operator's address
+      # @return [String] the fee destination address
+      def get_fee_destination(contract_address, operator_address)
+        result = call_contract(
+          contract_address: contract_address,
+          function: 'getFeeDestination(address)',
+          parameters: [operator_address]
+        )
+
+        Utils::ABI.decode_output('address', result)
+      end
+
+      # Checks if an operator is registered (example helper)
+      #
+      # @param contract_address [String] the contract address
+      # @param operator_address [String] the operator's address
+      # @return [Boolean] true if the operator is registered, false otherwise
+      def operator_registered?(contract_address, operator_address)
+        result = call_contract(
+          contract_address: contract_address,
+          function: 'isOperatorRegistered(address)',
+          parameters: [operator_address]
+        )
+
+        Utils::ABI.decode_output('bool', result)
+      end
+
+      private
+
+      # Builds a trigger transaction for a smart contract call
+      #
+      # @param contract_address [String] the contract address
+      # @param function [String] the function to call
+      # @param parameters [Array] the parameters to pass
+      # @param owner_address [String] the address of the transaction owner
+      # @param fee_limit [Integer] the maximum energy fee
+      # @param call_value [Integer] the value to send with the call
+      # @return [Hash] the transaction object
+      def build_trigger_transaction(
+        contract_address:,
+        function:,
+        parameters:,
+        owner_address:,
+        fee_limit:,
+        call_value:
+      )
+        endpoint = "#{@base_url}/wallet/triggersmartcontract"
+
+        # Encode function call (selector + parameters)
+        encoded_data = Utils::ABI.encode_function_call(function, parameters)
+
+        # IMPORTANT: Use 'data' field, not 'function_selector'
+        # When function_selector is provided, the API expects it to be the signature string
+        # with parameters in a separate 'parameter' field.
+        # Using 'data' allows us to send the complete encoded call data.
+        payload = {
+          contract_address: Utils::Address.to_hex(contract_address),
+          data: encoded_data,
+          fee_limit: fee_limit,
+          call_value: call_value,
+          owner_address: Utils::Address.to_hex(owner_address)
+        }
+
+        # Get transaction from API
+        response = Utils::HTTP.post(endpoint, payload)
+
+        raise "Failed to create transaction: #{response}" unless response['result']
+
+        response['transaction']
+      end
+
+      # Parses the result of a constant function call
+      #
+      # @param response [Hash] the API response
+      # @return [String] the parsed result
+      def parse_constant_result(response)
+        return nil unless response['result']
+
+        # Extract constant result (hex string)
+        constant_result = response['constant_result']
+        return nil if constant_result.nil? || constant_result.empty?
+
+        constant_result.first
+      end
+
+      # Validates a TRON address
+      #
+      # @param address [String] the address to validate
+      # @raise [ArgumentError] if the address is invalid
+      def validate_address!(address)
+        require_relative '../utils/address'
+        raise ArgumentError, "Invalid TRON address: #{address}" unless Utils::Address.validate(address)
+      end
+
+      # Derives a TRON address from a private key
+      #
+      # @param private_key [String] the private key in hex format
+      # @return [String] the derived address
+      def derive_address_from_private_key(private_key)
+        # Use the Key class to derive address from private key
+        key = Tron::Key.new(priv: private_key)
+        key.address
+      end
+    end
+  end
+end