tron.rb 1.1.2 → 1.1.3

data/lib/tron/abi/type.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module Tron
+  module Abi
+    # Provides a class to handle and parse common ABI types.
+    class Type
+      # Provides a specific parser error if type cannot be determined.
+      class ParseError < StandardError; end
+
+      # The base attribute, e.g., `string` or `bytes`.
+      attr :base_type
+
+      # The sub-type attribute, e.g., `256` as size of an uint256.
+      attr :sub_type
+
+      # The dimension attribute, e.g., `[10]` for an array of size 10.
+      attr :dimensions
+
+      # The components of a tuple type.
+      attr :components
+
+      # The name of tuple component.
+      attr :name
+
+      # Create a new Type object for base types, sub types, and dimensions.
+      # Should not be used; use {Type.parse} instead.
+      #
+      # @param base_type [String] the base-type attribute.
+      # @param sub_type [String] the sub-type attribute.
+      # @param dimensions [Array] the dimension attribute.
+      # @param components [Array] the components attribute.
+      # @param component_name [String] the tuple component's name.
+      # @return [Tron::Abi::Type] an ABI type object.
+      def initialize(base_type, sub_type, dimensions, components = nil, component_name = nil)
+        sub_type = sub_type.to_s
+        @base_type = base_type
+        @sub_type = sub_type
+        @dimensions = dimensions
+        @components = components
+        @name = component_name
+      end
+
+      # Converts the self.parse method into a constructor.
+      # Using a simple constructor since konstructor gem isn't available
+      def self.parse(type, components = nil, component_name = nil)
+        new_type = new(nil, nil, nil, nil, nil)
+        new_type.parse(type, components, component_name)
+        new_type
+      end
+
+      # Attempts to parse a string containing a common Solidity type.
+      # Creates a new Type upon success.
+      #
+      # @param type [String] a common Solidity type.
+      # @param components [Array] the components attribute.
+      # @param component_name [String] the tuple component's name.
+      # @return [Tron::Abi::Type] a parsed Type object.
+      # @raise [ParseError] if it fails to parse the type.
+      def parse(type, components = nil, component_name = nil)
+        if type.is_a?(Type)
+          @base_type = type.base_type
+          @sub_type = type.sub_type
+          @dimensions = type.dimensions
+          @components = type.components
+          @name = type.name
+          return
+        end
+
+        # ensure the type string is reasonable before attempting to parse
+        raise ParseError, "Invalid type format" unless type.is_a? String
+
+        if type.start_with?("tuple(") || type.start_with?("(")
+          tuple_str = type.start_with?("tuple(") ? type : "tuple#{type}"
+          inner, rest = extract_tuple(tuple_str)
+          inner_types = split_tuple_types(inner)
+          inner_types.each { |t| Type.parse(t) }
+          base_type = "tuple"
+          sub_type = ""
+          dimension = rest
+          components ||= inner_types.map { |t| { "type" => t } }
+        else
+          match = /\A([a-z]+)([0-9]*x?[0-9]*)((?:\[\d+\]|\[\])*)\z/.match(type)
+          raise ParseError, "Invalid type format" unless match
+          _, base_type, sub_type, dimension = match.to_a
+          sub_type = "256" if %w[uint int].include?(base_type) && sub_type.empty?
+        end
+
+        # type dimension can only be numeric or empty for dynamic arrays
+        dims = dimension.scan(/\[\d+\]|\[\]/)
+        raise ParseError, "Unknown characters found in array declaration" if dims.join != dimension
+
+        # enforce base types
+        validate_base_type base_type, sub_type
+
+        # return a new Type 
+        sub_type = sub_type.to_s
+        @base_type = base_type
+        @sub_type = sub_type
+        @dimensions = dims.map { |x| x == "[]" ? 0 : x[1...-1].to_i }
+        @components = components.map { |component| Abi::Type.parse(component["type"], component.dig("components"), component.dig("name")) } if components&.any?
+        @name = component_name
+      end
+
+      # Creates a new uint256 type used for size.
+      #
+      # @return [Tron::Abi::Type] a uint256 size type.
+      def self.size_type
+        @size_type ||= new("uint", 256, [])
+      end
+
+      # Compares two types for their attributes.
+      #
+      # @param another_type [Tron::Abi::Type] another type to be compared.
+      # @return [Boolean] true if all attributes match.
+      def ==(another_type)
+        base_type == another_type.base_type and
+          sub_type == another_type.sub_type and
+          dimensions == another_type.dimensions
+      end
+
+      # Computes the size of a type if possible.
+      #
+      # @return [Integer] the size of the type; or nil if not available.
+      def size
+        s = nil
+        if dimensions.empty?
+          if !(["string", "bytes", "tuple"].include?(base_type) and sub_type.empty?)
+            s = 32
+          elsif base_type == "tuple" and components&.none?(&:dynamic?)
+            s = components.sum(&:size)
+          end
+        elsif dimensions.last != 0 and !nested_sub.dynamic?
+          s = dimensions.last * nested_sub.size
+        end
+        @size ||= s
+      end
+
+      # Helps to determine whether array is of dynamic size.
+      #
+      # @return [Boolean] true if array is of dynamic size.
+      def dynamic?
+        size.nil?
+      end
+
+      # Types can have nested sub-types in arrays.
+      #
+      # @return [Tron::Abi::Type] nested sub-type.
+      def nested_sub
+        @nested_sub ||= self.class.new(base_type, sub_type, dimensions[0...-1], components, name)
+      end
+
+      # Allows exporting the type as string.
+      #
+      # @return [String] the type string.
+      def to_s
+        if base_type == "tuple"
+          "(" + components.map(&:to_s).join(",") + ")" + (dimensions.size > 0 ? dimensions.map { |x| "[#{x == 0 ? "" : x}]" }.join : "")
+        elsif dimensions.empty?
+          if %w[string bytes].include?(base_type) and sub_type.empty?
+            base_type
+          else
+            "#{base_type}#{sub_type}"
+          end
+        else
+          "#{base_type}#{sub_type}#{dimensions.map { |x| "[#{x == 0 ? "" : x}]" }.join}"
+        end
+      end
+
+      private
+
+      # Validates all known base types and raises if an issue occurs.
+      def validate_base_type(base_type, sub_type)
+        case base_type
+        when "string"
+          # string can not have any suffix
+          raise ParseError, "String type must have no suffix or numerical suffix" unless sub_type.empty?
+        when "bytes"
+          # bytes can be no longer than 32 bytes
+          raise ParseError, "Maximum 32 bytes for fixed-length string or bytes" unless sub_type.empty? or (sub_type.to_i <= 32 and sub_type.to_i > 0)
+        when "tuple"
+          # tuples can not have any suffix
+          raise ParseError, "Tuple type must have no suffix or numerical suffix" unless sub_type.empty?
+        when "uint", "int"
+          # integers must have a numerical suffix
+          raise ParseError, "Integer type must have numerical suffix" unless sub_type =~ /\A[0-9]+\z/
+
+          # integer size must be valid
+          size = sub_type.to_i
+          raise ParseError, "Integer size out of bounds" unless size >= 8 and size <= 256
+          raise ParseError, "Integer size must be multiple of 8" unless size % 8 == 0
+        when "ureal", "real", "fixed", "ufixed"
+          # floats must have valid dimensional suffix
+          raise ParseError, "Real type must have suffix of form <size>x<decimals>, e.g. 128x128" unless sub_type =~ /\A[0-9]+x[0-9]+\z/
+          size, decimals = sub_type.split("x").map(&:to_i)
+          total = size + decimals
+          raise ParseError, "Real size out of bounds (max 32 bytes)" unless total >= 8 and total <= 256
+          raise ParseError, "Real size must be multiples of 8" unless size % 8 == 0
+        when "hash"
+          # hashs must have numerical suffix
+          raise ParseError, "Hash type must have numerical suffix" unless sub_type =~ /\A[0-9]+\z/
+        when "address"
+          # addresses cannot have any suffix
+          raise ParseError, "Address cannot have suffix" unless sub_type.empty?
+        when "bool"
+          # booleans cannot have any suffix
+          raise ParseError, "Bool cannot have suffix" unless sub_type.empty?
+        else
+          # we cannot parse arbitrary types such as 'decimal' or 'hex'
+          raise ParseError, "Unknown base type"
+        end
+      end
+
+      # Extracts the inner type list and trailing dimensions from an inline tuple definition.
+      def extract_tuple(type)
+        idx = 6 # skip "tuple("
+        depth = 1
+        while idx < type.length && depth > 0
+          case type[idx]
+          when "("
+            depth += 1
+          when ")"
+            depth -= 1
+          end
+          idx += 1
+        end
+        raise ParseError, "Invalid tuple format" unless depth.zero?
+        inner = type[6...(idx - 1)]
+        rest = type[idx..] || ""
+        [inner, rest]
+      end
+
+      # Splits a tuple component list into individual type strings, handling nested tuples.
+      def split_tuple_types(str)
+        types = []
+        depth = 0
+        current = ""
+        str.each_char do |ch|
+          case ch
+          when "("
+            depth += 1
+            current += ch
+          when ")"
+            depth -= 1
+            current += ch
+          when ","
+            if depth.zero?
+              types << current
+              current = ""
+            else
+              current += ch
+            end
+          else
+            current += ch
+          end
+        end
+        types << current unless current.empty?
+        types
+      end
+    end
+  end
+end

data/lib/tron/abi/util.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Tron
+  module Abi
+    # Provides utility functions for ABI encoding/decoding
+    module Util
+      extend self
+
+      # Maximum uint value
+      UINT_MAX = (2 ** 256) - 1
+
+      # Minimum uint value
+      UINT_MIN = 0
+
+      # Maximum int value
+      INT_MAX = (2 ** 255) - 1
+
+      # Minimum int value
+      INT_MIN = -(2 ** 255)
+
+      # Pads a length to a multiple of 32 bytes
+      #
+      # @param x [Integer] the length to pad
+      # @return [Integer] the padded length
+      def ceil32(x)
+        ((x + 31) / 32).floor * 32
+      end
+
+      # Pads an integer to 32 bytes in binary format
+      #
+      # @param x [Integer] the integer to pad
+      # @return [String] the padded integer as a binary string
+      def zpad_int(x)
+        # Ensure x is positive for modulo operation
+        x = x % (2 ** 256) if x >= 2 ** 256 || x < 0
+        [x.to_s(16).rjust(64, '0')].pack('H*')
+      end
+
+      # Pads a string to a specified length with null bytes
+      #
+      # @param s [String] the string to pad
+      # @param length [Integer] the target length
+      # @return [String] the padded string
+      def zpad(s, length)
+        s + "\x00" * (length - s.length)
+      end
+
+      # Pads a hex string to 32 bytes (64 hex characters), returning binary
+      #
+      # @param s [String] the hex string to pad
+      # @return [String] the padded hex as a binary string
+      def zpad_hex(s)
+        s = s[2..-1] if s.start_with?('0x', '0X')
+        [s.rjust(64, '0')].pack('H*')
+      end
+
+      # Checks if a string is prefixed with 0x
+      #
+      # @param s [String] the string to check
+      # @return [Boolean] true if prefixed with 0x or 0X
+      def prefixed?(s)
+        s.start_with?('0x', '0X')
+      end
+
+      # Checks if a string is a valid hex string
+      #
+      # @param s [String] the string to check
+      # @return [Boolean] true if it's a valid hex string
+      def hex?(s)
+        s = s[2..-1] if s.start_with?('0x', '0X')
+        s.match(/\A[0-9a-fA-F]*\z/)
+      end
+
+      # Convert hex string to binary
+      #
+      # @param s [String] the hex string to convert
+      # @return [String] the binary representation
+      def hex_to_bin(s)
+        s = s[2..-1] if s.start_with?('0x', '0X')
+        [s].pack('H*')
+      end
+
+      # Convert binary to hex string
+      #
+      # @param b [String] the binary to convert
+      # @return [String] the hexadecimal representation
+      def bin_to_hex(b)
+        b.unpack('H*').first
+      end
+
+      # Deserialize big endian integer from binary data
+      #
+      # @param data [String] the binary data to deserialize
+      # @return [Integer] the deserialized integer
+      def deserialize_big_endian_to_int(data)
+        data.unpack1('H*').to_i(16)
+      end
+    end
+  end
+end

data/lib/tron/abi.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Tron
+  module Abi
+    # Base error class for ABI-related errors
+    class Error < StandardError; end
+    
+    # Error raised when there's an issue with encoding
+    class EncodingError < Error; end
+    
+    # Error raised when there's an issue with decoding  
+    class DecodingError < Error; end
+    
+    # Error raised when a value is out of bounds for its type
+    class ValueOutOfBounds < Error; end
+    
+    # Require all components of the ABI module
+    require_relative 'abi/type'
+    require_relative 'abi/encoder'
+    require_relative 'abi/decoder'
+    require_relative 'abi/function'
+    require_relative 'abi/event'
+    require_relative 'abi/util'
+    require_relative 'abi/constant'
+    
+    # For address handling functionality
+    require_relative 'utils/address'
+    require_relative 'key'
+    
+    # Convenience method for encoding
+    def self.encode(types, values)
+      # Parse the types
+      parsed_types = types.map { |t| Type.parse(t) }
+
+      # Split into static and dynamic parts
+      static_parts = []
+      dynamic_parts = []
+      dynamic_offsets = []
+      offset_index = 0
+
+      parsed_types.each_with_index do |type, i|
+        if type.dynamic?
+          # For dynamic types, store a placeholder offset and the actual data
+          static_parts << nil  # Placeholder for offset
+          dynamic_parts << Encoder.type(type, values[i])
+          dynamic_offsets[offset_index] = dynamic_parts.length - 1
+          offset_index += 1
+        else
+          # For static types, encode directly
+          static_parts << Encoder.type(type, values[i])
+        end
+      end
+
+      # Calculate actual offsets for dynamic parts
+      # The offset is the position in the encoded result where the dynamic data begins
+      # This is after all static parts (each parameter takes 32 bytes)
+      static_size = parsed_types.count * 32  # Size of all parameter slots
+      dynamic_offset = static_size  # Start of dynamic data
+
+      # Replace the nil placeholders with actual offsets
+      placeholders_replaced = 0
+      static_parts.map! do |part|
+        if part.nil?
+          offset_value = dynamic_offset
+          # Update offset for next dynamic part
+          dynamic_part_idx = dynamic_offsets[placeholders_replaced]
+          dynamic_offset += dynamic_parts[dynamic_part_idx].bytesize  # Use bytesize for binary
+          placeholders_replaced += 1
+          Encoder.type(Type.parse('uint256'), offset_value)
+        else
+          part
+        end
+      end
+
+      # Combine static and dynamic parts and convert to hex at the boundary
+      result_binary = static_parts.join + dynamic_parts.join
+      Util.bin_to_hex(result_binary)
+    end
+
+    # Convenience method for decoding
+    def self.decode(types, hex_data)
+      # Convert hex to binary at the boundary
+      data = Util.hex_to_bin(hex_data)
+      parsed_types = types.map { |t| Type.parse(t) }
+
+      # Decode each parameter, tracking the static section position as we go
+      results = []
+      static_offset = 0  # Position in the static section for both offset pointers and static values
+      
+      parsed_types.each do |type|
+        if type.dynamic?
+          # Check if we have enough data in static section for this offset
+          raise DecodingError, "Insufficient data for dynamic type offset" if data.bytesize < static_offset + 32
+          # Get offset from static section for this dynamic parameter
+          offset_value = Util.deserialize_big_endian_to_int(data[static_offset, 32])
+          
+          # Check if we have enough data at the dynamic offset location
+          raise DecodingError, "Insufficient data for dynamic type at offset #{offset_value}" if data.bytesize < offset_value + 32
+          
+          # Determine the size of data for this dynamic parameter
+          # First, read the length from the dynamic data location
+          data_length = Util.deserialize_big_endian_to_int(data[offset_value, 32])
+          
+          # Calculate total data size based on type
+          if %w(string bytes).include?(type.base_type) and type.sub_type.empty? and type.dimensions.empty?
+            # String or bytes: 32-byte length + padded content
+            total_size = 32 + Util.ceil32(data_length)
+          elsif !type.dimensions.empty?  # Array type
+            # Dynamic array: 32-byte length + element encodings
+            nested_type = type.nested_sub
+            if nested_type.dynamic?
+              # Complex case for arrays with dynamic elements - use full remaining data
+              param_data = data[offset_value..-1]
+              decoded_value = Decoder.type(type, param_data)
+              results << decoded_value
+              static_offset += 32  # Advance past the offset pointer
+              next
+            else
+              # Array with static elements: 32-byte length + (element_size * count)
+              total_size = 32 + (nested_type.size || 32) * data_length
+            end
+          else
+            # Default for other dynamic types: 32-byte length + padded content
+            total_size = 32 + Util.ceil32(data_length)
+          end
+          
+          # Verify we have enough data
+          raise DecodingError, "Insufficient data for dynamic type content" if data.bytesize < offset_value + total_size
+          
+          # Extract the parameter's data and decode
+          param_data = data[offset_value, total_size]
+          decoded_value = Decoder.type(type, param_data)
+          results << decoded_value
+          static_offset += 32  # Advance past the offset pointer
+        else
+          # For static types, decode directly from current static position
+          size = type.size  # Size in bytes
+          if size
+            # Check bounds before reading static data
+            raise DecodingError, "Insufficient data for static type" if data.bytesize < static_offset + size
+            decoded_value = Decoder.type(type, data[static_offset, size])
+            results << decoded_value
+            static_offset += size  # Advance to next position
+          else
+            raise DecodingError, "Cannot decode static type without size"
+          end
+        end
+      end
+
+      results
+    end
+  end
+end

data/lib/tron/client.rb

@@ -3,11 +3,26 @@ require_relative 'configuration'
 require_relative 'services/balance'
 require_relative 'services/resources'
 require_relative 'services/price'
+require_relative 'services/contract'
 
 module Tron
+  # The main client class for interacting with the TRON blockchain
+  # Provides methods for checking balances, resources, prices, and contract interactions
   class Client
     attr_reader :configuration
 
+    # Creates a new client instance with the given options
+    #
+    # @param options [Hash] configuration options
+    # @option options [String] :api_key TronGrid API key
+    # @option options [String] :tronscan_api_key Tronscan API key
+    # @option options [Symbol] :network network to use (:mainnet, :shasta, :nile)
+    # @option options [Integer] :timeout timeout for API requests
+    # @option options [Boolean] :cache_enabled whether caching is enabled
+    # @option options [Integer] :cache_ttl cache TTL in seconds
+    # @option options [Integer] :cache_max_stale max stale time in seconds
+    # @option options [String] :default_address default address for read-only calls
+    # @option options [Integer] :fee_limit default fee limit for transactions
     def initialize(options = {})
       @configuration = Configuration.new
       
@@ -23,27 +38,54 @@ module Tron
       @configuration.tronscan_api_key ||= ENV['TRONSCAN_API_KEY']
     end
 
+    # Configures the default client
+    #
+    # @yield [config] block to configure the client
+    # @yieldparam [Tron::Configuration] config the configuration object
     def self.configure
       yield configuration if block_given?
     end
 
+    # Returns the default configuration
+    #
+    # @return [Tron::Configuration] the configuration object
     def self.configuration
       @configuration ||= Configuration.new
     end
 
+    # Returns the balance service instance
+    #
+    # @return [Tron::Services::Balance] the balance service
     def balance_service
       @balance_service ||= Services::Balance.new(@configuration)
     end
 
+    # Returns the resources service instance
+    #
+    # @return [Tron::Services::Resources] the resources service
     def resources_service
       @resources_service ||= Services::Resources.new(@configuration)
     end
 
+    # Returns the price service instance
+    #
+    # @return [Tron::Services::Price] the price service
     def price_service
       @price_service ||= Services::Price.new(@configuration)
     end
 
-    # Convenience methods that combine multiple services
+    # Returns the contract service instance
+    #
+    # @return [Tron::Services::Contract] the contract service
+    def contract_service
+      @contract_service ||= Services::Contract.new(@configuration)
+    end
+
+    # Get wallet balance information including TRX and TRC20 tokens
+    #
+    # @param address [String] TRON address to check
+    # @param strict [Boolean] whether to enable strict validation
+    # @return [Hash] balance information hash
     def get_wallet_balance(address, strict: false)
       validate_address!(address)
       
@@ -54,6 +96,11 @@ module Tron
       }
     end
 
+    # Get complete account information including balances and resources
+    #
+    # @param address [String] TRON address to check
+    # @param strict [Boolean] whether to enable strict validation
+    # @return [Hash] full account information hash
     def get_full_account_info(address, strict: false)
       validate_address!(address)
       
@@ -65,6 +112,11 @@ module Tron
       }
     end
 
+    # Get wallet portfolio including balances converted to USD values
+    #
+    # @param address [String] TRON address to check
+    # @param include_zero_balances [Boolean] whether to include tokens with zero balance
+    # @return [Hash] portfolio information with USD values
     def get_wallet_portfolio(address, include_zero_balances: false)
       validate_address!(address)
 
@@ -120,10 +172,16 @@ module Tron
       }
     end
 
+    # Check if caching is enabled
+    #
+    # @return [Boolean] true if caching is enabled
     def cache_enabled?
       configuration.cache_enabled
     end
 
+    # Get cache statistics
+    #
+    # @return [Hash] cache statistics for different services
     def cache_stats
       {
         price: price_service.cache_stats,
@@ -131,6 +189,7 @@ module Tron
       }
     end
 
+    # Clear all caches
     def clear_cache
       price_service.clear_cache
       balance_service.clear_cache
@@ -138,6 +197,10 @@ module Tron
 
     private
 
+    # Validates a TRON address
+    #
+    # @param address [String] TRON 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)