block_given 0.1.0

data/lib/block_given/contract.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # Base class for typed contracts. Declare the ABI (and optionally a default
+  # address / chain) and every ABI function becomes a Ruby method:
+  #
+  #   class Usdc < BlockGiven::Contract
+  #     abi_file "abis/erc20.json"   # your app's ABI file (see BlockGiven.config.abi_path)
+  #     address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+  #   end
+  #
+  #   usdc = Usdc.new(wallet: BlockGiven::Wallet.new(private_key: "0x..."))
+  #   usdc.balance_of(wallet.address)                       # eth_call, decoded
+  #   tx = usdc.transfer(to: "0x...", value: 1e6)           # signed + broadcast -> BlockGiven::Transaction
+  #   tx.wait!                                              # polls the receipt
+  #
+  # Transaction / call overrides go in the reserved `tx:` keyword:
+  #   vault.deposit(amount, tx: { value: BlockGiven::Utils.parse_ether("0.1"), gas: 200_000 })
+  #   token.balance_of(addr, tx: { block: 18_000_000 })
+  class Contract
+    TX_OPTIONS = %i[value gas nonce max_fee_per_gas max_priority_fee_per_gas gas_price from block].freeze
+
+    class << self
+      attr_reader :interface
+
+      # Sets (or returns) the ABI. Accepts an Array, an artifact Hash, or a JSON String.
+      def abi(source = nil)
+        return interface&.raw if source.nil?
+
+        @interface = Abi::Interface.parse(source)
+        define_abi_methods!
+        @interface
+      end
+
+      # Loads the ABI from a JSON file. Relative paths are resolved against
+      # BlockGiven.config.abi_path when set (ABIs live in your app, not in the gem).
+      def abi_file(path)
+        base = BlockGiven.config.abi_path
+        path = File.join(base.to_s, path.to_s) if base && !File.absolute_path?(path.to_s)
+        raise AbiError, "ABI file not found: #{path}" unless File.file?(path)
+
+        abi(File.read(path))
+      end
+
+      # Default address for instances (can be overridden with .new(address: ...) / .at(...)).
+      def address(value = nil)
+        return @default_address if value.nil?
+
+        @default_address = Utils.checksum_address(value)
+      end
+      alias default_address address
+
+      def chain(value = nil)
+        return @chain if value.nil?
+
+        @chain = Chains.resolve(value)
+      end
+
+      def at(address, **options) = new(address: address, **options)
+
+      def functions = interface&.functions || []
+      def events = interface&.events || []
+      def errors = interface&.errors || []
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@interface, @interface)
+        subclass.instance_variable_set(:@default_address, @default_address)
+        subclass.instance_variable_set(:@chain, @chain)
+        subclass.send(:define_abi_methods!) if @interface
+      end
+
+      private
+
+      # One Ruby method per ABI function name (snake_case). Names clashing with
+      # existing methods (send, class, address...) are skipped: use #read / #write.
+      def define_abi_methods!
+        interface.function_names.each do |ruby_name|
+          if Contract.method_defined?(ruby_name) || Contract.private_method_defined?(ruby_name)
+            BlockGiven.config.logger.debug do
+              "[block_given] #{name}: skipping ##{ruby_name} (reserved), use read/write"
+            end
+            next
+          end
+
+          define_method(ruby_name) do |*args, tx: {}, **kwargs|
+            function = self.class.interface.function(ruby_name, args: args, kwargs: kwargs)
+            if function.read?
+              read(function, *args, tx: tx, **kwargs)
+            else
+              write(function, *args, tx: tx, **kwargs)
+            end
+          end
+        end
+      end
+    end
+
+    attr_reader :address, :wallet
+
+    def initialize(address: nil, wallet: nil, client: nil, chain: nil)
+      raise AbiError, "#{self.class.name} has no ABI: declare it with `abi [...]` or `abi_file`" unless interface
+
+      resolved = address || self.class.default_address
+      raise InvalidArgumentError, "#{self.class.name}: address is required" if resolved.nil?
+
+      @address = Utils.checksum_address(resolved)
+      @wallet = wallet
+      @client = client
+      @chain = chain
+    end
+
+    def interface = self.class.interface
+
+    def client
+      @client ||= begin
+        chain = @chain || self.class.chain
+        if wallet && (chain.nil? || wallet.client.chain == Chains.resolve(chain))
+          wallet.client
+        elsif chain
+          Client.new(chain: chain)
+        else
+          BlockGiven.client
+        end
+      end
+    end
+
+    def chain = client.chain
+    def with_wallet(wallet) = self.class.new(address: address, wallet: wallet, client: @client, chain: @chain)
+
+    # --- Reads / writes -----------------------------------------------------
+
+    # eth_call + decode. Overrides: tx: { block:, from: }.
+    def read(name, *args, tx: {}, **kwargs)
+      function = resolve(name, args, kwargs)
+      data = function.encode(args, kwargs)
+      options = tx_options(tx)
+      raw = with_decoded_errors do
+        client.call(to: address, data: data, from: options[:from] || wallet&.address, block: options[:block] || :latest)
+      end
+      function.decode_output(raw)
+    end
+
+    # Signs and broadcasts. Returns a BlockGiven::Transaction. Overrides: tx: { value:, gas:, nonce:, fees... }.
+    def write(name, *args, tx: {}, **kwargs)
+      prepare_write(name, *args, tx: tx, **kwargs).broadcast
+    end
+
+    # Signs without broadcasting. Returns a BlockGiven::SignedTransaction whose #hash and
+    # #nonce are known before any network call: persist them, then call #broadcast. The signed
+    # transaction keeps this contract's ABI, so reverts raised by #broadcast are decoded too.
+    def prepare_write(name, *args, tx: {}, **kwargs)
+      function = resolve(name, args, kwargs)
+      unless wallet
+        raise WalletRequiredError,
+              "#{self.class.name}##{function.ruby_name} needs a wallet (pass wallet: to .new)"
+      end
+
+      options = tx_options(tx)
+      value = options[:value] || 0
+      if value != 0 && !function.payable?
+        raise InvalidArgumentError, "#{function.name} is not payable, cannot send value"
+      end
+
+      data = function.encode(args, kwargs)
+      with_decoded_errors do
+        wallet.signed_transaction(
+          to: address, data: data, value: value, gas: options[:gas], nonce: options[:nonce],
+          max_fee_per_gas: options[:max_fee_per_gas], max_priority_fee_per_gas: options[:max_priority_fee_per_gas],
+          gas_price: options[:gas_price]
+        ).with_interface(interface)
+      end
+    end
+
+    # Dry-runs a write with eth_call from the wallet address and returns the decoded
+    # result. Raises BlockGiven::ContractRevertError with the decoded reason on failure.
+    def simulate(name, *args, tx: {}, **kwargs)
+      function = resolve(name, args, kwargs)
+      options = tx_options(tx)
+      data = function.encode(args, kwargs)
+      raw = with_decoded_errors do
+        client.call(to: address, data: data, from: options[:from] || wallet&.address, value: options[:value],
+                    gas: options[:gas], block: options[:block] || :latest)
+      end
+      function.decode_output(raw)
+    end
+
+    def estimate_gas(name, *args, tx: {}, **kwargs)
+      function = resolve(name, args, kwargs)
+      options = tx_options(tx)
+      data = function.encode(args, kwargs)
+      with_decoded_errors do
+        client.estimate_gas(to: address, data: data, from: options[:from] || wallet&.address, value: options[:value])
+      end
+    end
+
+    def encode_function_data(name, *args, **kwargs)
+      resolve(name, args, kwargs).encode(args, kwargs)
+    end
+
+    def decode_function_result(name, hex)
+      interface.function(name).decode_output(hex)
+    end
+
+    # --- Events -------------------------------------------------------------
+
+    # Fetches past events. `args` filters on indexed parameters.
+    #   usdc.get_events(:Transfer, from_block: 18_000_000, to_block: :latest, args: { to: wallet.address })
+    # Pass max_block_range: to split a large range into several eth_getLogs calls.
+    def get_events(name = nil, from_block:, to_block: :latest, args: {}, max_block_range: nil)
+      topics = name ? interface.event(name).encode_topics(args) : nil
+      logs = if max_block_range
+               client.get_logs_in_chunks(address: address, topics: topics, from_block: from_block,
+                                         to_block: to_block, max_block_range: max_block_range)
+             else
+               client.get_logs(address: address, topics: topics, from_block: from_block, to_block: to_block)
+             end
+      decode_logs(logs)
+    end
+
+    # Polls for new events in a background thread. Returns a BlockGiven::Watcher.
+    #   watcher = usdc.watch_event(:Transfer, args: { to: me }) { |event| puts event.args }
+    #   watcher.stop
+    #
+    # Resuming after a restart: pass from_block: (your persisted cursor + 1) and persist the
+    # `to` block handed to on_progress after each processed range. confirmations: keeps the
+    # watcher N blocks behind the head so reorged logs are never delivered.
+    def watch_event(name = nil, args: {}, from_block: nil, polling_interval: nil, max_block_range: nil,
+                    confirmations: 0, on_progress: nil, id: nil, &block)
+      raise ::ArgumentError, "a block is required" unless block
+
+      event = name && interface.event(name)
+      topics = event&.encode_topics(args)
+      label = "#{event ? event.name : '*'}@#{self.class.name || 'Contract'}(#{address[0, 10]})"
+      client.watch_logs(address: address, topics: topics, from_block: from_block,
+                        polling_interval: polling_interval, max_block_range: max_block_range,
+                        confirmations: confirmations, on_progress: on_progress, id: id, name: label) do |logs|
+        decode_logs(logs).each { |event| block.call(event) }
+      end
+    end
+    alias watch_events watch_event
+
+    # Decodes raw logs with this contract's ABI. Unknown topics are skipped.
+    def decode_logs(logs)
+      logs.filter_map do |log|
+        log = Normalizer.normalize(log) unless log.is_a?(Hash) && log.key?(:topics)
+        topic = Array(log[:topics]).first
+        event = topic && interface.event_by_topic(topic)
+        event&.decode(log)
+      end
+    end
+
+    # Events emitted by this contract in a receipt.
+    def events_from(receipt)
+      logs = receipt.respond_to?(:logs) ? receipt.logs : Array(receipt[:logs])
+      decode_logs(logs.select { |l| Utils.same_address?(l[:address], address) })
+    end
+
+    def explorer_url = chain.explorer_address_url(address)
+    def ==(other) = other.class == self.class && other.address == address
+    def inspect = "#<#{self.class.name} #{address}#{" wallet=#{wallet.address}" if wallet}>"
+
+    private
+
+    def resolve(name, args, kwargs)
+      name.is_a?(Abi::Function) ? name : interface.function(name, args: args, kwargs: kwargs)
+    end
+
+    def tx_options(tx)
+      raise InvalidArgumentError, "tx: must be a Hash" unless tx.is_a?(Hash)
+
+      options = tx.transform_keys(&:to_sym)
+      unknown = options.keys - TX_OPTIONS
+      unless unknown.empty?
+        raise InvalidArgumentError,
+              "unknown tx option(s): #{unknown.join(', ')} (allowed: #{TX_OPTIONS.join(', ')})"
+      end
+
+      options
+    end
+
+    def with_decoded_errors
+      yield
+    rescue ContractRevertError => e
+      raise e.decode_with(interface)
+    end
+  end
+end

data/lib/block_given/errors.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # Base class for every error raised by BlockGiven.
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+  class InvalidArgumentError < Error; end
+  class InvalidAddressError < InvalidArgumentError; end
+  class WalletRequiredError < Error; end
+  class TimeoutError < Error; end
+
+  class AbiError < Error; end
+  class FunctionNotFoundError < AbiError; end
+  class EventNotFoundError < AbiError; end
+  class AmbiguousFunctionError < AbiError; end
+
+  # Transport-level failure (non-2xx HTTP status, connection refused, ...).
+  class HttpError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  # JSON-RPC error object returned by the node.
+  class RpcError < Error
+    attr_reader :code, :data, :rpc_method
+
+    def initialize(message, code: nil, data: nil, rpc_method: nil)
+      super(message)
+      @code = code
+      @data = data
+      @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.
+    def self.from_payload(error, rpc_method: nil)
+      error = { "message" => error.to_s } unless error.is_a?(Hash)
+      code = error["code"]
+      message = error["message"].to_s
+      data = error["data"]
+      revert_data = extract_revert_data(data)
+
+      if revert_data || message.match?(/revert/i)
+        ContractRevertError.new(message, code: code, data: data, rpc_method: rpc_method, revert_data: revert_data)
+      else
+        new(message, code: code, data: data, rpc_method: rpc_method)
+      end
+    end
+
+    # Providers disagree on where the revert bytes live: Alchemy/geth put them in
+    # `data`, Hardhat/Anvil nest them under `data.data`.
+    def self.extract_revert_data(data)
+      case data
+      when String then data.start_with?("0x") ? data : nil
+      when Hash then extract_revert_data(data["data"] || data[:data])
+      end
+    end
+  end
+
+  # eth_call / eth_estimateGas / eth_sendRawTransaction rejected by the EVM.
+  class ContractRevertError < RpcError
+    ERROR_STRING_SELECTOR = "0x08c379a0"
+    PANIC_SELECTOR = "0x4e487b71"
+    PANIC_REASONS = {
+      0x00 => "generic compiler inserted panic",
+      0x01 => "assertion failed",
+      0x11 => "arithmetic overflow or underflow",
+      0x12 => "division or modulo by zero",
+      0x21 => "invalid enum conversion",
+      0x22 => "incorrectly encoded storage byte array",
+      0x31 => "pop() on an empty array",
+      0x32 => "array index out of bounds",
+      0x41 => "too much memory allocated or array too large",
+      0x51 => "call to a zero-initialized variable of internal function type"
+    }.freeze
+
+    attr_reader :revert_data, :error_name, :args
+
+    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
+      @args = args
+      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).
+    def reason
+      return @reason if defined?(@reason)
+
+      @reason = decode_builtin_reason
+    end
+
+    def selector
+      revert_data && revert_data.length >= 10 ? revert_data[0, 10] : nil
+    end
+
+    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.
+    def decode_with(interface)
+      return self unless custom_error? && interface
+
+      custom = interface.error_by_selector(selector)
+      return self unless custom
+
+      decoded = custom.decode(revert_data)
+      self.class.new(
+        "#{custom.name}(#{decoded.values.map(&:inspect).join(', ')})",
+        code: code, data: data, rpc_method: rpc_method, revert_data: revert_data,
+        error_name: custom.name, args: decoded
+      )
+    end
+
+    private
+
+    def build_message(original)
+      reason = decode_builtin_reason
+      return "execution reverted: #{reason}" if reason && !original.include?(reason)
+
+      original.empty? ? "execution reverted" : original
+    end
+
+    def decode_builtin_reason
+      return nil unless revert_data && revert_data.length > 10
+
+      payload = "0x#{revert_data[10..]}"
+      case selector
+      when ERROR_STRING_SELECTOR
+        Eth::Abi.decode(["string"], payload).first
+      when PANIC_SELECTOR
+        panic_code = Eth::Abi.decode(["uint256"], payload).first
+        "Panic(0x#{panic_code.to_s(16).rjust(2, '0')}): #{PANIC_REASONS.fetch(panic_code, 'unknown panic')}"
+      end
+    rescue StandardError
+      nil
+    end
+  end
+
+  # Raised by Transaction#wait! when the mined receipt has a failed status.
+  class TransactionRevertedError < Error
+    attr_reader :receipt
+
+    def initialize(receipt)
+      @receipt = receipt
+      super("transaction #{receipt.transaction_hash} reverted in block #{receipt.block_number}")
+    end
+  end
+end

data/lib/block_given/event.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # A decoded event log.
+  #
+  #   event.name           # => "Transfer"
+  #   event.args           # => { from: "0x...", to: "0x...", value: 1000000 }
+  #   event[:value]        # => 1000000
+  #   event.block_number   # => 12345
+  class Event
+    attr_reader :name, :signature, :args, :log
+
+    def initialize(name:, signature:, args:, log:)
+      @name = name
+      @signature = signature
+      @args = args
+      @log = log
+    end
+
+    def [](key) = args[Utils.snake_case(key).to_sym]
+    def address = log[:address] && Utils.checksum_address(log[:address])
+    def block_number = log[:block_number]
+    def block_hash = log[:block_hash]
+    def transaction_hash = log[:transaction_hash]
+    def transaction_index = log[:transaction_index]
+    def log_index = log[:log_index]
+    def removed? = !!log[:removed]
+
+    def to_h
+      { name: name, args: args, address: address, block_number: block_number,
+        transaction_hash: transaction_hash, log_index: log_index }
+    end
+
+    def inspect = "#<BlockGiven::Event #{name} #{args.inspect} block=#{block_number}>"
+  end
+end

data/lib/block_given/normalizer.rb

@@ -0,0 +1,37 @@
+# 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.
+  module Normalizer
+    module_function
+
+    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
+      max_priority_fee_per_gas chain_id type difficulty total_difficulty size nonce blob_gas_used
+      blob_gas_price excess_blob_gas max_fee_per_blob_gas l1_fee l1_gas_used l1_gas_price l1_fee_scalar
+      deposit_nonce deposit_receipt_version
+    ].freeze
+
+    def normalize(value)
+      case value
+      when Hash then value.each_with_object({}) do |(k, v), h|
+        h[key = Utils.snake_case(k).to_sym] = normalize_field(key, v)
+      end
+      when Array then value.map { |v| normalize(v) }
+      else value
+      end
+    end
+
+    def normalize_field(key, value)
+      if QUANTITY_KEYS.include?(key) && Utils.hex?(value)
+        value == "0x" ? nil : Utils.hex_to_int(value)
+      elsif key == :topics && value.is_a?(Array)
+        value
+      else
+        normalize(value)
+      end
+    end
+  end
+end