block_given 0.1.0

data/lib/block_given/poller.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module BlockGiven
+  # Blocking polling helper.
+  #
+  #   receipt = BlockGiven::Poller.poll(interval: 2, timeout: 120) { client.get_transaction_receipt(hash) }
+  #
+  # The block is called until it returns a non-nil / non-false value, which is
+  # returned. Raises BlockGiven::TimeoutError when the timeout elapses.
+  module Poller
+    module_function
+
+    def poll(interval:, timeout: nil, description: "condition")
+      started = monotonic_now
+      attempt = 0
+      loop do
+        result = yield(attempt)
+        return result if result
+
+        attempt += 1
+        elapsed = monotonic_now - started
+        raise TimeoutError, "timed out after #{timeout}s waiting for #{description}" if timeout && elapsed >= timeout
+
+        remaining = timeout ? timeout - elapsed : interval
+        sleep([interval, remaining].min)
+      end
+    end
+
+    def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  # Background polling loop running in its own thread. Returned by the
+  # `watch_*` helpers; call #stop (alias #unwatch) to end it.
+  #
+  # Every running watcher is registered under a unique id, so they can be listed
+  # and stopped even when the object reference was lost:
+  #
+  #   watcher = client.watch_block_number(id: "blocks") { |n| puts n }
+  #   BlockGiven.watchers                     # => [#<BlockGiven::Watcher blocks ...>]
+  #   BlockGiven::Watcher.find("blocks").stop
+  #   BlockGiven::Watcher.stop_all
+  class Watcher
+    @registry = {}
+    @registry_mutex = Mutex.new
+
+    class << self
+      # Running (or stopping) watchers, oldest first.
+      def all
+        @registry_mutex.synchronize { @registry.values.dup }
+      end
+
+      def find(id)
+        @registry_mutex.synchronize { @registry[id.to_s] }
+      end
+
+      def find!(id)
+        find(id) || raise(InvalidArgumentError, "no running watcher with id #{id.inspect} (running: #{ids.join(', ')})")
+      end
+
+      def ids = all.map(&:id)
+
+      # Graceful stop by id. Returns the watcher, or nil if unknown.
+      def stop(id, join: nil)
+        watcher = find(id)
+        watcher&.stop&.join(join)
+      end
+
+      def kill(id) = find(id)&.kill
+
+      def stop_all(join: nil)
+        watchers = all
+        watchers.each(&:stop)
+        watchers.each { |w| w.join(join) }
+        watchers
+      end
+
+      def kill_all = all.each(&:kill)
+
+      # @api private
+      def register(watcher)
+        @registry_mutex.synchronize do
+          if (existing = @registry[watcher.id]) && !existing.equal?(watcher)
+            raise InvalidArgumentError, "a watcher with id #{watcher.id.inspect} is already running"
+          end
+
+          @registry[watcher.id] = watcher
+        end
+      end
+
+      # @api private
+      def unregister(watcher)
+        @registry_mutex.synchronize { @registry.delete(watcher.id) if @registry[watcher.id].equal?(watcher) }
+      end
+
+      def generate_id(name) = "#{name.to_s.gsub(/[^a-zA-Z0-9_.:@-]/, '_')}-#{SecureRandom.hex(3)}"
+    end
+
+    attr_reader :id, :interval, :name, :started_at, :ticks, :last_error, :last_error_at, :last_tick_at
+    # Last fully processed position (block number for log watchers), set by the tick.
+    attr_accessor :cursor
+
+    def initialize(interval:, name: "watcher", id: nil, logger: nil, on_error: nil, &tick)
+      raise ::ArgumentError, "a block is required" unless tick
+
+      @interval = interval
+      @name = name.to_s
+      @id = (id || self.class.generate_id(@name)).to_s
+      @logger = logger
+      @on_error = on_error
+      @tick = tick
+      @mutex = Mutex.new
+      @cond = ConditionVariable.new
+      @stopped = false
+      @thread = nil
+      @ticks = 0
+      @started_at = nil
+      @last_tick_at = nil
+      @last_error = nil
+      @last_error_at = nil
+    end
+
+    def start
+      return self if running?
+
+      self.class.register(self)
+      @stopped = false
+      @started_at = Time.now
+      @thread = Thread.new { run }
+      @thread.name = "block_given:#{id}"
+      @thread.report_on_exception = false
+      self
+    end
+
+    # Graceful: the current tick finishes, then the thread exits.
+    def stop
+      @mutex.synchronize do
+        @stopped = true
+        @cond.broadcast
+      end
+      self
+    end
+    alias unwatch stop
+
+    # Forceful: kills the thread even in the middle of a tick (use when stop does not return).
+    def kill
+      stop
+      @thread&.kill
+      self.class.unregister(self)
+      self
+    end
+
+    def running? = !!@thread&.alive?
+    def stopped? = @stopped
+
+    def status
+      return :idle if @thread.nil?
+      return :running if running? && !stopped?
+      return :stopping if running?
+
+      :stopped
+    end
+
+    def join(timeout = nil)
+      @thread&.join(timeout)
+      self
+    end
+
+    # Replace the error handler. Without a handler errors are logged and polling continues.
+    def on_error(&handler)
+      @on_error = handler
+      self
+    end
+
+    def uptime = started_at ? Time.now - started_at : 0
+
+    def to_h
+      {
+        id: id, name: name, status: status, interval: interval, cursor: cursor, ticks: ticks,
+        started_at: started_at, last_tick_at: last_tick_at,
+        last_error: last_error && "#{last_error.class}: #{last_error.message}", last_error_at: last_error_at,
+        thread: @thread&.name
+      }
+    end
+
+    def inspect
+      error = last_error ? " last_error=#{last_error.class}" : ""
+      "#<BlockGiven::Watcher #{id} #{name} #{status} cursor=#{cursor.inspect} ticks=#{ticks}#{error}>"
+    end
+
+    private
+
+    def run
+      until stopped?
+        begin
+          @tick.call(self)
+        rescue StandardError => e
+          handle_error(e)
+        ensure
+          @ticks += 1
+          @last_tick_at = Time.now
+        end
+        wait_interval
+      end
+    ensure
+      self.class.unregister(self)
+    end
+
+    def wait_interval
+      @mutex.synchronize { @cond.wait(@mutex, interval) unless @stopped }
+    end
+
+    def handle_error(error)
+      @last_error = error
+      @last_error_at = Time.now
+      if @on_error
+        @on_error.call(error, self)
+      else
+        logger.warn { "[block_given] watcher #{id}: #{error.class}: #{error.message}" }
+      end
+    end
+
+    def logger = @logger || BlockGiven.config.logger
+  end
+end

data/lib/block_given/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # Loaded automatically inside a Rails app (Rails 7.0+). Once the app has booted,
+  # BlockGiven logs through Rails.logger unless an initializer configured another logger.
+  #
+  #   # config/initializers/block_given.rb
+  #   BlockGiven.configure do |c|
+  #     c.connector = BlockGiven::Connectors::Alchemy.new(api_key: Rails.application.credentials.alchemy_api_key)
+  #     c.chain = Rails.env.production? ? :base : :base_sepolia
+  #   end
+  class Railtie < Rails::Railtie
+    config.after_initialize do
+      BlockGiven.config.logger = Rails.logger if Rails.logger && !BlockGiven.config.logger_configured?
+    end
+  end
+end

data/lib/block_given/receipt.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # Transaction receipt with symbolized, integer-decoded fields.
+  class Receipt
+    attr_reader :to_h
+
+    def initialize(raw)
+      @to_h = raw.is_a?(Receipt) ? raw.to_h : Normalizer.normalize(raw)
+    end
+
+    def transaction_hash = to_h[:transaction_hash]
+    def block_number = to_h[:block_number]
+    def block_hash = to_h[:block_hash]
+    def from = to_h[:from]
+    def to = to_h[:to]
+    def contract_address = to_h[:contract_address]
+    def gas_used = to_h[:gas_used]
+    def effective_gas_price = to_h[:effective_gas_price]
+    def cumulative_gas_used = to_h[:cumulative_gas_used]
+    def transaction_index = to_h[:transaction_index]
+    def logs = to_h[:logs] || []
+
+    # :success / :reverted (pre-Byzantium receipts have no status: treated as success).
+    def status
+      return :success if to_h[:status].nil?
+
+      to_h[:status] == 1 ? :success : :reverted
+    end
+
+    def success? = status == :success
+    def reverted? = status == :reverted
+
+    # Total fee paid in wei.
+    def fee = gas_used && effective_gas_price ? gas_used * effective_gas_price : nil
+
+    def [](key) = to_h[key.to_sym]
+
+    def inspect
+      "#<BlockGiven::Receipt #{transaction_hash} status=#{status} block=#{block_number} " \
+        "gas_used=#{gas_used} logs=#{logs.size}>"
+    end
+  end
+end

data/lib/block_given/signed_transaction.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # A signed transaction that has not been broadcast yet. Its hash is derived
+  # from the signed bytes, so it is known before any network call: persist
+  # `hash` and `nonce`, then `broadcast`. Whatever happens to the RPC call, the
+  # transaction can be found again with `client.transaction(hash)`.
+  #
+  #   signed = registry.prepare_write(:record, movement_id, tx: { nonce: call.nonce })
+  #   call.update!(tx_hash: signed.hash, nonce: signed.nonce, status: :submitted)
+  #   signed.broadcast                                  # => BlockGiven::Transaction
+  #
+  #   signed.replacement.broadcast                      # same nonce, fees bumped by 12.5%
+  #
+  # `hash` is the transaction hash (a String, like Transaction#hash), so instances
+  # are not usable as Hash keys; compare them with ==.
+  class SignedTransaction
+    # Nodes reject a same-nonce replacement whose fees are not at least 10% higher.
+    MIN_REPLACEMENT_MULTIPLIER = 1.1
+    DEFAULT_REPLACEMENT_MULTIPLIER = 1.125
+
+    # Rebuilds a SignedTransaction from persisted raw bytes (after a restart, typically), so it
+    # can be broadcast again or replaced. The bytes must have been signed by `wallet`.
+    def self.from_raw(raw, wallet:, interface: nil)
+      decoded = begin
+        Eth::Tx.decode(Utils.prefix_hex(raw))
+      rescue StandardError => e
+        raise InvalidArgumentError, "cannot decode signed transaction: #{e.message}"
+      end
+      sender = Utils.checksum_address(Utils.prefix_hex(decoded.sender)) # eth returns unprefixed hex
+      unless Utils.same_address?(sender, wallet.address)
+        raise InvalidArgumentError, "signed transaction was sent by #{sender}, not by wallet #{wallet.address}"
+      end
+
+      new(raw: raw, params: params_from(decoded, sender), wallet: wallet, interface: interface)
+    end
+
+    def self.params_from(decoded, sender)
+      destination = decoded.destination.to_s
+      params = {
+        from: sender, to: destination.empty? ? nil : Utils.checksum_address(Utils.prefix_hex(destination)),
+        value: decoded.amount, data: decoded.payload.to_s.empty? ? "" : Utils.bin_to_hex(decoded.payload),
+        chain_id: decoded.chain_id, nonce: decoded.signer_nonce, gas: decoded.gas_limit
+      }
+      # Same shape as Wallet#prepare_transaction (access_list nil when empty).
+      if decoded.respond_to?(:max_fee_per_gas)
+        access_list = decoded.access_list
+        params.merge(max_fee_per_gas: decoded.max_fee_per_gas,
+                     max_priority_fee_per_gas: decoded.max_priority_fee_per_gas,
+                     access_list: access_list.nil? || access_list.empty? ? nil : access_list)
+      else
+        params.merge(gas_price: decoded.gas_price, access_list: nil)
+      end
+    end
+    private_class_method :params_from
+
+    attr_reader :raw, :hash, :params, :wallet, :interface
+
+    # interface: an Abi::Interface used to name custom errors when the node rejects the
+    # broadcast with revert data (set by Contract#prepare_write).
+    def initialize(raw:, params:, wallet:, interface: nil)
+      @raw = Utils.prefix_hex(raw)
+      @params = params.freeze
+      @wallet = wallet
+      @interface = interface
+      @hash = Utils.keccak256(@raw)
+    end
+
+    def with_interface(interface) = self.class.new(raw: raw, params: params, wallet: wallet, interface: interface)
+
+    def client = wallet.client
+
+    def from = params[:from]
+    def to = params[:to]
+    def value = params[:value]
+    def data = params[:data]
+    def nonce = params[:nonce]
+    def gas = params[:gas]
+    def chain_id = params[:chain_id]
+    def max_fee_per_gas = params[:max_fee_per_gas]
+    def max_priority_fee_per_gas = params[:max_priority_fee_per_gas]
+    def gas_price = params[:gas_price]
+    def legacy? = !gas_price.nil?
+
+    # eth_sendRawTransaction. Returns a Transaction carrying the locally computed hash.
+    def broadcast
+      sent = with_decoded_errors { client.send_raw_transaction(raw) }
+      unless sent.hash.to_s.casecmp?(hash)
+        client.logger.warn do
+          "[block_given] node returned #{sent.hash} for signed transaction #{hash}"
+        end
+      end
+      transaction
+    end
+    alias submit broadcast
+
+    # The Transaction handle for this hash, without broadcasting (status, receipt...).
+    def transaction = client.transaction(hash)
+
+    # Re-signs the same payload with the same nonce and higher fees, to replace a
+    # transaction stuck in the mempool. Fees are the max of (current fees x
+    # fee_multiplier) and a fresh estimate from the node, so the replacement also
+    # catches up with the market. Both transactions share a nonce: only one can be mined.
+    def replacement(fee_multiplier: DEFAULT_REPLACEMENT_MULTIPLIER)
+      if fee_multiplier < MIN_REPLACEMENT_MULTIPLIER
+        raise InvalidArgumentError, "fee_multiplier must be >= #{MIN_REPLACEMENT_MULTIPLIER} (got #{fee_multiplier})"
+      end
+      raise InvalidArgumentError, "cannot replace a transaction without fee params (use .from_raw)" unless fees?
+
+      wallet.signed_transaction(
+        to: to, value: value, data: data, gas: gas, nonce: nonce, chain_id: chain_id,
+        access_list: params[:access_list], **with_decoded_errors { bumped_fees(fee_multiplier) }
+      ).with_interface(interface)
+    end
+
+    def to_h = params.merge(hash: hash, raw: raw)
+
+    def to_s = hash
+    def ==(other) = other.is_a?(SignedTransaction) && other.raw == raw
+    def inspect = "#<BlockGiven::SignedTransaction #{hash} nonce=#{nonce} to=#{to}>"
+
+    private
+
+    def fees? = legacy? || (max_fee_per_gas && max_priority_fee_per_gas)
+
+    def bumped_fees(multiplier)
+      if legacy?
+        { gas_price: [bump(gas_price, multiplier), client.gas_price].max }
+      else
+        estimated = client.estimate_fees_per_gas
+        priority = [bump(max_priority_fee_per_gas, multiplier), estimated[:max_priority_fee_per_gas]].max
+        max_fee = [bump(max_fee_per_gas, multiplier), estimated[:max_fee_per_gas], priority].max
+        { max_fee_per_gas: max_fee, max_priority_fee_per_gas: priority }
+      end
+    end
+
+    def bump(fee, multiplier) = (fee * multiplier).ceil
+
+    def with_decoded_errors
+      yield
+    rescue ContractRevertError => e
+      raise interface ? e.decode_with(interface) : e
+    end
+  end
+end

data/lib/block_given/transaction.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # A broadcast transaction identified by its hash. Wraps receipt polling.
+  #
+  #   tx = usdc.transfer(to: "0x...", amount: 1e6)
+  #   tx.hash            # => "0x..."
+  #   receipt = tx.wait  # polls until mined (see BlockGiven.config.timeout / polling_interval)
+  #   tx.wait!           # same, but raises BlockGiven::TransactionRevertedError on failure
+  class Transaction
+    attr_reader :hash, :client
+
+    def initialize(hash, client:)
+      @hash = hash
+      @client = client
+      @receipt = nil
+    end
+
+    # Non-blocking: the receipt if the transaction is mined, nil otherwise. Cached once
+    # found: call #reload (or build a fresh handle with client.transaction) to re-query the
+    # node, e.g. on every tick of a long-lived worker.
+    def receipt
+      @receipt ||= client.get_transaction_receipt(hash)
+    end
+
+    def reload
+      @receipt = nil
+      self
+    end
+
+    def mined? = !receipt.nil?
+
+    # One RPC round trip to classify the transaction (two while it is not mined):
+    #   :success / :reverted  mined, from the receipt status
+    #   :pending              known by the node, waiting in the mempool
+    #   :unknown              the node has never seen it, or dropped it: safe to re-broadcast
+    #                         the same signed bytes (see SignedTransaction#replacement)
+    def status
+      return receipt.status if mined?
+
+      details ? :pending : :unknown
+    end
+
+    def success? = mined? && receipt.success?
+    def reverted? = mined? && receipt.reverted?
+    def pending? = status == :pending
+    def unknown? = status == :unknown
+
+    # Blocks since inclusion, 1 when mined in the latest block, 0 while not mined.
+    def confirmations
+      return 0 unless mined?
+
+      [client.block_number - receipt.block_number + 1, 0].max
+    end
+
+    # Non-blocking counterpart of wait(confirmations:). Defaults to BlockGiven.config.confirmations.
+    def confirmed?(count = nil) = confirmations >= (count || BlockGiven.config.confirmations)
+
+    def wait(confirmations: nil, timeout: nil, polling_interval: nil)
+      @receipt = client.wait_for_transaction_receipt(
+        hash, confirmations: confirmations, timeout: timeout, polling_interval: polling_interval
+      )
+    end
+
+    def wait!(**options)
+      receipt = wait(**options)
+      raise TransactionRevertedError, receipt if receipt.reverted?
+
+      receipt
+    end
+
+    # Raw transaction object from the node (nil while it is not yet known).
+    def details = client.get_transaction(hash)
+
+    def explorer_url = client.chain&.explorer_tx_url(hash)
+
+    def to_s = hash
+    def ==(other) = other.is_a?(Transaction) && other.hash == hash
+    def inspect = "#<BlockGiven::Transaction #{hash}#{mined_flag}>"
+
+    private
+
+    def mined_flag = @receipt ? " mined block=#{@receipt.block_number} status=#{@receipt.status}" : ""
+  end
+end

data/lib/block_given/utils.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/util"
+
+module BlockGiven
+  # Stateless helpers, mirroring viem's `utils` (parseUnits, formatUnits, keccak256, ...).
+  module Utils
+    module_function
+
+    ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
+    BLOCK_TAGS = %w[latest earliest pending safe finalized].freeze
+
+    def hex?(value)
+      value.is_a?(String) && value.match?(/\A0x[0-9a-fA-F]*\z/)
+    end
+
+    def prefix_hex(hex)
+      hex.start_with?("0x") ? hex : "0x#{hex}"
+    end
+
+    def strip_hex(hex)
+      hex.start_with?("0x") ? hex[2..] : hex
+    end
+
+    # Integer -> "0x1a" (no leading zeros, as JSON-RPC QUANTITY expects).
+    def to_hex(value)
+      case value
+      when Integer then "0x#{value.to_s(16)}"
+      when String then prefix_hex(value)
+      else raise InvalidArgumentError, "cannot convert #{value.inspect} to hex"
+      end
+    end
+
+    def hex_to_int(hex)
+      return nil if hex.nil?
+      return hex if hex.is_a?(Integer)
+
+      Integer(strip_hex(hex), 16)
+    end
+
+    def hex_to_bin(hex)
+      [strip_hex(hex)].pack("H*")
+    end
+
+    def bin_to_hex(bin)
+      "0x#{bin.unpack1('H*')}"
+    end
+
+    # Left-pads a hex value to 32 bytes (used for event topics).
+    def pad_hex(hex, bytes: 32)
+      "0x#{strip_hex(hex).rjust(bytes * 2, '0')}"
+    end
+
+    # keccak256 of raw bytes (or of the bytes represented by a 0x hex string).
+    def keccak256(data)
+      bytes = hex?(data) ? hex_to_bin(data) : data.to_s
+      bin_to_hex(Eth::Util.keccak256(bytes))
+    end
+
+    def address?(value)
+      value.is_a?(String) && value.match?(/\A0x[0-9a-fA-F]{40}\z/)
+    end
+
+    def checksum_address(value)
+      value = value.address if value.respond_to?(:address) && !value.is_a?(String)
+      raise InvalidAddressError, "invalid address: #{value.inspect}" unless address?(value)
+
+      Eth::Address.new(value).checksummed
+    end
+
+    def same_address?(a, b)
+      a.to_s.downcase == b.to_s.downcase
+    end
+
+    # "1.5", 6 -> 1_500_000. Accepts String, Integer, Float, Rational, BigDecimal.
+    def parse_units(value, decimals)
+      decimal = to_decimal(value)
+      scaled = decimal * (BigDecimal(10)**decimals)
+      raise InvalidArgumentError, "#{value} has more than #{decimals} decimals" unless scaled.frac.zero?
+
+      scaled.to_i
+    end
+
+    # 1_500_000, 6 -> "1.5"
+    def format_units(value, decimals)
+      decimal = BigDecimal(value.to_i) / (BigDecimal(10)**decimals)
+      str = decimal.to_s("F")
+      str = str.sub(/\.?0+\z/, "") if str.include?(".")
+      str
+    end
+
+    def parse_ether(value) = parse_units(value, 18)
+    def format_ether(value) = format_units(value, 18)
+    def parse_gwei(value) = parse_units(value, 9)
+    def format_gwei(value) = format_units(value, 9)
+
+    def to_decimal(value)
+      case value
+      when BigDecimal then value
+      when Integer then BigDecimal(value)
+      when Float then BigDecimal(value.to_s)
+      when Rational then BigDecimal(value, 40)
+      when String then BigDecimal(value.strip)
+      else raise InvalidArgumentError, "cannot convert #{value.inspect} to a decimal"
+      end
+    rescue ::ArgumentError
+      raise InvalidArgumentError, "cannot convert #{value.inspect} to a decimal"
+    end
+
+    # Accepts an Integer, a hex QUANTITY or a block tag (:latest, "pending", ...).
+    def block_tag(value)
+      case value
+      when nil then "latest"
+      when Integer then to_hex(value)
+      when Symbol then block_tag(value.to_s)
+      when String
+        return value if hex?(value) || BLOCK_TAGS.include?(value)
+
+        raise InvalidArgumentError, "invalid block tag: #{value.inspect}"
+      else raise InvalidArgumentError, "invalid block: #{value.inspect}"
+      end
+    end
+
+    def snake_case(name)
+      name.to_s
+          .sub(/\A_+/, "")
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr("-", "_")
+          .downcase
+    end
+  end
+end

data/lib/block_given/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  VERSION = "0.1.0"
+end