block_given 0.1.0

data/lib/block_given/client.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # Public JSON-RPC client bound to a chain and a connector (viem's PublicClient).
+  #
+  #   connector = BlockGiven::Connectors::Alchemy.new(api_key: "...")
+  #   client = BlockGiven::Client.new(chain: :base, connector: connector)
+  #   client.block_number
+  #   client.get_balance("0x...")
+  class Client
+    attr_reader :chain, :connector
+
+    def initialize(chain: nil, connector: nil, polling_interval: nil, timeout: nil, logger: nil)
+      @chain = chain ? Chains.resolve(chain) : BlockGiven.config.chain!
+      @connector = connector || BlockGiven.config.connector!
+      @polling_interval = polling_interval
+      @timeout = timeout
+      @logger = logger
+    end
+
+    def polling_interval = @polling_interval || BlockGiven.config.polling_interval
+    def timeout = @timeout || BlockGiven.config.timeout
+    def logger = @logger || BlockGiven.config.logger
+
+    # Raw JSON-RPC call: client.request("eth_blockNumber") / client.request("eth_getBalance", addr, "latest")
+    def request(method, *params)
+      logger.debug { "[block_given] -> #{method} #{params.inspect}" }
+      result = connector.request(method, params, chain: chain)
+      logger.debug { "[block_given] <- #{method} #{result.inspect[0, 200]}" }
+      result
+    end
+
+    # Batched JSON-RPC: client.batch([["eth_blockNumber"], ["eth_chainId"]])
+    def batch(calls) = connector.batch(calls, chain: chain)
+
+    # --- Chain / blocks -----------------------------------------------------
+
+    def chain_id = Utils.hex_to_int(request("eth_chainId"))
+    def block_number = Utils.hex_to_int(request("eth_blockNumber"))
+
+    def get_block(block = :latest, include_transactions: false)
+      method = Utils.hex?(block.to_s) && block.to_s.length == 66 ? "eth_getBlockByHash" : "eth_getBlockByNumber"
+      raw = request(method, block_param(block), include_transactions)
+      raw && Normalizer.normalize(raw)
+    end
+
+    def gas_price = Utils.hex_to_int(request("eth_gasPrice"))
+
+    def max_priority_fee_per_gas
+      Utils.hex_to_int(request("eth_maxPriorityFeePerGas"))
+    rescue RpcError
+      Utils.parse_gwei("1") # method not supported by every node
+    end
+
+    # EIP-1559 fee estimation (viem semantics: baseFee * multiplier + priority fee).
+    def estimate_fees_per_gas(base_fee_multiplier: nil)
+      multiplier = base_fee_multiplier || BlockGiven.config.base_fee_multiplier
+      block = get_block(:latest)
+      base_fee = block[:base_fee_per_gas] || gas_price
+      priority = max_priority_fee_per_gas
+      {
+        base_fee_per_gas: base_fee,
+        max_priority_fee_per_gas: priority,
+        max_fee_per_gas: (base_fee * multiplier).ceil + priority
+      }
+    end
+
+    # --- Accounts -----------------------------------------------------------
+
+    def get_balance(address, block: :latest)
+      Utils.hex_to_int(request("eth_getBalance", Utils.checksum_address(address), Utils.block_tag(block)))
+    end
+
+    def get_transaction_count(address, block: :pending)
+      Utils.hex_to_int(request("eth_getTransactionCount", Utils.checksum_address(address), Utils.block_tag(block)))
+    end
+
+    def get_code(address, block: :latest)
+      request("eth_getCode", Utils.checksum_address(address), Utils.block_tag(block))
+    end
+
+    def contract?(address) = get_code(address) != "0x"
+
+    def get_storage_at(address, slot, block: :latest)
+      request("eth_getStorageAt", Utils.checksum_address(address), Utils.to_hex(slot), Utils.block_tag(block))
+    end
+
+    # --- Calls --------------------------------------------------------------
+
+    # Executes a read-only call. Returns the raw hex result.
+    def call(to:, data:, from: nil, value: nil, gas: nil, block: :latest)
+      request("eth_call", call_object(to: to, data: data, from: from, value: value, gas: gas), Utils.block_tag(block))
+    end
+
+    def estimate_gas(to:, data: nil, from: nil, value: nil)
+      Utils.hex_to_int(request("eth_estimateGas", call_object(to: to, data: data, from: from, value: value)))
+    end
+
+    # --- Transactions -------------------------------------------------------
+
+    def send_raw_transaction(raw)
+      Transaction.new(request("eth_sendRawTransaction", Utils.prefix_hex(raw)), client: self)
+    end
+
+    def transaction(hash) = Transaction.new(hash, client: self)
+
+    def get_transaction(hash)
+      raw = request("eth_getTransactionByHash", hash)
+      raw && Normalizer.normalize(raw)
+    end
+
+    def get_transaction_receipt(hash)
+      raw = request("eth_getTransactionReceipt", hash)
+      raw && Receipt.new(raw)
+    end
+
+    # Polls until the receipt is available (and confirmed by N blocks).
+    def wait_for_transaction_receipt(hash, confirmations: nil, timeout: nil, polling_interval: nil)
+      confirmations ||= BlockGiven.config.confirmations
+      interval = polling_interval || self.polling_interval
+      Poller.poll(interval: interval, timeout: timeout || self.timeout, description: "receipt of #{hash}") do
+        receipt = get_transaction_receipt(hash)
+        next nil unless receipt&.block_number
+        next receipt if confirmations <= 1
+
+        block_number - receipt.block_number + 1 >= confirmations ? receipt : nil
+      end
+    end
+
+    # --- Logs ---------------------------------------------------------------
+
+    def get_logs(address: nil, topics: nil, from_block: :latest, to_block: :latest, block_hash: nil)
+      filter = {}
+      filter[:address] = Array(address).map { |a| Utils.checksum_address(a) } if address
+      filter[:address] = filter[:address].first if filter[:address]&.size == 1
+      filter[:topics] = topics if topics
+      if block_hash
+        filter[:blockHash] = block_hash
+      else
+        filter[:fromBlock] = Utils.block_tag(from_block)
+        filter[:toBlock] = Utils.block_tag(to_block)
+      end
+      Normalizer.normalize(request("eth_getLogs", filter))
+    end
+
+    # --- Watchers (background polling) --------------------------------------
+
+    # Yields each new block number. With emit_missed: true every block between two
+    # polls is yielded, otherwise only the latest one.
+    def watch_block_number(polling_interval: nil, emit_missed: false, id: nil, &block)
+      last = nil
+      watcher("block_number", polling_interval, id: id) do
+        current = block_number
+        next if last && current <= last
+
+        if emit_missed && last
+          ((last + 1)..current).each { |n| block.call(n) }
+        else
+          block.call(current)
+        end
+        last = current
+      end
+    end
+
+    def watch_blocks(polling_interval: nil, include_transactions: false, id: nil, &block)
+      watch_block_number(polling_interval: polling_interval, emit_missed: true, id: id) do |number|
+        block.call(get_block(number, include_transactions: include_transactions))
+      end
+    end
+
+    # get_logs over a large range, split in chunks of max_block_range blocks so provider
+    # limits are respected. Yields each chunk's logs when a block is given, else returns them all.
+    def get_logs_in_chunks(from_block:, address: nil, topics: nil, to_block: :latest, max_block_range: nil)
+      size = max_block_range || BlockGiven.config.max_block_range
+      to_block = block_number if to_block.nil? || Utils::BLOCK_TAGS.include?(to_block.to_s)
+      collected = []
+      from = from_block
+      while from <= to_block
+        to = [from + size - 1, to_block].min
+        logs = get_logs(address: address, topics: topics, from_block: from, to_block: to)
+        block_given? ? yield(logs, from, to) : collected.concat(logs)
+        from = to + 1
+      end
+      collected
+    end
+
+    # Yields new logs matching the filter, one Array per processed block range.
+    #
+    #   from_block:      resume from this block (catch-up is chunked by max_block_range)
+    #   confirmations:   stay this many blocks behind the head to dodge reorgs (default 0)
+    #   on_progress:     ->(from, to) called after each range is processed: persist `to` as your cursor
+    #   watcher.cursor:  last processed block number
+    #   id:              stable identifier for BlockGiven::Watcher.find / stop (default: auto-generated)
+    def watch_logs(address: nil, topics: nil, from_block: nil, polling_interval: nil, max_block_range: nil,
+                   confirmations: 0, on_progress: nil, id: nil, name: nil, &block)
+      last = from_block ? from_block - 1 : block_number - confirmations
+      watcher(name || "logs@#{Array(address).first || '*'}", polling_interval, id: id) do |watcher|
+        watcher.cursor ||= last
+        head = block_number - confirmations
+        while last < head && !watcher.stopped?
+          to = [last + (max_block_range || BlockGiven.config.max_block_range), head].min
+          logs = get_logs(address: address, topics: topics, from_block: last + 1, to_block: to)
+          block.call(logs) unless logs.empty?
+          on_progress&.call(last + 1, to)
+          last = watcher.cursor = to
+        end
+      end
+    end
+
+    # Generic background watcher on this client.
+    def watcher(name, polling_interval = nil, id: nil, &tick)
+      Watcher.new(interval: polling_interval || self.polling_interval, name: name, id: id, logger: logger, &tick).start
+    end
+
+    def inspect = "#<BlockGiven::Client chain=#{chain} connector=#{connector.inspect}>"
+
+    private
+
+    def block_param(block)
+      return block if Utils.hex?(block.to_s) && block.to_s.length == 66
+
+      Utils.block_tag(block)
+    end
+
+    def call_object(to:, data:, from:, value:, gas: nil)
+      obj = { to: Utils.checksum_address(to) }
+      obj[:data] = Utils.prefix_hex(data) if data && data != ""
+      obj[:from] = Utils.checksum_address(from) if from
+      obj[:value] = Utils.to_hex(value) if value && value != 0
+      obj[:gas] = Utils.to_hex(gas) if gas
+      obj
+    end
+  end
+end

data/lib/block_given/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module BlockGiven
+  # Global configuration set through `BlockGiven.configure { |c| ... }`.
+  class Configuration
+    attr_accessor :connector, :polling_interval, :timeout, :gas_multiplier, :base_fee_multiplier,
+                  :confirmations, :abi_path, :max_block_range
+    attr_reader :chain, :logger
+
+    def initialize
+      @connector = nil
+      @chain = nil
+      @polling_interval = 2.0     # seconds between two polls (receipts, blocks, events)
+      @timeout = 180              # seconds before wait_for_transaction_receipt gives up
+      @gas_multiplier = 1.2       # safety margin applied on top of eth_estimateGas
+      @base_fee_multiplier = 1.2  # viem default: maxFeePerGas = baseFee * 1.2 + priorityFee
+      @confirmations = 1
+      @max_block_range = 2_000    # eth_getLogs ranges are split in chunks of this many blocks
+      @abi_path = nil             # directory abi_file resolves relative paths against (e.g. Rails.root.join("abis"))
+      @logger = Logger.new($stderr, level: Logger::WARN, progname: "block_given")
+      @logger_configured = false
+    end
+
+    def logger=(logger)
+      @logger = logger
+      @logger_configured = true
+    end
+
+    # true once an application set its own logger (the Rails railtie respects it).
+    def logger_configured? = @logger_configured
+
+    # Accepts a BlockGiven::Chain, a symbol (:base), a name ("base-sepolia") or a chain id (8453).
+    def chain=(value)
+      @chain = value.nil? ? nil : Chains.resolve(value)
+    end
+
+    def connector!
+      connector || raise(ConfigurationError, "no connector configured: set BlockGiven.config.connector " \
+                                             "(e.g. BlockGiven::Connectors::Alchemy.new(api_key: ...))")
+    end
+
+    def chain!
+      chain || raise(ConfigurationError, "no chain configured: set BlockGiven.config.chain (e.g. :base)")
+    end
+  end
+end

data/lib/block_given/connectors/alchemy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Connectors
+    # Alchemy JSON-RPC connector. The endpoint is derived from the chain, so one
+    # connector instance can serve any Alchemy-supported network.
+    #
+    #   BlockGiven::Connectors::Alchemy.new(api_key: ENV["ALCHEMY_API_KEY"])
+    class Alchemy < Http
+      attr_reader :api_key
+
+      def initialize(api_key:, timeout: 30, retries: 3, retry_delay: 0.5, logger: nil, headers: {})
+        raise ConfigurationError, "Alchemy api_key is required" if api_key.nil? || api_key.to_s.empty?
+
+        @api_key = api_key.to_s
+        super(url: nil, headers: headers, timeout: timeout, retries: retries, retry_delay: retry_delay, logger: logger)
+      end
+
+      def endpoint(chain)
+        raise ConfigurationError, "Alchemy connector needs a chain" if chain.nil?
+        raise ConfigurationError, "#{chain.name} is not available on Alchemy" unless chain.alchemy_network
+
+        "https://#{chain.alchemy_network}.g.alchemy.com/v2/#{api_key}"
+      end
+
+      def inspect = "#<BlockGiven::Connectors::Alchemy api_key=#{redacted_key}>"
+
+      # Keeps the network host visible, masks the key: https://base-mainnet.g.alchemy.com/v2/abcd…
+      def redact(endpoint) = endpoint.to_s.sub(api_key, redacted_key)
+
+      private
+
+      def redacted_key = "#{api_key[0, 4]}…"
+    end
+  end
+end

data/lib/block_given/connectors/base.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Connectors
+    # A connector is a JSON-RPC transport. Subclasses implement #request; the
+    # chain is passed so multi-network providers (Alchemy) can pick the endpoint.
+    class Base
+      # @return the JSON-RPC `result` (raw JSON value). Raises BlockGiven::RpcError on error.
+      def request(method, params = [], chain: nil)
+        raise NotImplementedError, "#{self.class}#request"
+      end
+
+      # Naive batch: one request per call. Transports with real batching override it.
+      # Returns an array of results; failed calls are returned as RpcError instances.
+      def batch(calls, chain: nil)
+        calls.map do |(method, params)|
+          request(method, params || [], chain: chain)
+        rescue RpcError => e
+          e
+        end
+      end
+
+      def name = self.class.name.split("::").last.downcase
+    end
+  end
+end

data/lib/block_given/connectors/http.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module BlockGiven
+  module Connectors
+    # Generic JSON-RPC over HTTP(S) transport with retries and exponential backoff.
+    #
+    #   BlockGiven::Connectors::Http.new(url: "http://127.0.0.1:8545")
+    #   BlockGiven::Connectors::Http.new # -> falls back to chain.rpc_urls.first
+    class Http < Base
+      RETRIABLE_STATUSES = [408, 425, 429, 500, 502, 503, 504].freeze
+      RETRIABLE_RPC_CODES = [-32_005, -32_603, 429].freeze # rate limited / internal error
+      RETRIABLE_EXCEPTIONS = [Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED,
+                              Errno::EHOSTUNREACH, EOFError, SocketError, OpenSSL::SSL::SSLError].freeze
+
+      attr_reader :url, :headers, :timeout, :retries, :retry_delay
+
+      def initialize(url: nil, headers: {}, timeout: 30, retries: 3, retry_delay: 0.5, logger: nil)
+        super()
+        @url = url
+        user_agent = "block_given/#{BlockGiven::VERSION}"
+        @headers = { "Content-Type" => "application/json", "User-Agent" => user_agent }.merge(headers)
+        @timeout = timeout
+        @retries = retries
+        @retry_delay = retry_delay
+        @logger = logger
+        @id = 0
+        @mutex = Mutex.new
+      end
+
+      def endpoint(chain)
+        return url if url
+
+        chain&.rpc_urls&.first ||
+          raise(ConfigurationError, "no RPC url: pass url: to the connector or use a chain with rpc_urls")
+      end
+
+      def request(method, params = [], chain: nil)
+        payload = { jsonrpc: "2.0", id: next_id, method: method, params: params }
+        body = with_retries(method) { post(endpoint(chain), payload) }
+        handle_single(body, method)
+      end
+
+      def batch(calls, chain: nil)
+        return [] if calls.empty?
+
+        payload = calls.map { |(method, params)| { jsonrpc: "2.0", id: next_id, method: method, params: params || [] } }
+        body = with_retries("batch") { post(endpoint(chain), payload) }
+        raise RpcError, "batch response is not an array: #{body.inspect}" unless body.is_a?(Array)
+
+        by_id = body.to_h { |entry| [entry["id"], entry] }
+        payload.map do |req|
+          entry = by_id[req[:id]] || { "error" => { "message" => "missing response for id #{req[:id]}" } }
+          if entry.key?("error")
+            RpcError.from_payload(entry["error"], rpc_method: req[:method])
+          else
+            entry["result"]
+          end
+        end
+      end
+
+      def inspect = "#<#{self.class.name} url=#{url ? redact(url).inspect : 'chain default'}>"
+
+      # Endpoint as it may appear in logs and error messages. RPC URLs usually carry
+      # the API key in their path (Infura, QuickNode, ...), so only scheme and host are kept.
+      def redact(endpoint)
+        uri = URI.parse(endpoint.to_s)
+        host = uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+        path = uri.path.to_s.delete_prefix("/").empty? ? "" : "/…"
+        "#{uri.scheme}://#{host}#{path}"
+      rescue URI::InvalidURIError
+        "<invalid url>"
+      end
+
+      private
+
+      def logger = @logger || BlockGiven.config.logger
+
+      def next_id
+        @mutex.synchronize { @id += 1 }
+      end
+
+      def handle_single(body, method)
+        raise RpcError.new("unexpected JSON-RPC response: #{body.inspect}", rpc_method: method) unless body.is_a?(Hash)
+
+        if body.key?("error")
+          error = RpcError.from_payload(body["error"], rpc_method: method)
+          raise error unless RETRIABLE_RPC_CODES.include?(error.code) && !error.is_a?(ContractRevertError)
+
+          raise Retry, error
+        end
+        body["result"]
+      end
+
+      # Internal signal used to retry on retriable JSON-RPC errors.
+      class Retry < StandardError
+        attr_reader :cause_error
+
+        def initialize(cause_error)
+          @cause_error = cause_error
+          super(cause_error.message)
+        end
+      end
+
+      def with_retries(method)
+        attempt = 0
+        loop do
+          begin
+            return yield
+          rescue Retry => e
+            raise e.cause_error if attempt >= retries
+          rescue HttpError => e
+            raise unless RETRIABLE_STATUSES.include?(e.status) && attempt < retries
+          rescue *RETRIABLE_EXCEPTIONS => e
+            raise HttpError, "#{e.class}: #{e.message}" unless attempt < retries
+          end
+          attempt += 1
+          delay = retry_delay * (2**(attempt - 1))
+          logger.debug { "[block_given] retrying #{method} (attempt #{attempt}/#{retries}) in #{delay}s" }
+          sleep(delay)
+        end
+      end
+
+      def post(endpoint, payload)
+        uri = URI.parse(endpoint)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+        request = Net::HTTP::Post.new(uri.request_uri, headers)
+        request.body = JSON.generate(payload)
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise HttpError.new("HTTP #{response.code} from #{redact(endpoint)}: #{response.body.to_s[0, 200]}",
+                              status: response.code.to_i, body: response.body)
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise HttpError.new("invalid JSON from RPC endpoint: #{e.message}", body: response&.body)
+      end
+    end
+  end
+end

data/lib/block_given/connectors/stub.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Connectors
+    # In-memory connector for tests. Responses can be static values, sequences
+    # (consumed in order, last value repeats) or procs receiving the params.
+    #
+    #   stub = BlockGiven::Connectors::Stub.new(
+    #     "eth_blockNumber" => BlockGiven::Connectors::Stub.sequence("0x10", "0x11"),
+    #     "eth_call" => ->(params) { "0x" + "0" * 63 + "1" }
+    #   )
+    #   stub.calls # => [["eth_blockNumber", []], ...]
+    class Stub < Base
+      class Sequence
+        def initialize(values)
+          @values = values.dup
+        end
+
+        def next
+          @values.size > 1 ? @values.shift : @values.first
+        end
+      end
+
+      def self.sequence(*values) = Sequence.new(values)
+
+      attr_reader :calls
+
+      def initialize(responses = {}, &handler)
+        super()
+        @responses = {}
+        @handler = handler
+        @calls = []
+        responses.each { |method, value| stub(method, value) }
+      end
+
+      def stub(method, value = nil, &block)
+        @responses[method.to_s] = block || value
+        self
+      end
+
+      def request(method, params = [], chain: nil)
+        @calls << [method.to_s, params]
+        value = resolve(method.to_s, params, chain)
+        raise value if value.is_a?(Exception)
+
+        value
+      end
+
+      def calls_for(method) = calls.select { |(m, _)| m == method.to_s }.map(&:last)
+      def reset! = @calls.clear
+
+      private
+
+      def resolve(method, params, chain)
+        if @responses.key?(method)
+          value = @responses[method]
+          value = value.next if value.is_a?(Sequence)
+          return value.is_a?(Proc) ? value.call(params) : value
+        end
+        return @handler.call(method, params, chain) if @handler
+
+        raise RpcError.new("no stub for #{method}", code: -32_601, rpc_method: method)
+      end
+    end
+  end
+end