tron.rb 1.1.2 → 1.1.4

data/lib/tron/utils/address.rb

@@ -1,38 +1,91 @@
 # lib/tron/utils/address.rb
-require 'base58'
+require 'base58-alphabets'
 
 module Tron
   module Utils
+    # TRON address utilities for validation, conversion, and formatting
     class Address
+      # TRON address prefix in hex (41 corresponds to 'T' in Base58)
+      ADDRESS_PREFIX = '41'.freeze
+      
+      # Validates a TRON address
+      #
+      # @param address [String] the TRON address to validate
+      # @return [Boolean] true if the address is valid, false otherwise
       def self.validate(address)
         return false unless address && address.length == 34 && address.start_with?('T')
         
         begin
-          base58_part = address[1..-1]
-          Base58.decode(base58_part)
-          true
+          # Decode the entire Base58 address to get the raw bytes
+          decoded_bytes = Base58.decode_bin(address)
+          # Should have 21 bytes (1 byte prefix + 20 address bytes) + 4 bytes checksum = 25 bytes total
+          return false unless decoded_bytes.length == 25
+          
+          # Split into address part (21 bytes) and checksum (4 bytes)
+          addr_part = decoded_bytes[0...21]
+          checksum = decoded_bytes[21..-1]
+          
+          # Verify the checksum by double-SHA256 of the address part
+          require 'digest'
+          expected_checksum = Digest::SHA256.digest(Digest::SHA256.digest(addr_part))[0...4]
+          
+          # Check if the address prefix is correct (should be 0x41 which is decimal 65)
+          return (checksum == expected_checksum) && (addr_part[0].ord == 65) # 0x41 = 65 in decimal
         rescue
           false
         end
       end
 
+      # Converts a Base58 TRON address to hex format
+      #
+      # @param address [String] the Base58 TRON address to convert
+      # @return [String] the address in hex format
+      # @raise [ArgumentError] if the address is invalid
       def self.to_hex(address)
-        return address if address.start_with?('41') && address.length == 42 # Already hex format
+        return address if address.start_with?(ADDRESS_PREFIX) && address.length == 42 # Already hex format
 
-        base58_part = address.start_with?('T') ? address[1..-1] : address
-        decoded = Base58.decode(base58_part)
-        '41' + decoded.unpack('H*').first
+        # Decode the full Base58 address to get the raw bytes
+        decoded_bytes = Base58.decode_bin(address)
+        # Should have 21 bytes (1 byte prefix + 20 address bytes) + 4 bytes checksum = 25 bytes total
+        raise ArgumentError, "Invalid TRON address format: #{address}" unless decoded_bytes.length == 25
+
+        # Take only the first 21 bytes (address part with prefix)
+        addr_part = decoded_bytes[0...21]
+
+        # Convert to hex string
+        addr_part.unpack1('H*')
+      end
+
+      # Converts a hex address to Base58 format
+      #
+      # @param hex_address [String] the hex address to convert
+      # @return [String] the address in Base58 format
+      def self.from_hex(hex_address)
+        to_base58(hex_address)
       end
 
+      # Converts a hex address to Base58 format
+      #
+      # @param hex_address [String] the hex address to convert
+      # @return [String] the address in Base58 format
       def self.to_base58(hex_address)
         return hex_address if hex_address.start_with?('T') && hex_address.length == 34 # Already base58 format
 
-        hex_without_prefix = hex_address.start_with?('41') ? hex_address[2..-1] : hex_address
+        hex_without_prefix = hex_address.start_with?(ADDRESS_PREFIX) ? hex_address[2..-1] : hex_address
         address_bytes = [hex_without_prefix].pack('H*')
         
+        # Verify the address part is correct length (21 bytes after including prefix)
+        if address_bytes.length != 21
+          # Add the prefix byte 0x41 (decimal 65) if not present
+          address_bytes = [65].pack('C') + address_bytes if address_bytes.length == 20
+        end
+        
         require 'digest'
         checksum = Digest::SHA256.digest(Digest::SHA256.digest(address_bytes))[0...4]
-        Base58.binary_to_base58(address_bytes + checksum)
+        full_bytes = address_bytes + checksum
+
+        # Encode to Base58
+        Base58.encode_bin(full_bytes)
       end
     end
   end

data/lib/tron/utils/cache.rb

@@ -3,9 +3,13 @@ require 'monitor'
 
 module Tron
   module Utils
+    # A simple thread-safe cache with time-based expiration
     class Cache
       include MonitorMixin
 
+      # Creates a new cache instance with the specified maximum age
+      #
+      # @param max_age [Integer] maximum age of cached entries in seconds (default: 300)
       def initialize(max_age: 300) # 5 minutes default
         super()
         @cache = {}
@@ -13,6 +17,11 @@ module Tron
         @max_age = max_age
       end
 
+      # Retrieves a value from the cache
+      # Automatically removes expired entries before retrieval
+      #
+      # @param key [Object] the cache key
+      # @return [Object, nil] the cached value or nil if not found or expired
       def get(key)
         synchronize do
           cleanup_expired_entries
@@ -25,6 +34,10 @@ module Tron
         end
       end
 
+      # Sets a value in the cache with the current timestamp
+      #
+      # @param key [Object] the cache key
+      # @param value [Object] the value to cache
       def set(key, value)
         synchronize do
           @cache[key] = value
@@ -32,6 +45,9 @@ module Tron
         end
       end
 
+      # Removes a specific key from the cache
+      #
+      # @param key [Object] the cache key to delete
       def delete(key)
         synchronize do
           @cache.delete(key)
@@ -39,6 +55,7 @@ module Tron
         end
       end
 
+      # Clears all entries from the cache
       def clear
         synchronize do
           @cache.clear
@@ -48,6 +65,7 @@ module Tron
 
       private
 
+      # Removes expired entries from the cache
       def cleanup_expired_entries
         now = Time.now.to_f
         expired_keys = @timestamps.select { |_, timestamp| now - timestamp > @max_age }.keys

data/lib/tron/utils/crypto.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+require 'digest/keccak'
+require 'openssl'
+require 'base58-alphabets'
+
+module Tron
+  module Utils
+    # Crypto utilities for various cryptographic operations needed in TRON blockchain
+    module Crypto
+      extend self
+
+      # Converts a hexadecimal string to binary data
+      #
+      # @param string [String] the hex string to convert (with or without 0x prefix)
+      # @return [String] the binary representation
+      def hex_to_bin(string)
+        string = string[2..-1] if string.start_with?('0x', '0X')
+        [string].pack('H*')
+      end
+
+      # Converts binary data to a hexadecimal string
+      #
+      # @param bytes [String] the binary data to convert
+      # @return [String] the hexadecimal representation
+      def bin_to_hex(bytes)
+        bytes.unpack('H*').first
+      end
+
+      # Computes the Keccak256 hash of the given value
+      #
+      # @param value [String] the value to hash
+      # @return [String] the Keccak256 hash
+      def keccak256(value)
+        # Using keccak gem for Keccak256 hashing
+        Digest::Keccak.digest(value, 256)
+      end
+
+      # Computes the SHA256 hash of the given value
+      #
+      # @param value [String] the value to hash
+      # @return [String] the SHA256 hash
+      def sha256(value)
+        OpenSSL::Digest::SHA256.digest(value)
+      end
+
+      # Checks if a string is a valid hexadecimal string
+      #
+      # @param str [String] the string to check
+      # @return [Boolean] true if the string is valid hex, false otherwise
+      def is_hex?(str)
+        return false unless str.is_a?(String)
+        str = str[2..-1] if str.start_with?('0x', '0X')
+        str.match(/\A[0-9a-fA-F]*\z/)
+      end
+      
+      # Applies Base58Check encoding to the given data
+      # This creates a checksum and encodes the data with the checksum
+      #
+      # @param data [String] the data to encode
+      # @return [String] the Base58Check encoded string
+      def base58check(data)
+        checksum = sha256(sha256(data))[0..3]
+        Base58.encode_bin(data + checksum)
+      end
+    end
+  end
+end

data/lib/tron/utils/http.rb

@@ -6,6 +6,7 @@ require 'digest'
 
 module Tron
   module Utils
+    # HTTP utility class that handles HTTP requests with caching and error handling
     class HTTP
       # TTL values for different endpoint types (in seconds)
       # These are optimized based on data volatility
@@ -26,7 +27,8 @@ module Tron
         default: { ttl: 300, max_stale: 600 }
       }.freeze
 
-      # GET request with optional caching
+      # Makes a GET request with optional caching
+      #
       # @param url [String] the URL to request
       # @param headers [Hash] request headers
       # @param cache_options [Hash] optional cache configuration
@@ -34,6 +36,7 @@ module Tron
       # @option cache_options [Integer] :ttl custom TTL in seconds
       # @option cache_options [Integer] :max_stale custom max_stale in seconds
       # @option cache_options [Symbol] :endpoint_type endpoint type for TTL lookup
+      # @return [Hash, Array] the parsed JSON response
       def self.get(url, headers = {}, cache_options = {})
         if should_use_cache?(cache_options)
           cache_key = generate_cache_key('GET', url, headers)
@@ -47,12 +50,33 @@ module Tron
         end
       end
 
-      # POST request (no caching for mutations)
-      def self.post(url, body = nil, headers = {})
-        make_request(Net::HTTP::Post, url, body, headers)
+      # Makes a POST request (no caching for mutations)
+      #
+      # @param url [String] the URL to request
+      # @param payload [Hash, String] the request payload
+      # @param cache_options [Hash] optional cache configuration (unused for POST)
+      # @return [Hash, Array] the parsed JSON response
+      def self.post(url, payload, cache_options = {})
+        require 'net/http'
+        require 'json'
+
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == 'https')
+
+        request = Net::HTTP::Post.new(uri.path, {
+          'Content-Type' => 'application/json',
+          'TRON-PRO-API-KEY' => Tron.configuration.api_key
+        }.compact)
+
+        request.body = payload.to_json
+
+        response = http.request(request)
+        JSON.parse(response.body)
       end
 
       # Clear cache for a specific endpoint
+      #
       # @param url [String] the URL to clear from cache
       # @param headers [Hash] request headers used in the original request
       def self.clear_cache(url, headers = {})
@@ -61,8 +85,10 @@ module Tron
       end
 
       # Get cache statistics for an endpoint
+      #
       # @param url [String] the URL to get stats for
       # @param headers [Hash] request headers used in the original request
+      # @return [Hash] cache statistics for the endpoint
       def self.cache_stats(url, headers = {})
         cache_key = generate_cache_key('GET', url, headers)
         Tron::Cache.stats(cache_key)
@@ -71,6 +97,9 @@ module Tron
       private
 
       # Determine if caching should be used for this request
+      #
+      # @param cache_options [Hash] the cache configuration options
+      # @return [Boolean] true if caching should be used
       def self.should_use_cache?(cache_options)
         # Check if caching is explicitly disabled for this request
         return false if cache_options[:enabled] == false
@@ -80,6 +109,9 @@ module Tron
       end
 
       # Get TTL configuration for the request
+      #
+      # @param cache_options [Hash] the cache configuration options
+      # @return [Hash] TTL configuration with :ttl and :max_stale values
       def self.get_ttl_config(cache_options)
         # If custom TTL provided, use it
         if cache_options[:ttl] && cache_options[:max_stale]
@@ -104,6 +136,11 @@ module Tron
       end
 
       # Generate a unique cache key based on request parameters
+      #
+      # @param method [String] the HTTP method
+      # @param url [String] the request URL
+      # @param headers [Hash] the request headers
+      # @return [String] the cache key
       def self.generate_cache_key(method, url, headers)
         # Include method, URL, and relevant headers in the cache key
         # Exclude headers that don't affect the response (like User-Agent)
@@ -112,6 +149,14 @@ module Tron
         Digest::SHA256.hexdigest(key_parts.to_json)
       end
 
+      # Makes an HTTP request
+      #
+      # @param method_class [Class] the HTTP method class (e.g. Net::HTTP::Get)
+      # @param url [String] the URL to request
+      # @param body [String] the request body
+      # @param headers [Hash] the request headers
+      # @return [Hash, Array] the parsed JSON response
+      # @raise [RuntimeError] if the request fails
       def self.make_request(method_class, url, body, headers)
         uri = URI(url)
         http = Net::HTTP.new(uri.host, uri.port)

data/lib/tron/utils/rate_limiter.rb

@@ -3,9 +3,14 @@ require 'monitor'
 
 module Tron
   module Utils
+    # A thread-safe rate limiter that limits requests based on a maximum number of requests within a specific time window
     class RateLimiter
       include MonitorMixin
 
+      # Creates a new rate limiter instance
+      #
+      # @param max_requests [Integer] maximum number of requests allowed in the time window
+      # @param time_window [Float] time window in seconds
       def initialize(max_requests:, time_window:)
         super()
         @max_requests = max_requests
@@ -13,6 +18,9 @@ module Tron
         @request_timestamps = []
       end
 
+      # Checks if a request can be made without exceeding the rate limit
+      #
+      # @return [Boolean] true if a request can be made, false otherwise
       def can_make_request?
         synchronize do
           cleanup_old_requests
@@ -20,6 +28,10 @@ module Tron
         end
       end
 
+      # Executes a request, blocking if necessary to respect the rate limit
+      # This method will sleep if necessary to ensure the rate limit is not exceeded
+      #
+      # @return [Float] the time until the next request is allowed
       def execute_request
         synchronize do
           cleanup_old_requests
@@ -40,11 +52,15 @@ module Tron
 
       private
 
+      # Removes timestamps that are outside the time window
       def cleanup_old_requests
         now = Time.now.to_f
         @request_timestamps.reject! { |timestamp| now - timestamp > @time_window }
       end
 
+      # Calculates the time until the next request is allowed
+      #
+      # @return [Float] the time in seconds until the next request is allowed
       def calculate_time_to_next_request
         if @request_timestamps.length <= 1
           0

data/lib/tron/version.rb

@@ -2,5 +2,5 @@
 
 # lib/tron/version.rb
 module Tron
-  VERSION = "1.1.2".freeze
+  VERSION = "1.1.4".freeze
 end

data/lib/tron.rb

@@ -5,9 +5,20 @@ require_relative 'tron/version'
 require_relative 'tron/client'
 require_relative 'tron/configuration'
 require_relative 'tron/cache'
+require_relative 'tron/key'
+require_relative 'tron/signature'
+require_relative 'tron/abi'
+require_relative 'tron/contract'
+require_relative 'tron/protobuf'
 
+# The main module for the Tron Ruby Client
+# This module provides a simplified interface to interact with the TRON blockchain
 module Tron
   class << self
+    # Returns the default client instance
+    # Creates a new instance if one doesn't exist
+    #
+    # @return [Tron::Client] the client instance
     def client
       @client ||= Client.new(
         api_key: Client.configuration.api_key,
@@ -17,16 +28,29 @@ module Tron
       )
     end
 
+    # Configures the default client
+    # Resets the client when configuration changes
+    #
+    # @yield [config] block to configure the client
+    # @yieldparam [Tron::Configuration] config the configuration object
     def configure(&block)
       @client = nil # Reset client when configuration changes
       Client.configure(&block)
     end
 
+    # Returns the current configuration
+    #
+    # @return [Tron::Configuration] the configuration object
     def configuration
       Client.configuration
     end
 
-    # Delegate common methods to the default client
+    # Delegates common methods to the default client
+    #
+    # @param method [Symbol] the method to call
+    # @param args [Array] arguments to pass to the method
+    # @param block [Proc] block to pass to the method
+    # @return the result of the method call
     def method_missing(method, *args, &block)
       if client.respond_to?(method)
         client.send(method, *args, &block)
@@ -35,6 +59,11 @@ module Tron
       end
     end
 
+    # Checks if the module responds to a method
+    #
+    # @param method [Symbol] the method to check
+    # @param include_private [Boolean] whether to include private methods
+    # @return [Boolean] true if the module responds to the method
     def respond_to_missing?(method, include_private = false)
       client.respond_to?(method) || super
     end

metadata

@@ -1,43 +1,85 @@
 --- !ruby/object:Gem::Specification
 name: tron.rb
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
-- Your Name
+- Bolo Michelin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-24 00:00:00.000000000 Z
+date: 2025-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: base58
+  name: base58-alphabets
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: keccak
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rbsecp256k1
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.22'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.22'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -83,7 +125,7 @@ dependencies:
 description: A Ruby gem for interacting with TRON blockchain APIs, including balance
   checking, resource information, and token prices.
 email:
-- your.email@example.com
+- bolo@scionx.io
 executables:
 - tron-wallet
 extensions: []
@@ -93,18 +135,35 @@ files:
 - README.md
 - bin/tron-wallet
 - lib/tron.rb
+- lib/tron/abi.rb
+- lib/tron/abi/constant.rb
+- lib/tron/abi/decoder.rb
+- lib/tron/abi/encoder.rb
+- lib/tron/abi/event.rb
+- lib/tron/abi/function.rb
+- lib/tron/abi/type.rb
+- lib/tron/abi/util.rb
 - lib/tron/cache.rb
 - lib/tron/client.rb
 - lib/tron/configuration.rb
+- lib/tron/contract.rb
+- lib/tron/key.rb
+- lib/tron/protobuf.rb
+- lib/tron/protobuf/transaction_raw_serializer.rb
 - lib/tron/services/balance.rb
+- lib/tron/services/contract.rb
 - lib/tron/services/price.rb
 - lib/tron/services/resources.rb
+- lib/tron/services/transaction.rb
+- lib/tron/signature.rb
+- lib/tron/utils/abi.rb
 - lib/tron/utils/address.rb
 - lib/tron/utils/cache.rb
+- lib/tron/utils/crypto.rb
 - lib/tron/utils/http.rb
 - lib/tron/utils/rate_limiter.rb
 - lib/tron/version.rb
-homepage: https://github.com/yourusername/tron
+homepage: https://github.com/scionx-io/tron.rb
 licenses:
 - MIT
 metadata: {}
@@ -116,14 +175,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Ruby wrapper for TRON blockchain APIs