block_given 0.1.0 → 0.2.0

data/lib/block_given/crypto/keccak.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module Crypto
+    # Keccak-256 as used by Ethereum: the original Keccak submission (padding byte `0x01`), not the
+    # standardized NIST SHA3-256 (padding byte `0x06`), which produces different digests.
+    #
+    # Pure Ruby implementation of the Keccak-f[1600] permutation with a 1088-bit rate.
+    #
+    # @api private
+    # @example
+    #   BlockGiven::Crypto::Keccak.digest("").unpack1("H*")
+    #   # => "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"
+    module Keccak # rubocop:disable Metrics/ModuleLength
+      # Sponge rate in bytes for a 256-bit output (1600 - 2 * 256 bits).
+      RATE = 136
+      # Mask keeping lane arithmetic on 64 bits.
+      MASK = 0xFFFFFFFFFFFFFFFF
+      # Round constants of the iota step, one per round.
+      ROUND_CONSTANTS = [
+        0x0000000000000001, 0x0000000000008082, 0x800000000000808A, 0x8000000080008000,
+        0x000000000000808B, 0x0000000080000001, 0x8000000080008081, 0x8000000000008009,
+        0x000000000000008A, 0x0000000000000088, 0x0000000080008009, 0x000000008000000A,
+        0x000000008000808B, 0x800000000000008B, 0x8000000000008089, 0x8000000000008003,
+        0x8000000000008002, 0x8000000000000080, 0x000000000000800A, 0x800000008000000A,
+        0x8000000080008081, 0x8000000000008080, 0x0000000080000001, 0x8000000080008008
+      ].freeze
+
+      module_function
+
+      # Keccak-256 digest of a byte string.
+      #
+      # @param data [String] the bytes to hash (any encoding, read as binary)
+      # @return [String] the 32-byte digest as a binary String
+      def digest(data)
+        message = data.b
+        padding = RATE - (message.bytesize % RATE)
+        message << (padding == 1 ? "\x81".b : "\x01".b + ("\x00".b * (padding - 2)) + "\x80".b)
+
+        state = Array.new(25, 0)
+        (0...message.bytesize).step(RATE) do |offset|
+          message.byteslice(offset, RATE).unpack("Q<17").each_with_index { |lane, i| state[i] ^= lane }
+          state = permute(state)
+        end
+        state.first(4).pack("Q<4")
+      end
+
+      # Applies the 24 rounds of Keccak-f[1600] to a state.
+      #
+      # Unrolled on purpose: lanes live in local variables (about four times faster than indexing an Array in
+      # the inner loops). The rho rotation offsets and the pi lane permutation of the specification are baked
+      # into the `b*` assignments (lane x + 5y rotated, then moved to y + 5 * ((2x + 3y) % 5)).
+      #
+      # @param state [Array<Integer>] 25 lanes of 64 bits, indexed by x + 5 * y
+      # @return [Array<Integer>] the permuted state, as a new Array
+      def permute(state) # rubocop:disable Metrics/MethodLength
+        a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12,
+          a13, a14, a15, a16, a17, a18, a19, a20, a21, a22, a23, a24 = state
+        ROUND_CONSTANTS.each do |rc| # rubocop:disable Metrics/BlockLength
+          c0 = a0 ^ a5 ^ a10 ^ a15 ^ a20
+          c1 = a1 ^ a6 ^ a11 ^ a16 ^ a21
+          c2 = a2 ^ a7 ^ a12 ^ a17 ^ a22
+          c3 = a3 ^ a8 ^ a13 ^ a18 ^ a23
+          c4 = a4 ^ a9 ^ a14 ^ a19 ^ a24
+          d0 = c4 ^ (((c1 << 1) | (c1 >> 63)) & MASK)
+          d1 = c0 ^ (((c2 << 1) | (c2 >> 63)) & MASK)
+          d2 = c1 ^ (((c3 << 1) | (c3 >> 63)) & MASK)
+          d3 = c2 ^ (((c4 << 1) | (c4 >> 63)) & MASK)
+          d4 = c3 ^ (((c0 << 1) | (c0 >> 63)) & MASK)
+          a0 ^= d0
+          a1 ^= d1
+          a2 ^= d2
+          a3 ^= d3
+          a4 ^= d4
+          a5 ^= d0
+          a6 ^= d1
+          a7 ^= d2
+          a8 ^= d3
+          a9 ^= d4
+          a10 ^= d0
+          a11 ^= d1
+          a12 ^= d2
+          a13 ^= d3
+          a14 ^= d4
+          a15 ^= d0
+          a16 ^= d1
+          a17 ^= d2
+          a18 ^= d3
+          a19 ^= d4
+          a20 ^= d0
+          a21 ^= d1
+          a22 ^= d2
+          a23 ^= d3
+          a24 ^= d4
+          b0 = a0
+          b10 = (((a1 << 1) | (a1 >> 63)) & MASK)
+          b20 = (((a2 << 62) | (a2 >> 2)) & MASK)
+          b5 = (((a3 << 28) | (a3 >> 36)) & MASK)
+          b15 = (((a4 << 27) | (a4 >> 37)) & MASK)
+          b16 = (((a5 << 36) | (a5 >> 28)) & MASK)
+          b1 = (((a6 << 44) | (a6 >> 20)) & MASK)
+          b11 = (((a7 << 6) | (a7 >> 58)) & MASK)
+          b21 = (((a8 << 55) | (a8 >> 9)) & MASK)
+          b6 = (((a9 << 20) | (a9 >> 44)) & MASK)
+          b7 = (((a10 << 3) | (a10 >> 61)) & MASK)
+          b17 = (((a11 << 10) | (a11 >> 54)) & MASK)
+          b2 = (((a12 << 43) | (a12 >> 21)) & MASK)
+          b12 = (((a13 << 25) | (a13 >> 39)) & MASK)
+          b22 = (((a14 << 39) | (a14 >> 25)) & MASK)
+          b23 = (((a15 << 41) | (a15 >> 23)) & MASK)
+          b8 = (((a16 << 45) | (a16 >> 19)) & MASK)
+          b18 = (((a17 << 15) | (a17 >> 49)) & MASK)
+          b3 = (((a18 << 21) | (a18 >> 43)) & MASK)
+          b13 = (((a19 << 8) | (a19 >> 56)) & MASK)
+          b14 = (((a20 << 18) | (a20 >> 46)) & MASK)
+          b24 = (((a21 << 2) | (a21 >> 62)) & MASK)
+          b9 = (((a22 << 61) | (a22 >> 3)) & MASK)
+          b19 = (((a23 << 56) | (a23 >> 8)) & MASK)
+          b4 = (((a24 << 14) | (a24 >> 50)) & MASK)
+          a0 = b0 ^ (~b1 & b2)
+          a1 = b1 ^ (~b2 & b3)
+          a2 = b2 ^ (~b3 & b4)
+          a3 = b3 ^ (~b4 & b0)
+          a4 = b4 ^ (~b0 & b1)
+          a5 = b5 ^ (~b6 & b7)
+          a6 = b6 ^ (~b7 & b8)
+          a7 = b7 ^ (~b8 & b9)
+          a8 = b8 ^ (~b9 & b5)
+          a9 = b9 ^ (~b5 & b6)
+          a10 = b10 ^ (~b11 & b12)
+          a11 = b11 ^ (~b12 & b13)
+          a12 = b12 ^ (~b13 & b14)
+          a13 = b13 ^ (~b14 & b10)
+          a14 = b14 ^ (~b10 & b11)
+          a15 = b15 ^ (~b16 & b17)
+          a16 = b16 ^ (~b17 & b18)
+          a17 = b17 ^ (~b18 & b19)
+          a18 = b18 ^ (~b19 & b15)
+          a19 = b19 ^ (~b15 & b16)
+          a20 = b20 ^ (~b21 & b22)
+          a21 = b21 ^ (~b22 & b23)
+          a22 = b22 ^ (~b23 & b24)
+          a23 = b23 ^ (~b24 & b20)
+          a24 = b24 ^ (~b20 & b21)
+          a0 ^= rc
+        end
+        [a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12,
+         a13, a14, a15, a16, a17, a18, a19, a20, a21, a22, a23, a24]
+      end
+    end
+  end
+end

data/lib/block_given/crypto/secp256k1.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module BlockGiven
+  module Crypto
+    # ECDSA over secp256k1, the curve Ethereum accounts use: key generation, public key derivation,
+    # deterministic signing (RFC 6979, low-s as required by EIP-2, with the recovery id) and public key recovery.
+    #
+    # Elliptic curve point multiplications go through the OpenSSL standard library (`OpenSSL::PKey::EC::Point`);
+    # scalars stay plain Ruby Integers. Signatures are byte-identical to libsecp256k1's and viem's for the same
+    # key and hash, since the nonce is derived deterministically from both.
+    #
+    # @api private
+    module Secp256k1
+      # Order of the curve's base point.
+      N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
+      # Field prime.
+      P = (2**256) - (2**32) - 977
+      # Largest `s` value of a canonical (low-s) signature.
+      HALF_N = N >> 1
+
+      module_function
+
+      # The OpenSSL group for the curve, built once.
+      #
+      # @return [OpenSSL::PKey::EC::Group]
+      # @raise [BlockGiven::ConfigurationError] when the linked OpenSSL was built without secp256k1
+      def group
+        @group ||= OpenSSL::PKey::EC::Group.new("secp256k1")
+      rescue OpenSSL::PKey::EC::Group::Error => e
+        raise ConfigurationError, "the OpenSSL library Ruby is linked against does not support secp256k1 (#{e.message})"
+      end
+
+      # Whether an Integer is a valid private key, i.e. in [1, N - 1].
+      #
+      # @param key [Integer]
+      # @return [Boolean]
+      def valid_private_key?(key) = key.is_a?(Integer) && key.positive? && key < N
+
+      # Draws a uniformly random private key from `SecureRandom`.
+      #
+      # @return [Integer] a key in [1, N - 1]
+      def generate_private_key
+        loop do
+          key = bytes_to_int(SecureRandom.random_bytes(32))
+          return key if valid_private_key?(key)
+        end
+      end
+
+      # The uncompressed public key of a private key.
+      #
+      # @param private_key [Integer] a key in [1, N - 1]
+      # @return [String] 65 binary bytes: `0x04`, then X and Y on 32 bytes each
+      def public_key(private_key)
+        group.generator.mul(OpenSSL::BN.new(private_key)).to_octet_string(:uncompressed)
+      end
+
+      # Signs a 32-byte hash with a nonce derived per RFC 6979 (HMAC-SHA256), normalized to low-s.
+      #
+      # @param hash [String] the 32-byte message hash, binary
+      # @param private_key [Integer] a key in [1, N - 1]
+      # @return [Array(Integer, Integer, Integer)] `[r, s, recovery_id]`, `recovery_id` in 0..3 (bit 0: parity of
+      #   the nonce point's Y, bit 1: its X overflowed N)
+      def sign(hash, private_key)
+        z = bytes_to_int(hash) % N
+        nonces(int_to_bytes(private_key), int_to_bytes(z)).each do |k|
+          point = group.generator.mul(OpenSSL::BN.new(k)).to_octet_string(:uncompressed)
+          x = bytes_to_int(point.byteslice(1, 32))
+          r = x % N
+          next if r.zero?
+
+          s = (blinded_inverse(k) * (z + (r * private_key))) % N
+          next if s.zero?
+
+          recovery_id = (point.getbyte(64) & 1) | (x >= N ? 2 : 0)
+          return s > HALF_N ? [r, N - s, recovery_id ^ 1] : [r, s, recovery_id]
+        end
+      end
+
+      # Recovers the uncompressed public key that produced a signature over a hash.
+      #
+      # @param hash [String] the 32-byte message hash, binary
+      # @param r [Integer]
+      # @param s [Integer]
+      # @param recovery_id [Integer] 0..3
+      # @return [String] the 65-byte uncompressed public key, binary
+      # @raise [BlockGiven::InvalidArgumentError] when the signature is malformed or matches no curve point
+      def recover(hash, r, s, recovery_id)
+        unless r.positive? && r < N && s.positive? && s < N && (0..3).cover?(recovery_id)
+          raise InvalidArgumentError, "invalid signature"
+        end
+
+        x = r + ((recovery_id >> 1) * N)
+        raise InvalidArgumentError, "invalid signature" if x >= P
+
+        point_r = decompress(x, recovery_id & 1)
+        r_inverse = r.pow(N - 2, N)
+        u1 = (-bytes_to_int(hash) * r_inverse) % N
+        u2 = (s * r_inverse) % N
+        public_key = point_r.mul(OpenSSL::BN.new(u2), OpenSSL::BN.new(u1))
+        raise InvalidArgumentError, "invalid signature" if public_key.infinity?
+
+        public_key.to_octet_string(:uncompressed)
+      end
+
+      # Candidate nonces of RFC 6979 section 3.2 with HMAC-SHA256, in order (libsecp256k1's nonce function
+      # without extra entropy).
+      #
+      # @param key [String] the private key on 32 bytes
+      # @param message [String] the hash reduced modulo N, on 32 bytes
+      # @return [Enumerator<Integer>] endless sequence of nonces in [1, N - 1]
+      def nonces(key, message)
+        Enumerator.new do |yielder|
+          v = "\x01".b * 32
+          k = "\x00".b * 32
+          k = hmac(k, "#{v}\x00".b + key + message)
+          v = hmac(k, v)
+          k = hmac(k, "#{v}\x01".b + key + message)
+          v = hmac(k, v)
+          loop do
+            v = hmac(k, v)
+            candidate = bytes_to_int(v)
+            yielder << candidate if valid_private_key?(candidate)
+            k = hmac(k, "#{v}\x00".b)
+            v = hmac(k, v)
+          end
+        end
+      end
+
+      # The modular inverse of a nonce, computed on a randomly blinded value so that its timing does not depend
+      # on the nonce itself.
+      #
+      # @param k [Integer] a nonce in [1, N - 1]
+      # @return [Integer] k^-1 mod N
+      def blinded_inverse(k)
+        blind = (bytes_to_int(SecureRandom.random_bytes(32)) % (N - 1)) + 1
+        ((k * blind) % N).pow(N - 2, N) * blind % N
+      end
+
+      # The curve point with a given X coordinate and Y parity.
+      #
+      # @param x [Integer] X coordinate, below P
+      # @param y_parity [Integer] 0 for an even Y, 1 for an odd Y
+      # @return [OpenSSL::PKey::EC::Point]
+      # @raise [BlockGiven::InvalidArgumentError] when X is not on the curve
+      def decompress(x, y_parity)
+        OpenSSL::PKey::EC::Point.new(group, OpenSSL::BN.new((2 + y_parity).chr + int_to_bytes(x), 2))
+      rescue OpenSSL::PKey::EC::Point::Error
+        raise InvalidArgumentError, "invalid signature"
+      end
+
+      # @param key [String] HMAC key
+      # @param data [String]
+      # @return [String] the 32-byte HMAC-SHA256, binary
+      def hmac(key, data) = OpenSSL::HMAC.digest("SHA256", key, data)
+
+      # @param bytes [String] big-endian binary
+      # @return [Integer]
+      def bytes_to_int(bytes) = bytes.unpack1("H*").to_i(16)
+
+      # @param int [Integer] a non-negative Integer below 2**256
+      # @return [String] 32 big-endian bytes, binary
+      def int_to_bytes(int) = [int.to_s(16).rjust(64, "0")].pack("H*")
+    end
+  end
+end

data/lib/block_given/crypto.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "crypto/keccak"
+require_relative "crypto/secp256k1"
+
+module BlockGiven
+  # Cryptographic primitives Ethereum needs, in pure Ruby on top of the OpenSSL standard library: Keccak-256
+  # ({Keccak}) and ECDSA over secp256k1 ({Secp256k1}). No native extension is involved beyond OpenSSL.
+  #
+  # @api private
+  module Crypto
+    module_function
+
+    # The address controlled by a public key: the last 20 bytes of the keccak-256 of its X and Y coordinates.
+    #
+    # @param public_key [String] the 65-byte uncompressed public key, binary (`0x04` prefix included)
+    # @return [String] the EIP-55 checksummed address
+    def address(public_key)
+      Utils.checksum_address(Utils.bin_to_hex(Keccak.digest(public_key.byteslice(1, 64)).byteslice(12, 20)))
+    end
+  end
+end

data/lib/block_given/eip712.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  # EIP-712 typed structured data hashing (`encodeType`, `encodeData`, `hashStruct`, domain separator).
+  #
+  # The payload is a Hash with `types`, `primaryType`, `domain` and `message`, with Symbol or String keys.
+  # When `types` has no `EIP712Domain` entry it is derived from the domain keys present, in the canonical
+  # order (`name`, `version`, `chainId`, `verifyingContract`, `salt`), as viem does.
+  #
+  # Values: integers as Integer, decimal String or `0x` hex String; addresses and `bytes` / `bytesN` as `0x`
+  # hex; `string` as text; arrays as Arrays (hashed per the specification, element by element); structs as
+  # Hashes keyed by field name.
+  #
+  # @api private
+  module Eip712
+    # Domain fields in the order EIP-712 lists them, with their types, used when `EIP712Domain` is omitted.
+    DOMAIN_FIELDS = [
+      %w[name string], %w[version string], %w[chainId uint256], %w[verifyingContract address], %w[salt bytes32]
+    ].freeze
+
+    module_function
+
+    # The digest to sign: keccak256("\x19\x01" || domainSeparator || hashStruct(message)).
+    #
+    # @param typed_data [Hash] `types`, `primaryType`, `domain` and `message`
+    # @return [String] the 32-byte digest, binary
+    # @raise [BlockGiven::InvalidArgumentError] when a section is missing, a type is unknown or a value does not
+    #   fit its type
+    def hash(typed_data)
+      data = typed_data.to_h.transform_keys(&:to_s)
+      %w[types primaryType domain message].each do |key|
+        missing = data[key].nil? || (key != "domain" && data[key].empty?)
+        raise InvalidArgumentError, "typed data #{key} is missing" if missing
+      end
+      domain = data["domain"].transform_keys(&:to_s)
+      types = normalize_types(data["types"], domain)
+      Crypto::Keccak.digest("\x19\x01".b + hash_struct("EIP712Domain", domain, types) +
+                            hash_struct(data["primaryType"].to_s, data["message"], types))
+    end
+
+    # keccak256(typeHash || encodeData(fields)) of a struct value.
+    #
+    # @param type [String] the struct name
+    # @param value [Hash] field values by name (Symbol or String keys)
+    # @param types [Hash{String => Array<Array(String, String)>}] normalized types: struct name to [name, type]
+    # @return [String] 32 bytes, binary
+    # @raise [BlockGiven::InvalidArgumentError] when the value is not a Hash or misses a field
+    def hash_struct(type, value, types)
+      raise InvalidArgumentError, "#{type} expects a Hash, got #{value.inspect}" unless value.is_a?(Hash)
+
+      raise InvalidArgumentError, "unknown EIP-712 type #{type}" unless types.key?(type)
+
+      fields = value.transform_keys(&:to_s)
+      encoded = types[type].map do |name, field_type|
+        raise InvalidArgumentError, "#{type}.#{name} is missing" unless fields.key?(name)
+
+        encode_field(field_type, fields[name], types)
+      end
+      Crypto::Keccak.digest(Crypto::Keccak.digest(encode_type(type, types)) + encoded.join)
+    end
+
+    # `Name(type1 name1,...)` followed by the referenced structs sorted by name.
+    #
+    # @param type [String] the struct name
+    # @param types [Hash{String => Array<Array(String, String)>}]
+    # @return [String]
+    def encode_type(type, types)
+      ([type] + dependencies(type, types).reject { |t| t == type }.sort).map do |name|
+        "#{name}(#{types.fetch(name).map { |field, field_type| "#{field_type} #{field}" }.join(',')})"
+      end.join
+    end
+
+    # Every struct reachable from a type, the type itself included.
+    #
+    # @param type [String]
+    # @param types [Hash{String => Array<Array(String, String)>}]
+    # @param found [Array<String>] accumulator
+    # @return [Array<String>]
+    def dependencies(type, types, found = [])
+      base = type.sub(/(\[\d*\])+\z/, "")
+      return found if found.include?(base) || !types.key?(base)
+
+      found << base
+      types[base].each { |field| dependencies(field[1], types, found) }
+      found
+    end
+
+    # The 32-byte encoding of one field value.
+    #
+    # @param type [String] the field type
+    # @param value [Object]
+    # @param types [Hash{String => Array<Array(String, String)>}]
+    # @return [String] 32 bytes, binary
+    # @raise [BlockGiven::InvalidArgumentError] when the value does not fit the type
+    def encode_field(type, value, types)
+      if (array = type.match(/\A(.+)\[(\d*)\]\z/))
+        raise InvalidArgumentError, "#{type} expects an Array, got #{value.inspect}" unless value.is_a?(Array)
+        if !array[2].empty? && value.size != array[2].to_i
+          raise InvalidArgumentError, "#{type} expects #{array[2]} elements, got #{value.size}"
+        end
+
+        return Crypto::Keccak.digest(value.map { |element| encode_field(array[1], element, types) }.join)
+      end
+      return hash_struct(type, value, types) if types.key?(type)
+      return Crypto::Keccak.digest(value.to_s) if type == "string"
+      return Crypto::Keccak.digest(hex_bytes(type, value)) if type == "bytes"
+
+      encode_atomic(type, value)
+    end
+
+    # The 32-byte word of an atomic value.
+    #
+    # @param type [String] `uintN`, `intN`, `address`, `bool` or `bytesN`
+    # @param value [Object]
+    # @return [String] 32 bytes, binary
+    # @raise [BlockGiven::InvalidArgumentError] for an unknown type or an out-of-range value
+    def encode_atomic(type, value)
+      case type
+      when /\A(u?)int(\d*)\z/
+        bits = ::Regexp.last_match(2).empty? ? 256 : ::Regexp.last_match(2).to_i
+        word(integer(type, value), bits, signed: ::Regexp.last_match(1).empty?)
+      when "address"
+        raise InvalidArgumentError, "invalid address #{value.inspect}" unless Utils.address?(value)
+
+        Utils.hex_to_bin(Utils.pad_hex(value))
+      when "bool"
+        raise InvalidArgumentError, "bool expects true/false, got #{value.inspect}" unless [true, false].include?(value)
+
+        word(value ? 1 : 0, 8, signed: false)
+      when /\Abytes(\d+)\z/
+        bytes = hex_bytes(type, value)
+        raise InvalidArgumentError, "#{type} value is too long" if bytes.bytesize > ::Regexp.last_match(1).to_i
+
+        bytes.ljust(32, "\x00".b)
+      else raise InvalidArgumentError, "unknown EIP-712 type #{type}"
+      end
+    end
+
+    # @param type [String] for error messages
+    # @param value [Integer, String] Integer, decimal String or `0x` hex String
+    # @return [Integer]
+    # @raise [BlockGiven::InvalidArgumentError] when the value is not an integer
+    def integer(type, value)
+      return value if value.is_a?(Integer)
+      return Utils.hex_to_int(value) if Utils.hex?(value) && value.size > 2
+      return Integer(value, 10) if value.is_a?(String)
+
+      raise InvalidArgumentError, "#{type} expects an integer, got #{value.inspect}"
+    rescue ::ArgumentError
+      raise InvalidArgumentError, "#{type} expects an integer, got #{value.inspect}"
+    end
+
+    # A two's complement 32-byte word.
+    #
+    # @param value [Integer]
+    # @param bits [Integer] the type width
+    # @param signed [Boolean]
+    # @return [String] 32 bytes, binary
+    # @raise [BlockGiven::InvalidArgumentError] when the value does not fit
+    def word(value, bits, signed:)
+      range = signed ? (-(2**(bits - 1))...(2**(bits - 1))) : (0...(2**bits))
+      raise InvalidArgumentError, "#{value} does not fit in #{'u' unless signed}int#{bits}" unless range.cover?(value)
+
+      [(value % (2**256)).to_s(16).rjust(64, "0")].pack("H*")
+    end
+
+    # @param type [String] for error messages
+    # @param value [String] `0x` hex
+    # @return [String] the bytes, binary
+    # @raise [BlockGiven::InvalidArgumentError] when the value is not hex
+    def hex_bytes(type, value)
+      raise InvalidArgumentError, "#{type} expects 0x hex: #{value.inspect}" unless value.to_s.match?(/\A0x(\h\h)*\z/)
+
+      Utils.hex_to_bin(value)
+    end
+
+    # Struct definitions as `{ "Name" => [[field, type], ...] }`, `EIP712Domain` derived when absent.
+    #
+    # @param types [Hash] struct name to an Array of `{ name:, type: }`
+    # @param domain [Hash{String => Object}] the domain values
+    # @return [Hash{String => Array<Array(String, String)>}]
+    def normalize_types(types, domain)
+      normalized = types.to_h { |name, fields| [name.to_s, fields.map { |f| field_pair(name, f) }] }
+      normalized["EIP712Domain"] ||= DOMAIN_FIELDS.select { |name, _type| domain.key?(name) }
+      normalized
+    end
+
+    # @param struct [String, Symbol] for error messages
+    # @param field [Hash] `{ name:, type: }`, Symbol or String keys
+    # @return [Array(String, String)] name and type
+    # @raise [BlockGiven::InvalidArgumentError] when the definition is malformed
+    def field_pair(struct, field)
+      field = field.to_h.transform_keys(&:to_s)
+      raise InvalidArgumentError, "malformed field in #{struct}: #{field.inspect}" unless field["name"] && field["type"]
+
+      [field["name"].to_s, field["type"].to_s]
+    end
+  end
+end