eth 0.5.14 → 0.5.16

data/lib/eth/client/ws.rb

@@ -0,0 +1,323 @@
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "socket"
+require "openssl"
+require "uri"
+require "base64"
+require "securerandom"
+require "digest/sha1"
+require "thread"
+require "ipaddr"
+
+# Provides the {Eth} module.
+module Eth
+
+  # Provides a WS/S-RPC client with automatic reconnection support.
+  class Client::Ws < Client
+
+    # The host of the WebSocket endpoint.
+    attr_reader :host
+
+    # The port of the WebSocket endpoint.
+    attr_reader :port
+
+    # The full URI of the WebSocket endpoint, including path.
+    attr_reader :uri
+
+    # Attribute indicator for SSL.
+    attr_reader :ssl
+
+    # Constructor for the WebSocket client. Should not be used; use
+    # {Client.create} instead.
+    #
+    # @param host [String] a URI pointing to a WebSocket RPC-API.
+    def initialize(host)
+      super
+      @uri = URI.parse(host)
+      raise ArgumentError, "Unable to parse the WebSocket-URI!" unless %w[ws wss].include?(@uri.scheme)
+      @host = @uri.host
+      @port = @uri.port
+      @ssl = @uri.scheme == "wss"
+      @path = build_path(@uri)
+      @mutex = Mutex.new
+      @socket = nil
+      @fragments = nil
+    end
+
+    # Sends an RPC request to the connected WebSocket endpoint.
+    #
+    # @param payload [Hash] the RPC request parameters.
+    # @return [String] a JSON-encoded response.
+    def send_request(payload)
+      attempts = 0
+      begin
+        attempts += 1
+        @mutex.synchronize do
+          ensure_socket
+          write_frame(@socket, payload)
+          return read_message(@socket)
+        end
+      rescue IOError, SystemCallError => e
+        @mutex.synchronize { close_socket }
+        retry if attempts < 2
+        raise e
+      end
+    end
+
+    # Closes the underlying WebSocket connection.
+    #
+    # @return [void]
+    def close
+      @mutex.synchronize { close_socket }
+    end
+
+    private
+
+    def ensure_socket
+      return if @socket && !@socket.closed?
+
+      socket = open_socket
+      begin
+        perform_handshake(socket)
+        @socket = socket
+        @fragments = nil
+      rescue StandardError
+        begin
+          socket.close unless socket.closed?
+        rescue IOError, SystemCallError
+          nil
+        end
+        @socket = nil
+        raise
+      end
+    end
+
+    # Establishes the TCP socket for the RPC connection and upgrades it to TLS
+    # when a secure endpoint is requested. TLS sessions enforce peer
+    # verification, load the default system trust store, and enable hostname
+    # verification when the current OpenSSL bindings support it.
+    #
+    # @return [TCPSocket, OpenSSL::SSL::SSLSocket] the established socket.
+    # @raise [IOError, SystemCallError, OpenSSL::SSL::SSLError] if the socket
+    #   cannot be opened or the TLS handshake fails.
+    def open_socket
+      tcp = TCPSocket.new(@host, @port)
+      return tcp unless @ssl
+
+      context = OpenSSL::SSL::SSLContext.new
+      params = { verify_mode: OpenSSL::SSL::VERIFY_PEER }
+      params[:verify_hostname] = true if context.respond_to?(:verify_hostname=)
+      context.set_params(params)
+      context.cert_store = OpenSSL::X509::Store.new.tap(&:set_default_paths)
+
+      ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp, context)
+      ssl_socket.hostname = @host
+      ssl_socket.sync_close = true
+      ssl_socket.connect
+      ssl_socket
+    end
+
+    def perform_handshake(socket)
+      key = Base64.strict_encode64(SecureRandom.random_bytes(16))
+      request = build_handshake_request(key)
+      socket.write(request)
+      response = read_handshake_response(socket)
+      verify_handshake!(response, key)
+    end
+
+    def build_handshake_request(key)
+      origin = build_origin_header
+      host_header = build_host_header
+      "GET #{@path} HTTP/1.1\r\n" \
+      "Host: #{host_header}\r\n" \
+      "Upgrade: websocket\r\n" \
+      "Connection: Upgrade\r\n" \
+      "Sec-WebSocket-Version: 13\r\n" \
+      "Sec-WebSocket-Key: #{key}\r\n" \
+      "Origin: #{origin}\r\n\r\n"
+    end
+
+    def read_handshake_response(socket)
+      response = +""
+      until response.end_with?("\r\n\r\n")
+        chunk = socket.readpartial(1024)
+        raise IOError, "Incomplete WebSocket handshake" if chunk.nil?
+        response << chunk
+      end
+      response
+    rescue EOFError
+      raise IOError, "Incomplete WebSocket handshake"
+    end
+
+    def verify_handshake!(response, key)
+      status_line = response.lines.first&.strip
+      unless status_line&.start_with?("HTTP/1.1 101")
+        raise IOError, "WebSocket handshake failed (status: #{status_line || "unknown"})"
+      end
+
+      accept = response[/Sec-WebSocket-Accept:\s*(.+)\r/i, 1]&.strip
+      expected = Base64.strict_encode64(Digest::SHA1.digest("#{key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11"))
+      raise IOError, "WebSocket handshake failed (missing accept header)" unless accept
+      raise IOError, "WebSocket handshake failed (invalid accept header)" unless accept == expected
+    end
+
+    def write_frame(socket, payload, opcode = 0x1)
+      frame_payload = payload.is_a?(String) ? payload.dup : payload.to_s
+      mask_key = SecureRandom.random_bytes(4)
+      header = [0x80 | opcode]
+
+      length = frame_payload.bytesize
+      if length <= 125
+        header << (0x80 | length)
+      elsif length <= 0xFFFF
+        header << (0x80 | 126)
+        header.concat([length].pack("n").bytes)
+      else
+        header << (0x80 | 127)
+        header.concat([length].pack("Q>").bytes)
+      end
+
+      masked_payload = apply_mask(frame_payload, mask_key)
+      socket.write(header.pack("C*") + mask_key + masked_payload)
+    end
+
+    def read_message(socket)
+      loop do
+        frame = read_frame(socket)
+        return frame if frame
+      end
+    end
+
+    def read_frame(socket)
+      header = read_bytes(socket, 2)
+      byte1, byte2 = header.bytes
+      opcode = byte1 & 0x0F
+      masked = (byte2 & 0x80) == 0x80
+      length = byte2 & 0x7F
+
+      length = read_bytes(socket, 2).unpack1("n") if length == 126
+      length = read_bytes(socket, 8).unpack1("Q>") if length == 127
+
+      mask_key = masked ? read_bytes(socket, 4).bytes : nil
+      payload = read_bytes(socket, length)
+      payload_bytes = payload.bytes
+      if mask_key
+        payload_bytes.map!.with_index { |byte, index| byte ^ mask_key[index % 4] }
+      end
+      data = payload_bytes.pack("C*")
+
+      case opcode
+      when 0x0
+        (@fragments ||= +"") << data
+        if (byte1 & 0x80) == 0x80
+          message = @fragments.dup
+          @fragments = nil
+          message
+        else
+          nil
+        end
+      when 0x1, 0x2
+        if (byte1 & 0x80) == 0x80
+          data
+        else
+          @fragments = data
+          nil
+        end
+      when 0x8
+        close_socket
+        raise IOError, "WebSocket closed"
+      when 0x9
+        write_frame(socket, data, 0xA)
+        nil
+      when 0xA
+        nil
+      else
+        nil
+      end
+    end
+
+    def read_bytes(socket, length)
+      data = +""
+      while data.bytesize < length
+        chunk = socket.read(length - data.bytesize)
+        raise IOError, "Unexpected end of WebSocket stream" if chunk.nil? || chunk.empty?
+        data << chunk
+      end
+      data
+    end
+
+    def apply_mask(payload, mask_key)
+      mask_bytes = mask_key.bytes
+      payload.bytes.map.with_index { |byte, index| byte ^ mask_bytes[index % 4] }.pack("C*")
+    end
+
+    def build_origin_header
+      scheme = @ssl ? "https" : "http"
+      host = format_origin_host(@uri.host)
+      default_port = @ssl ? 443 : 80
+      port = @uri.port
+      port_suffix = port == default_port ? "" : ":#{port}"
+      "#{scheme}://#{host}#{port_suffix}"
+    end
+
+    def build_host_header
+      "#{format_host(@uri.host)}:#{@uri.port}"
+    end
+
+    def format_origin_host(host)
+      return "localhost" if loopback_host?(host)
+      format_host(host)
+    end
+
+    def format_host(host)
+      return host unless host&.include?(":")
+      host.start_with?("[") ? host : "[#{host}]"
+    end
+
+    def loopback_host?(host)
+      return false if host.nil?
+      return true if host == "localhost"
+      IPAddr.new(host).loopback?
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+
+    def close_socket
+      return unless @socket
+
+      begin
+        write_frame(@socket, [1000].pack("n"), 0x8)
+      rescue IOError, SystemCallError
+        # ignore errors while closing
+      ensure
+        begin
+          @socket.close unless @socket.closed?
+        rescue IOError, SystemCallError
+          nil
+        end
+        @socket = nil
+        @fragments = nil
+      end
+    end
+
+    def build_path(uri)
+      path = uri.path
+      path = "/" if path.nil? || path.empty?
+      query = uri.query
+      path += "?#{query}" if query
+      path
+    end
+  end
+end

data/lib/eth/client.rb

@@ -16,7 +16,7 @@
 module Eth
 
   # Provides the {Eth::Client} super-class to connect to Ethereum
-  # network's RPC-API endpoints (IPC or HTTP).
+  # network's RPC-API endpoints (IPC, HTTP/S, or WS/S).
   class Client
 
     # The client's RPC-request ID starting at 0.
@@ -40,20 +40,37 @@ module Eth
     # A custom error type if a contract interaction fails.
     class ContractExecutionError < StandardError; end
 
-    # Creates a new RPC-Client, either by providing an HTTP/S host or
-    # an IPC path. Supports basic authentication with username and password.
+    # Raised when an RPC call returns an error. Carries the optional
+    # hex-encoded error data to support custom error decoding.
+    class RpcError < IOError
+      attr_reader :data
+
+      # Constructor for the {RpcError} class.
+      #
+      # @param message [String] the error message returned by the RPC.
+      # @param data [String] optional hex encoded error data.
+      def initialize(message, data = nil)
+        super(message)
+        @data = data
+      end
+    end
+
+    # Creates a new RPC-Client, either by providing an HTTP/S host, WS/S host,
+    # or an IPC path. Supports basic authentication with username and password.
     #
     # **Note**, this sets the folling gas defaults: {Tx::DEFAULT_PRIORITY_FEE}
     # and {Tx::DEFAULT_GAS_PRICE. Use {#max_priority_fee_per_gas} and
     # {#max_fee_per_gas} to set custom values prior to submitting transactions.
     #
-    # @param host [String] either an HTTP/S host or an IPC path.
+    # @param host [String] either an HTTP/S host, WS/S host, or an IPC path.
     # @return [Eth::Client::Ipc] an IPC client.
     # @return [Eth::Client::Http] an HTTP client.
+    # @return [Eth::Client::Ws] a WebSocket client.
     # @raise [ArgumentError] in case it cannot determine the client type.
     def self.create(host)
       return Client::Ipc.new host if host.end_with? ".ipc"
       return Client::Http.new host if host.start_with? "http"
+      return Client::Ws.new host if host.start_with? "ws"
       raise ArgumentError, "Unable to detect client type!"
     end
 
@@ -251,21 +268,28 @@ module Eth
     #   @param **sender_key [Eth::Key] the sender private key.
     #   @param **legacy [Boolean] enables legacy transactions (pre-EIP-1559).
     # @return [Object] returns the result of the call.
+    # @see https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call
     def call(contract, function, *args, **kwargs)
-      func = contract.functions.select { |func| func.name == function }
-      raise ArgumentError, "this function does not exist!" if func.nil? || func.size === 0
-      selected_func = func.first
-      func.each do |f|
-        if f.inputs.size === args.size
-          selected_func = f
-        end
-      end
-      output = call_raw(contract, selected_func, *args, **kwargs)
+      function = contract.function(function, args: args.size)
+      output = function.decode_call_result(
+        eth_call(
+          {
+            data: function.encode_call(*args),
+            to: kwargs[:address] || contract.address,
+            from: kwargs[:from],
+            gas: kwargs[:gas],
+            gasPrice: kwargs[:gas_price],
+            value: kwargs[:value],
+          }.compact
+        )["result"]
+      )
       if output&.length == 1
         output[0]
       else
         output
       end
+    rescue RpcError => e
+      raise ContractExecutionError, contract.decode_error(e)
     end
 
     # Executes a contract function with a transaction (transactional
@@ -298,13 +322,12 @@ module Eth
         else
           Tx.estimate_intrinsic_gas(contract.bin)
         end
-      fun = contract.functions.select { |func| func.name == function }[0]
       params = {
         value: kwargs[:tx_value] || 0,
         gas_limit: gas_limit,
         chain_id: chain_id,
         to: kwargs[:address] || contract.address,
-        data: call_payload(fun, args),
+        data: contract.function(function, args: args.size).encode_call(*args),
       }
       send_transaction(params, kwargs[:legacy], kwargs[:sender_key], kwargs[:nonce])
     end
@@ -320,8 +343,8 @@ module Eth
       begin
         hash = wait_for_tx(transact(contract, function, *args, **kwargs))
         return hash, tx_succeeded?(hash)
-      rescue IOError => e
-        raise ContractExecutionError, e
+      rescue RpcError => e
+        raise ContractExecutionError, contract.decode_error(e)
       end
     end
 
@@ -442,28 +465,6 @@ module Eth
       end
     end
 
-    # Non-transactional function call called from call().
-    # @see https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call
-    def call_raw(contract, func, *args, **kwargs)
-      params = {
-        data: call_payload(func, args),
-        to: kwargs[:address] || contract.address,
-        from: kwargs[:from],
-      }.compact
-
-      raw_result = eth_call(params)["result"]
-      types = func.outputs.map { |i| i.type }
-      return nil if raw_result == "0x"
-      Eth::Abi.decode(types, raw_result)
-    end
-
-    # Encodes function call payloads.
-    def call_payload(fun, args)
-      types = fun.inputs.map(&:parsed_type)
-      encoded_str = Util.bin_to_hex(Eth::Abi.encode(types, args))
-      Util.prefix_hex(fun.signature + (encoded_str.empty? ? "0" * 64 : encoded_str))
-    end
-
     # Encodes constructor params
     def encode_constructor_params(contract, args)
       types = contract.constructor_inputs.map { |input| input.type }
@@ -481,7 +482,9 @@ module Eth
         id: next_id,
       }
       output = JSON.parse(send_request(payload.to_json))
-      raise IOError, output["error"]["message"] unless output["error"].nil?
+      if (err = output["error"])
+        raise RpcError.new(err["message"], err["data"])
+      end
       output
     end
 
@@ -523,3 +526,4 @@ end
 # Load the client/* libraries
 require "eth/client/http"
 require "eth/client/ipc"
+require "eth/client/ws"

data/lib/eth/contract/error.rb

@@ -0,0 +1,62 @@
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -*- encoding : ascii-8bit -*-
+
+# Provides the {Eth} module.
+module Eth
+  # Provide classes for contract custom errors.
+  class Contract::Error
+    attr_accessor :name, :inputs, :signature, :error_string
+
+    # Constructor of the {Eth::Contract::Error} class.
+    #
+    # @param data [Hash] contract abi data for the error.
+    def initialize(data)
+      @name = data["name"]
+      @inputs = data.fetch("inputs", []).map do |input|
+        Eth::Contract::FunctionInput.new(input)
+      end
+      @error_string = self.class.calc_signature(@name, @inputs)
+      @signature = self.class.encoded_error_signature(@error_string)
+    end
+
+    # Creates error strings.
+    #
+    # @param name [String] error name.
+    # @param inputs [Array<Eth::Contract::FunctionInput>] error input class list.
+    # @return [String] error string.
+    def self.calc_signature(name, inputs)
+      "#{name}(#{inputs.map { |x| x.parsed_type.to_s }.join(",")})"
+    end
+
+    # Encodes an error signature.
+    #
+    # @param signature [String] error signature.
+    # @return [String] encoded error signature string.
+    def self.encoded_error_signature(signature)
+      Util.prefix_hex(Util.bin_to_hex(Util.keccak256(signature)[0..3]))
+    end
+
+    # Decodes a revert error payload.
+    #
+    # @param data [String] the hex-encoded revert data including selector.
+    # @return [Array] decoded error arguments.
+    def decode(data)
+      types = inputs.map(&:type)
+      payload = "0x" + data[10..]
+      Eth::Abi.decode(types, payload)
+    end
+  end
+end

data/lib/eth/contract/function.rb

@@ -53,5 +53,26 @@ module Eth
     def self.encoded_function_signature(signature)
       Util.bin_to_hex Util.keccak256(signature)[0..3]
     end
+
+    # Encodes a function call arguments
+    #
+    # @param args [Array] function arguments
+    # @return [String] encoded function call data
+    def encode_call(*args)
+      types = inputs.map(&:parsed_type)
+      encoded_str = Util.bin_to_hex(Eth::Abi.encode(types, args))
+      Util.prefix_hex(signature + (encoded_str.empty? ? "0" * 64 : encoded_str))
+    end
+
+    # Decodes a function call result
+    #
+    # @param data [String] eth_call result in hex format
+    # @return [Array]
+    def decode_call_result(data)
+      return nil if data == "0x"
+
+      types = outputs.map(&:parsed_type)
+      Eth::Abi.decode(types, data)
+    end
   end
 end

data/lib/eth/contract/function_output.rb

@@ -19,19 +19,27 @@ module Eth
 
   # Provide classes for contract function output.
   class Contract::FunctionOutput
-    attr_accessor :type, :name
+    attr_accessor :type, :raw_type, :name
 
     # Constructor of the {Eth::Contract::FunctionOutput} class.
     #
     # @param data [Hash] contract abi data.
     def initialize(data)
-      @type = Eth::Abi::Type.parse(data["type"])
+      @raw_type = data["type"]
+      @type = Eth::Abi::Type.parse(data["type"], data["components"])
       @name = data["name"]
     end
 
     # Returns complete types with subtypes, e.g., `uint256`.
     def type
-      @type.base_type + @type.sub_type + @type.dimensions.map { |dimension| "[#{dimension > 0 ? dimension : ""}]" }.join("")
+      @type.base_type +
+        @type.sub_type +
+        @type.dimensions.map { |dimension| "[#{dimension > 0 ? dimension : ""}]" }.join("")
+    end
+
+    # Returns parsed types.
+    def parsed_type
+      @type
     end
   end
 end

data/lib/eth/contract.rb

@@ -25,7 +25,7 @@ module Eth
     attr_accessor :key
     attr_accessor :gas_limit, :gas_price, :max_fee_per_gas, :max_priority_fee_per_gas, :nonce
     attr_accessor :bin, :name, :abi, :class_object
-    attr_accessor :events, :functions, :constructor_inputs
+    attr_accessor :events, :functions, :constructor_inputs, :errors
 
     # Constructor of the {Eth::Contract} class.
     #
@@ -44,7 +44,7 @@ module Eth
       @name = _name
       @bin = bin
       @abi = abi
-      @constructor_inputs, @functions, @events = parse_abi(abi)
+      @constructor_inputs, @functions, @events, @errors = parse_abi(abi)
     end
 
     # Creates a contract wrapper from a Solidity file.
@@ -106,6 +106,52 @@ module Eth
       end
     end
 
+    # Finds a function by name.
+    #
+    # @param name [String] function name.
+    # @param args [Integer, nil] number of arguments of a function.
+    # @return [Eth::Contract::Function] function object.
+    # @raise [ArgumentError] if function not found.
+    def function(name, args: nil)
+      functions.find do |f|
+        f.name == name && (args.nil? || args == f.inputs.size)
+      end || raise(ArgumentError, "this function does not exist!")
+    end
+
+    # Finds an error by name.
+    #
+    # @param name [String] error name.
+    # @param args [Integer, nil] number of arguments of an error.
+    # @return [Eth::Contract::Error] error object.
+    # @raise [ArgumentError] if error not found.
+    def error(name, args: nil)
+      errors.find do |e|
+        e.name == name && (args.nil? || args == e.inputs.size)
+      end || raise(ArgumentError, "this error does not exist!")
+    end
+
+    # Decodes a custom error returned by an RPC error using the contract ABI.
+    #
+    # @param rpc_error [RpcError] the RPC error containing revert data.
+    # @return [String] a human readable error message.
+    def decode_error(rpc_error)
+      data = rpc_error.data
+      return rpc_error.message if data.nil? || errors.nil?
+
+      signature = data[0, 10]
+      if (err = errors.find { |e| e.signature == signature })
+        values = err.decode(data)
+        args = values&.map { |v| v.is_a?(String) ? v : v.inspect }&.join(",")
+        args ||= ""
+        "execution reverted: #{err.name}(#{args})"
+      elsif signature == "0x08c379a0"
+        reason = Abi.decode(["string"], "0x" + data[10..])&.first
+        "execution reverted: #{reason}"
+      else
+        rpc_error.message
+      end
+    end
+
     # Create meta classes for smart contracts.
     def build
       class_name = @name
@@ -116,9 +162,12 @@ module Eth
         def_delegators :parent, :name, :abi, :bin
         def_delegators :parent, :gas_limit, :gas_price, :gas_limit=, :gas_price=, :nonce, :nonce=
         def_delegators :parent, :max_fee_per_gas, :max_fee_per_gas=, :max_priority_fee_per_gas, :max_priority_fee_per_gas=
-        def_delegators :parent, :events
+        def_delegators :parent, :events, :errors
         def_delegators :parent, :address, :address=
         def_delegator :parent, :functions
+        def_delegator :parent, :function
+        def_delegator :parent, :error
+        def_delegator :parent, :decode_error
         def_delegator :parent, :constructor_inputs
         define_method :parent do
           parent
@@ -140,7 +189,8 @@ module Eth
       end
       functions = abi.select { |x| x["type"] == "function" }.map { |fun| Eth::Contract::Function.new(fun) }
       events = abi.select { |x| x["type"] == "event" }.map { |evt| Eth::Contract::Event.new(evt) }
-      [constructor_inputs, functions, events]
+      errors = abi.select { |x| x["type"] == "error" }.map { |err| Eth::Contract::Error.new(err) }
+      [constructor_inputs, functions, events, errors]
     end
   end
 end
@@ -151,3 +201,4 @@ require "eth/contract/function"
 require "eth/contract/function_input"
 require "eth/contract/function_output"
 require "eth/contract/initializer"
+require "eth/contract/error"