eth 0.4.12 → 0.5.0

data/lib/eth/tx.rb

@@ -1,197 +1,328 @@
+# 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 "rlp"
+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
-  class Tx
 
-    include RLP::Sedes::Serializable
-    extend Sedes
+  # Provides the `Tx` module supporting various transaction types.
+  module Tx
+    extend self
 
-    set_serializable_fields({
-      nonce: big_endian_int,
-      gas_price: big_endian_int,
-      gas_limit: big_endian_int,
-      to: address,
-      value: big_endian_int,
-      data_bin: binary,
-      v: big_endian_int,
-      r: big_endian_int,
-      s: big_endian_int
-    })
+    # Provides a special transactoin error if transaction type is unknown.
+    class TransactionTypeError < TypeError; end
 
-    attr_writer :signature
+    # Provides an decoder error if transaction cannot be decoded.
+    class DecoderError < StandardError; end
 
-    def self.decode(data)
-      data = Utils.hex_to_bin(data) if data.match(/\A(?:0x)?\h+\Z/)
-      txh = deserialize(RLP.decode data).to_h
+    # Provides a parameter error if parameter types are invalid.
+    class ParameterError < TypeError; end
 
-      txh[:chain_id] = Eth.chain_id_from_signature(txh)
+    # The minimum transaction gas limit required for a value transfer.
+    DEFAULT_GAS_LIMIT = 21_000.freeze
 
-      self.new txh
-    end
+    # The "default" transaction gas price of 20 GWei. Do not use.
+    DEFAULT_GAS_PRICE = (20 * Unit::GWEI).freeze
 
-    def initialize(params)
-      fields = {v: 0, r: 0, s: 0}.merge params
-      fields[:to] = Utils.normalize_address(fields[:to])
+    # The calldata gas cost of a non-zero byte as per EIP-2028.
+    COST_NON_ZERO_BYTE = 16.freeze
 
-      self.chain_id = (params[:chain_id]) ? params.delete(:chain_id) : Eth.chain_id
+    # The calldata gas cost of a zero byte.
+    COST_ZERO_BYTE = 4.freeze
 
-      if params[:data]
-        self.data = params.delete(:data)
-        fields[:data_bin] = data_bin
-      end
-      serializable_initialize fields
+    # The access list gas cost of a storage key as per EIP-2930.
+    COST_STORAGE_KEY = 1_900.freeze
 
-      check_transaction_validity
-    end
+    # The access list gas cost of an address as per EIP-2930.
+    COST_ADDRESS = 2_400.freeze
 
-    def unsigned_encoded
-      us = unsigned
-      RLP.encode(us, sedes: us.sedes)
-    end
+    # The maximum transaction gas limit is bound by the block gas limit.
+    BLOCK_GAS_LIMIT = 25_000_000.freeze
 
-    def signing_data
-      Utils.bin_to_prefixed_hex unsigned_encoded
-    end
+    # The legacy transaction type is 0.
+    TYPE_LEGACY = 0x00.freeze
 
-    def encoded
-      RLP.encode self
-    end
+    # The EIP-2930 transaction type is 1.
+    TYPE_2930 = 0x01.freeze
 
-    def hex
-      Utils.bin_to_prefixed_hex encoded
-    end
+    # The EIP-1559 transaction type is 2.
+    TYPE_1559 = 0x02.freeze
 
-    def sign(key)
-      sig = key.sign(unsigned_encoded)
-      vrs = Utils.v_r_s_for sig
-      self.v = (self.chain_id) ? ((self.chain_id * 2) + vrs[0] + 8) : vrs[0]
-      self.r = vrs[1]
-      self.s = vrs[2]
+    # The zero byte is 0x00.
+    ZERO_BYTE = "\x00".freeze
 
-      clear_signature
-      self
-    end
+    # 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_lmit(, 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)
 
-    def to_h
-      hash_keys.inject({}) do |hash, field|
-        hash[field] = send field
-        hash
+      # 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
-    end
 
-    def from
-      if ecdsa_signature
-        public_key = OpenSsl.recover_compact(signature_hash, ecdsa_signature)
-        Utils.public_key_to_address(public_key) if public_key
+      # 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
-    end
 
-    def signature
-      return @signature if @signature
-      @signature = { v: v, r: r, s: s } if [v, r, s].all? && (v > 0)
+      # 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
 
-    def ecdsa_signature
-      return @ecdsa_signature if @ecdsa_signature
+    # 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
 
-      if [v, r, s].all? && (v > 0)
-        s_v = (self.chain_id) ? (v - (self.chain_id * 2) - 8) : v
-        @ecdsa_signature = [
-          Utils.int_to_base256(s_v),
-          Utils.zpad_int(r),
-          Utils.zpad_int(s),
-        ].join
+        # 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
 
-    def hash
-      "0x#{Utils.bin_to_hex Utils.keccak256_rlp(self)}"
-    end
-    alias_method :id, :hash
-
-    def data_hex
-      Utils.bin_to_prefixed_hex data_bin
-    end
-
-    def data_hex=(hex)
-      self.data_bin = Utils.hex_to_bin(hex)
-    end
-
-    def data
-      Eth.tx_data_hex? ? data_hex : data_bin
+    # 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
 
-    def data=(string)
-      Eth.tx_data_hex? ? self.data_hex=(string) : self.data_bin=(string)
-    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|
 
-    def chain_id
-      @chain_id
-    end
+          # count addresses
+          gas += COST_ADDRESS
 
-    def chain_id=(cid)
-      if cid != @chain_id
-        self.v = 0
-        self.r = 0
-        self.s = 0
+          entry.last.each do |key|
 
-        clear_signature
+            # count storage keys
+            gas += COST_STORAGE_KEY
+          end
+        end
       end
-
-      @chain_id = (cid == 0) ? nil : cid
+      return gas
     end
 
-    def prevent_replays?
-      !self.chain_id.nil?
+    # Validates the common type-2 transaction fields such as nonce, priority
+    # fee, max gas fee, 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 priority fee is invalid.
+    # @raise [ParameterError] if max gas fee is invalid.
+    # @raise [ParameterError] if gas limit is invalid.
+    # @raise [ParameterError] if amount is invalid.
+    # @raise [ParameterError] if access list is invalid.
+    def validate_params(fields)
+      unless fields[:nonce] >= 0
+        raise ParameterError, "Invalid signer nonce #{fields[:nonce]}!"
+      end
+      unless fields[:priority_fee] >= 0
+        raise ParameterError, "Invalid gas priority fee #{fields[:priority_fee]}!"
+      end
+      unless fields[:max_gas_fee] >= 0
+        raise ParameterError, "Invalid max gas fee #{fields[:max_gas_fee]}!"
+      end
+      unless fields[:gas_limit] >= DEFAULT_GAS_LIMIT and 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
 
-    private
-
-    def clear_signature
-      @signature = nil
-      @ecdsa_signature = nil
+    # Validates the common legacy transaction fields such as nonce, gas
+    # price, 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 price is invalid.
+    # @raise [ParameterError] if gas limit is invalid.
+    # @raise [ParameterError] if amount is invalid.
+    # @raise [ParameterError] if access list is invalid.
+    def validate_legacy_params(fields)
+      unless fields[:nonce] >= 0
+        raise ParameterError, "Invalid signer nonce #{fields[:nonce]}!"
+      end
+      unless fields[:gas_price] >= 0
+        raise ParameterError, "Invalid gas price #{fields[:gas_price]}!"
+      end
+      unless fields[:gas_limit] >= DEFAULT_GAS_LIMIT and 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
 
-    def hash_keys
-      keys = self.class.serializable_fields.keys
-      keys.delete(:data_bin)
-      keys + [:data, :chain_id]
+    # 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
 
-    def check_transaction_validity
-      if [gas_price, gas_limit, value, nonce].max > UINT_MAX
-        raise InvalidTransaction, "Values way too high!"
-      elsif gas_limit < intrinsic_gas_used
-        raise InvalidTransaction, "Gas limit too low"
+    # 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
 
-    def intrinsic_gas_used
-      num_zero_bytes = data_bin.count(BYTE_ZERO)
-      num_non_zero_bytes = data_bin.size - num_zero_bytes
-
-      Gas::GTXCOST +
-        Gas::GTXDATAZERO * num_zero_bytes +
-        Gas::GTXDATANONZERO * num_non_zero_bytes
-    end
-
-    def signature_hash
-      Utils.keccak256 unsigned_encoded
+    # 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
 
-    def unsigned
-      Tx.new to_h.merge(v: (self.chain_id) ? self.chain_id : 0, r: 0, s: 0)
+    # 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
 
-    protected
-
-    def sedes
-      if self.prevent_replays? && !(Eth.replayable_v? v)
-        self.class
-      else
-        UnsignedTx
+    # 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
-
-  UnsignedTx = Tx.exclude([:v, :r, :s])
 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