erpc-sdk 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e0b83f0a7e0881001a42033b8c7116ea6407f1e024cd258e9cf7df546eb0d875
+  data.tar.gz: 48a8098b1739371b431ba2e534644002647ffff6fa4c57889cf0723ffeecfdc1
+SHA512:
+  metadata.gz: 6badad47dbad416e9cea863d849de82beefd7fbf9448acce21b9a146ebf4f13e1260aad6591b94bd33a71f21cb832640a66bb3767c8a40f3785ab2629d9f1a1c
+  data.tar.gz: d9c6f52fbfc4ca654e8540640a50dc6fdda24773d6bb3ed54752cd8d6ba99fdf33db19a92522acdef95c5761aa9d4e702ff024f773fd2fff06196c523504eab3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ELSOUL LABO B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# ERPC SDK for Ruby
+
+Synchronous Ruby client for ERPC. It covers standard Solana and Ethereum
+JSON-RPC, indexed data, analytics, WebSocket subscriptions, price REST and
+server-sent events, account usage, and scoped Cloud reads.
+
+```bash
+gem install erpc-sdk
+```
+
+Ruby 3.1 or newer is required. The gem has no runtime dependencies.
+
+## Quick start
+
+```ruby
+require "erpc_sdk"
+
+begin
+  config = ERPC::ClientConfig.new(api_key: ENV.fetch("ERPC_API_KEY"))
+  erpc = ERPC::Client.new(config)
+
+  slot = erpc.solana.rpc.get_slot.send
+  chain_id = erpc.ethereum.rpc.eth_chain_id.send
+  puts({ slot: slot, chain_id: chain_id })
+ensure
+  erpc&.close
+end
+```
+
+Both exact wire names (`getSlot`, `eth_chainId`) and idiomatic snake-case
+aliases (`get_slot`, `eth_chain_id`) create inert requests. Network I/O starts
+only when `send` is called. `request` restricts calls to the namespace catalog;
+`raw` is the forward-compatible escape hatch.
+
+## Namespaces
+
+| Namespace | Purpose |
+| --- | --- |
+| `erpc.solana.rpc` | Standard Solana JSON-RPC |
+| `erpc.solana.das` | Indexed assets and tokens |
+| `erpc.solana.history` | Address transactions and transfers |
+| `erpc.solana.leaders` | Leader slots and validator information |
+| `erpc.solana.analytics` | Epoch, slot, program, and TPS analytics |
+| `erpc.solana.subscriptions` | Enhanced WebSocket subscriptions |
+| `erpc.ethereum.rpc` | Standard Ethereum JSON-RPC |
+| `erpc.ethereum.subscriptions` | Ethereum WebSocket subscriptions |
+| `erpc.price` | Price metadata, updates, and SSE streams |
+| `erpc.account` | Token balance |
+| `erpc.usage` | Masked monthly API-key usage |
+
+## Intact batches
+
+```ruby
+results = erpc.solana.rpc.batch([
+  { method: "getSlot", params: [] },
+  { method: "getBlockHeight", params: [] }
+]).send
+```
+
+The SDK sends one caller batch as one server batch, restores caller order,
+accepts at most 256 calls, and rejects invalid mixed or unsupported batches
+locally. It never silently splits a batch.
+
+## Subscriptions and price streams
+
+```ruby
+heads = erpc.ethereum.subscriptions.subscribe("newHeads")
+header = heads.next
+heads.unsubscribe
+
+erpc.price.stream_price_updates(ids: [feed_id]).each do |event|
+  puts event.fetch("data")
+end
+```
+
+Subscriptions use a lazy persistent WebSocket connection. `unsubscribe` is
+idempotent, and `close` closes both network subscription transports.
+
+## Cloud reads
+
+```ruby
+cloud = ERPC::CloudClient.new(
+  ERPC::CloudClientConfig.new(access_token: access_token)
+)
+
+offerings = cloud.catalog.list
+resources = cloud.resources.list
+```
+
+Cloud configuration accepts HTTPS endpoints and localhost HTTP endpoints for
+testing. It retains only the access token supplied by the caller and does not
+implement interactive authorization or refresh-credential storage.
+
+## Safety boundaries
+
+- Credentials are redacted from configuration inspection, public endpoints,
+  transport errors, and JSON-RPC error data.
+- Requests are attempted once. State-changing calls are never retried.
+- REST, JSON-RPC, and caller batch boundaries remain explicit.
+- Unknown methods remain available through `raw` without being included in the
+  compatibility catalog.

data/lib/erpc_sdk/client.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ERPC
+  SolanaClient = Struct.new(:rpc, :das, :history, :leaders, :analytics, :subscriptions, keyword_init: true)
+  EthereumClient = Struct.new(:rpc, :subscriptions, keyword_init: true)
+
+  class Client
+    attr_reader :solana, :ethereum, :price, :account, :usage
+
+    def initialize(config, http_adapter: nil, websocket_factory: nil)
+      adapter = http_adapter || NetHttpAdapter.new
+      solana_transport = HttpJsonRpcTransport.new(
+        api_key: config.api_key,
+        endpoint: config.endpoint,
+        headers: config.headers,
+        timeout: config.timeout,
+        adapter: adapter
+      )
+      ethereum_transport = HttpJsonRpcTransport.new(
+        api_key: config.api_key,
+        endpoint: URLs.with_path(config.endpoint, "/eth"),
+        headers: config.headers,
+        timeout: config.timeout,
+        adapter: adapter
+      )
+      solana_ws = WebSocketJsonRpcTransport.new(
+        URLs.websocket(config.endpoint, config.api_key),
+        config.api_key,
+        config.timeout,
+        connection_factory: websocket_factory
+      )
+      ethereum_ws = WebSocketJsonRpcTransport.new(
+        URLs.websocket(config.endpoint, config.api_key, "/eth"),
+        config.api_key,
+        config.timeout,
+        connection_factory: websocket_factory
+      )
+
+      @solana = SolanaClient.new(
+        rpc: RpcNamespace.new(
+          solana_transport,
+          SOLANA_RPC_METHODS,
+          parameter_mode: :positional,
+          batch_policy: :solana_standard
+        ),
+        das: RpcNamespace.new(solana_transport, SOLANA_DAS_METHODS, parameter_mode: :named),
+        history: RpcNamespace.new(solana_transport, SOLANA_HISTORY_METHODS, parameter_mode: :positional),
+        leaders: RpcNamespace.new(
+          solana_transport,
+          SOLANA_LEADER_METHODS,
+          parameter_mode: :positional,
+          batch_policy: :unsupported
+        ),
+        analytics: RpcNamespace.new(
+          solana_transport,
+          SOLANA_ANALYTICS_METHODS,
+          parameter_mode: :positional
+        ),
+        subscriptions: SolanaSubscriptions.new(solana_ws)
+      )
+      @ethereum = EthereumClient.new(
+        rpc: RpcNamespace.new(ethereum_transport, ETHEREUM_RPC_METHODS, parameter_mode: :positional),
+        subscriptions: EthereumSubscriptions.new(ethereum_ws)
+      )
+      @price = PriceClient.new(
+        RestTransport.new(
+          credential: config.api_key,
+          endpoint: config.endpoint,
+          headers: config.headers,
+          timeout: config.timeout,
+          adapter: adapter
+        )
+      )
+      @account = AccountClient.new(
+        RestTransport.new(
+          credential: config.api_key,
+          endpoint: config.account_endpoint,
+          headers: config.headers,
+          timeout: config.timeout,
+          adapter: adapter
+        )
+      )
+      @usage = UsageClient.new(
+        RestTransport.new(
+          credential: config.api_key,
+          endpoint: config.user_endpoint,
+          headers: config.headers,
+          timeout: config.timeout,
+          adapter: adapter
+        )
+      )
+      @closed = false
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      solana.subscriptions.close
+      ethereum.subscriptions.close
+      nil
+    end
+  end
+
+  class CloudClient
+    attr_reader :catalog, :credit, :resources, :usage
+
+    def initialize(config, http_adapter: nil)
+      transport = RestTransport.new(
+        credential: config.access_token,
+        endpoint: config.endpoint,
+        headers: config.headers,
+        timeout: config.timeout,
+        adapter: http_adapter || NetHttpAdapter.new
+      )
+      @catalog = CloudCatalogClient.new(transport)
+      @credit = CloudCreditClient.new(transport)
+      @resources = CloudResourcesClient.new(transport)
+      @usage = UsageClient.new(transport)
+    end
+
+    def close
+      nil
+    end
+  end
+
+  module_function
+
+  def create_client(config, **options)
+    Client.new(config, **options)
+  end
+
+  def create_cloud_client(config, **options)
+    CloudClient.new(config, **options)
+  end
+end

data/lib/erpc_sdk/config.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module ERPC
+  DEFAULT_ENDPOINT = "https://edge.erpc.global"
+  DEFAULT_ACCOUNT_ENDPOINT = "https://solana-rpc.erpc.global"
+  DEFAULT_USER_ENDPOINT = "https://user-api.erpc.global"
+  DEFAULT_TIMEOUT = 30.0
+
+  module URLs
+    module_function
+
+    def normalize_endpoint(value, local_http_only: false)
+      uri = URI.parse(value.to_s)
+      unless uri.absolute? && uri.host && %w[http https].include?(uri.scheme)
+        raise ConfigError, "endpoint must be an absolute HTTP(S) URL"
+      end
+
+      local = %w[127.0.0.1 ::1 localhost].include?(uri.hostname)
+      if local_http_only && uri.scheme != "https" && !(uri.scheme == "http" && local)
+        raise ConfigError, "endpoint must use HTTPS except on localhost"
+      end
+
+      uri.query = nil
+      uri.fragment = nil
+      uri.path = uri.path.sub(%r{/+\z}, "")
+      uri.path = "/" if uri.path.empty?
+      uri.to_s
+    rescue URI::InvalidURIError, ArgumentError
+      raise ConfigError, "endpoint must be an absolute HTTP(S) URL"
+    end
+
+    def with_path(endpoint, path)
+      uri = URI.parse(endpoint)
+      base = uri.path.sub(%r{/+\z}, "")
+      uri.path = "#{base}/#{path.sub(%r{\A/+}, "")}"
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    end
+
+    def websocket(endpoint, api_key, path = "")
+      uri = URI.parse(with_path(endpoint, path))
+      uri.scheme = uri.scheme == "https" ? "wss" : "ws"
+      uri.query = URI.encode_www_form("api-key" => api_key)
+      uri.to_s
+    end
+
+    def escape_path(value)
+      value.to_s.b.each_byte.map do |byte|
+        character = byte.chr
+        character.match?(/[A-Za-z0-9_.~-]/) ? character : format("%%%02X", byte)
+      end.join
+    end
+  end
+
+  class ClientConfig
+    attr_reader :api_key, :endpoint, :account_endpoint, :user_endpoint, :headers, :timeout
+
+    def initialize(api_key:, endpoint: DEFAULT_ENDPOINT, account_endpoint: DEFAULT_ACCOUNT_ENDPOINT,
+                   user_endpoint: DEFAULT_USER_ENDPOINT, headers: {}, timeout: DEFAULT_TIMEOUT)
+      @api_key = api_key.to_s.strip
+      raise ConfigError, "api_key must not be empty" if @api_key.empty?
+      raise ConfigError, "timeout must be positive" unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+
+      @endpoint = URLs.normalize_endpoint(endpoint)
+      @account_endpoint = URLs.normalize_endpoint(account_endpoint)
+      @user_endpoint = URLs.normalize_endpoint(user_endpoint)
+      @headers = headers.to_h.transform_keys(&:to_s).transform_values(&:to_s).freeze
+      @timeout = timeout.to_f
+    end
+
+    def inspect
+      "#<#{self.class} api_key=[REDACTED] endpoint=#{endpoint.inspect} " \
+        "account_endpoint=#{account_endpoint.inspect} user_endpoint=#{user_endpoint.inspect} " \
+        "header_names=#{headers.keys.inspect} timeout=#{timeout.inspect}>"
+    end
+  end
+
+  class CloudClientConfig
+    attr_reader :access_token, :endpoint, :headers, :timeout
+
+    def initialize(access_token:, endpoint: DEFAULT_USER_ENDPOINT, headers: {}, timeout: DEFAULT_TIMEOUT)
+      @access_token = access_token.to_s.strip
+      raise ConfigError, "access_token must not be empty" if @access_token.empty?
+      raise ConfigError, "timeout must be positive" unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+
+      @endpoint = URLs.normalize_endpoint(endpoint, local_http_only: true)
+      @headers = headers.to_h.transform_keys(&:to_s).transform_values(&:to_s).freeze
+      @timeout = timeout.to_f
+    end
+
+    def inspect
+      "#<#{self.class} access_token=[REDACTED] endpoint=#{endpoint.inspect} " \
+        "header_names=#{headers.keys.inspect} timeout=#{timeout.inspect}>"
+    end
+  end
+end

data/lib/erpc_sdk/errors.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module ERPC
+  class Error < StandardError; end
+
+  class ConfigError < Error; end
+  class BatchPolicyError < Error; end
+  class InvalidResponseError < Error; end
+  class TransportError < Error; end
+
+  class TimeoutError < TransportError
+    attr_reader :timeout
+
+    def initialize(timeout)
+      @timeout = timeout
+      super("ERPC request timed out after #{timeout} seconds")
+    end
+  end
+
+  class HttpError < Error
+    attr_reader :status
+
+    def initialize(status)
+      @status = status
+      super("ERPC returned HTTP status #{status}")
+    end
+  end
+
+  class JsonRpcError < Error
+    attr_reader :code, :data
+
+    def initialize(code, message, data = nil)
+      @code = code
+      @data = data
+      super(message)
+    end
+  end
+
+  module Redaction
+    module_function
+
+    def text(value, credential)
+      result = value.to_s
+      variants(credential).each { |secret| result = result.gsub(secret, "[REDACTED]") unless secret.empty? }
+      result
+    end
+
+    def value(value, credential)
+      case value
+      when String
+        text(value, credential)
+      when Array
+        value.map { |item| self.value(item, credential) }
+      when Hash
+        value.to_h do |key, item|
+          [text(key, credential), self.value(item, credential)]
+        end
+      else
+        value
+      end
+    end
+
+    def variants(credential)
+      percent_encoded = credential.to_s.b.each_byte.map do |byte|
+        character = byte.chr
+        character.match?(/[A-Za-z0-9_.~-]/) ? character : format("%%%02X", byte)
+      end.join
+      [credential.to_s, URI.encode_www_form_component(credential.to_s), percent_encoded].uniq
+    end
+    private_class_method :variants
+  end
+end