erpc-sdk 0.5.0 → 0.7.0

data/lib/erpc_sdk/token_catalog.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "generated/token_catalog"
+
+module ERPC
+  # Canonical CAIP-2 chain identifiers used by the bundled token catalog.
+  module TokenChainIDs
+    ETHEREUM_MAINNET = TokenCatalogData::TOKEN_CHAIN_IDS.fetch(:ethereum)
+    SOLANA_MAINNET = TokenCatalogData::TOKEN_CHAIN_IDS.fetch(:solana)
+    AVALANCHE_C_MAINNET = TokenCatalogData::TOKEN_CHAIN_IDS.fetch(:avalanche_c)
+  end
+
+  # Offline access to the generated token and deployment catalog.
+  #
+  # All records are static, frozen Ruby values generated from the canonical
+  # registry. These methods never create a client, read a file, parse JSON, or
+  # access the network.
+  module TokenCatalog
+    TOKEN_CATALOG_VERSION = TokenCatalogData::TOKEN_CATALOG_VERSION
+    TOKEN_CATALOG_AS_OF_DATE = TokenCatalogData::TOKEN_CATALOG_AS_OF_DATE
+    TOKEN_CATALOG_CONTENT_DIGEST = TokenCatalogData::TOKEN_CATALOG_CONTENT_DIGEST
+    AS_OF_DATE = TOKEN_CATALOG_AS_OF_DATE
+    CONTENT_DIGEST = TOKEN_CATALOG_CONTENT_DIGEST
+
+    TOKEN_CHAIN_IDS = TokenCatalogData::TOKEN_CHAIN_IDS
+    TOKEN_ASSETS = TokenCatalogData::TOKEN_ASSETS
+    TOKEN_DEPLOYMENTS = TokenCatalogData::TOKEN_DEPLOYMENTS
+    TOKEN_ALIASES = TokenCatalogData::TOKEN_ALIASES
+
+    EMPTY_DEPLOYMENTS = [].freeze
+
+    ASSETS_BY_ID = TOKEN_ASSETS.each_with_object({}) do |asset, index|
+      index[asset.fetch(:asset_id)] = asset
+    end.freeze
+
+    DEPLOYMENTS_BY_ID = TOKEN_DEPLOYMENTS.each_with_object({}) do |deployment, index|
+      index[deployment.fetch(:deployment_id)] = deployment
+    end.freeze
+
+    DEPLOYMENTS_BY_SYMBOL = begin
+      grouped = Hash.new { |hash, key| hash[key] = [] }
+      TOKEN_DEPLOYMENTS.each do |deployment|
+        key = [deployment.fetch(:chain_id), deployment.fetch(:symbol)].freeze
+        grouped[key] << deployment
+      end
+      grouped.each_with_object({}) do |(key, deployments), index|
+        index[key] = deployments.sort_by { |deployment| deployment.fetch(:deployment_id) }.freeze
+      end.freeze
+    end
+
+    DEPLOYMENTS_BY_ADDRESS = begin
+      indexed = {}
+      TOKEN_DEPLOYMENTS.each do |deployment|
+        address = deployment[:address]
+        next unless address.is_a?(String) && !address.empty?
+
+        evm_chain = [TokenChainIDs::ETHEREUM_MAINNET, TokenChainIDs::AVALANCHE_C_MAINNET].include?(deployment.fetch(:chain_id))
+        normalized = evm_chain ? address.downcase : address
+        key = [deployment.fetch(:chain_id), normalized].freeze
+        indexed[key] ||= deployment
+      end
+      indexed.freeze
+    end
+
+    class << self
+      # Return the asset with the exact opaque asset ID.
+      def get_token_asset(asset_id)
+        return nil unless asset_id.is_a?(String) && !asset_id.empty?
+
+        ASSETS_BY_ID[asset_id]
+      end
+
+      # Return the deployment with the exact opaque deployment ID.
+      def get_token_deployment(deployment_id)
+        return nil unless deployment_id.is_a?(String) && !deployment_id.empty?
+
+        DEPLOYMENTS_BY_ID[deployment_id]
+      end
+
+      # List all deployments, optionally restricted by chain and stable
+      # currency. Every lifecycle status remains visible.
+      #
+      # The canonical Ruby form uses keywords:
+      #   list_token_deployments(chain_id: ..., stable_currency: ...)
+      # Positional values are also accepted for callers that prefer the
+      # compact form: list_token_deployments(chain_id, stable_currency).
+      def list_token_deployments(chain_id = nil, stable_currency = nil, **filters)
+        unless filters.empty?
+          return EMPTY_DEPLOYMENTS unless filters.keys.all? { |key| %i[chain_id stable_currency].include?(key) }
+          return EMPTY_DEPLOYMENTS if filters.key?(:chain_id) && !chain_id.nil?
+          return EMPTY_DEPLOYMENTS if filters.key?(:stable_currency) && !stable_currency.nil?
+
+          chain_id = filters[:chain_id] if filters.key?(:chain_id)
+          stable_currency = filters[:stable_currency] if filters.key?(:stable_currency)
+        end
+
+        return EMPTY_DEPLOYMENTS if !chain_id.nil? && !known_chain_id?(chain_id)
+        return EMPTY_DEPLOYMENTS if !stable_currency.nil? && !stable_currency?(stable_currency)
+
+        filtered = TOKEN_DEPLOYMENTS.select do |deployment|
+          (chain_id.nil? || deployment.fetch(:chain_id) == chain_id) &&
+            (stable_currency.nil? || deployment[:stable_currency] == stable_currency)
+        end
+        filtered.empty? ? EMPTY_DEPLOYMENTS : filtered.freeze
+      end
+
+      # Find every exact-case symbol match on a known chain, ordered by
+      # deployment ID.
+      def find_token_deployments_by_symbol(chain_id, symbol)
+        return EMPTY_DEPLOYMENTS unless known_chain_id?(chain_id)
+        return EMPTY_DEPLOYMENTS unless symbol.is_a?(String) && !symbol.empty?
+
+        DEPLOYMENTS_BY_SYMBOL.fetch([chain_id, symbol], EMPTY_DEPLOYMENTS)
+      end
+
+      # Find a non-native deployment by address. EVM addresses are strict
+      # ASCII hexadecimal and matched case-insensitively; Solana addresses are
+      # matched exactly.
+      def find_token_deployment_by_address(chain_id, address)
+        return nil unless known_chain_id?(chain_id)
+        return nil unless address.is_a?(String) && !address.empty?
+
+        if evm_chain_id?(chain_id)
+          return nil unless valid_evm_address?(address)
+
+          normalized = address.downcase
+          return nil if zero_evm_address?(normalized)
+        else
+          normalized = address
+        end
+
+        DEPLOYMENTS_BY_ADDRESS[[chain_id, normalized]]
+      end
+
+      # Return the native deployment for a known chain. Native deployments use
+      # a nil address and are intentionally not address-lookup candidates.
+      def get_native_token_deployment(chain_id)
+        return nil unless known_chain_id?(chain_id)
+
+        TOKEN_DEPLOYMENTS.find do |deployment|
+          deployment.fetch(:chain_id) == chain_id &&
+            deployment.fetch(:standard) == "native" && deployment[:address].nil?
+        end
+      end
+
+      private
+
+      def known_chain_id?(chain_id)
+        chain_id.is_a?(String) &&
+          [TokenChainIDs::ETHEREUM_MAINNET, TokenChainIDs::SOLANA_MAINNET, TokenChainIDs::AVALANCHE_C_MAINNET].include?(chain_id)
+      end
+
+      def evm_chain_id?(chain_id)
+        chain_id == TokenChainIDs::ETHEREUM_MAINNET || chain_id == TokenChainIDs::AVALANCHE_C_MAINNET
+      end
+
+      def stable_currency?(value)
+        value.is_a?(String) && %w[USD EUR JPY].include?(value)
+      end
+
+      def valid_evm_address?(address)
+        address.match?(/\A0x[0-9A-Fa-f]{40}\z/)
+      end
+
+      def zero_evm_address?(address)
+        address == "0x#{"0" * 40}"
+      end
+    end
+  end
+end

data/lib/erpc_sdk/token_rankings.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "generated/token_rankings"
+
+module ERPC
+  # Offline access to the generated token ranking snapshot.
+  #
+  # Ranking records are immutable values generated from the canonical registry.
+  # Lookups use exact chain IDs and never access a client, clock, file, or
+  # network. The current canonical snapshot is intentionally unconfigured, so
+  # its known-chain results are empty until a reviewed snapshot is published.
+  module TokenRankings
+    TOKEN_RANKINGS_METADATA = TokenRankingsData::TOKEN_RANKINGS_METADATA
+    TOKEN_RANKINGS = TokenRankingsData::TOKEN_RANKINGS
+    TOKEN_RANKINGS_CONTENT_DIGEST = TokenRankingsData::TOKEN_RANKINGS_CONTENT_DIGEST
+
+    TOKEN_RANKINGS_SCHEMA_VERSION = TOKEN_RANKINGS_METADATA.fetch(:schema_version)
+    TOKEN_RANKINGS_METRIC = TOKEN_RANKINGS_METADATA.fetch(:metric)
+    TOKEN_RANKINGS_AS_OF = TOKEN_RANKINGS_METADATA.fetch(:as_of)
+    TOKEN_RANKINGS_STATUS = TOKEN_RANKINGS_METADATA.fetch(:status)
+    TOKEN_RANKINGS_COVERAGE = TOKEN_RANKINGS_METADATA.fetch(:coverage)
+    TOKEN_RANKINGS_SOURCE_IDS = TOKEN_RANKINGS_METADATA.fetch(:source_ids)
+
+    EMPTY_RANKINGS = [].freeze
+
+    TOKEN_RANKINGS_BY_CHAIN = begin
+      grouped = {}
+      TOKEN_RANKINGS.each do |ranking|
+        chain_id = ranking.fetch(:chain_id)
+        grouped[chain_id] ||= []
+        grouped[chain_id] << ranking
+      end
+      grouped.each_with_object({}) do |(chain_id, rows), index|
+        index[chain_id] = rows.freeze
+      end.freeze
+    end
+
+    class << self
+      # Return rankings for one exact chain ID.
+      #
+      # Empty, unknown, and special string inputs return the same immutable
+      # empty array. No aliases or live data are inferred.
+      def list_token_rankings(chain_id)
+        return EMPTY_RANKINGS unless chain_id.is_a?(String) && !chain_id.empty?
+
+        TOKEN_RANKINGS_BY_CHAIN.fetch(chain_id, EMPTY_RANKINGS)
+      end
+    end
+  end
+end

data/lib/erpc_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ERPC
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/lib/erpc_sdk.rb

@@ -7,4 +7,8 @@ require_relative "erpc_sdk/transport"
 require_relative "erpc_sdk/rpc"
 require_relative "erpc_sdk/rest"
 require_relative "erpc_sdk/websocket"
+require_relative "erpc_sdk/dex_catalog"
+require_relative "erpc_sdk/swap"
 require_relative "erpc_sdk/client"
+require_relative "erpc_sdk/token_catalog"
+require_relative "erpc_sdk/token_rankings"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: erpc-sdk
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - ELSOUL LABO B.V.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -62,9 +62,16 @@ files:
 - lib/erpc_sdk.rb
 - lib/erpc_sdk/client.rb
 - lib/erpc_sdk/config.rb
+- lib/erpc_sdk/dex_catalog.rb
 - lib/erpc_sdk/errors.rb
+- lib/erpc_sdk/generated/dex_catalog.rb
+- lib/erpc_sdk/generated/token_catalog.rb
+- lib/erpc_sdk/generated/token_rankings.rb
 - lib/erpc_sdk/rest.rb
 - lib/erpc_sdk/rpc.rb
+- lib/erpc_sdk/swap.rb
+- lib/erpc_sdk/token_catalog.rb
+- lib/erpc_sdk/token_rankings.rb
 - lib/erpc_sdk/transport.rb
 - lib/erpc_sdk/version.rb
 - lib/erpc_sdk/websocket.rb