block_given 0.1.0 → 0.2.0

data/lib/block_given/transaction_envelope.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # Serialization, signing and decoding of the two transaction types the gem sends: EIP-1559 (type 2) and
+  # legacy (type 0) with EIP-155 replay protection.
+  #
+  # Parameters use the shape of {Wallet#prepare_transaction} (`:to`, `:value`, `:data`, `:chain_id`, `:nonce`,
+  # `:gas`, `:access_list`, plus `:gas_price` for legacy or the two EIP-1559 fee fields).
+  #
+  # Access lists are given and returned as `[{ address: "0x...", storage_keys: ["0x..."] }]`; the RLP form
+  # `[["0x...", ["0x..."]]]` and camelCase or String keys (`storageKeys`) are accepted as input too.
+  #
+  # @api private
+  module TransactionEnvelope
+    # EIP-2718 type byte of EIP-1559 transactions.
+    TYPE_EIP1559 = 2
+
+    module_function
+
+    # Signs a transaction.
+    #
+    # @param params [Hash{Symbol => Object}] resolved parameters ({Wallet#prepare_transaction}); `:gas_price`
+    #   selects a legacy transaction
+    # @param private_key [Integer] the signing key
+    # @return [String] the signed transaction bytes as `0x` hex
+    # @raise [BlockGiven::InvalidArgumentError] when a field is negative or the gas limit is below the
+    #   intrinsic gas of the transaction
+    def sign(params, private_key)
+      Fields.validate!(params)
+      if params[:gas_price]
+        sign_legacy(params, private_key)
+      else
+        sign_eip1559(params, private_key)
+      end
+    end
+
+    # Decodes signed transaction bytes and recovers the sender.
+    #
+    # @param raw [String] the signed transaction as hex, with or without `0x`
+    # @return [Hash{Symbol => Object}] the {Wallet#prepare_transaction} shape (`:from` checksummed, `:to` nil
+    #   for a contract creation, `:data` `""` when empty, `:access_list` nil when empty)
+    # @raise [BlockGiven::InvalidArgumentError] for malformed bytes, an unsupported transaction type or a
+    #   signature that recovers no key
+    def decode(raw)
+      hex = Utils.strip_hex(raw.to_s)
+      raise InvalidArgumentError, "not an even-length hex string" unless hex.match?(/\A(?:[0-9a-fA-F]{2})*\z/)
+
+      bytes = Utils.hex_to_bin(hex)
+      first = bytes.getbyte(0)
+      raise InvalidArgumentError, "empty transaction" if first.nil?
+      return decode_eip1559(bytes.byteslice(1..)) if first == TYPE_EIP1559
+      return decode_legacy(bytes) if first >= 0xc0
+
+      raise InvalidArgumentError, "unsupported transaction type #{first}"
+    end
+
+    # Signs an EIP-1559 transaction.
+    #
+    # @param params [Hash{Symbol => Object}]
+    # @param private_key [Integer]
+    # @return [String] `0x02...` hex
+    def sign_eip1559(params, private_key)
+      fields = [
+        params[:chain_id], params[:nonce], params[:max_priority_fee_per_gas], params[:max_fee_per_gas],
+        params[:gas], address_bytes(params[:to]), params[:value], Utils.hex_to_bin(params[:data].to_s),
+        Fields.rlp_access_list(params[:access_list])
+      ]
+      r, s, recovery_id = Crypto::Secp256k1.sign(Crypto::Keccak.digest(typed(fields)), private_key)
+      Utils.bin_to_hex(typed(fields + [recovery_id, r, s]))
+    end
+
+    # Signs a legacy transaction with EIP-155 replay protection (`v = recovery_id + 35 + 2 * chain_id`).
+    #
+    # @param params [Hash{Symbol => Object}]
+    # @param private_key [Integer]
+    # @return [String] RLP list hex
+    def sign_legacy(params, private_key)
+      fields = [
+        params[:nonce], params[:gas_price], params[:gas], address_bytes(params[:to]), params[:value],
+        Utils.hex_to_bin(params[:data].to_s)
+      ]
+      chain_id = params[:chain_id]
+      r, s, recovery_id = Crypto::Secp256k1.sign(Crypto::Keccak.digest(Rlp.encode(fields + [chain_id, 0, 0])),
+                                                 private_key)
+      Utils.bin_to_hex(Rlp.encode(fields + [recovery_id + 35 + (2 * chain_id), r, s]))
+    end
+
+    # Decodes the RLP payload of an EIP-1559 transaction (type byte removed).
+    #
+    # @param payload [String] binary
+    # @return [Hash{Symbol => Object}]
+    # @raise [BlockGiven::InvalidArgumentError] when the payload is not a 12-field list
+    def decode_eip1559(payload)
+      fields = Rlp.decode(payload)
+      unless fields.is_a?(Array) && fields.size == 12
+        raise InvalidArgumentError,
+              "EIP-1559 transaction must have 12 fields"
+      end
+
+      chain_id, nonce, priority, max_fee, gas, = fields.first(5).map { |f| Rlp.to_int(f) }
+      y_parity, r, s = fields.last(3).map { |f| Rlp.to_int(f) }
+      raise InvalidArgumentError, "invalid y parity #{y_parity}" if y_parity > 1
+
+      sender = recover_address(typed(fields.first(9)), r, s, y_parity)
+      access_list = Fields.parse_access_list(fields[8])
+      common_params(sender, fields[5], fields[6], fields[7]).merge(
+        chain_id: chain_id, nonce: nonce, gas: gas, max_fee_per_gas: max_fee, max_priority_fee_per_gas: priority,
+        access_list: access_list.empty? ? nil : access_list
+      )
+    end
+
+    # Decodes a legacy transaction, with (EIP-155) or without replay protection.
+    #
+    # @param bytes [String] binary RLP list
+    # @return [Hash{Symbol => Object}] `:chain_id` is nil for a transaction signed without replay protection
+    # @raise [BlockGiven::InvalidArgumentError] when the list does not have 9 fields or `v` is invalid
+    def decode_legacy(bytes)
+      fields = Rlp.decode(bytes)
+      raise InvalidArgumentError, "legacy transaction must have 9 fields" unless fields.is_a?(Array) && fields.size == 9
+
+      nonce, gas_price, gas = fields.first(3).map { |f| Rlp.to_int(f) }
+      v, r, s = fields.last(3).map { |f| Rlp.to_int(f) }
+      chain_id, recovery_id, unsigned = legacy_signing_payload(fields.first(6), v)
+      sender = recover_address(Rlp.encode(unsigned), r, s, recovery_id)
+      common_params(sender, fields[3], fields[4], fields[5]).merge(
+        chain_id: chain_id, nonce: nonce, gas: gas, gas_price: gas_price, access_list: nil
+      )
+    end
+
+    # The chain id, recovery id and unsigned field list of a legacy transaction, from its `v`.
+    #
+    # @param fields [Array<String>] the six unsigned fields
+    # @param v [Integer]
+    # @return [Array(Integer, Integer, Array)] chain id (nil for `v` 27 or 28), recovery id, fields to hash
+    # @raise [BlockGiven::InvalidArgumentError] when `v` is neither 27, 28 nor an EIP-155 value
+    def legacy_signing_payload(fields, v)
+      return [nil, v - 27, fields] if [27, 28].include?(v)
+      raise InvalidArgumentError, "invalid legacy signature v #{v}" if v < 37
+
+      chain_id = (v - 35) / 2
+      [chain_id, (v - 35) % 2, fields + [chain_id, 0, 0]]
+    end
+
+    # Fields both transaction types share, formatted.
+    #
+    # @param sender [String] checksummed sender
+    # @param to [String] binary destination (empty for a creation)
+    # @param value [String] binary amount
+    # @param data [String] binary calldata
+    # @return [Hash{Symbol => Object}]
+    # @raise [BlockGiven::InvalidArgumentError] when `to` is neither empty nor 20 bytes
+    def common_params(sender, to, value, data)
+      raise InvalidArgumentError, "invalid destination" unless to.is_a?(String) && [0, 20].include?(to.bytesize)
+      raise InvalidArgumentError, "invalid data field" unless data.is_a?(String)
+
+      {
+        from: sender, to: to.empty? ? nil : Utils.checksum_address(Utils.bin_to_hex(to)),
+        value: Rlp.to_int(value), data: data.empty? ? "" : Utils.bin_to_hex(data)
+      }
+    end
+
+    # Recovers the checksummed address that signed a payload.
+    #
+    # @param payload [String] the unsigned serialization, binary
+    # @param r [Integer]
+    # @param s [Integer]
+    # @param recovery_id [Integer]
+    # @return [String] the checksummed address
+    # @raise [BlockGiven::InvalidArgumentError] when no key can be recovered
+    def recover_address(payload, r, s, recovery_id)
+      public_key = Crypto::Secp256k1.recover(Crypto::Keccak.digest(payload), r, s, recovery_id)
+      Crypto.address(public_key)
+    end
+
+    # @param fields [Array] RLP items
+    # @return [String] the type-2 envelope: `0x02` followed by the RLP list, binary
+    def typed(fields) = TYPE_EIP1559.chr.b + Rlp.encode(fields)
+
+    # @param address [String, nil] hex address or nil for a contract creation
+    # @return [String] 20 binary bytes, or an empty String
+    def address_bytes(address) = address.nil? ? "".b : Utils.hex_to_bin(address)
+  end
+end

data/lib/block_given/utils.rb

@@ -4,26 +4,55 @@ require "bigdecimal"
 require "bigdecimal/util"
 
 module BlockGiven
-  # Stateless helpers, mirroring viem's `utils` (parseUnits, formatUnits, keccak256, ...).
+  # Stateless helpers mirroring viem's `utils`: hex and byte conversion, keccak256, addresses, unit parsing and
+  # formatting, block tags and name casing.
+  #
+  # Every method is a module function (`BlockGiven::Utils.parse_units(...)`). Hex values are `0x`-prefixed
+  # Strings, amounts are Integers in the smallest unit (wei for ETH), and addresses come back EIP-55
+  # checksummed.
+  #
+  # @example
+  #   BlockGiven::Utils.parse_units("1.5", 6)   # => 1_500_000
+  #   BlockGiven::Utils.format_ether(10**18)     # => "1"
+  #   BlockGiven::Utils.checksum_address("0xd8da6bf26964af9d7eed9e03e53415d37aa96045")
+  #   # => "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
   module Utils
     module_function
 
+    # The zero address (`address(0)`): 20 zero bytes, used as the `from` of mints and the `to` of burns.
     ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
+    # Block tags JSON-RPC accepts in place of a block number (see {.block_tag}).
     BLOCK_TAGS = %w[latest earliest pending safe finalized].freeze
 
+    # Whether a value is a `0x`-prefixed hexadecimal String (the empty `"0x"` counts).
+    #
+    # @param value [Object]
+    # @return [Boolean]
     def hex?(value)
       value.is_a?(String) && value.match?(/\A0x[0-9a-fA-F]*\z/)
     end
 
+    # Add the `0x` prefix to a hex string when it is missing.
+    #
+    # @param hex [String]
+    # @return [String]
     def prefix_hex(hex)
       hex.start_with?("0x") ? hex : "0x#{hex}"
     end
 
+    # Remove the `0x` prefix from a hex string when it is present.
+    #
+    # @param hex [String]
+    # @return [String]
     def strip_hex(hex)
       hex.start_with?("0x") ? hex[2..] : hex
     end
 
-    # Integer -> "0x1a" (no leading zeros, as JSON-RPC QUANTITY expects).
+    # Convert an Integer to a JSON-RPC QUANTITY (`26` -> `"0x1a"`, no leading zeros); Strings only get prefixed.
+    #
+    # @param value [Integer, String] Integer to encode, or hex String to `0x`-prefix
+    # @return [String]
+    # @raise [BlockGiven::InvalidArgumentError] for any other type
     def to_hex(value)
       case value
       when Integer then "0x#{value.to_s(16)}"
@@ -32,6 +61,10 @@ module BlockGiven
       end
     end
 
+    # Convert a hex QUANTITY to an Integer.
+    #
+    # @param hex [String, Integer, nil] hex String with or without `0x`; Integers pass through
+    # @return [Integer, nil] nil when `hex` is nil
     def hex_to_int(hex)
       return nil if hex.nil?
       return hex if hex.is_a?(Integer)
@@ -39,41 +72,87 @@ module BlockGiven
       Integer(strip_hex(hex), 16)
     end
 
+    # Decode a hex string into binary bytes.
+    #
+    # @param hex [String] hex with or without `0x`
+    # @return [String] binary (ASCII-8BIT) String
     def hex_to_bin(hex)
       [strip_hex(hex)].pack("H*")
     end
 
+    # Encode binary bytes as a `0x` hex string.
+    #
+    # @param bin [String] binary String
+    # @return [String] lowercase `0x` hex
     def bin_to_hex(bin)
       "0x#{bin.unpack1('H*')}"
     end
 
-    # Left-pads a hex value to 32 bytes (used for event topics).
+    # Left-pad a hex value with zeros to a fixed byte length, 32 bytes by default as event topics require.
+    #
+    # @param hex [String] hex with or without `0x`
+    # @param bytes [Integer] target length in bytes
+    # @return [String] `0x` followed by `bytes * 2` hex chars (longer inputs are returned with only the prefix
+    #   normalised)
     def pad_hex(hex, bytes: 32)
       "0x#{strip_hex(hex).rjust(bytes * 2, '0')}"
     end
 
-    # keccak256 of raw bytes (or of the bytes represented by a 0x hex string).
+    # keccak256 of raw bytes, or of the bytes a `0x` hex string represents.
+    #
+    # @param data [String] `0x` hex is decoded first; any other String is hashed as-is (e.g. an event signature)
+    # @return [String] 32-byte digest as a `0x` hex string
+    # @example
+    #   BlockGiven::Utils.keccak256("Transfer(address,address,uint256)")
+    #   # => "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
     def keccak256(data)
       bytes = hex?(data) ? hex_to_bin(data) : data.to_s
-      bin_to_hex(Eth::Util.keccak256(bytes))
+      bin_to_hex(Crypto::Keccak.digest(bytes))
     end
 
+    # Whether a value is a 20-byte hex address (`0x` + 40 hex chars); the EIP-55 checksum is not verified.
+    #
+    # @param value [Object]
+    # @return [Boolean]
     def address?(value)
       value.is_a?(String) && value.match?(/\A0x[0-9a-fA-F]{40}\z/)
     end
 
+    # Return the EIP-55 checksummed form of an address.
+    #
+    # @param value [String, #address] hex address in any casing, or an object responding to `address` such as a
+    #   {Wallet} or a {Contract}
+    # @return [String] checksummed `0x` address
+    # @raise [BlockGiven::InvalidAddressError] when the value is not a 20-byte hex address
     def checksum_address(value)
       value = value.address if value.respond_to?(:address) && !value.is_a?(String)
       raise InvalidAddressError, "invalid address: #{value.inspect}" unless address?(value)
 
-      Eth::Address.new(value).checksummed
+      hex = strip_hex(value).downcase
+      nibbles = Crypto::Keccak.digest(hex).unpack1("H*")
+      "0x#{hex.chars.each_with_index.map { |char, i| nibbles[i].to_i(16) >= 8 ? char.upcase : char }.join}"
     end
 
+    # Compare two addresses ignoring checksum casing.
+    #
+    # @param a [String, #to_s]
+    # @param b [String, #to_s]
+    # @return [Boolean]
     def same_address?(a, b)
       a.to_s.downcase == b.to_s.downcase
     end
 
-    # "1.5", 6 -> 1_500_000. Accepts String, Integer, Float, Rational, BigDecimal.
+    # Convert a human readable amount to an Integer in the smallest unit (viem's `parseUnits`).
+    #
+    # @param value [String, Integer, Float, Rational, BigDecimal] decimal amount; Strings avoid float rounding
+    # @param decimals [Integer] decimals of the token (18 for ETH, 6 for USDC)
+    # @return [Integer] amount in the smallest unit
+    # @raise [BlockGiven::InvalidArgumentError] when the value is not a decimal or has more than `decimals`
+    #   fractional digits
+    # @example
+    #   BlockGiven::Utils.parse_units("1.5", 6)       # => 1_500_000
+    #   BlockGiven::Utils.parse_units("0.000001", 18) # => 1_000_000_000_000
+    #   BlockGiven::Utils.parse_units("1.0000001", 6) # raises BlockGiven::InvalidArgumentError
     def parse_units(value, decimals)
       decimal = to_decimal(value)
       scaled = decimal * (BigDecimal(10)**decimals)
@@ -82,7 +161,15 @@ module BlockGiven
       scaled.to_i
     end
 
-    # 1_500_000, 6 -> "1.5"
+    # Format an Integer amount in the smallest unit as a decimal String (viem's `formatUnits`).
+    #
+    # Trailing zeros and a trailing dot are removed, so `1_000_000` with 6 decimals gives `"1"`, not `"1.0"`.
+    #
+    # @param value [Integer, #to_i] amount in the smallest unit
+    # @param decimals [Integer] decimals of the token
+    # @return [String] plain decimal notation, never scientific
+    # @example
+    #   BlockGiven::Utils.format_units(1_500_000, 6) # => "1.5"
     def format_units(value, decimals)
       decimal = BigDecimal(value.to_i) / (BigDecimal(10)**decimals)
       str = decimal.to_s("F")
@@ -90,11 +177,40 @@ module BlockGiven
       str
     end
 
+    # {.parse_units} with 18 decimals: ether to wei.
+    #
+    # @param value [String, Integer, Float, Rational, BigDecimal] amount in ether
+    # @return [Integer] wei
+    # @raise [BlockGiven::InvalidArgumentError] see {.parse_units}
     def parse_ether(value) = parse_units(value, 18)
+
+    # {.format_units} with 18 decimals: wei to ether.
+    #
+    # @param value [Integer, #to_i] wei
+    # @return [String] ether
     def format_ether(value) = format_units(value, 18)
+
+    # {.parse_units} with 9 decimals: gwei to wei (handy for gas prices).
+    #
+    # @param value [String, Integer, Float, Rational, BigDecimal] amount in gwei
+    # @return [Integer] wei
+    # @raise [BlockGiven::InvalidArgumentError] see {.parse_units}
     def parse_gwei(value) = parse_units(value, 9)
+
+    # {.format_units} with 9 decimals: wei to gwei.
+    #
+    # @param value [Integer, #to_i] wei
+    # @return [String] gwei
     def format_gwei(value) = format_units(value, 9)
 
+    # Convert a numeric value to a BigDecimal without floating point surprises.
+    #
+    # Floats go through their String form, Rationals get 40 significant digits, Strings are stripped first.
+    #
+    # @api private
+    # @param value [BigDecimal, Integer, Float, Rational, String]
+    # @return [BigDecimal]
+    # @raise [BlockGiven::InvalidArgumentError] for other types or Strings BigDecimal cannot parse
     def to_decimal(value)
       case value
       when BigDecimal then value
@@ -108,7 +224,16 @@ module BlockGiven
       raise InvalidArgumentError, "cannot convert #{value.inspect} to a decimal"
     end
 
-    # Accepts an Integer, a hex QUANTITY or a block tag (:latest, "pending", ...).
+    # Build the block parameter of a JSON-RPC call from an Integer, a hex QUANTITY or a block tag.
+    #
+    # @param value [Integer, String, Symbol, nil] block number, `0x` hex QUANTITY, or one of {BLOCK_TAGS} as
+    #   String or Symbol; nil means `"latest"`
+    # @return [String] hex QUANTITY or tag, ready to be sent as RPC parameter
+    # @raise [BlockGiven::InvalidArgumentError] for an unknown tag or an unsupported type
+    # @example
+    #   BlockGiven::Utils.block_tag(nil)        # => "latest"
+    #   BlockGiven::Utils.block_tag(18_000_000) # => "0x112a880"
+    #   BlockGiven::Utils.block_tag(:finalized) # => "finalized"
     def block_tag(value)
       case value
       when nil then "latest"
@@ -122,6 +247,15 @@ module BlockGiven
       end
     end
 
+    # Convert a camelCase or PascalCase name to snake_case, as used for ABI names and RPC keys.
+    #
+    # Leading underscores are dropped (`"_owner"` -> `"owner"`), acronyms are split (`"ERC20Token"` ->
+    # `"erc20_token"`) and dashes become underscores.
+    #
+    # @param name [String, Symbol]
+    # @return [String]
+    # @example
+    #   BlockGiven::Utils.snake_case("maxFeePerGas") # => "max_fee_per_gas"
     def snake_case(name)
       name.to_s
           .sub(/\A_+/, "")

data/lib/block_given/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module BlockGiven
-  VERSION = "0.1.0"
+  # Version of the gem, following semantic versioning.
+  VERSION = "0.2.0"
 end