block_given 0.1.0 → 0.2.0

data/lib/block_given/abi/coder.rb

@@ -2,11 +2,44 @@
 
 module BlockGiven
   module Abi
-    # Turns Ruby values into what the ABI encoder expects, and decoded values
-    # into idiomatic Ruby (checksummed addresses, hex bytes, named tuples as Hash).
+    # Turns Ruby values into what the ABI encoder expects, and decoded values into idiomatic Ruby.
+    #
+    # ## Input coercion (Ruby to ABI), per Solidity type
+    #
+    # - `intN` / `uintN`: `Integer`; a whole `Float`, `BigDecimal` or `Rational` (`1e6` becomes
+    #   `1000000`); a decimal String (`"1000000"`) or a `0x` hex String. A fractional or non-finite number
+    #   raises `InvalidArgumentError` pointing at `BlockGiven::Utils.parse_units`.
+    # - `address`: a `0x` 40-hex-digit String, or any non-String object responding to `#address` (a
+    #   {BlockGiven::Wallet}, a {BlockGiven::Contract}). Malformed values raise `InvalidAddressError`.
+    # - `bool`: `true` or `false` only (no truthiness).
+    # - `string`: anything, converted with `#to_s`.
+    # - `bytes` / `bytesN`: a `0x` hex String, or a binary String which is hex-encoded.
+    # - tuples: a Hash keyed by component name (Symbol or String, snake_case or camelCase, matched after
+    #   `Utils.snake_case`) or an Array in declaration order; components are coerced recursively.
+    # - arrays: an Array whose elements are coerced recursively with the element type.
+    #
+    # ## Output formatting (ABI to Ruby)
+    #
+    # - `address`: EIP-55 checksummed String.
+    # - `bytes` / `bytesN`: `0x` hex String.
+    # - `string`: UTF-8 String.
+    # - integers and booleans: unchanged (`Integer`, `true` / `false`).
+    # - tuples: a Hash with snake_case Symbol keys when every component is named, an Array otherwise.
+    # - arrays: an Array of formatted elements.
+    #
+    # {Function#decode_output} additionally unwraps a single output and returns several as an Array.
     module Coder
       module_function
 
+      # ABI-encodes values for the given parameters after coercing them (see the module documentation).
+      #
+      # @param params [Array<Parameter>] the parameter types, in order
+      # @param values [Array] one Ruby value per parameter
+      # @return [String] `0x`-prefixed encoded data (no selector)
+      # @raise [BlockGiven::InvalidArgumentError] when the count differs or a value cannot be coerced
+      # @raise [BlockGiven::InvalidAddressError] when an address value is malformed
+      # @raise [BlockGiven::AbiEncodingError] when the encoder rejects a coerced value (out of bounds, ...)
+      # @raise [BlockGiven::AbiError] when a type is not supported
       def encode(params, values)
         if params.size != values.size
           raise InvalidArgumentError,
@@ -14,24 +47,42 @@ module BlockGiven
         end
 
         coerced = params.zip(values).map { |param, value| coerce(value, param) }
-        Utils.bin_to_hex(Eth::Abi.encode(params.map(&:type), coerced))
-      rescue Eth::Abi::EncodingError, Eth::Abi::ValueOutOfBounds => e
-        raise AbiError, "ABI encoding failed: #{e.message}"
+        Utils.bin_to_hex(Codec.encode(params.map(&:type), coerced))
+      rescue AbiEncodingError => e
+        raise AbiEncodingError, "ABI encoding failed: #{e.message}"
       end
 
+      # ABI-decodes data for the given parameters and formats the values (see the module documentation).
+      #
+      # @param params [Array<Parameter>] the parameter types, in order
+      # @param hex [String] `0x`-prefixed encoded data
+      # @return [Array] one formatted Ruby value per parameter (empty when `params` is empty, whatever
+      #   the data)
+      # @raise [BlockGiven::AbiError] when the data is empty (typically no contract at the address)
+      # @raise [BlockGiven::AbiDecodingError] when the data is not hex or too short for the types
       def decode(params, hex)
         return [] if params.empty?
 
         data = Utils.strip_hex(hex.to_s)
         raise AbiError, "cannot decode empty data (does the contract exist at this address?)" if data.empty?
+        raise AbiDecodingError, "data is not hex" unless data.match?(/\A(\h\h)+\z/)
 
-        values = Eth::Abi.decode(params.map(&:type), "0x#{data}")
+        values = Codec.decode(params.map(&:type), Utils.hex_to_bin(data))
         params.zip(values).map { |param, value| format(value, param) }
-      rescue Eth::Abi::DecodingError => e
-        raise AbiError, "ABI decoding failed: #{e.message}"
+      rescue AbiDecodingError => e
+        raise AbiDecodingError, "ABI decoding failed: #{e.message}"
       end
 
-      # Ruby -> encoder input.
+      # Coerces one Ruby value into the encoder input for a parameter (recursing into arrays and tuples).
+      #
+      # Types without a dedicated rule (`fixed`, `function`...) are passed through unchanged.
+      #
+      # @api private
+      # @param value [Object] the Ruby value
+      # @param param [Parameter] the target parameter
+      # @return [Object] the encoder-ready value
+      # @raise [BlockGiven::InvalidArgumentError] when the value does not fit the type
+      # @raise [BlockGiven::InvalidAddressError] when an address is malformed
       def coerce(value, param)
         if param.array?
           raise InvalidArgumentError, "#{param.name} expects an Array, got #{value.inspect}" unless value.is_a?(Array)
@@ -50,19 +101,34 @@ module BlockGiven
         end
       end
 
-      # Decoded value -> Ruby.
+      # Formats one decoded value into idiomatic Ruby for a parameter (recursing into arrays and tuples).
+      #
+      # @api private
+      # @param value [Object] the value returned by {Codec.decode}
+      # @param param [Parameter] the decoded parameter
+      # @return [Object] checksummed address, `0x` hex bytes, UTF-8 string, Hash or Array for tuples, or
+      #   the value unchanged
       def format(value, param)
         return value.map { |v| format(v, param.element) } if param.array?
         return format_tuple(value, param) if param.tuple?
 
         case param.raw_type
         when "address" then Utils.checksum_address(value)
-        when /\Abytes\d*\z/ then value.is_a?(String) && !Utils.hex?(value) ? Utils.bin_to_hex(value) : value
+        when /\Abytes\d*\z/ then Utils.bin_to_hex(value)
         when "string" then value.to_s.dup.force_encoding(Encoding::UTF_8)
         else value
         end
       end
 
+      # Coerces a value for an `intN` / `uintN` parameter.
+      #
+      # @api private
+      # @param value [Integer, Float, BigDecimal, Rational, String] an Integer, a whole number, a decimal
+      #   String or a `0x` hex String
+      # @param param [Parameter]
+      # @return [Integer]
+      # @raise [BlockGiven::InvalidArgumentError] for fractional or non-finite numbers (use
+      #   `Utils.parse_units`), unparsable Strings or any other type
       def coerce_integer(value, param)
         case value
         when Integer then value
@@ -80,6 +146,13 @@ module BlockGiven
         raise InvalidArgumentError, "#{param.name} expects an integer, got #{value.inspect}"
       end
 
+      # Coerces a value for an `address` parameter.
+      #
+      # @api private
+      # @param value [String, #address] a `0x` hex address or a non-String object responding to `#address`
+      # @param param [Parameter]
+      # @return [String] the address as given (not checksummed)
+      # @raise [BlockGiven::InvalidAddressError] when the resulting value is not a 20-byte hex address
       def coerce_address(value, param)
         value = value.address if value.respond_to?(:address) && !value.is_a?(String)
         raise InvalidAddressError, "#{param.name}: invalid address #{value.inspect}" unless Utils.address?(value)
@@ -87,18 +160,41 @@ module BlockGiven
         value
       end
 
+      # Coerces a value for a `bool` parameter; only `true` and `false` are accepted.
+      #
+      # @api private
+      # @param value [Boolean]
+      # @param param [Parameter]
+      # @return [Boolean]
+      # @raise [BlockGiven::InvalidArgumentError] for anything else (no truthiness)
       def coerce_bool(value, param)
         return value if [true, false].include?(value)
 
         raise InvalidArgumentError, "#{param.name} expects true/false, got #{value.inspect}"
       end
 
+      # Coerces a value for a `bytes` / `bytesN` parameter.
+      #
+      # @api private
+      # @param value [String] a `0x` hex String (kept) or a binary String (hex-encoded)
+      # @param param [Parameter]
+      # @return [String] `0x` hex
+      # @raise [BlockGiven::InvalidArgumentError] when the value is not a String
       def coerce_bytes(value, param)
         raise InvalidArgumentError, "#{param.name} expects a hex or binary String" unless value.is_a?(String)
 
         Utils.hex?(value) ? value : Utils.bin_to_hex(value)
       end
 
+      # Coerces a value for a tuple parameter into an Array of coerced components.
+      #
+      # @api private
+      # @param value [Hash, Array] components by name (see {.tuple_values_from_hash}) or in declaration
+      #   order
+      # @param param [Parameter] a tuple parameter
+      # @return [Array] coerced component values, in declaration order
+      # @raise [BlockGiven::InvalidArgumentError] when the value is neither a Hash nor an Array, when the
+      #   number of values differs from the number of components, or when a field is missing
       def coerce_tuple(value, param)
         values =
           case value
@@ -113,6 +209,14 @@ module BlockGiven
         param.components.zip(values).map { |component, v| coerce(v, component) }
       end
 
+      # Orders the values of a tuple Hash by component; keys match component names after `Utils.snake_case`
+      # (Symbol or String, snake_case or camelCase). Extra keys are ignored.
+      #
+      # @api private
+      # @param hash [Hash] component values by name
+      # @param param [Parameter] a tuple parameter
+      # @return [Array] values in component declaration order
+      # @raise [BlockGiven::InvalidArgumentError] when a component has no matching key
       def tuple_values_from_hash(hash, param)
         lookup = hash.transform_keys { |k| Utils.snake_case(k) }
         param.components.map do |component|
@@ -123,6 +227,13 @@ module BlockGiven
         end
       end
 
+      # Formats a decoded tuple: a Hash with snake_case Symbol keys when every component is named, an
+      # Array otherwise.
+      #
+      # @api private
+      # @param values [Array] decoded component values
+      # @param param [Parameter] a tuple parameter
+      # @return [Hash{Symbol => Object}, Array]
       def format_tuple(values, param)
         formatted = param.components.zip(values).map { |component, v| format(v, component) }
         return formatted if param.components.any?(&:unnamed?)

data/lib/block_given/abi/custom_error.rb

@@ -3,19 +3,48 @@
 module BlockGiven
   module Abi
     # Solidity custom error (`error InsufficientBalance(uint256 available, uint256 required)`).
+    #
+    # Used by `BlockGiven::ContractRevertError#decode_with` to name a revert and decode its arguments.
+    #
+    # @example
+    #   error = interface.error_by_selector(revert_data[0, 10])
+    #   error.signature           # => "InsufficientBalance(uint256,uint256)"
+    #   error.decode(revert_data) # => { available: 5, required: 10 }
     class CustomError
+      # @!attribute [r] name
+      #   @return [String] the Solidity name (`"InsufficientBalance"`)
+      # @!attribute [r] inputs
+      #   @return [Array<Parameter>] the error arguments, in declaration order
       attr_reader :name, :inputs
 
+      # Builds a custom error from its ABI definition.
+      #
+      # @param definition [Hash] the ABI entry (`"name"`, `"inputs"`), String or Symbol keys
       def initialize(definition)
         definition = definition.transform_keys(&:to_s)
         @name = definition["name"].to_s
         @inputs = Array(definition["inputs"]).each_with_index.map { |i, idx| Parameter.new(i, index: idx) }
       end
 
+      # The canonical signature, with tuples expanded (`"InsufficientBalance(uint256,uint256)"`).
+      #
+      # @return [String]
       def signature = "#{name}(#{inputs.map(&:type).join(',')})"
+
+      # The 4-byte selector: first 4 bytes of `keccak256(signature)`, `0x`-prefixed lowercase (memoized).
+      #
+      # @return [String]
       def selector = @selector ||= Utils.keccak256(signature)[0, 10]
 
-      # Returns a Hash of decoded arguments keyed by snake_case names.
+      # Decodes the arguments of revert data produced by this error.
+      #
+      # The 4-byte selector at the start of the data is skipped, the remainder is decoded against
+      # {#inputs} with {Coder.decode}.
+      #
+      # @param revert_data [String] the full revert data (`0x` + selector + encoded arguments)
+      # @return [Hash{Symbol => Object}] decoded arguments keyed by snake_case name, in declaration order;
+      #   empty for an error without arguments
+      # @raise [BlockGiven::AbiError] when the data cannot be decoded against the inputs
       def decode(revert_data)
         payload = "0x#{Utils.strip_hex(revert_data)[8..]}"
         return {} if inputs.empty?
@@ -23,6 +52,9 @@ module BlockGiven
         inputs.map(&:ruby_name).zip(Coder.decode(inputs, payload)).to_h
       end
 
+      # Compact representation with the signature.
+      #
+      # @return [String]
       def inspect = "#<BlockGiven::Abi::CustomError #{signature}>"
     end
   end

data/lib/block_given/abi/event.rb

@@ -2,9 +2,25 @@
 
 module BlockGiven
   module Abi
+    # One ABI event: builds `eth_getLogs` topic filters and decodes logs into {BlockGiven::Event}s.
+    #
+    # @example
+    #   transfer = interface.event(:Transfer)
+    #   transfer.topic                                   # => "0xddf252ad..."
+    #   transfer.encode_topics(to: wallet.address)       # => ["0xddf252ad...", nil, "0x000...wallet"]
+    #   transfer.decode(log).args                        # => { from: "0x...", to: "0x...", value: 1000000 }
     class Event
+      # @!attribute [r] name
+      #   @return [String] the Solidity name (`"Transfer"`)
+      # @!attribute [r] inputs
+      #   @return [Array<Parameter>] the parameters, indexed and not, in declaration order
+      # @!attribute [r] anonymous
+      #   @return [Boolean] whether the event is declared `anonymous` (no signature topic)
       attr_reader :name, :inputs, :anonymous
 
+      # Builds an event from its ABI definition.
+      #
+      # @param definition [Hash] the ABI entry (`"name"`, `"inputs"`, `"anonymous"`), String or Symbol keys
       def initialize(definition)
         definition = definition.transform_keys(&:to_s)
         @name = definition["name"].to_s
@@ -12,20 +28,62 @@ module BlockGiven
         @anonymous = !!definition["anonymous"]
       end
 
+      # The snake_case Ruby name (`Transfer` becomes `:transfer`, `OwnershipTransferred` becomes
+      # `:ownership_transferred`).
+      #
+      # @return [Symbol]
       def ruby_name = Utils.snake_case(name).to_sym
+
+      # The canonical signature, with tuples expanded (`"Transfer(address,address,uint256)"`).
+      #
+      # @return [String]
       def signature = "#{name}(#{inputs.map(&:type).join(',')})"
+
+      # The `topics[0]` value of the event: `keccak256(signature)`, `0x`-prefixed lowercase (memoized).
+      #
+      # @return [String]
       def topic = @topic ||= Utils.keccak256(signature)
+
+      # Whether the event is anonymous (its logs carry no signature topic).
+      #
+      # @return [Boolean]
       def anonymous? = anonymous
 
+      # Parameters declared `indexed`, in declaration order (they live in `topics[1..]`).
+      #
+      # @return [Array<Parameter>]
       def indexed_inputs = inputs.select(&:indexed?)
+
+      # Parameters not declared `indexed`, in declaration order (they are ABI-encoded in `data`).
+      #
+      # @return [Array<Parameter>]
       def data_inputs = inputs.reject(&:indexed?)
 
+      # Whether a log was emitted by this (non-anonymous) event, based on its first topic.
+      #
+      # @param log [Hash] a log with a `:topics` or `"topics"` key
+      # @return [Boolean] always `false` for anonymous events
       def matches?(log)
         topic0 = Array(log[:topics] || log["topics"]).first
         !anonymous? && topic0&.downcase == topic
       end
 
-      # Decodes a normalized log (Hash with :topics and :data) into a BlockGiven::Event.
+      # Decodes a log into a {BlockGiven::Event}.
+      #
+      # Indexed parameters are read from the topics (after `topics[0]`, unless the event is anonymous)
+      # and non-indexed ones from `data`. Arguments are keyed by snake_case name in declaration order.
+      # Indexed parameters of dynamic type (`string`, `bytes`, arrays, dynamic tuples) cannot be
+      # recovered: their keccak hash topic is kept as the value. A missing topic yields `nil`.
+      #
+      # @param log [Hash] a log Hash with `:topics` / `"topics"` and `:data` / `"data"` keys (a normalized
+      #   log from {BlockGiven::Client} or a raw JSON-RPC log)
+      # @return [BlockGiven::Event] the decoded event, keeping the original log
+      # @raise [BlockGiven::AbiError] when `data` cannot be decoded against the non-indexed parameters
+      # @example
+      #   event = interface.event(:Transfer).decode(log)
+      #   event.args         # => { from: "0x...", to: "0x...", value: 1000000 }
+      #   event[:value]      # => 1000000
+      #   event.block_number # => 18000000
       def decode(log)
         topics = Array(log[:topics] || log["topics"])
         data = log[:data] || log["data"] || "0x"
@@ -45,8 +103,23 @@ module BlockGiven
         BlockGiven::Event.new(name: name, signature: signature, args: ordered, log: log)
       end
 
-      # Builds the topics filter array for eth_getLogs from indexed argument values.
-      # Values can be nil (wildcard), a single value or an Array (OR).
+      # Builds the `topics` filter of `eth_getLogs` from indexed argument values.
+      #
+      # The first topic is {#topic} (omitted for anonymous events), followed by one entry per indexed
+      # parameter: `nil` is a wildcard, a single value matches that value, an Array matches any of its
+      # values (OR). Trailing wildcards are trimmed. Values are coerced with {Coder.encode}; dynamic types
+      # (`string`, `bytes`, arrays, dynamic tuples) are hashed with keccak256 as the EVM does.
+      #
+      # @param filters [Hash{Symbol, String => Object, Array, nil}] values by indexed parameter name
+      #   (snake_case or camelCase)
+      # @return [Array<String, Array<String>, nil>] the topics filter
+      # @raise [BlockGiven::InvalidArgumentError] when a key is not an indexed parameter, or when a value
+      #   cannot be coerced
+      # @raise [BlockGiven::InvalidAddressError] when an address value is malformed
+      # @example
+      #   transfer.encode_topics(to: me)              # => [topic, nil, "0x000...me"]
+      #   transfer.encode_topics(from: [a, b])        # => [topic, ["0x000...a", "0x000...b"]]
+      #   transfer.encode_topics                      # => [topic]
       def encode_topics(filters = {})
         normalized = filters.transform_keys { |k| Utils.snake_case(k).to_sym }
         unknown = normalized.keys - indexed_inputs.map(&:ruby_name)
@@ -65,11 +138,19 @@ module BlockGiven
         anonymous? ? topics : [topic, *topics]
       end
 
+      # The canonical signature (same as {#signature}).
+      #
+      # @return [String]
       def to_s = signature
+
+      # Compact representation with the signature.
+      #
+      # @return [String]
       def inspect = "#<BlockGiven::Abi::Event #{signature}>"
 
       private
 
+      # Decodes one indexed topic; dynamic types keep the hash since the value itself is not in the log.
       def decode_topic(topic, param)
         return nil if topic.nil?
         return topic if param.dynamic? # only the keccak hash of the value is available
@@ -77,6 +158,7 @@ module BlockGiven
         Coder.decode([param], topic).first
       end
 
+      # Encodes one filter value as a 32-byte topic (keccak256 for dynamic types).
       def encode_topic(value, param)
         return Utils.keccak256(param.raw_type == "string" ? value.to_s : value) if param.dynamic?
 

data/lib/block_given/abi/function.rb

@@ -2,9 +2,33 @@
 
 module BlockGiven
   module Abi
+    # One ABI function: encodes calldata from Ruby arguments and decodes return data.
+    #
+    # @example
+    #   transfer = interface.function(:transfer)
+    #   transfer.signature                         # => "transfer(address,uint256)"
+    #   transfer.selector                          # => "0xa9059cbb"
+    #   transfer.encode([to, 1_000_000])           # => "0xa9059cbb000000..."
+    #   transfer.encode([], { to: to, value: 1e6 }) # keyword form, same result
+    #   transfer.decode_output("0x0000...0001")    # => true
     class Function
+      # @!attribute [r] name
+      #   @return [String] the Solidity name (`"balanceOf"`)
+      # @!attribute [r] inputs
+      #   @return [Array<Parameter>] the input parameters, in declaration order
+      # @!attribute [r] outputs
+      #   @return [Array<Parameter>] the output parameters, in declaration order
+      # @!attribute [r] state_mutability
+      #   @return [String] `"view"`, `"pure"`, `"nonpayable"` or `"payable"`
       attr_reader :name, :inputs, :outputs, :state_mutability
 
+      # Builds a function from its ABI definition.
+      #
+      # Pre-Solidity 0.5 ABIs without `stateMutability` are supported: `payable: true` maps to
+      # `"payable"`, `constant: true` to `"view"`, anything else to `"nonpayable"`.
+      #
+      # @param definition [Hash] the ABI entry (`"name"`, `"inputs"`, `"outputs"`, `"stateMutability"`),
+      #   String or Symbol keys
       def initialize(definition)
         definition = definition.transform_keys(&:to_s)
         @name = definition["name"].to_s
@@ -13,28 +37,88 @@ module BlockGiven
         @state_mutability = (definition["stateMutability"] || legacy_mutability(definition)).to_s
       end
 
+      # The snake_case Ruby method name (`balanceOf` becomes `:balance_of`).
+      #
+      # @return [Symbol]
       def ruby_name = Utils.snake_case(name).to_sym
+
+      # The canonical signature, with tuples expanded (`"transfer(address,uint256)"`).
+      #
+      # @return [String]
       def signature = "#{name}(#{inputs.map(&:type).join(',')})"
+
+      # The 4-byte selector: first 4 bytes of `keccak256(signature)`, `0x`-prefixed lowercase (memoized).
+      #
+      # @return [String]
       def selector = @selector ||= Utils.keccak256(signature)[0, 10]
 
+      # Whether the function is `view` or `pure`, i.e. served by `eth_call`.
+      #
+      # @return [Boolean]
       def read? = %w[view pure].include?(state_mutability)
+
+      # Whether the function needs a transaction (`nonpayable` or `payable`).
+      #
+      # @return [Boolean]
       def write? = !read?
+
+      # Whether the function accepts ether (`payable`).
+      #
+      # @return [Boolean]
       def payable? = state_mutability == "payable"
 
+      # The snake_case names of the inputs, in declaration order (unnamed inputs get `:argN`).
+      #
+      # @return [Array<Symbol>]
       def input_names = inputs.map(&:ruby_name)
 
-      # Positional args or keyword args (matched on snake_cased input names).
+      # ABI-encodes a call: selector followed by the encoded arguments.
+      #
+      # Arguments are given positionally or by keyword (matched on snake_cased input names, see
+      # {#resolve_args}) and coerced with {Coder.encode}.
+      #
+      # @param args [Array] positional arguments, in declaration order
+      # @param kwargs [Hash] keyword arguments by input name (any case); exclusive with `args`
+      # @return [String] `0x`-prefixed calldata
+      # @raise [BlockGiven::InvalidArgumentError] when positional and keyword arguments are mixed, when
+      #   keywords are used with unnamed inputs, on unknown or missing keywords, on a wrong argument count
+      #   or when a value cannot be coerced to its Solidity type
+      # @raise [BlockGiven::InvalidAddressError] when an address argument is malformed
+      # @raise [BlockGiven::AbiError] when the underlying ABI encoder rejects a value
+      # @example
+      #   transfer.encode([to, 1_000_000])
+      #   transfer.encode([], { to: to, value: 1_000_000 })
       def encode(args = [], kwargs = {})
         values = resolve_args(args, kwargs)
         selector + Utils.strip_hex(Coder.encode(inputs, values))
       end
 
-      # Single output -> value; several -> Array.
+      # Decodes return data into Ruby values (see {Coder.decode} for the formatting rules).
+      #
+      # @param hex [String] the `0x`-prefixed return data of `eth_call`
+      # @return [Object] the single output value when the function has one output
+      # @return [Array<Object>] one value per output otherwise (empty Array for no outputs)
+      # @raise [BlockGiven::AbiError] when the data is empty (no contract at the address, typically) or
+      #   cannot be decoded
+      # @example
+      #   balance_of.decode_output("0x00000000000000000000000000000000000000000000000000000000000f4240")
+      #   # => 1000000
       def decode_output(hex)
         values = Coder.decode(outputs, hex)
         outputs.size == 1 ? values.first : values
       end
 
+      # Turns positional or keyword arguments into the positional Array expected by the encoder.
+      #
+      # Keyword names are matched after `Utils.snake_case` (leading underscores stripped, camelCase
+      # converted), so `_to`, `to` and `To` all designate the same input.
+      #
+      # @api private
+      # @param args [Array] positional arguments
+      # @param kwargs [Hash] keyword arguments
+      # @return [Array] values in input declaration order
+      # @raise [BlockGiven::InvalidArgumentError] when both forms are mixed, when the ABI inputs are
+      #   unnamed, or on unknown / missing keywords
       def resolve_args(args, kwargs)
         raise InvalidArgumentError, "#{name}: mix of positional and keyword arguments" if !args.empty? && !kwargs.empty?
         return args if kwargs.empty?
@@ -56,11 +140,19 @@ module BlockGiven
         input_names.map { |n| normalized[n] }
       end
 
+      # The canonical signature (same as {#signature}).
+      #
+      # @return [String]
       def to_s = signature
+
+      # Compact representation with the signature and state mutability.
+      #
+      # @return [String]
       def inspect = "#<BlockGiven::Abi::Function #{signature} #{state_mutability}>"
 
       private
 
+      # State mutability for pre-0.5 ABIs that only carry `payable` / `constant` flags.
       def legacy_mutability(definition)
         return "payable" if definition["payable"]
         return "view" if definition["constant"]