siwe-rb 0.1.0

data/lib/siwe/message.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "error"
+require_relative "error_type"
+require_relative "parser"
+require_relative "response"
+require_relative "util"
+
+module Siwe
+  # An EIP-4361 Sign-In with Ethereum message.
+  # Construct via `Siwe::Message.new(**fields)` or parse via `Siwe::Message.parse(string)`.
+  # Render via `#prepare_message` (alias `#to_eip4361`, `#to_s`).
+  class Message
+    FIELDS = %i[
+      scheme domain address statement uri version chain_id nonce
+      issued_at expiration_time not_before request_id resources
+    ].freeze
+
+    attr_reader(*FIELDS, :warnings)
+
+    def self.parse(str)
+      result = Parser.parse(str)
+      msg = allocate
+      msg.send(:init_from_parser, result)
+      msg
+    end
+
+    def self.from_json(json_str)
+      data = JSON.parse(json_str, symbolize_names: true)
+      new(**data.slice(*FIELDS))
+    rescue JSON::ParserError => e
+      raise Error.new(ErrorType::UNABLE_TO_PARSE, message: "Invalid JSON: #{e.message}")
+    end
+
+    def initialize(domain:, address:, uri:, chain_id:, nonce: nil, version: "1",
+                   scheme: nil, statement: nil, issued_at: nil,
+                   expiration_time: nil, not_before: nil, request_id: nil, resources: nil)
+      @warnings = []
+      @scheme = scheme
+      @domain = domain
+      @address = normalize_address(address)
+      @statement = statement
+      @uri = uri
+      @version = version
+      @chain_id = coerce_chain_id(chain_id)
+      @nonce = nonce || Util.generate_nonce
+      @issued_at = issued_at || Time.now.utc.iso8601
+      @expiration_time = expiration_time
+      @not_before = not_before
+      @request_id = request_id
+      @resources = resources
+
+      validate_required!
+      roundtrip_validate!
+      freeze
+    end
+
+    def prepare_message
+      header_prefix = @scheme ? "#{@scheme}://#{@domain}" : @domain
+      header = "#{header_prefix} wants you to sign in with your Ethereum account:"
+
+      prefix = "#{header}\n#{@address}"
+      prefix = if @statement.nil?
+                 "#{prefix}\n\n"
+               else
+                 "#{prefix}\n\n#{@statement}\n"
+               end
+
+      suffix = "URI: #{@uri}\nVersion: #{@version}\nChain ID: #{@chain_id}"
+      suffix << "\nNonce: #{@nonce}"
+      suffix << "\nIssued At: #{@issued_at}" if @issued_at
+      suffix << "\nExpiration Time: #{@expiration_time}" if @expiration_time
+      suffix << "\nNot Before: #{@not_before}" if @not_before
+      suffix << "\nRequest ID: #{@request_id}" unless @request_id.nil?
+      if @resources
+        suffix << "\nResources:"
+        @resources.each { |r| suffix << "\n- #{r}" }
+      end
+
+      "#{prefix}\n#{suffix}"
+    end
+
+    alias to_eip4361 prepare_message
+    alias to_s prepare_message
+
+    # Verify a signature against this message and the verification params.
+    # Returns Siwe::Response — never raises on verification failure.
+    def verify(signature:, domain:, nonce:, scheme: nil, uri: nil, chain_id: nil,
+               request_id: nil, time: nil, config: nil, strict: false)
+      cfg = config || Siwe.config
+
+      check_param_mismatches!(domain: domain, nonce: nonce, scheme: scheme,
+                              uri: uri, chain_id: chain_id, request_id: request_id, strict: strict)
+      check_temporal!(time)
+      check_signature!(signature, cfg)
+
+      Response.new(success: true, error: nil, data: self)
+    rescue Error => e
+      Response.new(success: false, error: e, data: self)
+    end
+
+    # Verify a signature; raises Siwe::Error on failure, returns self on success.
+    def verify!(**)
+      response = verify(**)
+      raise response.error if response.failure?
+
+      self
+    end
+
+    def to_h
+      FIELDS.to_h { |f| [f, instance_variable_get("@#{f}")] }
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    def ==(other)
+      other.is_a?(Message) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    private
+
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+    def check_param_mismatches!(domain:, nonce:, scheme:, uri:, chain_id:, request_id:, strict:)
+      raise Error.new(ErrorType::MISSING_DOMAIN) if domain.nil? || domain.empty?
+      raise Error.new(ErrorType::MISSING_NONCE) if nonce.nil? || nonce.empty?
+
+      raise Error.new(ErrorType::DOMAIN_MISMATCH, expected: @domain, received: domain) if @domain != domain
+      if scheme && @scheme != scheme
+        raise Error.new(ErrorType::SCHEME_MISMATCH, expected: @scheme.to_s, received: scheme)
+      end
+      raise Error.new(ErrorType::NONCE_MISMATCH, expected: @nonce, received: nonce) if @nonce != nonce
+
+      raise Error.new(ErrorType::MISSING_URI) if strict && uri.nil?
+      raise Error.new(ErrorType::URI_MISMATCH, expected: @uri, received: uri) if uri && @uri != uri
+
+      raise Error.new(ErrorType::MISSING_CHAIN_ID) if strict && chain_id.nil?
+      if chain_id && @chain_id != chain_id
+        raise Error.new(ErrorType::CHAIN_ID_MISMATCH, expected: @chain_id.to_s, received: chain_id.to_s)
+      end
+
+      return unless request_id && @request_id != request_id
+
+      raise Error.new(ErrorType::REQUEST_ID_MISMATCH, expected: @request_id.to_s, received: request_id.to_s)
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+
+    def check_temporal!(time_str)
+      check_at = time_str ? Time.iso8601(time_str) : Time.now.utc
+      if @expiration_time && Time.iso8601(@expiration_time) < check_at
+        raise Error.new(ErrorType::EXPIRED_MESSAGE, expected: @expiration_time, received: check_at.iso8601)
+      end
+      return unless @not_before && Time.iso8601(@not_before) > check_at
+
+      raise Error.new(ErrorType::NOT_YET_VALID_MESSAGE, expected: @not_before, received: check_at.iso8601)
+    rescue ArgumentError => e
+      raise Error.new(ErrorType::INVALID_TIME_FORMAT, message: e.message)
+    end
+
+    def check_signature!(signature, cfg)
+      if signature.nil? || signature.empty?
+        raise Error.new(ErrorType::INVALID_SIGNATURE, expected: "non-empty signature", received: signature.inspect)
+      end
+
+      recovered = recover_eoa(signature, cfg)
+      return if recovered && recovered.downcase == @address.downcase
+
+      # EOA recovery failed or address mismatch — try smart-wallet path if configured.
+      return if smart_wallet_valid?(signature, cfg)
+
+      raise Error.new(ErrorType::INVALID_SIGNATURE, expected: @address, received: recovered.to_s)
+    end
+
+    def recover_eoa(signature, cfg)
+      cfg.adapter.verify_message(prepare_message, signature)
+    rescue StandardError
+      nil
+    end
+
+    def smart_wallet_valid?(signature, cfg)
+      rpc = resolve_rpc(cfg)
+      return false if rpc.nil?
+
+      check_chain_id_match!(rpc)
+      SmartWallet.verify(rpc: rpc, address: @address, message: prepare_message, signature: signature)
+    end
+
+    def resolve_rpc(cfg)
+      return cfg.rpc if cfg.rpc
+      return Rpc::HttpClient.new(cfg.rpc_url) if cfg.rpc_url
+
+      nil
+    end
+
+    def check_chain_id_match!(rpc)
+      return unless rpc.respond_to?(:chain_id)
+
+      rpc_chain = rpc.chain_id
+      return if rpc_chain.nil? || rpc_chain == @chain_id
+
+      raise Error.new(ErrorType::INVALID_SIGNATURE_CHAIN_ID,
+                      expected: @chain_id.to_s, received: rpc_chain.to_s)
+    end
+
+    def init_from_parser(result)
+      result[:fields].each { |k, v| instance_variable_set("@#{k}", v) }
+      @warnings = result[:warnings]
+      freeze
+    end
+
+    def normalize_address(addr)
+      raise Error.new(ErrorType::INVALID_ADDRESS, expected: "valid EIP-55 address", received: addr.to_s) if addr.nil?
+
+      case Util.address_case(addr)
+      when :checksum
+        addr
+      when :lower, :upper
+        @warnings << "address is not EIP-55 checksummed - #{addr}"
+        Util.checksum_address(addr) || addr
+      when :invalid_checksum
+        raise Error.new(ErrorType::INVALID_ADDRESS, expected: "valid EIP-55 address", received: addr)
+      else
+        raise Error.new(ErrorType::INVALID_ADDRESS, expected: "0x + 40 hex chars", received: addr.to_s)
+      end
+    end
+
+    def coerce_chain_id(value)
+      case value
+      when Integer then value
+      when String
+        unless value.match?(/\A\d+\z/)
+          raise Error.new(ErrorType::UNABLE_TO_PARSE, expected: "integer chain ID", received: value)
+        end
+
+        value.to_i
+      else
+        raise Error.new(ErrorType::UNABLE_TO_PARSE, expected: "integer chain ID", received: value.inspect)
+      end
+    end
+
+    def validate_required!
+      if @domain.nil? || @domain.to_s.empty?
+        raise Error.new(ErrorType::INVALID_DOMAIN, expected: "non-empty domain",
+                                                   received: @domain.inspect)
+      end
+      if @uri.nil? || @uri.to_s.empty?
+        raise Error.new(ErrorType::INVALID_URI, expected: "non-empty URI",
+                                                received: @uri.inspect)
+      end
+      unless @version == "1"
+        raise Error.new(ErrorType::INVALID_MESSAGE_VERSION, expected: "1",
+                                                            received: @version.to_s)
+      end
+      return if Parser::NONCE_REGEX.match?(@nonce.to_s)
+
+      raise Error.new(ErrorType::INVALID_NONCE, expected: "alphanumeric 8+ chars",
+                                                received: @nonce.to_s)
+    end
+
+    def roundtrip_validate!
+      Parser.parse(prepare_message)
+    rescue Error => e
+      raise Error.new(e.type, expected: e.expected, received: e.received,
+                              message: "Constructed message fails to parse: #{e.message}")
+    end
+  end
+end

data/lib/siwe/parser.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "error_type"
+require_relative "util"
+
+module Siwe
+  # Parser for the EIP-4361 Sign-In with Ethereum message format.
+  # Validates structure line-by-line and per-field via ABNF-aligned regexes.
+  # Returns a hash of typed fields plus an array of non-fatal warnings.
+  class Parser
+    HEADER_SUFFIX = " wants you to sign in with your Ethereum account:"
+    SCHEME_REGEX  = /\A([A-Za-z][A-Za-z0-9+\-.]*)\z/
+    # RFC 3986 authority (without scheme://) — userinfo, host (reg-name/IPv4/IP-literal), port.
+    DOMAIN_REGEX  = /\A[A-Za-z0-9\-._~%!$&'()*+,;=:@\[\]]+\z/
+    ADDRESS_REGEX = /\A0x[0-9a-fA-F]{40}\z/
+    NONCE_REGEX   = /\A[A-Za-z0-9]{8,}\z/
+    CHAIN_REGEX   = /\A[0-9]+\z/
+    # Statement chars per ABNF: %d32-33 %d35-36 %d38-59 %d61 %d63-64 %d91 %d93 %d95 %d126.
+    # Note: explicitly excludes %d34 (") and %d37 (%). Built via Regexp.new to avoid
+    # accidental string interpolation of `#$&` inside a regex literal.
+    STATEMENT_REGEX = Regexp.new('\A[a-zA-Z0-9 !\x23\x24\x26-\x3B\x3D\x3F\x40\x5B\x5D\x5F\x7E]*\z')
+    REQUEST_ID_REGEX = %r{\A[A-Za-z0-9\-._~%!$&'()*+,;=:@/?]*\z}
+    URI_REGEX = /\A[A-Za-z][A-Za-z0-9+\-.]*:[^\s]*\z/
+
+    def self.parse(str)
+      new(str).parse
+    end
+
+    def initialize(str)
+      @str = str
+      @warnings = []
+    end
+
+    def parse # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      raise unable_to_parse("message is not a string") unless @str.is_a?(String)
+
+      lines = @str.split("\n", -1)
+      raise unable_to_parse("message too short") if lines.length < 6
+
+      scheme, domain = parse_header(lines[0])
+      address = parse_address(lines[1])
+
+      uri_idx = lines.index { |l| l.start_with?("URI: ") }
+      raise unable_to_parse("URI: line not found") if uri_idx.nil? || uri_idx < 3
+
+      statement = parse_statement_block(lines[2...uri_idx])
+
+      uri        = parse_field(lines[uri_idx],     "URI: ",       :invalid_uri,             URI_REGEX)
+      version    = parse_field(lines[uri_idx + 1], "Version: ",   :invalid_message_version, /\A1\z/)
+      chain_str  = parse_field(lines[uri_idx + 2], "Chain ID: ",  :unable_to_parse,         CHAIN_REGEX)
+      nonce      = parse_field(lines[uri_idx + 3], "Nonce: ",     :invalid_nonce,           NONCE_REGEX)
+      issued_at  = parse_iso_field(lines[uri_idx + 4], "Issued At: ", "issuedAt")
+
+      cursor = uri_idx + 5
+      expiration_time = nil
+      not_before = nil
+      request_id = nil
+      resources = nil
+
+      if cursor < lines.length && lines[cursor]&.start_with?("Expiration Time: ")
+        expiration_time = parse_iso_field(lines[cursor], "Expiration Time: ", "expirationTime")
+        cursor += 1
+      end
+      if cursor < lines.length && lines[cursor]&.start_with?("Not Before: ")
+        not_before = parse_iso_field(lines[cursor], "Not Before: ", "notBefore")
+        cursor += 1
+      end
+      if cursor < lines.length && lines[cursor]&.start_with?("Request ID: ")
+        request_id = parse_field(lines[cursor], "Request ID: ", :unable_to_parse, REQUEST_ID_REGEX)
+        cursor += 1
+      end
+      if cursor < lines.length && lines[cursor] == "Resources:"
+        cursor += 1
+        resources = parse_resources(lines, cursor)
+        cursor += resources.length
+      end
+
+      validate_trailing(lines, cursor)
+      classify_address!(address)
+
+      {
+        fields: {
+          scheme: scheme,
+          domain: domain,
+          address: address,
+          statement: statement,
+          uri: uri,
+          version: version,
+          chain_id: chain_str.to_i,
+          nonce: nonce,
+          issued_at: issued_at,
+          expiration_time: expiration_time,
+          not_before: not_before,
+          request_id: request_id,
+          resources: resources
+        },
+        warnings: @warnings
+      }
+    end
+
+    private
+
+    def parse_header(line) # rubocop:disable Metrics/AbcSize
+      raise unable_to_parse("missing header") if line.nil? || line.empty?
+      raise unable_to_parse("malformed header") unless line.end_with?(HEADER_SUFFIX)
+
+      prefix = line[0...(line.length - HEADER_SUFFIX.length)]
+      raise unable_to_parse("empty domain") if prefix.empty?
+
+      if prefix.include?("://")
+        scheme, _, domain = prefix.partition("://")
+        raise unable_to_parse("invalid scheme: #{scheme.inspect}") unless SCHEME_REGEX.match?(scheme)
+        raise unable_to_parse("empty domain") if domain.empty?
+        unless DOMAIN_REGEX.match?(domain)
+          raise Error.new(ErrorType::INVALID_DOMAIN, expected: "RFC 3986 authority",
+                                                     received: domain)
+        end
+
+        [scheme, domain]
+      else
+        unless DOMAIN_REGEX.match?(prefix)
+          raise Error.new(ErrorType::INVALID_DOMAIN, expected: "RFC 3986 authority",
+                                                     received: prefix)
+        end
+
+        [nil, prefix]
+      end
+    end
+
+    def parse_address(line)
+      raise unable_to_parse("missing address line") if line.nil?
+      unless ADDRESS_REGEX.match?(line)
+        raise Error.new(ErrorType::INVALID_ADDRESS, expected: "0x + 40 hex chars",
+                                                    received: line)
+      end
+
+      line
+    end
+
+    def classify_address!(address)
+      case Util.address_case(address)
+      when :checksum, :lower, :upper
+        @warnings << "address is not EIP-55 checksummed - #{address}" if Util.address_case(address) != :checksum
+      when :invalid_checksum
+        raise Error.new(ErrorType::INVALID_ADDRESS, expected: "EIP-55 checksum address",
+                                                    received: address)
+      else
+        raise Error.new(ErrorType::INVALID_ADDRESS, expected: "0x + 40 hex chars",
+                                                    received: address)
+      end
+    end
+
+    def parse_statement_block(stmt_lines)
+      case stmt_lines.length
+      when 2
+        raise unable_to_parse("malformed statement block") unless stmt_lines.all?(&:empty?)
+
+        nil
+      when 3
+        first, stmt, last = stmt_lines
+        raise unable_to_parse("statement must be enclosed by blank lines") unless first.empty? && last.empty?
+        raise unable_to_parse("statement must not contain LF") if stmt.include?("\n")
+        raise unable_to_parse("statement contains disallowed characters") unless STATEMENT_REGEX.match?(stmt)
+
+        stmt
+      else
+        raise unable_to_parse("malformed statement block (#{stmt_lines.length} lines)")
+      end
+    end
+
+    def parse_field(line, prefix, error_type, regex)
+      raise unable_to_parse("missing #{prefix.strip}") if line.nil?
+      raise unable_to_parse("expected #{prefix.strip} line") unless line.start_with?(prefix)
+
+      value = line[prefix.length..]
+      raise Error.new(error_type, expected: prefix.strip, received: value) unless regex.match?(value)
+
+      value
+    end
+
+    def parse_iso_field(line, prefix, name)
+      value = parse_field(line, prefix, :invalid_time_format, /.+/)
+      unless Util.valid_iso8601?(value)
+        raise Error.new(ErrorType::INVALID_TIME_FORMAT, expected: "ISO 8601 #{name}", received: value)
+      end
+
+      value
+    end
+
+    def parse_resources(lines, start_idx)
+      idx = start_idx
+      out = []
+      while idx < lines.length && lines[idx].start_with?("- ")
+        uri = lines[idx][2..]
+        unless URI_REGEX.match?(uri)
+          raise Error.new(ErrorType::INVALID_URI, expected: "RFC 3986 resource URI", received: uri)
+        end
+
+        out << uri
+        idx += 1
+      end
+      out
+    end
+
+    def validate_trailing(lines, cursor)
+      while cursor < lines.length
+        unless lines[cursor].empty?
+          raise unable_to_parse("trailing content at line #{cursor + 1}: #{lines[cursor].inspect}")
+        end
+
+        cursor += 1
+      end
+    end
+
+    def unable_to_parse(detail)
+      Error.new(ErrorType::UNABLE_TO_PARSE, message: "Unable to parse the message: #{detail}")
+    end
+  end
+end

data/lib/siwe/response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Siwe
+  Response = Data.define(:success, :error, :data) do
+    def success?
+      success == true
+    end
+
+    def failure?
+      !success?
+    end
+  end
+end

data/lib/siwe/rpc.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "error"
+require_relative "error_type"
+
+module Siwe
+  module Rpc
+    # Minimal JSON-RPC client for eth_call. Default implementation used when
+    # Siwe.configure { |c| c.rpc_url = ... } is set. Anything that responds to
+    # `eth_call(to:, data:, block:)` (and optionally `chain_id`) can be plugged
+    # in via `c.rpc = ...` to use a different transport (web3.rb, eth-rpc, etc.).
+    class HttpClient
+      attr_reader :url, :timeout
+
+      def initialize(url, chain_id: nil, timeout: 10)
+        raise ArgumentError, "rpc url is required" if url.nil? || url.empty?
+
+        @url = url
+        @uri = URI(url)
+        @chain_id = chain_id
+        @timeout = timeout
+      end
+
+      def chain_id
+        @chain_id ||= fetch_chain_id
+      end
+
+      # Send eth_call. Returns the result as a hex string WITHOUT the 0x prefix.
+      # When +to+ is nil, omits it from params (used by EIP-6492 deploy-and-call).
+      # Raises Siwe::Error :rpc_error on transport / HTTP / JSON-RPC failure.
+      def eth_call(to:, data:, block: "latest")
+        call_params = { data: data }
+        call_params[:to] = to if to
+        rpc_request("eth_call", [call_params, block])
+      end
+
+      private
+
+      def fetch_chain_id
+        hex = rpc_request("eth_chainId", [])
+        hex.to_i(16)
+      rescue Error
+        nil
+      end
+
+      def rpc_request(method, params)
+        body = { jsonrpc: "2.0", id: 1, method: method, params: params }.to_json
+        response = post(body)
+        parse_response(response)
+      end
+
+      def post(body)
+        http = Net::HTTP.new(@uri.host, @uri.port)
+        http.use_ssl = (@uri.scheme == "https")
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        path = @uri.request_uri
+        path = "/" if path.empty?
+        request = Net::HTTP::Post.new(path, "Content-Type" => "application/json")
+        request.body = body
+        http.request(request)
+      rescue StandardError => e
+        raise Error.new(ErrorType::RPC_ERROR, message: "RPC transport error: #{e.class}: #{e.message}")
+      end
+
+      def parse_response(response)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Error.new(ErrorType::RPC_ERROR, message: "RPC HTTP #{response.code}: #{response.message}")
+        end
+
+        body = JSON.parse(response.body)
+        raise Error.new(ErrorType::RPC_ERROR, message: "RPC error: #{body["error"].inspect}") if body["error"]
+
+        result = body["result"]
+        raise Error.new(ErrorType::RPC_ERROR, message: "RPC returned no result") if result.nil?
+
+        strip_hex_prefix(result.to_s)
+      rescue JSON::ParserError => e
+        raise Error.new(ErrorType::RPC_ERROR, message: "Invalid RPC JSON: #{e.message}")
+      end
+
+      def strip_hex_prefix(hex)
+        hex.start_with?("0x") ? hex[2..] : hex
+      end
+    end
+  end
+end

data/lib/siwe/smart_wallet.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "eth"
+
+require_relative "eip6492"
+require_relative "error"
+require_relative "error_type"
+
+module Siwe
+  # Smart-wallet signature verification via the EIP-6492 off-chain universal
+  # validator. A single eth_call (deploy-and-call) covers both deployed ERC-1271
+  # wallets (e.g. Safe) and counterfactual EIP-6492-wrapped signatures
+  # (e.g. Coinbase Smart Wallet).
+  module SmartWallet
+    module_function
+
+    # Verify a smart-wallet signature.
+    # rpc       — anything responding to `eth_call(to:, data:, block:)`
+    # address   — claimed signer (smart contract or factory-deployed address)
+    # message   — EIP-4361 message string (will be EIP-191 hashed internally)
+    # signature — hex-encoded signature, may or may not include 0x prefix,
+    #             may include the EIP-6492 magic-suffix wrapper
+    # Returns true (valid) or false (validator returned non-1).
+    # Re-raises Siwe::Error from the rpc client on transport errors.
+    def verify(rpc:, address:, message:, signature:) # rubocop:disable Naming/PredicateMethod
+      hash_hex = bin_to_hex(eip191_hash(message))
+      sig_hex = strip_hex_prefix(signature)
+
+      args = Eth::Abi.encode(
+        %w[address bytes32 bytes],
+        [address, Eth::Util.hex_to_bin(hash_hex), Eth::Util.hex_to_bin(sig_hex)]
+      )
+      data = "0x#{Eip6492::VALIDATOR_BYTECODE}#{Eth::Util.bin_to_hex(args)}"
+
+      result = rpc.eth_call(to: nil, data: data)
+      result_indicates_valid?(result)
+    end
+
+    # Hash a message per EIP-191 (`personal_sign`). Returns binary keccak256.
+    def eip191_hash(message)
+      prefixed = Eth::Signature.prefix_message(message)
+      Eth::Util.keccak256(prefixed)
+    end
+
+    # Validator returns 0x01 (possibly zero-padded to 32 bytes) for valid,
+    # 0x00 for invalid. The default RPC client strips the 0x prefix; for
+    # callers that don't, normalize here.
+    def result_indicates_valid?(hex)
+      return false if hex.nil?
+
+      hex = strip_hex_prefix(hex.to_s)
+      hex.gsub(/\A0+/, "") == "1"
+    end
+
+    def strip_hex_prefix(hex)
+      hex.start_with?("0x") ? hex[2..] : hex
+    end
+
+    def bin_to_hex(bin)
+      bin.unpack1("H*")
+    end
+  end
+end