block_given 0.1.0 → 0.2.0

data/lib/block_given/errors.rb

@@ -1,24 +1,62 @@
 # frozen_string_literal: true
 
 module BlockGiven
-  # Base class for every error raised by BlockGiven.
+  # Base class for every error raised by BlockGiven; rescue it to catch anything coming out of the gem.
   class Error < StandardError; end
 
+  # Raised when the global configuration is missing or invalid: no connector, no chain, no RPC URL, a chain
+  # unknown to {Chains.resolve}, or a chain Alchemy does not serve.
   class ConfigurationError < Error; end
+
+  # Raised when a method receives a value it cannot use: malformed hex or decimal, unknown block tag,
+  # unexpected keyword on a contract method, duplicate or unknown watcher id.
   class InvalidArgumentError < Error; end
+
+  # Raised when a value is not a 20-byte `0x` hex address (see {Utils.checksum_address}).
   class InvalidAddressError < InvalidArgumentError; end
+
+  # Raised when a contract write (or its preparation) is attempted on a contract without a wallet.
   class WalletRequiredError < Error; end
+
+  # Raised when a blocking poll, such as waiting for a transaction receipt, exceeds its timeout.
   class TimeoutError < Error; end
 
+  # Base class for ABI problems: missing or unreadable ABI file, unknown function or event.
   class AbiError < Error; end
+
+  # Raised when a value cannot be ABI-encoded for its type: out-of-bounds integer, `bytesN` value longer than
+  # N bytes, wrong array length, malformed address.
+  class AbiEncodingError < AbiError; end
+
+  # Raised when data cannot be ABI-decoded for the expected types: too short, or an offset or length pointing
+  # outside of it.
+  class AbiDecodingError < AbiError; end
+
+  # Raised when an ABI has no function matching the requested name, signature or argument list.
   class FunctionNotFoundError < AbiError; end
+
+  # Raised when an ABI has no event with the requested name.
   class EventNotFoundError < AbiError; end
+
+  # Raised when a function name is overloaded and several overloads accept the given arguments; call it with the
+  # full signature instead.
   class AmbiguousFunctionError < AbiError; end
 
-  # Transport-level failure (non-2xx HTTP status, connection refused, ...).
+  # Transport-level failure: non-2xx HTTP status, connection refused, invalid JSON body or exhausted retries.
+  #
+  # Endpoints in the message are redacted so API keys never leak into logs.
+  #
+  # @!attribute [r] status
+  #   @return [Integer, nil] HTTP status code when the server answered, nil for connection failures
+  # @!attribute [r] body
+  #   @return [String, nil] raw response body when one was received (truncated in the message, complete here)
   class HttpError < Error
     attr_reader :status, :body
 
+    # @param message [String] human readable description
+    # @param status [Integer, nil] HTTP status code
+    # @param body [String, nil] raw response body
+    # @return [HttpError]
     def initialize(message, status: nil, body: nil)
       super(message)
       @status = status
@@ -26,10 +64,25 @@ module BlockGiven
     end
   end
 
-  # JSON-RPC error object returned by the node.
+  # JSON-RPC error object (`{ code, message, data }`) returned by the node for a request that reached it.
+  #
+  # Reverts are surfaced as the {ContractRevertError} subclass by {.from_payload}, which connectors use to turn
+  # payloads into exceptions.
+  #
+  # @!attribute [r] code
+  #   @return [Integer, nil] JSON-RPC error code (`-32000` for generic node errors, `3` for execution reverted)
+  # @!attribute [r] data
+  #   @return [String, Hash, nil] raw `error.data` field, untouched, as the provider returned it
+  # @!attribute [r] rpc_method
+  #   @return [String, nil] JSON-RPC method whose call failed (`"eth_call"`, `"eth_sendRawTransaction"`)
   class RpcError < Error
     attr_reader :code, :data, :rpc_method
 
+    # @param message [String] `error.message` from the payload
+    # @param code [Integer, nil] `error.code`
+    # @param data [String, Hash, nil] `error.data`
+    # @param rpc_method [String, nil] JSON-RPC method that was called
+    # @return [RpcError]
     def initialize(message, code: nil, data: nil, rpc_method: nil)
       super(message)
       @code = code
@@ -37,8 +90,18 @@ module BlockGiven
       @rpc_method = rpc_method
     end
 
-    # Builds the most specific error for a JSON-RPC error payload. Reverts carry
-    # ABI-encoded data that we surface as a ContractRevertError.
+    # Build the most specific error for a JSON-RPC error payload.
+    #
+    # Payloads carrying `0x` revert bytes in `data` (or nested under `data.data`), or whose message mentions
+    # "revert", become a {ContractRevertError} with the revert bytes attached; anything else becomes a plain
+    # {RpcError}. A payload that is not a Hash is wrapped with its string form as message.
+    #
+    # @param error [Hash, Object] JSON-RPC `error` object with String keys `"code"`, `"message"` and `"data"`
+    # @param rpc_method [String, nil] method that was called, kept on the error for context
+    # @return [BlockGiven::RpcError, BlockGiven::ContractRevertError]
+    # @example
+    #   BlockGiven::RpcError.from_payload({ "code" => 3, "message" => "execution reverted", "data" => "0x08c3..." })
+    #   # => #<BlockGiven::ContractRevertError: execution reverted: insufficient balance>
     def self.from_payload(error, rpc_method: nil)
       error = { "message" => error.to_s } unless error.is_a?(Hash)
       code = error["code"]
@@ -53,8 +116,14 @@ module BlockGiven
       end
     end
 
-    # Providers disagree on where the revert bytes live: Alchemy/geth put them in
-    # `data`, Hardhat/Anvil nest them under `data.data`.
+    # Extract the `0x` revert bytes from an error `data` field.
+    #
+    # Providers disagree on where the revert bytes live: Alchemy/geth put them in `data`, Hardhat/Anvil nest
+    # them under `data.data`.
+    #
+    # @api private
+    # @param data [String, Hash, nil] raw `error.data`
+    # @return [String, nil] `0x` hex string, or nil when no revert bytes are present
     def self.extract_revert_data(data)
       case data
       when String then data.start_with?("0x") ? data : nil
@@ -63,10 +132,27 @@ module BlockGiven
     end
   end
 
-  # eth_call / eth_estimateGas / eth_sendRawTransaction rejected by the EVM.
+  # `eth_call`, `eth_estimateGas` or `eth_sendRawTransaction` rejected by the EVM with a revert.
+  #
+  # The message is rewritten to `"execution reverted: <reason>"` when the revert data is a Solidity
+  # `Error(string)` or `Panic(uint256)`. Custom errors (`error InsufficientBalance(uint256)`) are decoded on
+  # demand with {#decode_with} against a contract ABI; {Contract} and {SignedTransaction} do this automatically
+  # before re-raising.
+  #
+  # @!attribute [r] revert_data
+  #   @return [String, nil] ABI-encoded revert bytes as a `0x` hex string (4-byte selector followed by the
+  #     encoded arguments), nil when the node returned none
+  # @!attribute [r] error_name
+  #   @return [String, nil] name of the custom error, set once decoded with {#decode_with}
+  # @!attribute [r] args
+  #   @return [Hash{Symbol => Object}, nil] custom error arguments keyed by snake_case name, set once decoded
+  #     with {#decode_with}
   class ContractRevertError < RpcError
+    # 4-byte selector of Solidity's built-in `Error(string)`, the revert with a reason string.
     ERROR_STRING_SELECTOR = "0x08c379a0"
+    # 4-byte selector of Solidity's built-in `Panic(uint256)` (assertion failures, overflows, ...).
     PANIC_SELECTOR = "0x4e487b71"
+    # Human readable description of each Solidity panic code carried by `Panic(uint256)`.
     PANIC_REASONS = {
       0x00 => "generic compiler inserted panic",
       0x01 => "assertion failed",
@@ -82,6 +168,15 @@ module BlockGiven
 
     attr_reader :revert_data, :error_name, :args
 
+    # @param message [String] message from the RPC error payload; replaced by the decoded built-in reason when
+    #   one is found and the original does not already contain it, or by `"execution reverted"` when empty
+    # @param code [Integer, nil] JSON-RPC error code
+    # @param data [String, Hash, nil] raw `error.data`
+    # @param rpc_method [String, nil] JSON-RPC method that was called
+    # @param revert_data [String, nil] `0x` revert bytes
+    # @param error_name [String, nil] decoded custom error name (set by {#decode_with})
+    # @param args [Hash{Symbol => Object}, nil] decoded custom error arguments (set by {#decode_with})
+    # @return [ContractRevertError]
     def initialize(message, code: nil, data: nil, rpc_method: nil, revert_data: nil, error_name: nil, args: nil)
       @revert_data = revert_data
       @error_name = error_name
@@ -89,23 +184,43 @@ module BlockGiven
       super(build_message(message), code: code, data: data, rpc_method: rpc_method)
     end
 
-    # Human readable revert reason when it can be decoded (Error(string) / Panic).
+    # Human readable revert reason when the revert data is a built-in `Error(string)` or `Panic(uint256)`.
+    #
+    # Memoised. Custom errors and undecodable data yield nil; use {#decode_with} for custom errors.
+    #
+    # @return [String, nil] the `Error(string)` text, or `"Panic(0x11): arithmetic overflow or underflow"`
     def reason
       return @reason if defined?(@reason)
 
       @reason = decode_builtin_reason
     end
 
+    # 4-byte selector at the start of the revert data.
+    #
+    # @return [String, nil] `0x` followed by 8 hex chars, nil without revert data
     def selector
       revert_data && revert_data.length >= 10 ? revert_data[0, 10] : nil
     end
 
+    # Whether the revert data is a custom error, i.e. its selector is neither `Error(string)` nor `Panic`.
+    #
+    # @return [Boolean]
     def custom_error?
       !selector.nil? && ![ERROR_STRING_SELECTOR, PANIC_SELECTOR].include?(selector)
     end
 
-    # Returns a copy of this error enriched with a custom error decoded from the
-    # given ABI interface, or self when the interface does not know the selector.
+    # Return a copy of this error enriched with a custom error decoded from an ABI interface.
+    #
+    # @param interface [BlockGiven::Abi::Interface, nil] interface whose custom errors are matched by selector
+    # @return [BlockGiven::ContractRevertError] a new error whose message is `Name(arg1, arg2)` with
+    #   {#error_name} and {#args} set; `self` when the data is not a custom error, no interface is given or the
+    #   interface does not know the selector
+    # @example
+    #   begin
+    #     token.transfer(to, amount)
+    #   rescue BlockGiven::ContractRevertError => e
+    #     e.decode_with(token.interface).error_name # => "ERC20InsufficientBalance"
+    #   end
     def decode_with(interface)
       return self unless custom_error? && interface
 
@@ -135,9 +250,9 @@ module BlockGiven
       payload = "0x#{revert_data[10..]}"
       case selector
       when ERROR_STRING_SELECTOR
-        Eth::Abi.decode(["string"], payload).first
+        Abi::Codec.decode(["string"], Utils.hex_to_bin(payload)).first
       when PANIC_SELECTOR
-        panic_code = Eth::Abi.decode(["uint256"], payload).first
+        panic_code = Abi::Codec.decode(["uint256"], Utils.hex_to_bin(payload)).first
         "Panic(0x#{panic_code.to_s(16).rjust(2, '0')}): #{PANIC_REASONS.fetch(panic_code, 'unknown panic')}"
       end
     rescue StandardError
@@ -145,10 +260,15 @@ module BlockGiven
     end
   end
 
-  # Raised by Transaction#wait! when the mined receipt has a failed status.
+  # Raised by {Transaction#wait!} when the mined receipt has a failed status (`status == 0`).
+  #
+  # @!attribute [r] receipt
+  #   @return [BlockGiven::Receipt] the mined receipt carrying the failed status
   class TransactionRevertedError < Error
     attr_reader :receipt
 
+    # @param receipt [BlockGiven::Receipt] receipt whose `transaction_hash` and `block_number` build the message
+    # @return [TransactionRevertedError]
     def initialize(receipt)
       @receipt = receipt
       super("transaction #{receipt.transaction_hash} reverted in block #{receipt.block_number}")

data/lib/block_given/event.rb

@@ -1,15 +1,39 @@
 # frozen_string_literal: true
 
 module BlockGiven
-  # A decoded event log.
+  # A log decoded against an ABI event definition (see `Abi::Event#decode`).
   #
+  # {#args} holds the decoded parameters keyed by their snake_case name, in ABI declaration order (indexed and
+  # non-indexed inputs interleaved as declared). Indexed parameters of dynamic type (`string`, `bytes`,
+  # arrays, tuples) cannot be recovered from a log: their value is the keccak-256 topic hash as `0x` hex.
+  # {#log} keeps the raw normalized log the event was decoded from.
+  #
+  # @example
   #   event.name           # => "Transfer"
   #   event.args           # => { from: "0x...", to: "0x...", value: 1000000 }
   #   event[:value]        # => 1000000
+  #   event["value"]       # => 1000000 (String keys are snake_cased and symbolized)
   #   event.block_number   # => 12345
   class Event
+    # @!attribute [r] name
+    #   @return [String] the event name as declared in the ABI, e.g. `"Transfer"`
+    # @!attribute [r] signature
+    #   @return [String] the canonical signature, e.g. `"Transfer(address,address,uint256)"`
+    # @!attribute [r] args
+    #   @return [Hash{Symbol => Object}] decoded parameters keyed by snake_case name, in ABI declaration order;
+    #     addresses checksummed, integers as Integer, static bytes as `0x` hex, indexed dynamic types as their
+    #     topic hash
+    # @!attribute [r] log
+    #   @return [Hash{Symbol => Object}] the raw normalized log (`:address`, `:topics`, `:data`, `:block_number`,
+    #     `:transaction_hash`, `:log_index`, `:removed`...)
     attr_reader :name, :signature, :args, :log
 
+    # Builds a decoded event. Instances are normally created by `Abi::Event#decode` rather than directly.
+    #
+    # @param name [String] the event name
+    # @param signature [String] the canonical event signature
+    # @param args [Hash{Symbol => Object}] the decoded parameters, keyed by snake_case Symbol
+    # @param log [Hash{Symbol => Object}] the normalized log the event was decoded from
     def initialize(name:, signature:, args:, log:)
       @name = name
       @signature = signature
@@ -17,20 +41,46 @@ module BlockGiven
       @log = log
     end
 
+    # Reads a decoded parameter by name.
+    #
+    # @param key [Symbol, String] the parameter name, in camelCase or snake_case (`:tokenId`, `"token_id"`...)
+    # @return [Object, nil] the decoded value, or nil when the event has no such parameter
     def [](key) = args[Utils.snake_case(key).to_sym]
+
+    # @return [String, nil] the EIP-55 checksummed address of the contract that emitted the log, or nil when
+    #   the log carries no address
     def address = log[:address] && Utils.checksum_address(log[:address])
+
+    # @return [Integer, nil] the number of the block containing the log (nil for a pending log)
     def block_number = log[:block_number]
+
+    # @return [String, nil] the hash of the containing block as `0x` hex
     def block_hash = log[:block_hash]
+
+    # @return [String, nil] the hash of the emitting transaction as `0x` hex
     def transaction_hash = log[:transaction_hash]
+
+    # @return [Integer, nil] the position of the emitting transaction in its block
     def transaction_index = log[:transaction_index]
+
+    # @return [Integer, nil] the position of the log in its block
     def log_index = log[:log_index]
+
+    # @return [Boolean] true when the node flagged the log as removed by a chain reorganisation
     def removed? = !!log[:removed]
 
+    # A compact Hash view, handy for persistence or logging.
+    #
+    # @return [Hash{Symbol => Object}] `:name`, `:args`, `:address` (checksummed), `:block_number`,
+    #   `:transaction_hash` and `:log_index`
     def to_h
       { name: name, args: args, address: address, block_number: block_number,
         transaction_hash: transaction_hash, log_index: log_index }
     end
 
+    # Debug representation with the name, decoded args and block number.
+    #
+    # @return [String] e.g. `#<BlockGiven::Event Transfer {:from=>"0x...", ...} block=123>`
     def inspect = "#<BlockGiven::Event #{name} #{args.inspect} block=#{block_number}>"
   end
 end

data/lib/block_given/normalizer.rb

@@ -1,11 +1,24 @@
 # frozen_string_literal: true
 
 module BlockGiven
-  # Converts raw JSON-RPC objects (blocks, transactions, receipts, logs) into
-  # Ruby-friendly hashes: snake_case symbol keys, QUANTITY fields as Integers.
+  # Convert raw JSON-RPC objects (blocks, transactions, receipts, logs) into Ruby-friendly hashes.
+  #
+  # Keys become snake_case symbols (`"blockNumber"` -> `:block_number`) and the fields listed in
+  # {QUANTITY_KEYS} are decoded from hex QUANTITY strings to Integers. Nested hashes and arrays are normalised
+  # recursively, except a log's `topics`, which stay an Array of `0x` hex strings. Addresses, hashes and `data`
+  # fields are left exactly as the node returned them. {Client} runs every block, transaction, receipt and log
+  # through this module before handing it back.
+  #
+  # @example
+  #   BlockGiven::Normalizer.normalize({ "blockNumber" => "0x10", "logIndex" => "0x0", "topics" => ["0xddf2"] })
+  #   # => { block_number: 16, log_index: 0, topics: ["0xddf2"] }
   module Normalizer
     module_function
 
+    # Snake_case keys whose values are JSON-RPC QUANTITY hex strings, decoded to Integers by {.normalize}.
+    #
+    # Covers block, transaction and receipt fields, EIP-4844 blob fields, and the L1 fee fields added by
+    # OP Stack chains (Base, Optimism).
     QUANTITY_KEYS = %i[
       number timestamp gas_used gas_limit base_fee_per_gas block_number transaction_index log_index
       cumulative_gas_used effective_gas_price status value gas gas_price max_fee_per_gas
@@ -14,6 +27,11 @@ module BlockGiven
       deposit_nonce deposit_receipt_version
     ].freeze
 
+    # Normalise a raw RPC value recursively.
+    #
+    # @param value [Hash, Array, Object] a Hash is rebuilt with snake_case Symbol keys and normalised values,
+    #   an Array is mapped element by element, anything else is returned untouched
+    # @return [Hash{Symbol => Object}, Array, Object]
     def normalize(value)
       case value
       when Hash then value.each_with_object({}) do |(k, v), h|
@@ -24,6 +42,13 @@ module BlockGiven
       end
     end
 
+    # Normalise one field of an RPC hash, given its already snake_cased key.
+    #
+    # @api private
+    # @param key [Symbol] snake_case key
+    # @param value [Object] raw value
+    # @return [Object] an Integer for a {QUANTITY_KEYS} key holding hex (nil when the node returned an empty
+    #   `"0x"`), the untouched Array for `:topics`, otherwise {.normalize} of the value
     def normalize_field(key, value)
       if QUANTITY_KEYS.include?(key) && Utils.hex?(value)
         value == "0x" ? nil : Utils.hex_to_int(value)