eth 0.5.13 → 0.5.15

data/lib/eth/contract/event.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,40 +16,93 @@
 
 # Provides the {Eth} module.
 module Eth
-
   # Provide classes for contract event.
   class Contract::Event
-    attr_accessor :name, :signature, :input_types, :inputs, :event_string, :address
-
     # Constructor of the {Eth::Contract::Event} class.
     #
     # @param data [Hash] contract event data.
     def initialize(data)
-      @name = data["name"]
-      @input_types = data["inputs"].collect do |x|
-        type_name x
-      end
-      @inputs = data["inputs"].collect { |x| x["name"] }
-      @event_string = Abi::Event.signature(data)
-      @signature = Digest::Keccak.hexdigest(@event_string, 256)
+      @data = data
+    end
+
+    # Returns the name of the event.
+    #
+    # @return [String] The event name.
+    def name
+      @data["name"]
+    end
+
+    # Returns the input types for the event.
+    #
+    # @return [Array<String>] An array of input type names.
+    def input_types
+      @input_types ||= @data["inputs"].map { |x| type_name(x) }
+    end
+
+    # Returns the names of input parameters.
+    #
+    # @return [Array<String>] An array of input parameter names.
+    def inputs
+      @inputs ||= @data["inputs"].map { |x| x["name"] }
+    end
+
+    # Returns the event signature string.
+    #
+    # @return [String] The event signature string, generated from ABI.
+    def event_string
+      @event_string ||= Abi::Event.signature(@data)
+    end
+
+    # Returns the Keccak-256 event signature hash.
+    #
+    # @return [String] The event signature hash in hexadecimal format.
+    def signature
+      @signature ||= Digest::Keccak.hexdigest(event_string, 256)
+    end
+
+    # Returns the Ethereum address associated with the event.
+    #
+    # @return [String, nil] The Ethereum address, or `nil` if not set.
+    def address
+      @address ||= nil
     end
 
     # Set the address of the smart contract
     #
     # @param address [String] contract address.
     def set_address(address)
-      @address = address.nil? ? nil : Eth::Address.new(address).address
+      @address = address ? Eth::Address.new(address).address : nil
+    end
+
+    # Decodes event parameters from logs.
+    #
+    # @param topics [Array<String>] The list of log topics, including the event selector.
+    # @param data [String] The log data containing non-indexed parameters.
+    # @return [ActiveSupport::HashWithIndifferentAccess] A hash of decoded event parameters.
+    def decode_params(topics, data = "0x")
+      inputs = @data["inputs"]
+
+      indexed_inputs, non_indexed_inputs = inputs.partition { _1["indexed"] }
+
+      {
+        **indexed_inputs.each_with_index.inject({}) do |result, (input, index)|
+          result[input["name"]] = Eth::Abi.decode([input["type"]], topics[index + 1])[0]
+          result
+        end,
+        **Hash[non_indexed_inputs.map { _1["name"] }.zip(
+                 Eth::Abi.decode(non_indexed_inputs.map { |i| i["type"] }, data)
+               )],
+      }
     end
 
     private
 
     def type_name(x)
-      type = x["type"]
-      case type
+      case x["type"]
       when "tuple"
-        "(#{x["components"].collect { |c| type_name(c) }.join(",")})"
+        "(#{x["components"].map { |c| type_name(c) }.join(",")})"
       else
-        type
+        x["type"]
       end
     end
   end

data/lib/eth/contract/function.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -53,5 +53,26 @@ module Eth
     def self.encoded_function_signature(signature)
       Util.bin_to_hex Util.keccak256(signature)[0..3]
     end
+
+    # Encodes a function call arguments
+    #
+    # @param args [Array] function arguments
+    # @return [String] encoded function call data
+    def encode_call(*args)
+      types = inputs.map(&:parsed_type)
+      encoded_str = Util.bin_to_hex(Eth::Abi.encode(types, args))
+      Util.prefix_hex(signature + (encoded_str.empty? ? "0" * 64 : encoded_str))
+    end
+
+    # Decodes a function call result
+    #
+    # @param data [String] eth_call result in hex format
+    # @return [Array]
+    def decode_call_result(data)
+      return nil if data == "0x"
+
+      types = outputs.map(&:parsed_type)
+      Eth::Abi.decode(types, data)
+    end
   end
 end

data/lib/eth/contract/function_input.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/contract/function_output.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,19 +19,27 @@ module Eth
 
   # Provide classes for contract function output.
   class Contract::FunctionOutput
-    attr_accessor :type, :name
+    attr_accessor :type, :raw_type, :name
 
     # Constructor of the {Eth::Contract::FunctionOutput} class.
     #
     # @param data [Hash] contract abi data.
     def initialize(data)
-      @type = Eth::Abi::Type.parse(data["type"])
+      @raw_type = data["type"]
+      @type = Eth::Abi::Type.parse(data["type"], data["components"])
       @name = data["name"]
     end
 
     # Returns complete types with subtypes, e.g., `uint256`.
     def type
-      @type.base_type + @type.sub_type + @type.dimensions.map { |dimension| "[#{dimension > 0 ? dimension : ""}]" }.join("")
+      @type.base_type +
+        @type.sub_type +
+        @type.dimensions.map { |dimension| "[#{dimension > 0 ? dimension : ""}]" }.join("")
+    end
+
+    # Returns parsed types.
+    def parsed_type
+      @type
     end
   end
 end

data/lib/eth/contract/initializer.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/contract.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -25,7 +25,7 @@ module Eth
     attr_accessor :key
     attr_accessor :gas_limit, :gas_price, :max_fee_per_gas, :max_priority_fee_per_gas, :nonce
     attr_accessor :bin, :name, :abi, :class_object
-    attr_accessor :events, :functions, :constructor_inputs
+    attr_accessor :events, :functions, :constructor_inputs, :errors
 
     # Constructor of the {Eth::Contract} class.
     #
@@ -44,7 +44,7 @@ module Eth
       @name = _name
       @bin = bin
       @abi = abi
-      @constructor_inputs, @functions, @events = parse_abi(abi)
+      @constructor_inputs, @functions, @events, @errors = parse_abi(abi)
     end
 
     # Creates a contract wrapper from a Solidity file.
@@ -106,6 +106,52 @@ module Eth
       end
     end
 
+    # Finds a function by name.
+    #
+    # @param name [String] function name.
+    # @param args [Integer, nil] number of arguments of a function.
+    # @return [Eth::Contract::Function] function object.
+    # @raise [ArgumentError] if function not found.
+    def function(name, args: nil)
+      functions.find do |f|
+        f.name == name && (args.nil? || args == f.inputs.size)
+      end || raise(ArgumentError, "this function does not exist!")
+    end
+
+    # Finds an error by name.
+    #
+    # @param name [String] error name.
+    # @param args [Integer, nil] number of arguments of an error.
+    # @return [Eth::Contract::Error] error object.
+    # @raise [ArgumentError] if error not found.
+    def error(name, args: nil)
+      errors.find do |e|
+        e.name == name && (args.nil? || args == e.inputs.size)
+      end || raise(ArgumentError, "this error does not exist!")
+    end
+
+    # Decodes a custom error returned by an RPC error using the contract ABI.
+    #
+    # @param rpc_error [RpcError] the RPC error containing revert data.
+    # @return [String] a human readable error message.
+    def decode_error(rpc_error)
+      data = rpc_error.data
+      return rpc_error.message if data.nil? || errors.nil?
+
+      signature = data[0, 10]
+      if (err = errors.find { |e| e.signature == signature })
+        values = err.decode(data)
+        args = values&.map { |v| v.is_a?(String) ? v : v.inspect }&.join(",")
+        args ||= ""
+        "execution reverted: #{err.name}(#{args})"
+      elsif signature == "0x08c379a0"
+        reason = Abi.decode(["string"], "0x" + data[10..])&.first
+        "execution reverted: #{reason}"
+      else
+        rpc_error.message
+      end
+    end
+
     # Create meta classes for smart contracts.
     def build
       class_name = @name
@@ -116,9 +162,12 @@ module Eth
         def_delegators :parent, :name, :abi, :bin
         def_delegators :parent, :gas_limit, :gas_price, :gas_limit=, :gas_price=, :nonce, :nonce=
         def_delegators :parent, :max_fee_per_gas, :max_fee_per_gas=, :max_priority_fee_per_gas, :max_priority_fee_per_gas=
-        def_delegators :parent, :events
+        def_delegators :parent, :events, :errors
         def_delegators :parent, :address, :address=
         def_delegator :parent, :functions
+        def_delegator :parent, :function
+        def_delegator :parent, :error
+        def_delegator :parent, :decode_error
         def_delegator :parent, :constructor_inputs
         define_method :parent do
           parent
@@ -140,7 +189,8 @@ module Eth
       end
       functions = abi.select { |x| x["type"] == "function" }.map { |fun| Eth::Contract::Function.new(fun) }
       events = abi.select { |x| x["type"] == "event" }.map { |evt| Eth::Contract::Event.new(evt) }
-      [constructor_inputs, functions, events]
+      errors = abi.select { |x| x["type"] == "error" }.map { |err| Eth::Contract::Error.new(err) }
+      [constructor_inputs, functions, events, errors]
     end
   end
 end
@@ -151,3 +201,4 @@ require "eth/contract/function"
 require "eth/contract/function_input"
 require "eth/contract/function_output"
 require "eth/contract/initializer"
+require "eth/contract/error"

data/lib/eth/eip712.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -47,7 +47,12 @@ module Eth
 
         # recursively look for further nested dependencies
         types[primary_type.to_sym].each do |t|
-          dependency = type_dependencies t[:type], types, result
+          nested_type = t[:type]
+          # unpack arrays to their inner types to resolve dependencies
+          if nested_type.end_with?("]")
+            nested_type = nested_type.partition("[").first
+          end
+          dependency = type_dependencies nested_type, types, result
         end
         return result
       end
@@ -113,18 +118,12 @@ module Eth
       types[primary_type.to_sym].each do |field|
         value = data[field[:name].to_sym]
         type = field[:type]
-        raise NotImplementedError, "Arrays currently unimplemented for EIP-712." if type.end_with? "]"
-        if type == "string"
-          encoded_types.push "bytes32"
-          encoded_values.push Util.keccak256 value
-        elsif type == "bytes"
-          encoded_types.push "bytes32"
-          value = Util.hex_to_bin value
-          encoded_values.push Util.keccak256 value
-        elsif !types[type.to_sym].nil?
+        if type.end_with?("]")
+          encoded_types.push type
+          encoded_values.push encode_array(type, value, types)
+        elsif type == "string" || type == "bytes" || !types[type.to_sym].nil?
           encoded_types.push "bytes32"
-          value = encode_data type, value, types
-          encoded_values.push Util.keccak256 value
+          encoded_values.push encode_value(type, value, types)
         else
           encoded_types.push type
           encoded_values.push value
@@ -135,6 +134,43 @@ module Eth
       return Abi.encode encoded_types, encoded_values
     end
 
+    # Encodes a single value according to its type following EIP-712 rules.
+    # Returns a 32-byte binary string.
+    def encode_value(type, value, types)
+      if type == "string"
+        return Util.keccak256 value
+      elsif type == "bytes"
+        value = Util.hex_to_bin value
+        return Util.keccak256 value
+      elsif !types[type.to_sym].nil?
+        nested = encode_data type, value, types
+        return Util.keccak256 nested
+      else
+        # encode basic types via ABI to get 32-byte representation
+        return Abi.encode([type], [value])
+      end
+    end
+
+    # Prepares array values by encoding each element according to its
+    # base type. Returns an array compatible with Abi.encode.
+    def encode_array(type, value, types)
+      inner_type = type.slice(0, type.rindex("["))
+      return [] if value.nil?
+      value.map do |v|
+        if inner_type.end_with?("]")
+          encode_array inner_type, v, types
+        elsif inner_type == "string"
+          Util.keccak256 v
+        elsif inner_type == "bytes"
+          Util.keccak256 Util.hex_to_bin(v)
+        elsif !types[inner_type.to_sym].nil?
+          Util.keccak256 encode_data(inner_type, v, types)
+        else
+          v
+        end
+      end
+    end
+
     # Recursively ABI-encodes and hashes all data and types.
     #
     # @param primary_type [String] the primary type which we want to hash.

data/lib/eth/ens/coin_type.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/ens/resolver.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/ens.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/key/decrypter.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/key/encrypter.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/key.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -75,7 +75,7 @@ module Eth
       signature = compact.bytes
       v = Chain.to_v recovery_id, chain_id
       leading_zero = true
-      [v].pack("N").unpack("C*").each do |byte|
+      [v].pack("Q>").unpack("C*").each do |byte|
         leading_zero = false if byte > 0 and leading_zero
         signature.append byte unless leading_zero and byte === 0
       end

data/lib/eth/rlp/decoder.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/rlp/encoder.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/rlp/sedes/big_endian_int.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/rlp/sedes/binary.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/rlp/sedes/list.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/rlp/sedes.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/rlp.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/signature.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/solidity.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/eth/tx/eip1559.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -78,7 +78,7 @@ module Eth
       # @option params [Integer] :max_gas_fee the max transaction fee per gas.
       # @option params [Integer] :gas_limit the gas limit.
       # @option params [Eth::Address] :from the sender address.
-      # @option params [Eth::Address] :to the reciever address.
+      # @option params [Eth::Address] :to the receiver address.
       # @option params [Integer] :value the transaction value.
       # @option params [String] :data the transaction data payload.
       # @option params [Array] :access_list an optional access list.
@@ -148,13 +148,13 @@ module Eth
         raise ParameterError, "Transaction missing fields!" if tx.size < 9
 
         # populate the 9 payload fields
-        chain_id = Util.deserialize_big_endian_to_int tx[0]
-        nonce = Util.deserialize_big_endian_to_int tx[1]
-        priority_fee = Util.deserialize_big_endian_to_int tx[2]
-        max_gas_fee = Util.deserialize_big_endian_to_int tx[3]
-        gas_limit = Util.deserialize_big_endian_to_int tx[4]
+        chain_id = Util.deserialize_rlp_int tx[0]
+        nonce = Util.deserialize_rlp_int tx[1]
+        priority_fee = Util.deserialize_rlp_int tx[2]
+        max_gas_fee = Util.deserialize_rlp_int tx[3]
+        gas_limit = Util.deserialize_rlp_int tx[4]
         to = Util.bin_to_hex tx[5]
-        value = Util.deserialize_big_endian_to_int tx[6]
+        value = Util.deserialize_rlp_int tx[6]
         data = tx[7]
         access_list = tx[8]
 
@@ -257,6 +257,31 @@ module Eth
         return hash
       end
 
+      # Signs the transaction with a provided signature blob.
+      #
+      # @param signature [String] the concatenated `r`, `s`, and `v` values.
+      # @return [String] a transaction hash.
+      # @raise [Signature::SignatureError] if transaction is already signed.
+      # @raise [Signature::SignatureError] if sender address does not match signer.
+      def sign_with(signature)
+        if Tx.signed? self
+          raise Signature::SignatureError, "Transaction is already signed!"
+        end
+
+        # ensure the sender address matches the signature
+        unless @sender.nil? or sender.empty?
+          public_key = Signature.recover(unsigned_hash, signature, @chain_id)
+          signer_address = Tx.sanitize_address Util.public_key_to_address(public_key).to_s
+          from_address = Tx.sanitize_address @sender
+          raise Signature::SignatureError, "Signer does not match sender" unless signer_address == from_address
+        end
+
+        r, s, v = Signature.dissect signature
+        recovery_id = Chain.to_recovery_id v.to_i(16), @chain_id
+        send :_set_signature, recovery_id, r, s
+        return hash
+      end
+
       # Encodes a raw transaction object, wraps it in an EIP-2718 envelope
       # with an EIP-1559 type prefix.
       #

data/lib/eth/tx/eip2930.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 The Ruby-Eth Contributors
+# Copyright (c) 2016-2025 The Ruby-Eth Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -76,7 +76,7 @@ module Eth
       # @option params [Integer] :gas_price the gas price.
       # @option params [Integer] :gas_limit the gas limit.
       # @option params [Eth::Address] :from the sender address.
-      # @option params [Eth::Address] :to the reciever address.
+      # @option params [Eth::Address] :to the receiver address.
       # @option params [Integer] :value the transaction value.
       # @option params [String] :data the transaction data payload.
       # @option params [Array] :access_list an optional access list.
@@ -145,12 +145,12 @@ module Eth
         raise ParameterError, "Transaction missing fields!" if tx.size < 8
 
         # populate the 8 payload fields
-        chain_id = Util.deserialize_big_endian_to_int tx[0]
-        nonce = Util.deserialize_big_endian_to_int tx[1]
-        gas_price = Util.deserialize_big_endian_to_int tx[2]
-        gas_limit = Util.deserialize_big_endian_to_int tx[3]
+        chain_id = Util.deserialize_rlp_int tx[0]
+        nonce = Util.deserialize_rlp_int tx[1]
+        gas_price = Util.deserialize_rlp_int tx[2]
+        gas_limit = Util.deserialize_rlp_int tx[3]
         to = Util.bin_to_hex tx[4]
-        value = Util.deserialize_big_endian_to_int tx[5]
+        value = Util.deserialize_rlp_int tx[5]
         data = tx[6]
         access_list = tx[7]
 
@@ -251,6 +251,31 @@ module Eth
         return hash
       end
 
+      # Signs the transaction with a provided signature blob.
+      #
+      # @param signature [String] the concatenated `r`, `s`, and `v` values.
+      # @return [String] a transaction hash.
+      # @raise [Signature::SignatureError] if transaction is already signed.
+      # @raise [Signature::SignatureError] if sender address does not match signer.
+      def sign_with(signature)
+        if Tx.signed? self
+          raise Signature::SignatureError, "Transaction is already signed!"
+        end
+
+        # ensure the sender address matches the signature
+        unless @sender.nil? or sender.empty?
+          public_key = Signature.recover(unsigned_hash, signature, @chain_id)
+          signer_address = Tx.sanitize_address Util.public_key_to_address(public_key).to_s
+          from_address = Tx.sanitize_address @sender
+          raise Signature::SignatureError, "Signer does not match sender" unless signer_address == from_address
+        end
+
+        r, s, v = Signature.dissect signature
+        recovery_id = Chain.to_recovery_id v.to_i(16), @chain_id
+        send :_set_signature, recovery_id, r, s
+        return hash
+      end
+
       # Encodes a raw transaction object, wraps it in an EIP-2718 envelope
       # with an EIP-2930 type prefix.
       #