block_given 0.1.0

data/lib/block_given/abi/custom_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    # Solidity custom error (`error InsufficientBalance(uint256 available, uint256 required)`).
+    class CustomError
+      attr_reader :name, :inputs
+
+      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
+
+      def signature = "#{name}(#{inputs.map(&:type).join(',')})"
+      def selector = @selector ||= Utils.keccak256(signature)[0, 10]
+
+      # Returns a Hash of decoded arguments keyed by snake_case names.
+      def decode(revert_data)
+        payload = "0x#{Utils.strip_hex(revert_data)[8..]}"
+        return {} if inputs.empty?
+
+        inputs.map(&:ruby_name).zip(Coder.decode(inputs, payload)).to_h
+      end
+
+      def inspect = "#<BlockGiven::Abi::CustomError #{signature}>"
+    end
+  end
+end

data/lib/block_given/abi/event.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    class Event
+      attr_reader :name, :inputs, :anonymous
+
+      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) }
+        @anonymous = !!definition["anonymous"]
+      end
+
+      def ruby_name = Utils.snake_case(name).to_sym
+      def signature = "#{name}(#{inputs.map(&:type).join(',')})"
+      def topic = @topic ||= Utils.keccak256(signature)
+      def anonymous? = anonymous
+
+      def indexed_inputs = inputs.select(&:indexed?)
+      def data_inputs = inputs.reject(&:indexed?)
+
+      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.
+      def decode(log)
+        topics = Array(log[:topics] || log["topics"])
+        data = log[:data] || log["data"] || "0x"
+        indexed_topics = anonymous? ? topics : topics[1..] || []
+
+        args = {}
+        indexed_inputs.each_with_index do |param, i|
+          args[param.ruby_name] = decode_topic(indexed_topics[i], param)
+        end
+        unless data_inputs.empty?
+          Coder.decode(data_inputs, data).each_with_index do |value, i|
+            args[data_inputs[i].ruby_name] = value
+          end
+        end
+        # keep declaration order
+        ordered = inputs.to_h { |p| [p.ruby_name, args[p.ruby_name]] }
+        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).
+      def encode_topics(filters = {})
+        normalized = filters.transform_keys { |k| Utils.snake_case(k).to_sym }
+        unknown = normalized.keys - indexed_inputs.map(&:ruby_name)
+        unless unknown.empty?
+          indexed = indexed_inputs.map(&:ruby_name).join(", ")
+          raise InvalidArgumentError, "#{name}: #{unknown.join(', ')} is not an indexed parameter (indexed: #{indexed})"
+        end
+
+        topics = indexed_inputs.map do |param|
+          value = normalized[param.ruby_name]
+          next nil if value.nil?
+
+          value.is_a?(Array) ? value.map { |v| encode_topic(v, param) } : encode_topic(value, param)
+        end
+        topics = topics.reverse.drop_while(&:nil?).reverse # trailing wildcards are implicit
+        anonymous? ? topics : [topic, *topics]
+      end
+
+      def to_s = signature
+      def inspect = "#<BlockGiven::Abi::Event #{signature}>"
+
+      private
+
+      def decode_topic(topic, param)
+        return nil if topic.nil?
+        return topic if param.dynamic? # only the keccak hash of the value is available
+
+        Coder.decode([param], topic).first
+      end
+
+      def encode_topic(value, param)
+        return Utils.keccak256(param.raw_type == "string" ? value.to_s : value) if param.dynamic?
+
+        Utils.prefix_hex(Utils.strip_hex(Coder.encode([param], [value])))
+      end
+    end
+  end
+end

data/lib/block_given/abi/function.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    class Function
+      attr_reader :name, :inputs, :outputs, :state_mutability
+
+      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) }
+        @outputs = Array(definition["outputs"]).each_with_index.map { |o, idx| Parameter.new(o, index: idx) }
+        @state_mutability = (definition["stateMutability"] || legacy_mutability(definition)).to_s
+      end
+
+      def ruby_name = Utils.snake_case(name).to_sym
+      def signature = "#{name}(#{inputs.map(&:type).join(',')})"
+      def selector = @selector ||= Utils.keccak256(signature)[0, 10]
+
+      def read? = %w[view pure].include?(state_mutability)
+      def write? = !read?
+      def payable? = state_mutability == "payable"
+
+      def input_names = inputs.map(&:ruby_name)
+
+      # Positional args or keyword args (matched on snake_cased input names).
+      def encode(args = [], kwargs = {})
+        values = resolve_args(args, kwargs)
+        selector + Utils.strip_hex(Coder.encode(inputs, values))
+      end
+
+      # Single output -> value; several -> Array.
+      def decode_output(hex)
+        values = Coder.decode(outputs, hex)
+        outputs.size == 1 ? values.first : values
+      end
+
+      def resolve_args(args, kwargs)
+        raise InvalidArgumentError, "#{name}: mix of positional and keyword arguments" if !args.empty? && !kwargs.empty?
+        return args if kwargs.empty?
+
+        if inputs.any?(&:unnamed?)
+          raise InvalidArgumentError, "#{name}: inputs are unnamed in the ABI, use positional arguments"
+        end
+
+        normalized = kwargs.transform_keys { |k| Utils.snake_case(k).to_sym }
+        unknown = normalized.keys - input_names
+        unless unknown.empty?
+          raise InvalidArgumentError,
+                "#{name}: unknown argument(s) #{unknown.join(', ')} (expected #{input_names.join(', ')})"
+        end
+
+        missing = input_names - normalized.keys
+        raise InvalidArgumentError, "#{name}: missing argument(s) #{missing.join(', ')}" unless missing.empty?
+
+        input_names.map { |n| normalized[n] }
+      end
+
+      def to_s = signature
+      def inspect = "#<BlockGiven::Abi::Function #{signature} #{state_mutability}>"
+
+      private
+
+      def legacy_mutability(definition)
+        return "payable" if definition["payable"]
+        return "view" if definition["constant"]
+
+        "nonpayable"
+      end
+    end
+  end
+end

data/lib/block_given/abi/interface.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module BlockGiven
+  module Abi
+    # Parsed ABI: functions (with overload resolution), events and custom errors.
+    class Interface
+      attr_reader :functions, :events, :errors, :constructor, :raw
+
+      # Accepts an ABI Array, a Hardhat/Foundry artifact Hash (with "abi"), a JSON String or a Pathname.
+      def self.parse(source)
+        return source if source.is_a?(Interface)
+
+        new(load_definitions(source))
+      end
+
+      def self.load_definitions(source)
+        case source
+        when Array then source
+        when Hash then source["abi"] || source[:abi] || raise(AbiError, "Hash has no 'abi' key")
+        when Pathname, File then load_definitions(JSON.parse(File.read(source)))
+        when String then load_definitions(JSON.parse(source))
+        else raise AbiError, "cannot parse ABI from #{source.class}"
+        end
+      rescue JSON::ParserError => e
+        raise AbiError, "invalid ABI JSON: #{e.message}"
+      end
+
+      def initialize(definitions)
+        @raw = definitions.map { |d| d.transform_keys(&:to_s) }
+        @functions = []
+        @events = []
+        @errors = []
+        @constructor = nil
+        @raw.each do |definition|
+          case definition["type"]
+          when "function", nil then @functions << Function.new(definition)
+          when "event" then @events << Event.new(definition)
+          when "error" then @errors << CustomError.new(definition)
+          when "constructor" then @constructor = definition
+          end
+        end
+        @functions_by_name = @functions.group_by(&:ruby_name)
+      end
+
+      def function_names = @functions_by_name.keys
+
+      # Finds a function by name (snake_case or camelCase) or by full signature
+      # ("transfer(address,uint256)"). Overloads are disambiguated by argument
+      # count or keyword names.
+      def function(name, args: [], kwargs: {})
+        name = name.to_s
+        return function_by_signature(name) if name.include?("(")
+
+        candidates = @functions_by_name[Utils.snake_case(name).to_sym]
+        if candidates.nil?
+          raise FunctionNotFoundError,
+                "no function #{name.inspect} in ABI (known: #{function_names.join(', ')})"
+        end
+        return candidates.first if candidates.size == 1
+
+        matching =
+          if kwargs.empty?
+            candidates.select { |f| f.inputs.size == args.size }
+          else
+            keys = kwargs.keys.map { |k| Utils.snake_case(k).to_sym }.sort
+            candidates.select { |f| f.input_names.sort == keys }
+          end
+        return matching.first if matching.size == 1
+
+        if matching.size > 1
+          raise AmbiguousFunctionError,
+                "#{name} is overloaded, use the full signature: #{candidates.map(&:signature).join(' | ')}"
+        end
+        raise FunctionNotFoundError,
+              "no overload of #{name} matches the given arguments (#{candidates.map(&:signature).join(' | ')})"
+      end
+
+      def function_by_signature(signature)
+        @functions.find { |f| f.signature == signature.delete(" ") } ||
+          raise(FunctionNotFoundError, "no function with signature #{signature.inspect}")
+      end
+
+      def function_by_selector(selector)
+        @functions.find { |f| f.selector == selector.downcase }
+      end
+
+      def event(name)
+        name = name.to_s
+        key = Utils.snake_case(name).to_sym
+        @events.find { |e| e.ruby_name == key || e.signature == name } ||
+          raise(EventNotFoundError, "no event #{name.inspect} in ABI (known: #{@events.map(&:name).join(', ')})")
+      end
+
+      def event_by_topic(topic)
+        @events.find { |e| e.topic == topic.to_s.downcase }
+      end
+
+      def error_by_selector(selector)
+        @errors.find { |e| e.selector == selector.to_s.downcase }
+      end
+
+      def inspect
+        "#<BlockGiven::Abi::Interface functions=#{@functions.size} events=#{@events.size} errors=#{@errors.size}>"
+      end
+    end
+  end
+end

data/lib/block_given/abi/parameter.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Abi
+    # One ABI input/output. Knows its canonical Solidity type ("(uint256,address)[]").
+    class Parameter
+      attr_reader :name, :raw_type, :components, :indexed, :internal_type
+
+      def initialize(definition, index: 0)
+        definition = definition.transform_keys(&:to_s)
+        @name = definition["name"].to_s
+        @name = "arg#{index}" if @name.empty?
+        @unnamed = definition["name"].to_s.empty?
+        @raw_type = definition["type"].to_s
+        @indexed = definition["indexed"] ? true : false
+        @internal_type = definition["internalType"]
+        @components = Array(definition["components"]).each_with_index.map { |c, i| Parameter.new(c, index: i) }
+      end
+
+      def unnamed? = @unnamed
+      def indexed? = indexed
+      def ruby_name = Utils.snake_case(name).to_sym
+
+      def tuple? = raw_type.start_with?("tuple")
+      def array? = raw_type.end_with?("]")
+
+      # "tuple[]" with components -> "(uint256,address)[]"
+      def type
+        return raw_type unless tuple?
+
+        raw_type.sub("tuple", "(#{components.map(&:type).join(',')})")
+      end
+
+      # Base type without the outermost array dimension.
+      def element
+        return nil unless array?
+
+        Parameter.new(
+          { "name" => name, "type" => raw_type.sub(/\[\d*\]\z/, ""),
+            "components" => components.map(&:to_h) }
+        )
+      end
+
+      def dynamic?
+        raw_type == "string" || raw_type == "bytes" || raw_type.end_with?("[]") ||
+          (tuple? && components.any?(&:dynamic?)) || (array? && element.dynamic?)
+      end
+
+      def to_h
+        h = { "name" => unnamed? ? "" : name, "type" => raw_type }
+        h["components"] = components.map(&:to_h) if tuple?
+        h["indexed"] = indexed if indexed
+        h
+      end
+    end
+  end
+end

data/lib/block_given/chain.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # Static description of an EVM network, similar to viem/chains.
+  Chain = Struct.new(
+    :id, :name, :network, :native_currency, :rpc_urls, :block_explorer_url, :alchemy_network, :testnet,
+    keyword_init: true
+  ) do
+    def initialize(id:, name:, network: nil, native_currency: nil, rpc_urls: [], block_explorer_url: nil,
+                   alchemy_network: nil, testnet: false)
+      super(
+        id: id, name: name, network: network || name.to_s.downcase.gsub(/[^a-z0-9]+/, "-"),
+        native_currency: native_currency || { name: "Ether", symbol: "ETH", decimals: 18 },
+        rpc_urls: Array(rpc_urls), block_explorer_url: block_explorer_url,
+        alchemy_network: alchemy_network, testnet: testnet
+      )
+    end
+
+    def testnet? = !!testnet
+
+    def explorer_tx_url(hash)
+      block_explorer_url && "#{block_explorer_url}/tx/#{hash}"
+    end
+
+    def explorer_address_url(address)
+      block_explorer_url && "#{block_explorer_url}/address/#{address}"
+    end
+
+    def to_s = "#{name} (#{id})"
+    def inspect = "#<BlockGiven::Chain #{self}>"
+  end
+
+  module Chains
+    MAINNET = Chain.new(
+      id: 1, name: "Ethereum", network: "mainnet",
+      rpc_urls: ["https://eth.merkle.io"], block_explorer_url: "https://etherscan.io",
+      alchemy_network: "eth-mainnet"
+    )
+    SEPOLIA = Chain.new(
+      id: 11_155_111, name: "Sepolia", network: "sepolia",
+      rpc_urls: ["https://sepolia.drpc.org"], block_explorer_url: "https://sepolia.etherscan.io",
+      alchemy_network: "eth-sepolia", testnet: true
+    )
+    BASE = Chain.new(
+      id: 8453, name: "Base", network: "base",
+      rpc_urls: ["https://mainnet.base.org"], block_explorer_url: "https://basescan.org",
+      alchemy_network: "base-mainnet"
+    )
+    BASE_SEPOLIA = Chain.new(
+      id: 84_532, name: "Base Sepolia", network: "base-sepolia",
+      rpc_urls: ["https://sepolia.base.org"], block_explorer_url: "https://sepolia.basescan.org",
+      alchemy_network: "base-sepolia", testnet: true
+    )
+    POLYGON = Chain.new(
+      id: 137, name: "Polygon", network: "polygon",
+      native_currency: { name: "POL", symbol: "POL", decimals: 18 },
+      rpc_urls: ["https://polygon-rpc.com"], block_explorer_url: "https://polygonscan.com",
+      alchemy_network: "polygon-mainnet"
+    )
+    POLYGON_AMOY = Chain.new(
+      id: 80_002, name: "Polygon Amoy", network: "polygon-amoy",
+      native_currency: { name: "POL", symbol: "POL", decimals: 18 },
+      rpc_urls: ["https://rpc-amoy.polygon.technology"], block_explorer_url: "https://amoy.polygonscan.com",
+      alchemy_network: "polygon-amoy", testnet: true
+    )
+    ARBITRUM = Chain.new(
+      id: 42_161, name: "Arbitrum One", network: "arbitrum",
+      rpc_urls: ["https://arb1.arbitrum.io/rpc"], block_explorer_url: "https://arbiscan.io",
+      alchemy_network: "arb-mainnet"
+    )
+    ARBITRUM_SEPOLIA = Chain.new(
+      id: 421_614, name: "Arbitrum Sepolia", network: "arbitrum-sepolia",
+      rpc_urls: ["https://sepolia-rollup.arbitrum.io/rpc"], block_explorer_url: "https://sepolia.arbiscan.io",
+      alchemy_network: "arb-sepolia", testnet: true
+    )
+    OPTIMISM = Chain.new(
+      id: 10, name: "OP Mainnet", network: "optimism",
+      rpc_urls: ["https://mainnet.optimism.io"], block_explorer_url: "https://optimistic.etherscan.io",
+      alchemy_network: "opt-mainnet"
+    )
+    OPTIMISM_SEPOLIA = Chain.new(
+      id: 11_155_420, name: "OP Sepolia", network: "optimism-sepolia",
+      rpc_urls: ["https://sepolia.optimism.io"], block_explorer_url: "https://sepolia-optimism.etherscan.io",
+      alchemy_network: "opt-sepolia", testnet: true
+    )
+    # Hardhat / Anvil / Ganache default chain, handy with a local fork.
+    LOCALHOST = Chain.new(
+      id: 31_337, name: "Localhost", network: "localhost",
+      rpc_urls: ["http://127.0.0.1:8545"], testnet: true
+    )
+
+    ALL = [MAINNET, SEPOLIA, BASE, BASE_SEPOLIA, POLYGON, POLYGON_AMOY, ARBITRUM, ARBITRUM_SEPOLIA,
+           OPTIMISM, OPTIMISM_SEPOLIA, LOCALHOST].freeze
+
+    module_function
+
+    # Chains.resolve(:base) / Chains.resolve("base-sepolia") / Chains.resolve(8453) / Chains.resolve(chain)
+    def resolve(value)
+      case value
+      when Chain then value
+      when Integer then find_by_id(value) || raise(ConfigurationError, "unknown chain id #{value}")
+      when Symbol, String
+        key = value.to_s.downcase.tr("_", "-")
+        ALL.find { |c| c.network == key } || raise(ConfigurationError, "unknown chain #{value.inspect}")
+      else raise ConfigurationError, "cannot resolve chain from #{value.inspect}"
+      end
+    end
+
+    def find_by_id(id) = ALL.find { |c| c.id == id }
+    def [](value) = resolve(value)
+  end
+end