block_given 0.1.0 → 0.2.0

data/lib/block_given/poller.rb

@@ -3,15 +3,32 @@
 require "securerandom"
 
 module BlockGiven
-  # Blocking polling helper.
+  # Blocking polling helper: calls a block repeatedly until it returns a truthy value or a timeout elapses.
   #
-  #   receipt = BlockGiven::Poller.poll(interval: 2, timeout: 120) { client.get_transaction_receipt(hash) }
+  # Used by {Client#wait_for_transaction_receipt}; background (non-blocking) polling is {Watcher}'s job.
   #
-  # The block is called until it returns a non-nil / non-false value, which is
-  # returned. Raises BlockGiven::TimeoutError when the timeout elapses.
+  # @example
+  #   receipt = BlockGiven::Poller.poll(interval: 2, timeout: 120, description: "receipt") do
+  #     client.get_transaction_receipt(hash)
+  #   end
   module Poller
     module_function
 
+    # Calls the block until it returns a non-nil / non-false value, sleeping `interval` seconds between
+    # attempts, and returns that value.
+    #
+    # The timeout is checked after each failed attempt against a monotonic clock, and the last sleep is
+    # shortened so the deadline is never overshot by more than one interval. With `timeout: nil` the loop
+    # runs until the block succeeds.
+    #
+    # @param interval [Numeric] seconds slept between two attempts
+    # @param timeout [Numeric, nil] seconds after which {TimeoutError} is raised; nil waits forever
+    # @param description [String] what is being waited for, used in the {TimeoutError} message
+    # @yield [attempt] once per attempt, starting immediately (no initial sleep)
+    # @yieldparam attempt [Integer] zero-based attempt counter
+    # @yieldreturn [Object, nil, false] the value to return, or nil / false to keep polling
+    # @return [Object] the first truthy value returned by the block
+    # @raise [TimeoutError] when `timeout` seconds elapsed without the block returning a truthy value
     def poll(interval:, timeout: nil, description: "condition")
       started = monotonic_now
       attempt = 0
@@ -28,47 +45,95 @@ module BlockGiven
       end
     end
 
+    # Current reading of the monotonic clock, in seconds (immune to wall-clock adjustments).
+    #
+    # @api private
+    # @return [Float]
     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.
+  # Background polling loop running in its own thread, returned by the `watch_*` helpers of {Client}.
   #
-  # Every running watcher is registered under a unique id, so they can be listed
-  # and stopped even when the object reference was lost:
+  # A watcher calls its tick block, sleeps `interval` seconds (interruptible by {#stop}), and repeats until
+  # stopped. Exceptions raised by the tick are caught: they are recorded in {#last_error} / {#last_error_at}
+  # and either passed to the {#on_error} handler or logged as warnings, and polling continues. The thread is
+  # named `block_given:<id>` and does not report exceptions itself.
   #
+  # Every running watcher is registered under a unique {#id}, so watchers can be listed ({Watcher.all},
+  # {BlockGiven.watchers}) and stopped ({Watcher.stop}, {Watcher.stop_all}) even when the object reference
+  # was lost. A watcher leaves the registry when its thread ends (or is killed). Starting a second watcher
+  # with the id of a running one raises {InvalidArgumentError}.
+  #
+  # {#cursor} is free storage for the tick: {Client#watch_logs} keeps the last fully processed block number
+  # there, so a supervisor can read where the watcher stands.
+  #
+  # @example Registry lookups by id
   #   watcher = client.watch_block_number(id: "blocks") { |n| puts n }
-  #   BlockGiven.watchers                     # => [#<BlockGiven::Watcher blocks ...>]
-  #   BlockGiven::Watcher.find("blocks").stop
+  #   BlockGiven.watchers                       # => [#<BlockGiven::Watcher blocks block_number running ...>]
+  #   BlockGiven::Watcher.find("blocks").status # => :running
+  #   BlockGiven::Watcher.stop("blocks", join: 5)
   #   BlockGiven::Watcher.stop_all
+  # @example Custom error handling
+  #   watcher.on_error { |error, w| Sentry.capture_exception(error, extra: w.to_h) }
   class Watcher
     @registry = {}
     @registry_mutex = Mutex.new
 
     class << self
       # Running (or stopping) watchers, oldest first.
+      #
+      # @return [Array<Watcher>] a snapshot copy of the registry
       def all
         @registry_mutex.synchronize { @registry.values.dup }
       end
 
+      # Looks up a running watcher by id.
+      #
+      # @example
+      #   BlockGiven::Watcher.find("usdc-transfers")&.cursor
+      # @param id [String, Symbol, #to_s] watcher id
+      # @return [Watcher, nil] the watcher, or nil when no running watcher has this id
       def find(id)
         @registry_mutex.synchronize { @registry[id.to_s] }
       end
 
+      # Looks up a running watcher by id, raising when it is unknown.
+      #
+      # @param id [String, Symbol, #to_s] watcher id
+      # @return [Watcher]
+      # @raise [InvalidArgumentError] when no running watcher has this id (the message lists the running ids)
       def find!(id)
         find(id) || raise(InvalidArgumentError, "no running watcher with id #{id.inspect} (running: #{ids.join(', ')})")
       end
 
+      # Ids of the running watchers, oldest first.
+      #
+      # @return [Array<String>]
       def ids = all.map(&:id)
 
-      # Graceful stop by id. Returns the watcher, or nil if unknown.
+      # Gracefully stops a watcher by id (see {#stop}) and optionally waits for its thread to end.
+      #
+      # @example
+      #   BlockGiven::Watcher.stop("usdc-transfers", join: 5) # => the watcher, or nil if it was not running
+      # @param id [String, Symbol, #to_s] watcher id
+      # @param join [Numeric, nil] seconds to wait for the thread after asking it to stop; nil waits until it
+      #   ends, but note that {#join} is only called when the watcher exists
+      # @return [Watcher, nil] the stopped watcher, or nil when no running watcher has this id
       def stop(id, join: nil)
         watcher = find(id)
         watcher&.stop&.join(join)
       end
 
+      # Forcefully kills a watcher by id (see {#kill}).
+      #
+      # @param id [String, Symbol, #to_s] watcher id
+      # @return [Watcher, nil] the killed watcher, or nil when no running watcher has this id
       def kill(id) = find(id)&.kill
 
+      # Gracefully stops every running watcher, then waits for each thread.
+      #
+      # @param join [Numeric, nil] seconds to wait for each thread; nil waits until it ends
+      # @return [Array<Watcher>] the watchers that were running
       def stop_all(join: nil)
         watchers = all
         watchers.each(&:stop)
@@ -76,9 +141,17 @@ module BlockGiven
         watchers
       end
 
+      # Forcefully kills every running watcher (see {#kill}).
+      #
+      # @return [Array<Watcher>] the watchers that were running
       def kill_all = all.each(&:kill)
 
+      # Adds a watcher to the registry under its id; called by {#start}.
+      #
       # @api private
+      # @param watcher [Watcher]
+      # @return [Watcher] the registered watcher
+      # @raise [InvalidArgumentError] when a different watcher with the same id is already registered
       def register(watcher)
         @registry_mutex.synchronize do
           if (existing = @registry[watcher.id]) && !existing.equal?(watcher)
@@ -89,18 +162,60 @@ module BlockGiven
         end
       end
 
+      # Removes a watcher from the registry, only if the registered object is this very watcher.
+      #
       # @api private
+      # @param watcher [Watcher]
+      # @return [Watcher, nil] the removed watcher, or nil when it was not registered
       def unregister(watcher)
         @registry_mutex.synchronize { @registry.delete(watcher.id) if @registry[watcher.id].equal?(watcher) }
       end
 
+      # Builds a unique id from a name: the name with unsafe characters replaced by `_`, plus a random suffix.
+      #
+      # @example
+      #   BlockGiven::Watcher.generate_id("logs@0xAbc") # => "logs@0xAbc-3f9a1c"
+      # @param name [String, #to_s] human-readable name
+      # @return [String] `"<sanitized name>-<6 hex chars>"`
       def generate_id(name) = "#{name.to_s.gsub(/[^a-zA-Z0-9_.:@-]/, '_')}-#{SecureRandom.hex(3)}"
     end
 
+    # @!attribute [r] id
+    #   @return [String] unique identifier used by the registry ({Watcher.find}, {Watcher.stop})
+    # @!attribute [r] interval
+    #   @return [Numeric] seconds slept between two ticks
+    # @!attribute [r] name
+    #   @return [String] human-readable name (e.g. `"block_number"`, `"logs@0x..."`)
+    # @!attribute [r] started_at
+    #   @return [Time, nil] when {#start} was last called; nil while idle
+    # @!attribute [r] ticks
+    #   @return [Integer] number of completed ticks, including those that raised
+    # @!attribute [r] last_error
+    #   @return [StandardError, nil] the most recent exception raised by the tick, if any
+    # @!attribute [r] last_error_at
+    #   @return [Time, nil] when {#last_error} was recorded
+    # @!attribute [r] last_tick_at
+    #   @return [Time, nil] when the most recent tick finished
+
     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.
+    # Last fully processed position, set by the tick: {Client#watch_logs} stores the last block number whose
+    # logs were handed to the caller, and only after they were. nil until the first tick ran.
+    #
+    # @return [Integer, Object, nil]
     attr_accessor :cursor
 
+    # Builds a watcher without starting it; call {#start}.
+    #
+    # @param interval [Numeric] seconds slept between two ticks
+    # @param name [String, #to_s] human-readable name, also the base of the generated id
+    # @param id [String, #to_s, nil] stable identifier for the registry. Defaults to {Watcher.generate_id}.
+    # @param logger [Logger, nil] receives a warning per failed tick when no `on_error` handler is set.
+    #   Defaults to `BlockGiven.config.logger`.
+    # @param on_error [#call, nil] error handler called with `(error, watcher)`; see {#on_error}
+    # @yield [watcher] on every tick, from the watcher thread
+    # @yieldparam watcher [Watcher] the watcher itself, to check {#stopped?} or update {#cursor}
+    # @yieldreturn [void]
+    # @raise [ArgumentError] when no block is given
     def initialize(interval:, name: "watcher", id: nil, logger: nil, on_error: nil, &tick)
       raise ::ArgumentError, "a block is required" unless tick
 
@@ -121,6 +236,12 @@ module BlockGiven
       @last_error_at = nil
     end
 
+    # Registers the watcher and starts its thread (named `block_given:<id>`). No-op when already running.
+    #
+    # The first tick runs immediately in the new thread. A watcher can be restarted after it stopped.
+    #
+    # @return [self]
+    # @raise [InvalidArgumentError] when another watcher with the same id is running
     def start
       return self if running?
 
@@ -133,7 +254,10 @@ module BlockGiven
       self
     end
 
-    # Graceful: the current tick finishes, then the thread exits.
+    # Asks the watcher to stop gracefully: the current tick finishes, the sleep is interrupted, then the
+    # thread exits and the watcher leaves the registry. Returns at once; use {#join} to wait.
+    #
+    # @return [self]
     def stop
       @mutex.synchronize do
         @stopped = true
@@ -143,7 +267,10 @@ module BlockGiven
     end
     alias unwatch stop
 
-    # Forceful: kills the thread even in the middle of a tick (use when stop does not return).
+    # Stops forcefully: kills the thread even in the middle of a tick and unregisters the watcher at once.
+    # Use it when {#stop} does not return because a tick hangs.
+    #
+    # @return [self]
     def kill
       stop
       @thread&.kill
@@ -151,9 +278,20 @@ module BlockGiven
       self
     end
 
+    # Whether the watcher thread is alive (also true while it is stopping).
+    #
+    # @return [Boolean]
     def running? = !!@thread&.alive?
+
+    # Whether {#stop} (or {#kill}) was requested; the tick can check it to exit long loops early.
+    #
+    # @return [Boolean]
     def stopped? = @stopped
 
+    # Lifecycle state of the watcher.
+    #
+    # @return [Symbol] `:idle` (never started), `:running`, `:stopping` (stop requested, thread still alive)
+    #   or `:stopped`
     def status
       return :idle if @thread.nil?
       return :running if running? && !stopped?
@@ -162,19 +300,40 @@ module BlockGiven
       :stopped
     end
 
+    # Waits for the watcher thread to end.
+    #
+    # @param timeout [Numeric, nil] seconds to wait; nil waits until the thread ends
+    # @return [self] whether or not the thread ended within `timeout`
     def join(timeout = nil)
       @thread&.join(timeout)
       self
     end
 
-    # Replace the error handler. Without a handler errors are logged and polling continues.
+    # Replaces the error handler called when a tick raises.
+    #
+    # Without a handler, errors are logged as warnings and polling continues; with one, the handler decides
+    # (it may call {#stop}). Either way the error is recorded in {#last_error} first.
+    #
+    # @yield [error, watcher] for each exception raised by the tick, from the watcher thread
+    # @yieldparam error [StandardError] the exception
+    # @yieldparam watcher [Watcher] the watcher itself
+    # @yieldreturn [void]
+    # @return [self]
     def on_error(&handler)
       @on_error = handler
       self
     end
 
+    # Seconds elapsed since {#start}.
+    #
+    # @return [Numeric] 0 when the watcher was never started
     def uptime = started_at ? Time.now - started_at : 0
 
+    # Snapshot of the watcher state, suited for health endpoints and logs.
+    #
+    # @return [Hash{Symbol => Object}] `:id`, `:name`, `:status`, `:interval`, `:cursor`, `:ticks`,
+    #   `:started_at`, `:last_tick_at`, `:last_error` (as `"Class: message"` or nil), `:last_error_at` and
+    #   `:thread` (the thread name, or nil while idle)
     def to_h
       {
         id: id, name: name, status: status, interval: interval, cursor: cursor, ticks: ticks,
@@ -184,6 +343,9 @@ module BlockGiven
       }
     end
 
+    # One-line description: id, name, status, cursor, tick count and the class of the last error if any.
+    #
+    # @return [String]
     def inspect
       error = last_error ? " last_error=#{last_error.class}" : ""
       "#<BlockGiven::Watcher #{id} #{name} #{status} cursor=#{cursor.inspect} ticks=#{ticks}#{error}>"

data/lib/block_given/receipt.rb

@@ -1,41 +1,101 @@
 # frozen_string_literal: true
 
 module BlockGiven
-  # Transaction receipt with symbolized, integer-decoded fields.
+  # A transaction receipt (`eth_getTransactionReceipt`) with snake_case symbol keys and Integer quantities.
+  #
+  # Hashes are `0x` hex Strings; addresses are `0x` hex Strings as returned by the node (not re-checksummed);
+  # every QUANTITY field (block number, gas, status...) is decoded to an Integer by {Normalizer}.
+  #
+  # @example
+  #   receipt = tx.wait
+  #   receipt.status       # => :success
+  #   receipt.block_number # => 12_345_678
+  #   receipt.fee          # => 21_000 * effective_gas_price, in wei
+  #   receipt[:logs_bloom] # any raw field, by snake_case key
   class Receipt
+    # @return [Hash{Symbol => Object}] every receipt field, with snake_case symbol keys and Integer quantities
     attr_reader :to_h
 
+    # Wraps a raw receipt from the node.
+    #
+    # @param raw [Hash, Receipt] the JSON-RPC receipt object (String or Symbol keys, hex quantities), or another
+    #   {Receipt} whose fields are reused as is
     def initialize(raw)
       @to_h = raw.is_a?(Receipt) ? raw.to_h : Normalizer.normalize(raw)
     end
 
+    # @return [String] the transaction hash as `0x` hex
     def transaction_hash = to_h[:transaction_hash]
+
+    # @return [Integer, nil] the number of the block the transaction was included in
     def block_number = to_h[:block_number]
+
+    # @return [String, nil] the hash of the including block as `0x` hex
     def block_hash = to_h[:block_hash]
+
+    # @return [String] the sender address as `0x` hex, as returned by the node
     def from = to_h[:from]
+
+    # @return [String, nil] the recipient address as `0x` hex, or nil for a contract creation
     def to = to_h[:to]
+
+    # @return [String, nil] the address of the created contract as `0x` hex, nil unless the transaction was a
+    #   contract creation
     def contract_address = to_h[:contract_address]
+
+    # @return [Integer, nil] gas consumed by this transaction alone
     def gas_used = to_h[:gas_used]
+
+    # @return [Integer, nil] the gas price actually paid, in wei per gas (base fee + priority fee for EIP-1559)
     def effective_gas_price = to_h[:effective_gas_price]
+
+    # @return [Integer, nil] gas consumed by the block up to and including this transaction
     def cumulative_gas_used = to_h[:cumulative_gas_used]
+
+    # @return [Integer, nil] the position of the transaction in its block
     def transaction_index = to_h[:transaction_index]
+
+    # Raw logs emitted by the transaction, in emission order. Decode them with a contract's `events_from`.
+    #
+    # @return [Array<Hash{Symbol => Object}>] normalized log objects (`:address`, `:topics`, `:data`,
+    #   `:block_number`, `:log_index`, `:removed`...); an empty Array when the receipt has none
     def logs = to_h[:logs] || []
 
-    # :success / :reverted (pre-Byzantium receipts have no status: treated as success).
+    # Outcome of the transaction.
+    #
+    # `:success` when the receipt status is 1, `:reverted` otherwise. Pre-Byzantium receipts have no status
+    # field: they are treated as `:success`.
+    #
+    # @return [Symbol] `:success` or `:reverted`
+    # @example
+    #   receipt.status # => :reverted
+    #   receipt.reverted? # => true
     def status
       return :success if to_h[:status].nil?
 
       to_h[:status] == 1 ? :success : :reverted
     end
 
+    # @return [Boolean] true when {#status} is `:success`
     def success? = status == :success
+
+    # @return [Boolean] true when {#status} is `:reverted`
     def reverted? = status == :reverted
 
-    # Total fee paid in wei.
+    # Total fee paid for the transaction: `gas_used * effective_gas_price`.
+    #
+    # @return [Integer, nil] the fee in wei, or nil when the node did not return both fields
     def fee = gas_used && effective_gas_price ? gas_used * effective_gas_price : nil
 
+    # Reads any receipt field by name, including chain-specific ones (e.g. `:l1_fee` on OP-stack chains).
+    #
+    # @param key [Symbol, String] the snake_case field name (Strings are symbolized as is)
+    # @return [Object, nil] the field value, or nil when absent
     def [](key) = to_h[key.to_sym]
 
+    # Debug representation with the hash, status, block, gas used and log count.
+    #
+    # @return [String] e.g. `#<BlockGiven::Receipt 0x... status=success block=123 gas_used=21000 logs=0>`
     def inspect
       "#<BlockGiven::Receipt #{transaction_hash} status=#{status} block=#{block_number} " \
         "gas_used=#{gas_used} logs=#{logs.size}>"

data/lib/block_given/rlp.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # Recursive Length Prefix serialization, the encoding of Ethereum transactions.
+  #
+  # Items are binary Strings, non-negative Integers (encoded big-endian without leading zeros, 0 being the
+  # empty string) and Arrays of items. Decoding returns binary Strings and Arrays only: the caller knows which
+  # fields are integers ({.to_int}).
+  #
+  # @api private
+  module Rlp
+    module_function
+
+    # Serializes an item.
+    #
+    # @param item [String, Integer, Array] a binary String, a non-negative Integer or a (nested) Array of them
+    # @return [String] the RLP bytes, binary
+    # @raise [BlockGiven::InvalidArgumentError] for a negative Integer or an unsupported type
+    def encode(item)
+      case item
+      when Array
+        payload = item.map { |element| encode(element) }.join.b
+        length_prefix(payload.bytesize, 0xc0) + payload
+      when Integer
+        raise InvalidArgumentError, "RLP cannot encode negative integer #{item}" if item.negative?
+
+        encode(int_to_bytes(item))
+      when String
+        bytes = item.b
+        return bytes if bytes.bytesize == 1 && bytes.getbyte(0) < 0x80
+
+        length_prefix(bytes.bytesize, 0x80) + bytes
+      else raise InvalidArgumentError, "RLP cannot encode #{item.class}"
+      end
+    end
+
+    # Deserializes exactly one item spanning the whole input.
+    #
+    # @param bytes [String] RLP bytes, binary
+    # @return [String, Array] binary Strings and nested Arrays
+    # @raise [BlockGiven::InvalidArgumentError] when the input is truncated, has trailing bytes or is not in
+    #   canonical form
+    def decode(bytes)
+      bytes = bytes.b
+      item, consumed = decode_at(bytes, 0)
+      raise InvalidArgumentError, "RLP: #{bytes.bytesize - consumed} trailing byte(s)" if consumed != bytes.bytesize
+
+      item
+    end
+
+    # Reads a decoded String field as an unsigned big-endian Integer.
+    #
+    # @param bytes [String] binary String
+    # @return [Integer] 0 for the empty String
+    # @raise [BlockGiven::InvalidArgumentError] when the value is a list or has leading zero bytes
+    def to_int(bytes)
+      raise InvalidArgumentError, "RLP: expected an integer, got a list" unless bytes.is_a?(String)
+      raise InvalidArgumentError, "RLP: integer with leading zero" if bytes.start_with?("\x00".b)
+
+      bytes.empty? ? 0 : bytes.unpack1("H*").to_i(16)
+    end
+
+    # Big-endian bytes of a non-negative Integer, without leading zeros.
+    #
+    # @param int [Integer]
+    # @return [String] binary, empty for 0
+    def int_to_bytes(int)
+      return "".b if int.zero?
+
+      hex = int.to_s(16)
+      [hex.length.odd? ? "0#{hex}" : hex].pack("H*")
+    end
+
+    # Prefix announcing a payload length.
+    #
+    # @param length [Integer] payload size in bytes
+    # @param offset [Integer] 0x80 for a String, 0xc0 for a list
+    # @return [String] binary prefix
+    def length_prefix(length, offset)
+      return (offset + length).chr.b if length < 56
+
+      length_bytes = int_to_bytes(length)
+      (offset + 55 + length_bytes.bytesize).chr.b + length_bytes
+    end
+
+    # Decodes the item starting at a position.
+    #
+    # @param bytes [String] the whole input, binary
+    # @param position [Integer] where the item starts
+    # @return [Array(Object, Integer)] the item and the position right after it
+    # @raise [BlockGiven::InvalidArgumentError] for truncated or non-canonical input
+    def decode_at(bytes, position)
+      prefix = bytes.getbyte(position)
+      raise InvalidArgumentError, "RLP: unexpected end of input" if prefix.nil?
+      return [bytes.byteslice(position, 1), position + 1] if prefix < 0x80
+
+      list = prefix >= 0xc0
+      start, length = payload_bounds(bytes, position, prefix - (list ? 0xc0 : 0x80))
+      raise InvalidArgumentError, "RLP: unexpected end of input" if start + length > bytes.bytesize
+      return [decode_list(bytes, start, start + length), start + length] if list
+
+      payload = bytes.byteslice(start, length)
+      raise InvalidArgumentError, "RLP: non-canonical single byte" if length == 1 && payload.getbyte(0) < 0x80
+
+      [payload, start + length]
+    end
+
+    # Start and length of the payload following a prefix.
+    #
+    # @param bytes [String] the whole input, binary
+    # @param position [Integer] position of the prefix byte
+    # @param short [Integer] prefix minus its type offset (0x80 or 0xc0)
+    # @return [Array(Integer, Integer)] payload start and length
+    # @raise [BlockGiven::InvalidArgumentError] for a truncated or non-canonical length
+    def payload_bounds(bytes, position, short)
+      return [position + 1, short] if short < 56
+
+      size = short - 55
+      length_bytes = bytes.byteslice(position + 1, size).to_s
+      raise InvalidArgumentError, "RLP: unexpected end of input" if length_bytes.bytesize != size
+
+      length = to_int(length_bytes)
+      raise InvalidArgumentError, "RLP: non-canonical length" if length < 56
+
+      [position + 1 + size, length]
+    end
+
+    # Decodes the items of a list payload.
+    #
+    # @param bytes [String] the whole input, binary
+    # @param position [Integer] start of the list payload
+    # @param stop [Integer] end of the list payload
+    # @return [Array] the decoded items
+    # @raise [BlockGiven::InvalidArgumentError] when an item overflows the list
+    def decode_list(bytes, position, stop)
+      items = []
+      while position < stop
+        item, position = decode_at(bytes, position)
+        items << item
+      end
+      raise InvalidArgumentError, "RLP: list item overflows its list" if position != stop
+
+      items
+    end
+  end
+end