tron.rb 1.0.4 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be59d0725833375ac579bd873677eb22814a8befb727df0e1ab001834f7d24ef
-  data.tar.gz: 8d37550f4418c2a5b7592b86ddd74b0a1eda37b8014d9b93e5edfc337f051cae
+  metadata.gz: 3bd7e8033f046e59d3a917a16574a0bdf10fa37d8c36e9964b6cf67c730cf94d
+  data.tar.gz: 7b3684dc20f0e671895e8702e18552da9325d11447583299a5311a712e274b14
 SHA512:
-  metadata.gz: 71f329e6b189ace240c47daf9b21ee2e47d96a88e1c8dee1123fd112128109999fabc17b335c12d8ddf43c41b5a062b6e5acfbb01e299e22cb7a5d38cfea9d38
-  data.tar.gz: 42e4dbab34144d90091569eb66881d24ab42605bc3f69822b2d43e3bdf79a4551db191ba33577d353eac8108ef3fa2f9ad380f72e23d71692e58124b9ce7f8db
+  metadata.gz: c5d04047d7736973110a1530ab187b6e180fe2c8fac4b6feb1bbf58f098313de2e0f328bdb6475a98f733d93d07b1806c22180def5634cfc3dd63f1ca2f1c91b
+  data.tar.gz: 949e517a1c47970fa8c6a43367602c4eb0404e84ee4cc64923e6ba89f8e0f04dc41113fd584c38cf36d56541a8abaa0cf1f5f8e85d8ee878d6cfd30b36486a55

data/README.md

@@ -33,6 +33,11 @@ Tron.configure do |config|
   config.tronscan_api_key = 'your_tronscan_api_key'
   config.network = :mainnet  # or :shasta or :nile
   config.timeout = 30
+
+  # Cache configuration (optional)
+  config.cache_enabled = true     # Enable/disable caching (default: true)
+  config.cache_ttl = 300          # Cache TTL in seconds (default: 300 = 5 minutes)
+  config.cache_max_stale = 600    # Max stale time in seconds (default: 600 = 10 minutes)
 end
 ```
 
@@ -112,11 +117,137 @@ end
 - ✓ Token prices
 - ✓ Portfolio tracking
 - ✓ Multi-network support (mainnet, shasta, nile)
+- ✓ Intelligent caching with TTL and stale-while-revalidate
+- ✓ Cache statistics and monitoring
 - ✓ Clean, simple output
 - ✓ Proper decimal formatting
 - ✓ Environment variable support
 - ✓ Rate limit management with API keys
 
+## Caching
+
+The gem includes an intelligent caching system to reduce API calls and improve performance.
+
+### How Caching Works
+
+The cache uses a **time-based expiration strategy** with **stale-while-revalidate** behavior:
+
+1. **Fresh Cache (age < TTL)**: Returns cached value immediately
+2. **Stale Cache (age > TTL but < max_stale)**: Attempts to refresh, falls back to stale value on error
+3. **Expired Cache (age > max_stale)**: Forces refresh, raises error if refresh fails
+
+This approach ensures:
+- Fast responses from fresh cache
+- High availability with stale fallbacks
+- Automatic background refresh for popular endpoints
+
+### Cache Configuration
+
+```ruby
+Tron.configure do |config|
+  # Enable or disable caching globally (default: true)
+  config.cache_enabled = true
+
+  # Set default TTL (time-to-live) in seconds (default: 300 = 5 minutes)
+  config.cache_ttl = 300
+
+  # Set max stale time in seconds (default: 600 = 10 minutes)
+  config.cache_max_stale = 600
+end
+```
+
+### Endpoint-Specific TTL Values
+
+Different endpoints have optimized TTL values based on data volatility:
+
+| Endpoint Type | TTL | Max Stale | Use Case |
+|---------------|-----|-----------|----------|
+| **balance** | 5 min | 10 min | Wallet balances, moderate volatility |
+| **price** | 1 min | 2 min | Token prices, high volatility |
+| **token_info** | 15 min | 30 min | Token metadata, low volatility |
+| **resources** | 5 min | 10 min | Account resources, moderate volatility |
+| **default** | 5 min | 10 min | Unclassified endpoints |
+
+### Cache Statistics
+
+Monitor cache performance to optimize your configuration:
+
+```ruby
+# Get global cache statistics
+stats = Tron::Cache.global_stats
+puts "Cache Hit Rate: #{stats[:hit_rate_percentage]}%"
+puts "Total Hits: #{stats[:total_hits]}"
+puts "Total Misses: #{stats[:total_misses]}"
+puts "Cache Size: #{stats[:cache_size]} entries"
+
+# Get statistics for a specific cache entry
+key_stats = Tron::Cache.stats("specific_key")
+if key_stats
+  puts "Entry Hits: #{key_stats[:hits]}"
+  puts "Entry Misses: #{key_stats[:misses]}"
+  puts "Cached At: #{key_stats[:cached_at]}"
+  puts "Expires At: #{key_stats[:expires_at]}"
+  puts "Expired: #{key_stats[:expired]}"
+end
+```
+
+### Cache Management
+
+```ruby
+# Clear entire cache
+Tron::Cache.clear
+
+# Delete specific cache entry
+Tron::Cache.delete("cache_key")
+
+# Check if key exists in cache
+if Tron::Cache.exists?("cache_key")
+  puts "Key is cached"
+end
+
+# Get cache size
+puts "Cache has #{Tron::Cache.size} entries"
+
+# Reset statistics (useful for testing)
+Tron::Cache.reset_stats
+```
+
+### Advanced Cache Usage
+
+#### Disable Caching for Specific Requests
+
+```ruby
+# Disable cache for a specific HTTP request
+response = Tron::Utils::HTTP.get(url, headers, { enabled: false })
+```
+
+#### Custom TTL for Specific Requests
+
+```ruby
+# Use custom TTL values for a specific request
+response = Tron::Utils::HTTP.get(url, headers, {
+  ttl: 60,         # 1 minute
+  max_stale: 120   # 2 minutes
+})
+```
+
+#### Use Endpoint-Specific TTL
+
+```ruby
+# Use predefined TTL for specific endpoint type
+response = Tron::Utils::HTTP.get(url, headers, {
+  endpoint_type: :price  # Uses 1 min TTL, 2 min max_stale
+})
+```
+
+### Cache Best Practices
+
+1. **Enable caching in production** - Reduces API calls and improves response times
+2. **Monitor hit rates** - Aim for >70% hit rate for frequently accessed data
+3. **Adjust TTL based on data volatility** - Shorter TTL for prices, longer for token metadata
+4. **Use stale fallbacks** - Ensures high availability during API issues
+5. **Clear cache after mutations** - If you modify data, clear related cache entries
+
 ## Services Architecture
 
 The gem is organized into modular services:
@@ -124,8 +255,9 @@ The gem is organized into modular services:
 - `Tron::Services::Balance` - TRX and TRC20 token balances
 - `Tron::Services::Resources` - Account resources (bandwidth/energy)
 - `Tron::Services::Price` - Token price information
-- `Tron::Utils::HTTP` - HTTP client with error handling
+- `Tron::Utils::HTTP` - HTTP client with error handling and caching
 - `Tron::Utils::Address` - TRON address validation and conversion
+- `Tron::Cache` - Thread-safe caching with TTL and statistics
 
 ## API Reference
 

data/lib/tron/cache.rb

@@ -0,0 +1,186 @@
+require 'thread'
+
+module Tron
+  # Thread-safe, global cache implementation for TRON wallet toolkit
+  # 
+  # This cache provides a simple key-value store with time-based expiration and 
+  # failure fallback capabilities. It's designed specifically for caching API 
+  # responses to improve performance and reduce rate limit issues.
+  # 
+  # Features:
+  # - Thread-safe operations using Mutex synchronization
+  # - Time-based expiration with TTL (time-to-live) and max_stale settings
+  # - Fallback behavior when cache refresh fails
+  # - Global storage shared across all instances
+  # - Cache statistics tracking (hits, misses)
+  # 
+  # Example usage:
+  #   Tron::Cache.fetch("wallet_balance_#{address}", ttl: 300, max_stale: 600) do
+  #     api_client.get_wallet_balance(address)
+  #   end
+  class Cache
+    # Class-level storage for global cache
+    @@store = {}
+    @@mutex = Mutex.new
+    # Global statistics
+    @@global_stats = { total_hits: 0, total_misses: 0, total_fetches: 0 }
+
+    # Fetches a value from cache or executes the block to generate and cache it
+    #
+    # The fetch method implements a time-based caching strategy with fallback:
+    # 1. If entry exists and is fresh (age < ttl) → return cached value
+    # 2. If entry exists but stale (age > ttl but < max_stale) → try to update:
+    #    - If block succeeds: cache new value and return it
+    #    - If block raises error: return stale value (fallback)
+    # 3. If no cache or too old → execute block, cache result, return it
+    #
+    # @param key [String] the cache key (should be unique for the data being cached)
+    # @param ttl [Integer] time-to-live in seconds (how long to consider value fresh)
+    # @param max_stale [Integer] maximum stale time in seconds (how long to keep stale values)
+    # @yield [Proc] block to execute if value is not cached or expired
+    # @return [Object] the cached value or result from the block
+    # @raise [ArgumentError] if no block is provided
+    def self.fetch(key, ttl:, max_stale:, &block)
+      raise ArgumentError, "Block required for cache fetch" unless block_given?
+      
+      @@mutex.synchronize do
+        entry = @@store[key]
+        @@global_stats[:total_fetches] += 1
+
+        if entry && Time.now - entry[:cached_at] < ttl
+          # Cache is fresh - return cached value
+          # Increment hit counter if present
+          @@store[key][:hits] = (entry[:hits] || 0) + 1
+          @@global_stats[:total_hits] += 1
+          return entry[:value]
+        elsif entry && Time.now - entry[:cached_at] < max_stale
+          # Cache is stale but within max_stale - try to update with fallback
+          begin
+            new_value = yield
+            @@store[key] = {
+              value: new_value,
+              cached_at: Time.now,
+              ttl: ttl,
+              max_stale: max_stale,
+              hits: 0,
+              misses: 0
+            }
+            @@global_stats[:total_misses] += 1
+            return new_value
+          rescue => e
+            # Return stale value as fallback
+            # Increment miss counter since the block failed
+            @@store[key][:misses] = (entry[:misses] || 0) + 1
+            @@global_stats[:total_hits] += 1  # Stale hit is still a hit
+            return entry[:value]
+          end
+        else
+          # No cache or too old - execute block and cache result
+          new_value = yield
+          @@store[key] = {
+            value: new_value,
+            cached_at: Time.now,
+            ttl: ttl,
+            max_stale: max_stale,
+            hits: 0,
+            misses: 0
+          }
+          @@global_stats[:total_misses] += 1
+          return new_value
+        end
+      end
+    end
+
+    # Checks if a key exists in the cache (without considering expiration)
+    #
+    # @param key [String] the cache key
+    # @return [Boolean] true if key exists in the cache, false otherwise
+    def self.exists?(key)
+      @@mutex.synchronize do
+        @@store.key?(key)
+      end
+    end
+
+    # Deletes a specific key from the cache
+    #
+    # @param key [String] the cache key to delete
+    # @return [void]
+    def self.delete(key)
+      @@mutex.synchronize do
+        @@store.delete(key)
+      end
+    end
+
+    # Clears all cached entries
+    # 
+    # This is useful for testing or when a full cache refresh is needed.
+    # @return [void]
+    def self.clear
+      @@mutex.synchronize do
+        @@store.clear
+      end
+    end
+
+    # Returns the number of cached entries
+    # @return [Integer] number of cached entries
+    def self.size
+      @@mutex.synchronize do
+        @@store.size
+      end
+    end
+    
+    # Returns cache statistics for a specific key
+    #
+    # @param key [String] the cache key
+    # @return [Hash, nil] statistics hash if key exists, nil otherwise
+    def self.stats(key)
+      @@mutex.synchronize do
+        entry = @@store[key]
+        return nil unless entry
+
+        {
+          hits: entry[:hits] || 0,
+          misses: entry[:misses] || 0,
+          cached_at: entry[:cached_at],
+          expires_at: entry[:cached_at] + entry[:ttl],
+          ttl: entry[:ttl],
+          max_stale: entry[:max_stale],
+          expired: Time.now - entry[:cached_at] >= entry[:ttl]
+        }
+      end
+    end
+
+    # Returns global cache statistics across all keys
+    #
+    # This provides an overall view of cache performance including hit rate.
+    # @return [Hash] global statistics including total_hits, total_misses, hit_rate
+    def self.global_stats
+      @@mutex.synchronize do
+        total_requests = @@global_stats[:total_fetches]
+        hit_rate = if total_requests > 0
+          (@@global_stats[:total_hits].to_f / total_requests * 100).round(2)
+        else
+          0.0
+        end
+
+        {
+          total_hits: @@global_stats[:total_hits],
+          total_misses: @@global_stats[:total_misses],
+          total_fetches: @@global_stats[:total_fetches],
+          hit_rate_percentage: hit_rate,
+          cache_size: @@store.size,
+          memory_keys: @@store.keys.size
+        }
+      end
+    end
+
+    # Reset global statistics
+    # Useful for testing or when you want to start fresh statistics
+    # @return [void]
+    def self.reset_stats
+      @@mutex.synchronize do
+        @@global_stats = { total_hits: 0, total_misses: 0, total_fetches: 0 }
+      end
+    end
+  end
+end

data/lib/tron/configuration.rb

@@ -2,11 +2,16 @@
 module Tron
   class Configuration
     attr_accessor :api_key, :tronscan_api_key, :network, :timeout, :base_url, :tronscan_base_url, :strict_mode
+    attr_accessor :cache_enabled, :cache_ttl, :cache_max_stale
 
     def initialize
       @network = :mainnet
       @timeout = 30
       @strict_mode = false
+      # Cache configuration defaults
+      @cache_enabled = true
+      @cache_ttl = 300        # 5 minutes default TTL
+      @cache_max_stale = 600  # 10 minutes max stale
       setup_urls
     end
 

data/lib/tron/utils/http.rb

@@ -2,20 +2,116 @@
 require 'net/http'
 require 'uri'
 require 'json'
+require 'digest'
 
 module Tron
   module Utils
     class HTTP
-      def self.get(url, headers = {})
-        make_request(Net::HTTP::Get, url, nil, headers)
+      # TTL values for different endpoint types (in seconds)
+      # These are optimized based on data volatility
+      ENDPOINT_TTL = {
+        # Balance endpoints - moderate volatility (5 minutes)
+        balance: { ttl: 300, max_stale: 600 },
+
+        # Token info endpoints - low volatility (15 minutes)
+        token_info: { ttl: 900, max_stale: 1800 },
+
+        # Price endpoints - high volatility (1 minute)
+        price: { ttl: 60, max_stale: 120 },
+
+        # Account resources - moderate volatility (5 minutes)
+        resources: { ttl: 300, max_stale: 600 },
+
+        # Default for unclassified endpoints
+        default: { ttl: 300, max_stale: 600 }
+      }.freeze
+
+      # GET request with optional caching
+      # @param url [String] the URL to request
+      # @param headers [Hash] request headers
+      # @param cache_options [Hash] optional cache configuration
+      # @option cache_options [Boolean] :enabled override global cache setting
+      # @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
+      def self.get(url, headers = {}, cache_options = {})
+        if should_use_cache?(cache_options)
+          cache_key = generate_cache_key('GET', url, headers)
+          ttl_config = get_ttl_config(cache_options)
+
+          Tron::Cache.fetch(cache_key, ttl: ttl_config[:ttl], max_stale: ttl_config[:max_stale]) do
+            make_request(Net::HTTP::Get, url, nil, headers)
+          end
+        else
+          make_request(Net::HTTP::Get, url, nil, headers)
+        end
       end
 
+      # POST request (no caching for mutations)
       def self.post(url, body = nil, headers = {})
         make_request(Net::HTTP::Post, url, body, headers)
       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 = {})
+        cache_key = generate_cache_key('GET', url, headers)
+        Tron::Cache.delete(cache_key)
+      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
+      def self.cache_stats(url, headers = {})
+        cache_key = generate_cache_key('GET', url, headers)
+        Tron::Cache.stats(cache_key)
+      end
+
       private
 
+      # Determine if caching should be used for this request
+      def self.should_use_cache?(cache_options)
+        # Check if caching is explicitly disabled for this request
+        return false if cache_options[:enabled] == false
+
+        # Otherwise, use global configuration
+        Tron.configuration.cache_enabled
+      end
+
+      # Get TTL configuration for the request
+      def self.get_ttl_config(cache_options)
+        # If custom TTL provided, use it
+        if cache_options[:ttl] && cache_options[:max_stale]
+          return { ttl: cache_options[:ttl], max_stale: cache_options[:max_stale] }
+        end
+
+        # If endpoint type specified, use its TTL
+        if cache_options[:endpoint_type] && ENDPOINT_TTL[cache_options[:endpoint_type]]
+          return ENDPOINT_TTL[cache_options[:endpoint_type]]
+        end
+
+        # Use global configuration if set
+        if Tron.configuration.cache_ttl && Tron.configuration.cache_max_stale
+          return {
+            ttl: Tron.configuration.cache_ttl,
+            max_stale: Tron.configuration.cache_max_stale
+          }
+        end
+
+        # Fall back to default
+        ENDPOINT_TTL[:default]
+      end
+
+      # Generate a unique cache key based on request parameters
+      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)
+        relevant_headers = headers.reject { |k, _| k.to_s.downcase == 'user-agent' }
+        key_parts = [method, url, relevant_headers.sort.to_h]
+        Digest::SHA256.hexdigest(key_parts.to_json)
+      end
+
       def self.make_request(method_class, url, body, headers)
         uri = URI(url)
         http = Net::HTTP.new(uri.host, uri.port)
@@ -26,7 +122,7 @@ module Tron
         request.body = body if body
 
         response = http.request(request)
-        
+
         case response
         when Net::HTTPSuccess
           json_response = JSON.parse(response.body)

data/lib/tron/version.rb

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

data/lib/tron.rb

@@ -4,6 +4,7 @@ require 'dotenv/load' if File.exist?('.env')
 require_relative 'tron/version'
 require_relative 'tron/client'
 require_relative 'tron/configuration'
+require_relative 'tron/cache'
 
 module Tron
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tron.rb
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.5
 platform: ruby
 authors:
 - Your Name
@@ -93,6 +93,7 @@ files:
 - README.md
 - bin/tron-wallet
 - lib/tron.rb
+- lib/tron/cache.rb
 - lib/tron/client.rb
 - lib/tron/configuration.rb
 - lib/tron/services/balance.rb