eth-custom 0.5.7

data/lib/eth/tx/legacy.rb

@@ -0,0 +1,297 @@
+# Copyright (c) 2016-2022 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Provides the {Eth} module.
+module Eth
+
+  # Provides the `Tx` module supporting various transaction types.
+  module Tx
+
+    # Provides legacy support for transactions on blockchains that do not
+    # implement EIP-1559, EIP-2718, or EIP-2930.
+    class Legacy
+
+      # The transaction nonce provided by the signer.
+      attr_reader :signer_nonce
+
+      # The gas price for the transaction in Wei.
+      attr_reader :gas_price
+
+      # The gas limit for the transaction.
+      attr_reader :gas_limit
+
+      # The recipient address.
+      attr_reader :destination
+
+      # The transaction amount in Wei.
+      attr_reader :amount
+
+      # The transaction data payload.
+      attr_reader :payload
+
+      # The signature `v` byte.
+      attr_reader :signature_v
+
+      # The signature `r` value.
+      attr_reader :signature_r
+
+      # The signature `s` value.
+      attr_reader :signature_s
+
+      # The EIP-155 chain ID field.
+      # Ref: https://eips.ethereum.org/EIPS/eip-155
+      attr_reader :chain_id
+
+      # The sender address.
+      attr_reader :sender
+
+      # The transaction type.
+      attr_reader :type
+
+      # Create a legacy transaction object that can be prepared for
+      # signature and broadcast. Should not be used unless there is
+      # no EIP-1559 support.
+      #
+      # @param params [Hash] all necessary transaction fields.
+      # @option params [Integer] :nonce the signer nonce.
+      # @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 [Integer] :value the transaction value.
+      # @option params [String] :data the transaction data payload.
+      # @param chain_id [Integer] the EIP-155 Chain ID.
+      # @raise [ParameterError] if gas limit is too low.
+      def initialize(params, chain_id = Chain::ETHEREUM)
+        fields = { v: chain_id, r: 0, s: 0 }.merge params
+
+        # populate optional fields with serializable empty values
+        fields[:value] = Tx.sanitize_amount fields[:value]
+        fields[:from] = Tx.sanitize_address fields[:from]
+        fields[:to] = Tx.sanitize_address fields[:to]
+        fields[:data] = Tx.sanitize_data fields[:data]
+
+        # ensure sane values for all mandatory fields
+        fields = Tx.validate_params fields
+        fields = Tx.validate_legacy_params fields
+
+        # ensure gas limit is not too low
+        minimum_cost = Tx.estimate_intrinsic_gas fields[:data]
+        raise ParameterError, "Transaction gas limit is too low, try #{minimum_cost}!" if fields[:gas_limit].to_i < minimum_cost
+
+        # populate class attributes
+        @signer_nonce = fields[:nonce].to_i
+        @gas_price = fields[:gas_price].to_i
+        @gas_limit = fields[:gas_limit].to_i
+        @sender = fields[:from].to_s
+        @destination = fields[:to].to_s
+        @amount = fields[:value].to_i
+        @payload = fields[:data]
+
+        # the signature v is set to the chain id for unsigned transactions
+        @signature_v = fields[:v]
+        @chain_id = chain_id
+
+        # the signature fields are empty for unsigned transactions.
+        @signature_r = fields[:r]
+        @signature_s = fields[:s]
+
+        # last but not least, set the type.
+        @type = TYPE_LEGACY
+      end
+
+      # overloads the constructor for decoding raw transactions and creating unsigned copies
+      konstructor :decode, :unsigned_copy
+
+      # Decodes a raw transaction hex into an {Eth::Tx::Legacy}
+      # transaction object.
+      #
+      # @param hex [String] the raw transaction hex-string.
+      # @return [Eth::Tx::Legacy] transaction object.
+      # @raise [ParameterError] if transaction misses fields.
+      def decode(hex)
+        bin = Util.hex_to_bin hex
+        tx = Rlp.decode bin
+
+        # decoded transactions always have 9 fields, even if they are empty or zero
+        raise ParameterError, "Transaction missing fields!" if tx.size < 9
+
+        # populate the 9 fields
+        nonce = Util.deserialize_big_endian_to_int tx[0]
+        gas_price = Util.deserialize_big_endian_to_int tx[1]
+        gas_limit = Util.deserialize_big_endian_to_int tx[2]
+        to = Util.bin_to_hex tx[3]
+        value = Util.deserialize_big_endian_to_int tx[4]
+        data = tx[5]
+        v = Util.bin_to_hex tx[6]
+        r = Util.bin_to_hex tx[7]
+        s = Util.bin_to_hex tx[8]
+
+        # try to recover the chain id from v
+        chain_id = Chain.to_chain_id Util.deserialize_big_endian_to_int tx[6]
+
+        # populate class attributes
+        @signer_nonce = nonce.to_i
+        @gas_price = gas_price.to_i
+        @gas_limit = gas_limit.to_i
+        @destination = to.to_s
+        @amount = value.to_i
+        @payload = data
+        @chain_id = chain_id
+
+        # allows us to force-setting a signature if the transaction is signed already
+        _set_signature(v, r, s)
+
+        unless chain_id.nil?
+
+          # recover sender address
+          public_key = Signature.recover(unsigned_hash, "#{r.rjust(64, "0")}#{s.rjust(64, "0")}#{v}", chain_id)
+          address = Util.public_key_to_address(public_key).to_s
+          @sender = Tx.sanitize_address address
+        else
+
+          # keep the 'from' field blank
+          @sender = Tx.sanitize_address nil
+        end
+
+        # last but not least, set the type.
+        @type = TYPE_LEGACY
+      end
+
+      # Creates an unsigned copy of a transaction.
+      #
+      # @param tx [Eth::Tx::Legacy] an legacy transaction object.
+      # @return [Eth::Tx::Legacy] an unsigned transaction object.
+      # @raise [TransactionTypeError] if transaction type does not match.
+      def unsigned_copy(tx)
+
+        # not checking transaction validity unless it's of a different class
+        raise TransactionTypeError, "Cannot copy transaction of different type!" unless tx.instance_of? Tx::Legacy
+
+        # populate class attributes
+        @signer_nonce = tx.signer_nonce
+        @gas_price = tx.gas_price
+        @gas_limit = tx.gas_limit
+        @destination = tx.destination
+        @amount = tx.amount
+        @payload = tx.payload
+        @chain_id = tx.chain_id
+
+        # force-set signature to unsigned
+        _set_signature(tx.chain_id, 0, 0)
+
+        # keep the 'from' field blank
+        @sender = Tx.sanitize_address nil
+
+        # last but not least, set the type.
+        @type = TYPE_LEGACY
+      end
+
+      # Sign the transaction with a given key.
+      #
+      # @param key [Eth::Key] the key-pair to use for signing.
+      # @return [String] a transaction hash.
+      # @raise [Signature::SignatureError] if transaction is already signed.
+      # @raise [Signature::SignatureError] if sender address does not match signing key.
+      def sign(key)
+        if Tx.is_signed? self
+          raise Signature::SignatureError, "Transaction is already signed!"
+        end
+
+        # ensure the sender address matches the given key
+        unless @sender.nil? or sender.empty?
+          signer_address = Tx.sanitize_address key.address.to_s
+          from_address = Tx.sanitize_address @sender
+          raise Signature::SignatureError, "Signer does not match sender" unless signer_address == from_address
+        end
+
+        # sign a keccak hash of the unsigned, encoded transaction
+        signature = key.sign(unsigned_hash, @chain_id)
+        r, s, v = Signature.dissect signature
+        @signature_v = v
+        @signature_r = r
+        @signature_s = s
+        return hash
+      end
+
+      # Encodes a raw transaction object.
+      #
+      # @return [String] a raw, RLP-encoded legacy transaction.
+      # @raise [Signature::SignatureError] if the transaction is not yet signed.
+      def encoded
+        unless Tx.is_signed? self
+          raise Signature::SignatureError, "Transaction is not signed!"
+        end
+        tx_data = []
+        tx_data.push Util.serialize_int_to_big_endian @signer_nonce
+        tx_data.push Util.serialize_int_to_big_endian @gas_price
+        tx_data.push Util.serialize_int_to_big_endian @gas_limit
+        tx_data.push Util.hex_to_bin @destination
+        tx_data.push Util.serialize_int_to_big_endian @amount
+        tx_data.push Rlp::Sedes.binary.serialize @payload
+        tx_data.push Util.serialize_int_to_big_endian @signature_v
+        tx_data.push Util.serialize_int_to_big_endian @signature_r
+        tx_data.push Util.serialize_int_to_big_endian @signature_s
+        Rlp.encode tx_data
+      end
+
+      # Gets the encoded, raw transaction hex.
+      #
+      # @return [String] the raw transaction hex.
+      def hex
+        Util.bin_to_hex encoded
+      end
+
+      # Gets the transaction hash.
+      #
+      # @return [String] the transaction hash.
+      def hash
+        Util.bin_to_hex Util.keccak256 encoded
+      end
+
+      # Encodes the unsigned transaction object, required for signing.
+      #
+      # @return [String] an RLP-encoded, unsigned transaction.
+      def unsigned_encoded
+        tx_data = []
+        tx_data.push Util.serialize_int_to_big_endian @signer_nonce
+        tx_data.push Util.serialize_int_to_big_endian @gas_price
+        tx_data.push Util.serialize_int_to_big_endian @gas_limit
+        tx_data.push Util.hex_to_bin @destination
+        tx_data.push Util.serialize_int_to_big_endian @amount
+        tx_data.push Rlp::Sedes.binary.serialize @payload
+        tx_data.push Util.serialize_int_to_big_endian @chain_id
+        tx_data.push Util.serialize_int_to_big_endian 0
+        tx_data.push Util.serialize_int_to_big_endian 0
+        Rlp.encode tx_data
+      end
+
+      # Gets the sign-hash required to sign a raw transaction.
+      #
+      # @return [String] a Keccak-256 hash of an unsigned transaction.
+      def unsigned_hash
+        Util.keccak256 unsigned_encoded
+      end
+
+      private
+
+      # Force-sets an existing signature of a decoded transaction.
+      def _set_signature(v, r, s)
+        @signature_v = v
+        @signature_r = r
+        @signature_s = s
+      end
+    end
+  end
+end

data/lib/eth/tx.rb

@@ -0,0 +1,322 @@
+# Copyright (c) 2016-2022 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "konstructor"
+
+require "eth/chain"
+require "eth/tx/eip1559"
+require "eth/tx/eip2930"
+require "eth/tx/legacy"
+require "eth/unit"
+
+# Provides the {Eth} module.
+module Eth
+
+  # Provides the `Tx` module supporting various transaction types.
+  module Tx
+    extend self
+
+    # Provides a special transaction error if transaction type is unknown.
+    class TransactionTypeError < TypeError; end
+
+    # Provides an decoder error if transaction cannot be decoded.
+    class DecoderError < StandardError; end
+
+    # Provides a parameter error if parameter types are invalid.
+    class ParameterError < TypeError; end
+
+    # The minimum transaction gas limit required for a value transfer.
+    DEFAULT_GAS_LIMIT = 21_000.freeze
+
+    # The "default" transaction gas price of 20 GWei. Do not use.
+    DEFAULT_GAS_PRICE = (20 * Unit::GWEI).freeze
+
+    # The calldata gas cost of a non-zero byte as per EIP-2028.
+    COST_NON_ZERO_BYTE = 16.freeze
+
+    # The calldata gas cost of a zero byte.
+    COST_ZERO_BYTE = 4.freeze
+
+    # The access list gas cost of a storage key as per EIP-2930.
+    COST_STORAGE_KEY = 1_900.freeze
+
+    # The access list gas cost of an address as per EIP-2930.
+    COST_ADDRESS = 2_400.freeze
+
+    # The maximum transaction gas limit is bound by the block gas limit.
+    BLOCK_GAS_LIMIT = 25_000_000.freeze
+
+    # The legacy transaction type is 0.
+    TYPE_LEGACY = 0x00.freeze
+
+    # The EIP-2930 transaction type is 1.
+    TYPE_2930 = 0x01.freeze
+
+    # The EIP-1559 transaction type is 2.
+    TYPE_1559 = 0x02.freeze
+
+    # The zero byte is 0x00.
+    ZERO_BYTE = "\x00".freeze
+
+    # Smart contract transaction gas cost
+    CREATE_GAS = 32_000.freeze
+
+    # Creates a new transaction of any type for given parameters and chain ID.
+    # Required parameters are (optional in brackets):
+    # - EIP-1559: chain_id, nonce, priority_fee, max_gas_fee, gas_limit(, from, to,
+    #   value, data, access_list)
+    # - EIP-2930: chain_id, nonce, gas_price, gas_limit, access_list(, from, to,
+    #   value, data)
+    # - Legacy: nonce, gas_price, gas_limit(, from, to, value, data)
+    #
+    # @param params [Hash] all necessary transaction fields.
+    # @param chain_id [Integer] the EIP-155 Chain ID (legacy transactions only).
+    def new(params, chain_id = Chain::ETHEREUM)
+
+      # if we deal with max gas fee parameter, attempt EIP-1559
+      unless params[:max_gas_fee].nil?
+        params[:chain_id] = chain_id if params[:chain_id].nil?
+        return Tx::Eip1559.new params
+      end
+
+      # if we deal with access list parameter, attempt EIP-2930
+      unless params[:access_list].nil?
+        params[:chain_id] = chain_id if params[:chain_id].nil?
+        return Tx::Eip2930.new params
+      end
+
+      # if nothing else, go with legacy transactions
+      chain_id = params[:chain_id] if !params[:chain_id].nil? and params[:chain_id] != chain_id
+      return Tx::Legacy.new params, chain_id
+    end
+
+    # Decodes a transaction hex of any known type (2, 1, or legacy).
+    #
+    # @param hex [String] the raw transaction hex-string.
+    # @return [Eth::Tx] transaction payload.
+    # @raise [TransactionTypeError] if the transaction type is unknown.
+    def decode(hex)
+      hex = Util.remove_hex_prefix hex
+      type = hex[0, 2].to_i(16)
+      case type
+      when TYPE_1559
+
+        # EIP-1559 transaction (type 2)
+        return Tx::Eip1559.decode hex
+      when TYPE_2930
+
+        # EIP-2930 transaction (type 1)
+        return Tx::Eip2930.decode hex
+      else
+
+        # Legacy transaction if first byte is RLP (>= 192)
+        if type >= 0xc0
+          return Tx::Legacy.decode hex
+        else
+          raise TransactionTypeError, "Cannot decode unknown transaction type #{type}!"
+        end
+      end
+    end
+
+    # Creates an unsigned copy of any transaction object.
+    #
+    # @param tx [Eth::Tx] any transaction payload.
+    # @return [Eth::Tx] an unsigned transaction payload of the same type.
+    # @raise [TransactionTypeError] if the transaction type is unknown.
+    def unsigned_copy(tx)
+      case tx.type
+      when TYPE_1559
+
+        # EIP-1559 transaction (type 2)
+        return Tx::Eip1559.unsigned_copy tx
+      when TYPE_2930
+
+        # EIP-2930 transaction (type 1)
+        return Tx::Eip2930.unsigned_copy tx
+      when TYPE_LEGACY
+
+        # Legacy transaction ("type 0")
+        return Tx::Legacy.unsigned_copy tx
+      end
+      raise TransactionTypeError, "Cannot copy unknown transaction type #{tx.type}!"
+    end
+
+    # Estimates intrinsic gas for provided call data (EIP-2028) and
+    # access lists (EIP-2930).
+    #
+    # @param data [String] the call data.
+    # @param list [Array] the access list.
+    # @return [Integer] the estimated intrinsic gas cost.
+    def estimate_intrinsic_gas(data = "", list = [])
+      gas = DEFAULT_GAS_LIMIT
+      unless data.nil? or data.empty?
+        data = Util.hex_to_bin data if Util.is_hex? data
+
+        # count zero bytes
+        zero = data.count ZERO_BYTE
+        gas += zero * COST_ZERO_BYTE
+
+        # count non-zero bytes
+        none = data.size - zero
+        gas += none * COST_NON_ZERO_BYTE
+      end
+      unless list.nil? or list.empty?
+        list.each do |entry|
+
+          # count addresses
+          gas += COST_ADDRESS
+
+          entry.last.each do |key|
+
+            # count storage keys
+            gas += COST_STORAGE_KEY
+          end
+        end
+      end
+      return gas
+    end
+
+    # Validates the common transaction fields such as nonce, gas limit,
+    # amount, and access list.
+    #
+    # @param fields [Hash] the transaction fields.
+    # @return [Hash] the validated transaction fields.
+    # @raise [ParameterError] if nonce is an invalid integer.
+    # @raise [ParameterError] if gas limit is invalid.
+    # @raise [ParameterError] if amount is invalid.
+    # @raise [ParameterError] if access list is invalid.
+    def validate_params(fields)
+      if fields[:nonce].nil? or fields[:nonce] < 0
+        raise ParameterError, "Invalid signer nonce #{fields[:nonce]}!"
+      end
+      if fields[:gas_limit].nil? or fields[:gas_limit] < DEFAULT_GAS_LIMIT or fields[:gas_limit] > BLOCK_GAS_LIMIT
+        raise ParameterError, "Invalid gas limit #{fields[:gas_limit]}!"
+      end
+      unless fields[:value] >= 0
+        raise ParameterError, "Invalid transaction value #{fields[:value]}!"
+      end
+      unless fields[:access_list].nil? or fields[:access_list].is_a? Array
+        raise ParameterError, "Invalid access list #{fields[:access_list]}!"
+      end
+      return fields
+    end
+
+    # Validates the common type-2 transaction fields such as priority
+    # fee and max gas fee.
+    #
+    # @param fields [Hash] the transaction fields.
+    # @return [Hash] the validated transaction fields.
+    # @raise [ParameterError] if priority fee is invalid.
+    # @raise [ParameterError] if max gas fee is invalid.
+    def validate_eip1559_params(fields)
+      if fields[:priority_fee].nil? or fields[:priority_fee] < 0
+        raise ParameterError, "Invalid gas priority fee #{fields[:priority_fee]}!"
+      end
+      if fields[:max_gas_fee].nil? or fields[:max_gas_fee] < 0
+        raise ParameterError, "Invalid max gas fee #{fields[:max_gas_fee]}!"
+      end
+      return fields
+    end
+
+    # Validates the common legacy transaction fields such as gas price.
+    #
+    # @param fields [Hash] the transaction fields.
+    # @return [Hash] the validated transaction fields.
+    # @raise [ParameterError] if gas price is invalid.
+    def validate_legacy_params(fields)
+      if fields[:gas_price].nil? or fields[:gas_price] < 0
+        raise ParameterError, "Invalid gas price #{fields[:gas_price]}!"
+      end
+      return fields
+    end
+
+    # Populates the transaction chain id field with a serializable default
+    # value (1) in case it is undefined.
+    #
+    # @param id [Integer] the transaction chain id.
+    # @return [Integer] the sanitized transaction chain id.
+    def sanitize_chain(id)
+      id = Chain::ETHEREUM if id.nil?
+      return id
+    end
+
+    # Populates the transaction destination address with a serializable
+    # empty value in case it is undefined; also ensures the address is
+    # checksummed but not prefixed for consistency.
+    #
+    # @param addr [String] the transaction destination address.
+    # @return [String] the sanitized transaction destination address.
+    def sanitize_address(addr)
+      addr = "" if addr.nil?
+      if addr.is_a? String and !addr.empty?
+        addr = Address.new(addr).to_s
+        addr = Util.remove_hex_prefix addr
+      end
+      return addr
+    end
+
+    # Populates the transaction value field with a serializable empty value
+    # in case it is undefined.
+    #
+    # @param val [Integer] the transaction value.
+    # @return [Integer] the sanitized transaction value.
+    def sanitize_amount(val)
+      val = 0 if val.nil?
+      return val
+    end
+
+    # Populates the transaction payload field with a serializable empty value
+    # in case it is undefined; also ensures the data is binary not hex.
+    #
+    # @param data [String] the transaction payload data.
+    # @return [String] the sanitized transaction payload data.
+    def sanitize_data(data)
+      data = "" if data.nil?
+
+      # ensure payload to be binary if it's hex, otherwise we'll treat it raw
+      data = Util.hex_to_bin data if Util.is_hex? data
+      return data
+    end
+
+    # Populates the transaction access list field with a serializable empty
+    # array in case it is undefined; also ensures the nested data is binary
+    # not hex.
+    #
+    # @param list [Array] the transaction access list.
+    # @return [Array] the sanitized transaction access list.
+    def sanitize_list(list)
+      list = [] if list.nil?
+      list.each_with_index do |value, index|
+        if value.is_a? Array
+
+          # recursively check the entire array
+          list[index] = sanitize_list value
+        elsif Util.is_hex? value
+
+          # only modify if we find a hex value
+          list[index] = Util.hex_to_bin value
+        end
+      end
+      return list
+    end
+
+    # Allows to check wether a transaction is signed already.
+    #
+    # @return [Bool] true if transaction is already signed.
+    def is_signed?(tx)
+      !tx.signature_r.nil? and tx.signature_r != 0 and
+      !tx.signature_s.nil? and tx.signature_s != 0
+    end
+  end
+end

data/lib/eth/unit.rb

@@ -0,0 +1,49 @@
+# Copyright (c) 2016-2022 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "bigdecimal"
+
+# Provides the {Eth} module.
+module Eth
+
+  # Provides constants for common Ethereum units.
+  module Unit
+    extend self
+
+    # Ethereum unit 1 wei := 0.000000000000000001 Ether.
+    WEI = BigDecimal("1e0").freeze
+
+    # Ethereum unit 1 babbage := 0.000000000000001 Ether or 1_000 wei.
+    BABBAGE = BigDecimal("1e3").freeze
+
+    # Ethereum unit 1 lovelace := 0.000000000001 Ether or 1_000_000 wei.
+    LOVELACE = BigDecimal("1e6").freeze
+
+    # Ethereum unit 1 shannon := 0.000000001 Ether or 1_000_000_000 wei.
+    SHANNON = BigDecimal("1e9").freeze
+
+    # Ethereum unit 1 szabo := 0.000_001 Ether or 1_000_000_000_000 wei.
+    SZABO = BigDecimal("1e12").freeze
+
+    # Ethereum unit 1 finney := 0.001 Ether or 1_000_000_000_000_000 wei.
+    FINNEY = BigDecimal("1e15").freeze
+
+    # Ethereum unit 1 Ether := 1_000_000_000_000_000_000 wei.
+    ETHER = BigDecimal("1e18").freeze
+
+    # Ethereum unit 1 Gwei := 0.000000001 Ether or 1_000_000_000 wei.
+    # Same as shannon, but more commonly used (billion wei).
+    GWEI = SHANNON.freeze
+  end
+end