tron.rb 1.0.9 → 1.1.3

data/lib/tron/services/price.rb

@@ -5,7 +5,11 @@ require_relative '../utils/rate_limiter'
 
 module Tron
   module Services
+    # The Price service handles retrieving token price information for TRON tokens
     class Price
+      # Creates a new instance of the Price 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
@@ -14,6 +18,10 @@ module Tron
         @cache_misses = 0
       end
 
+      # Gets the price information for a specific token
+      #
+      # @param token [String] the token symbol (default: 'trx')
+      # @return [Hash] the token price information
       def get_token_price(token = 'trx')
         cache_key = cache_key_for(token)
 
@@ -57,6 +65,9 @@ module Tron
         end
       end
 
+      # Gets price information for all available tokens
+      #
+      # @return [Hash] the price information for all tokens
       def get_all_prices
         url = "#{@config.tronscan_base_url}/api/getAssetWithPriceList"
         headers = tronscan_headers
@@ -78,6 +89,10 @@ module Tron
         end
       end
 
+      # Gets the USD price for a specific token
+      #
+      # @param token [String] the token symbol
+      # @return [Float] the token price in USD, or nil if unavailable
       def get_token_price_usd(token)
         cache_key = "#{cache_key_for(token)}:usd"
 
@@ -105,6 +120,11 @@ module Tron
         result
       end
 
+      # Calculates the USD value for a given token balance
+      #
+      # @param balance [String, Numeric] the token balance
+      # @param token [String] the token symbol
+      # @return [Float] the USD value, or nil if unavailable
       def get_token_value_usd(balance, token)
         price = get_token_price_usd(token)
         if price
@@ -115,6 +135,10 @@ module Tron
         end
       end
 
+      # Gets prices for multiple tokens at once
+      #
+      # @param tokens [Array<String>] an array of token symbols
+      # @return [Hash] a hash mapping token symbols to their prices
       def get_multiple_token_prices(tokens)
         prices = {}
         tokens.each_with_index do |token, index|
@@ -134,6 +158,11 @@ module Tron
         prices
       end
 
+      # Formats a price value for display
+      #
+      # @param price [Float, nil] the price value
+      # @param currency [String] the currency symbol (default: 'USD')
+      # @return [String] the formatted price
       def format_price(price, currency = 'USD')
         if price.nil?
           '(price unavailable)'
@@ -146,6 +175,9 @@ module Tron
         end
       end
 
+      # Gets cache statistics for the price service
+      #
+      # @return [Hash] a hash containing cache statistics
       def cache_stats
         total = @cache_hits + @cache_misses
         {
@@ -156,6 +188,7 @@ module Tron
         }
       end
 
+      # Clears the cache for the price service
       def clear_cache
         @cache&.clear
         @cache_hits = 0
@@ -164,10 +197,17 @@ module Tron
 
       private
 
+      # Generates a cache key for a specific token
+      #
+      # @param token [String] the token symbol
+      # @return [String] the cache key
       def cache_key_for(token)
         "price:#{token.downcase}:#{@config.network}"
       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/resources.rb

@@ -4,11 +4,20 @@ require_relative '../utils/address'
 
 module Tron
   module Services
+    # The Resources service handles retrieving account resources (bandwidth, energy, storage) for TRON addresses
     class Resources
+      # Creates a new instance of the Resources service
+      #
+      # @param config [Tron::Configuration] the configuration object
       def initialize(config)
         @config = config
       end
 
+      # Gets the account resources for a given address
+      #
+      # @param address [String] the TRON address to check
+      # @return [Hash] a hash containing resource information
+      # @raise [ArgumentError] if the address is invalid
       def get(address)
         validate_address!(address)
         
@@ -23,6 +32,10 @@ module Tron
 
       private
 
+      # Gets account resources using the getaccountresource endpoint
+      #
+      # @param address [String] the TRON address to check
+      # @return [Hash] a hash containing resource information
       def get_account_resources(address)
         url = "#{@config.base_url}/wallet/getaccountresource"
         headers = api_headers
@@ -68,6 +81,10 @@ module Tron
         }
       end
 
+      # Gets account resources using the getaccount endpoint as a fallback
+      #
+      # @param address [String] the TRON address to check
+      # @return [Hash] a hash containing resource information
       def get_account_resources_fallback(address)
         url = "#{@config.base_url}/wallet/getaccount"
         headers = api_headers
@@ -100,16 +117,26 @@ module Tron
         }
       end
 
+      # 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
 
+      # Creates headers for the TRON API
+      #
+      # @return [Hash] the API headers
       def api_headers
         headers = { 'accept' => 'application/json', 'Content-Type' => 'application/json' }
         headers['TRON-PRO-API-KEY'] = @config.api_key if @config.api_key
         headers
       end
 
+      # Returns default resource values
+      #
+      # @return [Hash] a hash with zero resource values
       def default_resources
         {
           bandwidth: 0,

data/lib/tron/services/transaction.rb

@@ -0,0 +1,104 @@
+require_relative '../utils/http'
+require_relative '../key'
+require 'json'
+
+module Tron
+  module Services
+    # The Transaction service handles signing and broadcasting of TRON transactions
+    class Transaction
+      # Creates a new instance of the Transaction service
+      #
+      # @param configuration [Tron::Configuration] the configuration object
+      def initialize(configuration)
+        @configuration = configuration
+        @base_url = configuration.base_url
+      end
+
+      # Signs and broadcasts a transaction
+      #
+      # @param transaction [Hash] the transaction to sign and broadcast
+      # @param private_key [String] the private key to sign the transaction with
+      # @param local_signing [Boolean] whether to sign locally (default: true)
+      # @return [Hash] the response from the broadcast
+      def sign_and_broadcast(transaction, private_key, local_signing: true)
+        if local_signing
+          signed_tx = sign_transaction_locally(transaction, private_key)
+        else
+          signed_tx = sign_transaction_via_api(transaction, private_key)
+        end
+
+        broadcast_transaction(signed_tx)
+      end
+
+      private
+
+      # Signs a transaction locally using the private key
+      #
+      # IMPORTANT: TRON uses SHA256 for transaction hashing, NOT Keccak256
+      # The txID provided by TronGrid API is already the correct SHA256 hash
+      # of the properly protobuf-serialized raw_data
+      #
+      # @param transaction [Hash] the transaction to sign (must have 'txID' field)
+      # @param private_key [String] the private key in hex format
+      # @return [Hash] the signed transaction
+      # @raise [ArgumentError] if transaction doesn't have txID field
+      def sign_transaction_locally(transaction, private_key)
+        # Create a key instance with the provided private key
+        key = Key.new(priv: private_key)
+
+        # Ensure transaction has txID from TronGrid API
+        unless transaction['txID']
+          raise ArgumentError, "Transaction must have 'txID' field. Create transaction via TronGrid API first."
+        end
+
+        # The txID is the SHA256 hash of the protobuf-serialized raw_data
+        # Convert from hex string to binary for signing
+        tx_hash = Tron::Utils::Crypto.hex_to_bin(transaction['txID'])
+
+        # Sign the transaction hash locally
+        # SECURITY: Private key never leaves this machine!
+        signature = key.sign(tx_hash)
+
+        # Add the signature to the transaction
+        transaction['signature'] = [signature]
+
+        transaction
+      end
+
+      # Signs a transaction via the API (legacy method)
+      #
+      # @param transaction [Hash] the transaction to sign
+      # @param private_key [String] the private key in hex format
+      # @return [Hash] the signed transaction from the API
+      def sign_transaction_via_api(transaction, private_key)
+        # Legacy API-based signing
+        endpoint = "#{@base_url}/wallet/gettransactionsign"
+        payload = {
+          transaction: transaction,
+          private_key: private_key
+        }
+
+        Utils::HTTP.post(endpoint, payload)
+      end
+
+      # Broadcasts a signed transaction to the TRON network
+      #
+      # @param signed_transaction [Hash] the signed transaction to broadcast
+      # @return [Hash] the response from the broadcast
+      # @raise [RuntimeError] if the transaction fails to broadcast
+      def broadcast_transaction(signed_transaction)
+        endpoint = "#{@base_url}/wallet/broadcasttransaction"
+
+        response = Utils::HTTP.post(endpoint, signed_transaction)
+
+        # Check if the transaction was successful
+        unless response['result']
+          error = response['Error'] || response['error'] || 'Unknown error'
+          raise "Transaction failed: #{error}"
+        end
+
+        response
+      end
+    end
+  end
+end

data/lib/tron/signature.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Tron
+  # Module for handling TRON signature operations
+  module Signature
+    # Custom error class for signature-related errors
+    class SignatureError < StandardError; end
+    
+    # Prefix byte for TRON signed messages
+    PREFIX_BYTE = "\x19".freeze
+    
+    # Prefixes a message according to the TRON signed message format
+    # This format is used in personal_sign operations
+    #
+    # @param message [String] the message to prefix
+    # @return [String] the prefixed message ready for signing
+    def self.prefix_message(message)
+      "#{PREFIX_BYTE}Tron Signed Message:\n#{message.size}#{message}"
+    end
+  end
+end

data/lib/tron/utils/abi.rb

@@ -0,0 +1,321 @@
+require 'digest'
+
+module Tron
+  module Utils
+    # Utility class for handling TRON contract ABIs
+    class ABI
+      # Type mappings for Solidity to Ruby
+      SOLIDITY_TYPES = {
+        'address' => :address,
+        'uint256' => :uint256,
+        'uint' => :uint256,
+        'bool' => :bool,
+        'bytes16' => :bytes16,
+        'bytes32' => :bytes32,
+        'string' => :string
+      }.freeze
+
+      # Parse function signature
+      #
+      # @param signature [String] the function signature to parse
+      # @return [Hash] a hash with :name and :params keys
+      # @raise [ArgumentError] if the signature is invalid
+      def self.parse_signature(signature)
+        match = signature.match(/^(\w+)\((.*)\)$/)
+        raise ArgumentError, "Invalid function signature: #{signature}" unless match
+
+        {
+          name: match[1],
+          params: match[2].empty? ? [] : match[2].split(',').map(&:strip)
+        }
+      end
+
+      # Encode function call
+      #
+      # @param signature [String] the function signature
+      # @param parameters [Array] the parameter values
+      # @return [String] the encoded function call
+      def self.encode_function_call(signature, parameters = [])
+        parsed = parse_signature(signature)
+
+        # Get function selector (first 4 bytes of keccak256 hash)
+        selector = function_selector(signature)
+
+        # Encode parameters
+        encoded_params = encode_parameters(parsed[:params], parameters)
+
+        selector + encoded_params
+      end
+
+      # Function selector (4-byte hash)
+      #
+      # @param signature [String] the function signature
+      # @return [String] the 4-byte function selector as hex
+      def self.function_selector(signature)
+        require_relative 'crypto'
+        # Note: TRON uses same ABI as Ethereum
+        # Using Keccak256 for hash
+        hash = Crypto.keccak256(signature)
+        # Take only the first 4 bytes (8 hex chars)
+        Crypto.bin_to_hex(hash[0, 4])
+      end
+
+      # Encode parameters
+      #
+      # @param types [Array<String>] the parameter types
+      # @param values [Array] the parameter values
+      # @return [String] the encoded parameters as hex
+      # @raise [ArgumentError] if there's a mismatch between types and values
+      def self.encode_parameters(types, values)
+        raise ArgumentError, "Types and values length mismatch" if types.length != values.length
+
+        encoded_parts = []
+        dynamic_params = []
+        dynamic_offset = types.length * 32 # Each static param takes 32 bytes (64 hex chars)
+        
+        types.each_with_index do |type, index|
+          value = values[index]
+          
+          case type
+          when 'address'
+            # Address is padded to 32 bytes (64 hex chars)
+            padded_address = encode_address(value)
+            encoded_parts << padded_address
+          when 'uint256', 'uint'
+            # Convert to hex and pad to 32 bytes (64 hex chars)
+            hex_value = encode_uint256(value)
+            encoded_parts << hex_value
+          when 'bool'
+            # Boolean to uint256 (1 for true, 0 for false)
+            encoded_parts << encode_bool(value)
+          when /^bytes(\d+)$/
+            # Static, fixed-size bytes array, pad to 32 bytes
+            encoded_parts << encode_bytes($1.to_i, value)
+          when 'string', 'bytes'
+            # For dynamic types, add offset and store actual data separately
+            encoded_parts << dynamic_offset.to_s(16).rjust(64, '0') # offset
+            # Calculate the actual data for later encoding
+            dynamic_data = encode_dynamic_parameter(type, value)
+            dynamic_params << dynamic_data
+            dynamic_offset += (dynamic_data.length / 2.0).ceil # Increase offset by byte length, rounded up to nearest whole byte
+          else
+            raise ArgumentError, "Unsupported ABI type: #{type}"
+          end
+        end
+        
+        # Encode dynamic parameters
+        dynamic_parts = []
+        dynamic_params.each do |data|
+          dynamic_parts << data
+        end
+        
+        (encoded_parts + dynamic_parts).join
+      end
+
+      # Encode a single value
+      #
+      # @param type [String] the type to encode
+      # @param value [Object] the value to encode
+      # @return [String] the encoded value as hex
+      # @raise [ArgumentError] if the type is unsupported
+      def self.encode_value(type, value)
+        case type
+        when 'address'
+          encode_address(value)
+        when 'uint256', 'uint'
+          encode_uint256(value)
+        when 'bool'
+          encode_bool(value)
+        when /^bytes(\d+)$/
+          encode_bytes($1.to_i, value)
+        when 'string'
+          encode_string(value)
+        else
+          raise ArgumentError, "Unsupported type: #{type}"
+        end
+      end
+
+      # Encode TRON address (T address to hex)
+      #
+      # @param address [String] the TRON address to encode
+      # @return [String] the encoded address as hex
+      def self.encode_address(address)
+        # Convert TRON T-address to hex address
+        # Remove 'T' prefix, convert base58 to hex, pad to 32 bytes
+        hex = Address.to_hex(address)
+        # Strip the 41 prefix for ABI encoding (only use the 20-byte address)
+        hex = hex[2..-1] if hex.start_with?('41')
+        hex.rjust(64, '0') # Pad to 64 hex chars (32 bytes)
+      end
+
+      # Encode uint256
+      #
+      # @param value [Integer, String] the value to encode
+      # @return [String] the encoded uint256 as hex
+      def self.encode_uint256(value)
+        value.to_i.to_s(16).rjust(64, '0')
+      end
+
+      # Encode bool
+      #
+      # @param value [Boolean] the boolean value to encode
+      # @return [String] the encoded boolean as hex
+      def self.encode_bool(value)
+        value ? '1'.rjust(64, '0') : '0'.rjust(64, '0')
+      end
+
+      # Encode bytes
+      #
+      # @param size [Integer] the size of the bytes type
+      # @param value [String] the value to encode
+      # @return [String] the encoded bytes as hex
+      def self.encode_bytes(size, value)
+        hex = value.is_a?(String) ? value.unpack1('H*') : value.to_s
+        # Limit to the size of the bytes type and pad to 32 bytes
+        hex_part = hex[0...(size * 2)] # Each byte is 2 hex chars
+        hex_part.ljust(64, '0')
+      end
+
+      # Encode string
+      #
+      # @param value [String] the string to encode
+      # @raise [NotImplementedError] since string encoding is handled separately
+      def self.encode_string(value)
+        # For dynamic types like string, return the length and data separately
+        # This will be handled by the main encode_parameters method
+        raise NotImplementedError, "String encoding is handled via encode_dynamic_parameter"
+      end
+
+      # Encode bytes (dynamic type)
+      #
+      # @param value [String] the bytes value to encode
+      # @return [String] the encoded dynamic bytes as hex
+      def self.encode_bytes_dynamic(value)
+        # For dynamic bytes, encode length and data
+        bytes_data = value.is_a?(String) ? value : value.to_s
+        bytes_array = bytes_data.start_with?('0x') ? bytes_data[2..-1].scan(/../) : bytes_data.scan(/../)
+        length = bytes_array.length.to_s(16).rjust(64, '0')
+        data = bytes_array.map { |b| b.rjust(2, '0') }.join
+        # Pad data to 32-byte boundaries (64 hex chars)
+        padded_length = ((data.length / 64.0).ceil * 64).to_i
+        padded_data = data.ljust(padded_length, '0')
+        
+        length + padded_data
+      end
+
+      # Decode output
+      #
+      # @param type [String] the type to decode
+      # @param hex_data [String] the hex data to decode
+      # @return [Object] the decoded value
+      def self.decode_output(type, hex_data)
+        case type
+        when 'bool'
+          hex_data.to_i(16) != 0
+        when 'address'
+          Address.from_hex(hex_data)
+        when 'uint256', 'uint'
+          hex_data.to_i(16)
+        else
+          hex_data
+        end
+      end
+
+      # Decodes parameters based on ABI types
+      #
+      # @param types [Array<String>] the types to decode
+      # @param data [String] the hex data to decode
+      # @return [Array] the decoded values
+      # @raise [ArgumentError] if the data is invalid or type is unsupported
+      def self.decode_parameters(types, data)
+        # Remove '0x' prefix if present
+        raw_data = data.start_with?('0x') ? data[2..-1] : data
+
+        # Ensure the data length is valid
+        if raw_data.length % 64 != 0
+          raise ArgumentError, "Invalid data length: must be multiple of 64 hex chars"
+        end
+
+        values = []
+        pos = 0
+
+        types.each do |type|
+          # Each parameter is 32 bytes (64 hex chars)
+          param_hex = raw_data[pos...(pos + 64)]
+          pos += 64
+
+          case type
+          when /address/
+            # Extract the address (last 40 hex chars)
+            addr_hex = param_hex[-40..-1]
+            # Add TRON prefix
+            values << "41#{addr_hex}"
+          when /uint/, /int/
+            # Convert hex to integer
+            values << param_hex.to_i(16)
+          when /bool/
+            # Boolean is 0 or 1
+            values << (param_hex.to_i(16) != 0)
+          when /string|bytes/
+            # Dynamic type - get offset first
+            offset = param_hex.to_i(16) * 2 # Convert to byte position in hex string
+
+            # Extract length of data
+            length_hex = raw_data[offset...(offset + 64)]
+            length = length_hex.to_i(16) * 2 # Each byte is 2 hex chars
+
+            # Extract actual data
+            actual_data = raw_data[(offset + 64)...(offset + 64 + length)]
+
+            if type.start_with?('string')
+              # Convert hex to string
+              values << [actual_data].pack('H*')
+            else
+              # Return hex string for bytes
+              values << actual_data
+            end
+          else
+            raise ArgumentError, "Unsupported ABI type for decoding: #{type}"
+          end
+        end
+
+        values
+      end
+
+      private
+
+      # Helper method to encode dynamic parameters
+      #
+      # @param type [String] the dynamic type ('string' or 'bytes')
+      # @param value [Object] the value to encode
+      # @return [String] the encoded dynamic parameter as hex
+      # @raise [ArgumentError] if the type is unsupported
+      def self.encode_dynamic_parameter(type, value)
+        if type.start_with?('string')
+          # For strings, we need to encode length and data
+          str_bytes = value.bytes
+          length = str_bytes.length.to_s(16).rjust(64, '0')
+          data = str_bytes.map { |b| b.to_s(16).rjust(2, '0') }.join
+          # Pad data to 32-byte boundaries (64 hex chars)
+          padded_length = ((data.length / 64.0).ceil * 64).to_i
+          padded_data = data.ljust(padded_length, '0')
+
+          length + padded_data
+        elsif type.start_with?('bytes')
+          # For bytes, similar to string
+          bytes_data = value.is_a?(String) ? value : value.to_s
+          bytes_array = bytes_data.start_with?('0x') ? bytes_data[2..-1].scan(/../) : bytes_data.scan(/../)
+          length = bytes_array.length.to_s(16).rjust(64, '0')
+          data = bytes_array.map { |b| b.rjust(2, '0') }.join
+          # Pad data to 32-byte boundaries (64 hex chars)
+          padded_length = ((data.length / 64.0).ceil * 64).to_i
+          padded_data = data.ljust(padded_length, '0')
+
+          length + padded_data
+        else
+          raise ArgumentError, "Unsupported dynamic type: #{type}"
+        end
+      end
+    end
+  end
+end