block_given 0.1.0 → 0.2.0

data/lib/block_given/signed_transaction.rb

@@ -1,63 +1,91 @@
 # frozen_string_literal: true
 
 module BlockGiven
-  # A signed transaction that has not been broadcast yet. Its hash is derived
-  # from the signed bytes, so it is known before any network call: persist
-  # `hash` and `nonce`, then `broadcast`. Whatever happens to the RPC call, the
-  # transaction can be found again with `client.transaction(hash)`.
+  # A signed transaction that has not been broadcast yet.
   #
-  #   signed = registry.prepare_write(:record, movement_id, tx: { nonce: call.nonce })
-  #   call.update!(tx_hash: signed.hash, nonce: signed.nonce, status: :submitted)
-  #   signed.broadcast                                  # => BlockGiven::Transaction
+  # The transaction hash is the keccak-256 of the signed RLP bytes, so {#hash} and {#nonce} are known before
+  # any network call: persist them (or {#raw} / {#to_h}), then {#broadcast}. Whatever happens to the RPC call,
+  # the transaction can be found again with `client.transaction(hash)` or {#transaction}.
+  #
+  # Lifecycle:
+  #
+  # 1. {Wallet#signed_transaction} (or `Contract#prepare_write`) signs and returns an instance.
+  # 2. {#broadcast} sends the bytes with `eth_sendRawTransaction` and returns a {Transaction} carrying the local
+  #    hash (a warning is logged if the node answers with a different hash).
+  # 3. If the transaction is stuck in the mempool, {#replacement} re-signs the same payload with the same nonce
+  #    and higher fees; only one of the two can ever be mined.
+  # 4. After a restart, {.from_raw} rebuilds an instance from the persisted bytes so steps 2 and 3 still work.
   #
-  #   signed.replacement.broadcast                      # same nonce, fees bumped by 12.5%
+  # `hash` is the transaction hash (a String, like {Transaction#hash}), not Ruby's Object#hash: instances are
+  # not usable as Hash keys or Set members; compare them with {#==}.
   #
-  # `hash` is the transaction hash (a String, like Transaction#hash), so instances
-  # are not usable as Hash keys; compare them with ==.
+  # @example Sign, persist, broadcast, then replace when stuck
+  #   signed = registry.prepare_write(:record, movement_id, tx: { nonce: call.nonce })
+  #   call.update!(tx_hash: signed.hash, nonce: signed.nonce, raw_tx: signed.raw, status: :submitted)
+  #   tx = signed.broadcast                            # => BlockGiven::Transaction (same hash)
+  #
+  #   signed.replacement.broadcast if tx.pending?      # same nonce, fees bumped by 12.5%
   class SignedTransaction
-    # Nodes reject a same-nonce replacement whose fees are not at least 10% higher.
+    # Nodes reject a same-nonce replacement whose fees are not at least 10% higher than the original's.
     MIN_REPLACEMENT_MULTIPLIER = 1.1
+    # Fee multiplier used by {#replacement} when none is given (12.5% bump, geth's default replacement rule).
     DEFAULT_REPLACEMENT_MULTIPLIER = 1.125
 
-    # Rebuilds a SignedTransaction from persisted raw bytes (after a restart, typically), so it
-    # can be broadcast again or replaced. The bytes must have been signed by `wallet`.
+    # Rebuilds a signed transaction from persisted raw bytes, typically after a process restart, so it can be
+    # broadcast again ({#broadcast}) or replaced ({#replacement}).
+    #
+    # Both EIP-1559 (type 2) and legacy (type 0) transactions are supported and the recovered sender must be
+    # `wallet`'s address, since only that wallet can sign a replacement. A non-empty access list comes back as
+    # `[{ address:, storage_keys: }]`.
+    #
+    # @param raw [String] the signed transaction bytes as hex (with or without `0x`), as returned by {#raw}
+    # @param wallet [Wallet] the wallet that signed the bytes; used by {#replacement} to re-sign
+    # @param interface [Abi::Interface, nil] ABI used to decode custom errors when the node rejects the
+    #   broadcast with revert data (typically `contract.interface`)
+    # @return [SignedTransaction] the rebuilt transaction; its {#params} mirror {Wallet#prepare_transaction}
+    # @raise [BlockGiven::InvalidArgumentError] when the bytes cannot be decoded, or when they were signed by
+    #   another address than `wallet.address`
+    # @example
+    #   signed = BlockGiven::SignedTransaction.from_raw(payout.raw_tx, wallet: wallet, interface: usdc.interface)
+    #   signed.hash == payout.tx_hash # => true
+    #   signed.transaction.status     # => :pending
     def self.from_raw(raw, wallet:, interface: nil)
-      decoded = begin
-        Eth::Tx.decode(Utils.prefix_hex(raw))
-      rescue StandardError => e
+      params = begin
+        TransactionEnvelope.decode(raw)
+      rescue InvalidArgumentError => e
         raise InvalidArgumentError, "cannot decode signed transaction: #{e.message}"
       end
-      sender = Utils.checksum_address(Utils.prefix_hex(decoded.sender)) # eth returns unprefixed hex
-      unless Utils.same_address?(sender, wallet.address)
-        raise InvalidArgumentError, "signed transaction was sent by #{sender}, not by wallet #{wallet.address}"
+      unless Utils.same_address?(params[:from], wallet.address)
+        raise InvalidArgumentError, "signed transaction was sent by #{params[:from]}, not by wallet #{wallet.address}"
       end
 
-      new(raw: raw, params: params_from(decoded, sender), wallet: wallet, interface: interface)
+      new(raw: raw, params: params, wallet: wallet, interface: interface)
     end
 
-    def self.params_from(decoded, sender)
-      destination = decoded.destination.to_s
-      params = {
-        from: sender, to: destination.empty? ? nil : Utils.checksum_address(Utils.prefix_hex(destination)),
-        value: decoded.amount, data: decoded.payload.to_s.empty? ? "" : Utils.bin_to_hex(decoded.payload),
-        chain_id: decoded.chain_id, nonce: decoded.signer_nonce, gas: decoded.gas_limit
-      }
-      # Same shape as Wallet#prepare_transaction (access_list nil when empty).
-      if decoded.respond_to?(:max_fee_per_gas)
-        access_list = decoded.access_list
-        params.merge(max_fee_per_gas: decoded.max_fee_per_gas,
-                     max_priority_fee_per_gas: decoded.max_priority_fee_per_gas,
-                     access_list: access_list.nil? || access_list.empty? ? nil : access_list)
-      else
-        params.merge(gas_price: decoded.gas_price, access_list: nil)
-      end
-    end
-    private_class_method :params_from
-
+    # @!attribute [r] raw
+    #   @return [String] the RLP-encoded signed transaction as `0x`-prefixed hex, as sent to
+    #     `eth_sendRawTransaction`
+    # @!attribute [r] hash
+    #   @return [String] the transaction hash (`0x` hex, keccak-256 of {#raw}), identical to the hash the node
+    #     will report once broadcast. A String, so this is not Ruby's Object#hash
+    # @!attribute [r] params
+    #   @return [Hash{Symbol => Object}] the frozen resolved parameters the bytes were signed from, in the shape
+    #     returned by {Wallet#prepare_transaction} (`:from`, `:to`, `:value`, `:data`, `:chain_id`, `:nonce`,
+    #     `:gas`, `:access_list`, plus `:gas_price` or the two EIP-1559 fee fields)
+    # @!attribute [r] wallet
+    #   @return [Wallet] the wallet that signed the bytes and that {#replacement} re-signs with
+    # @!attribute [r] interface
+    #   @return [Abi::Interface, nil] ABI used to name custom errors on revert, or nil
     attr_reader :raw, :hash, :params, :wallet, :interface
 
-    # interface: an Abi::Interface used to name custom errors when the node rejects the
-    # broadcast with revert data (set by Contract#prepare_write).
+    # Wraps already signed bytes. Applications normally get instances from {Wallet#signed_transaction},
+    # `Contract#prepare_write` or {.from_raw} rather than calling this directly.
+    #
+    # @param raw [String] the signed transaction bytes as hex (with or without `0x`)
+    # @param params [Hash{Symbol => Object}] the resolved parameters the bytes were signed from (frozen here)
+    # @param wallet [Wallet] the signing wallet
+    # @param interface [Abi::Interface, nil] ABI used to name custom errors when the node rejects the
+    #   broadcast with revert data (set by `Contract#prepare_write`)
     def initialize(raw:, params:, wallet:, interface: nil)
       @raw = Utils.prefix_hex(raw)
       @params = params.freeze
@@ -66,23 +94,64 @@ module BlockGiven
       @hash = Utils.keccak256(@raw)
     end
 
+    # Returns a copy of this signed transaction that decodes custom errors with the given ABI.
+    #
+    # @param interface [Abi::Interface, nil] the ABI to use for revert decoding
+    # @return [SignedTransaction] a new instance with the same bytes, params and wallet
     def with_interface(interface) = self.class.new(raw: raw, params: params, wallet: wallet, interface: interface)
 
+    # The client used to broadcast and to look the transaction up.
+    #
+    # @return [Client] `wallet.client`
     def client = wallet.client
 
+    # @return [String] the checksummed sender address (`params[:from]`)
     def from = params[:from]
+
+    # @return [String, nil] the checksummed recipient address, or nil for a contract creation
     def to = params[:to]
+
+    # @return [Integer] the amount of wei transferred
     def value = params[:value]
+
+    # @return [String] the calldata as `0x` hex, or `""` when there is none
     def data = params[:data]
+
+    # @return [Integer] the nonce the bytes were signed with; a {#replacement} reuses it
     def nonce = params[:nonce]
+
+    # @return [Integer] the gas limit
     def gas = params[:gas]
+
+    # @return [Integer] the chain id the transaction is valid on (EIP-155)
     def chain_id = params[:chain_id]
+
+    # @return [Integer, nil] the EIP-1559 max fee per gas in wei, or nil for a legacy transaction
     def max_fee_per_gas = params[:max_fee_per_gas]
+
+    # @return [Integer, nil] the EIP-1559 max priority fee per gas in wei, or nil for a legacy transaction
     def max_priority_fee_per_gas = params[:max_priority_fee_per_gas]
+
+    # @return [Integer, nil] the gas price in wei for a legacy (type 0) transaction, or nil for EIP-1559
     def gas_price = params[:gas_price]
+
+    # @return [Boolean] true when this is a legacy (type 0) transaction, i.e. {#gas_price} is set
     def legacy? = !gas_price.nil?
 
-    # eth_sendRawTransaction. Returns a Transaction carrying the locally computed hash.
+    # Broadcasts the signed bytes with `eth_sendRawTransaction`.
+    #
+    # The returned {Transaction} carries the locally computed {#hash}, not the value answered by the node; if
+    # the node reports a different hash a warning is logged through `client.logger`, but the local hash is
+    # still the one to track. Revert errors raised by the node are enriched with {#interface} when present.
+    #
+    # @return [Transaction] a handle on the broadcast transaction, identified by {#hash}
+    # @raise [BlockGiven::ContractRevertError] when the node rejects the transaction with revert data (decoded
+    #   to a named custom error when {#interface} knows its selector)
+    # @raise [BlockGiven::RpcError] for any other node-side rejection (nonce too low, underpriced, ...)
+    # @example
+    #   tx = signed.broadcast
+    #   tx.hash == signed.hash # => true
+    #   tx.wait!
     def broadcast
       sent = with_decoded_errors { client.send_raw_transaction(raw) }
       unless sent.hash.to_s.casecmp?(hash)
@@ -94,13 +163,32 @@ module BlockGiven
     end
     alias submit broadcast
 
-    # The Transaction handle for this hash, without broadcasting (status, receipt...).
+    # The {Transaction} handle for {#hash}, without broadcasting anything (status, receipt, confirmations...).
+    #
+    # @return [Transaction] the same handle `client.transaction(hash)` returns
     def transaction = client.transaction(hash)
 
-    # Re-signs the same payload with the same nonce and higher fees, to replace a
-    # transaction stuck in the mempool. Fees are the max of (current fees x
-    # fee_multiplier) and a fresh estimate from the node, so the replacement also
-    # catches up with the market. Both transactions share a nonce: only one can be mined.
+    # Re-signs the same payload with the same nonce and higher fees, to replace a transaction stuck in the
+    # mempool.
+    #
+    # Each fee becomes the maximum of the current fee multiplied by `fee_multiplier` (rounded up) and a fresh
+    # estimate from the node ({Client#estimate_fees_per_gas} for EIP-1559, {Client#gas_price} for legacy), so
+    # the replacement both satisfies the node's bump rule and catches up with the market. For EIP-1559 the
+    # max fee is also kept at or above the priority fee. Everything else (`to`, `value`, `data`, `gas`,
+    # `nonce`, `chain_id`, `access_list`, {#interface}) is reused. Both transactions share a nonce: only one
+    # can be mined, the other is rejected by the node.
+    #
+    # @param fee_multiplier [Numeric] multiplier applied to the current fees; must be at least
+    #   {MIN_REPLACEMENT_MULTIPLIER} (1.1), defaults to {DEFAULT_REPLACEMENT_MULTIPLIER} (1.125)
+    # @return [SignedTransaction] a new signed transaction with the same nonce and higher fees, not broadcast
+    # @raise [BlockGiven::InvalidArgumentError] when `fee_multiplier` is below 1.1, or when the instance has no
+    #   fee parameters (neither `gas_price` nor both EIP-1559 fields; rebuild it with {.from_raw})
+    # @raise [BlockGiven::ContractRevertError] when the fee estimation itself is rejected by the node with
+    #   revert data
+    # @example
+    #   faster = signed.replacement(fee_multiplier: 1.5)
+    #   faster.nonce == signed.nonce # => true
+    #   faster.broadcast
     def replacement(fee_multiplier: DEFAULT_REPLACEMENT_MULTIPLIER)
       if fee_multiplier < MIN_REPLACEMENT_MULTIPLIER
         raise InvalidArgumentError, "fee_multiplier must be >= #{MIN_REPLACEMENT_MULTIPLIER} (got #{fee_multiplier})"
@@ -113,10 +201,23 @@ module BlockGiven
       ).with_interface(interface)
     end
 
+    # Everything needed to persist and later rebuild the transaction.
+    #
+    # @return [Hash{Symbol => Object}] {#params} merged with `:hash` and `:raw`
     def to_h = params.merge(hash: hash, raw: raw)
 
+    # @return [String] the transaction {#hash}
     def to_s = hash
+
+    # Two signed transactions are equal when their signed bytes are identical.
+    #
+    # @param other [Object] the object to compare with
+    # @return [Boolean] true when `other` is a {SignedTransaction} with the same {#raw} bytes
     def ==(other) = other.is_a?(SignedTransaction) && other.raw == raw
+
+    # Debug representation with the hash, nonce and recipient; never includes the raw bytes.
+    #
+    # @return [String] e.g. `#<BlockGiven::SignedTransaction 0x... nonce=12 to=0x...>`
     def inspect = "#<BlockGiven::SignedTransaction #{hash} nonce=#{nonce} to=#{to}>"
 
     private

data/lib/block_given/transaction.rb

@@ -1,67 +1,142 @@
 # frozen_string_literal: true
 
 module BlockGiven
-  # A broadcast transaction identified by its hash. Wraps receipt polling.
+  # A broadcast transaction identified by its hash. Wraps receipt lookup, status classification and polling.
   #
+  # Instances are cheap handles: nothing is fetched until a method asks the node. The receipt is memoized
+  # once found (see {#receipt} and {#reload}).
+  #
+  # @example Wait for a contract write
   #   tx = usdc.transfer(to: "0x...", amount: 1e6)
   #   tx.hash            # => "0x..."
   #   receipt = tx.wait  # polls until mined (see BlockGiven.config.timeout / polling_interval)
   #   tx.wait!           # same, but raises BlockGiven::TransactionRevertedError on failure
+  #
+  # @example Classify a persisted transaction in one round trip
+  #   tx = client.transaction(payout.tx_hash)
+  #   case tx.status
+  #   when :success  then payout.confirmed! if tx.confirmed?(5)
+  #   when :reverted then payout.failed!
+  #   when :pending  then signed.replacement.broadcast if payout.submitted_at < 5.minutes.ago
+  #   when :unknown  then signed.broadcast   # never seen or dropped by the node: resend the same bytes
+  #   end
   class Transaction
+    # @!attribute [r] hash
+    #   @return [String] the transaction hash as `0x` hex. A String, so this is not Ruby's Object#hash and
+    #     instances are not usable as Hash keys
+    # @!attribute [r] client
+    #   @return [Client] the client used to query the node
     attr_reader :hash, :client
 
+    # Builds a handle on a transaction hash. Applications usually get instances from {Client#transaction},
+    # {SignedTransaction#broadcast} or contract writes rather than calling this directly.
+    #
+    # @param hash [String] the transaction hash as `0x` hex
+    # @param client [Client] the client used to query the node
     def initialize(hash, client:)
       @hash = hash
       @client = client
       @receipt = nil
     end
 
-    # Non-blocking: the receipt if the transaction is mined, nil otherwise. Cached once
-    # found: call #reload (or build a fresh handle with client.transaction) to re-query the
-    # node, e.g. on every tick of a long-lived worker.
+    # The receipt, without blocking: nil while the transaction is not mined.
+    #
+    # Cached once found: call {#reload} (or build a fresh handle with {Client#transaction}) to query the node
+    # again, e.g. on every tick of a long-lived worker.
+    #
+    # @return [Receipt, nil] the receipt once the transaction is mined, nil otherwise
     def receipt
       @receipt ||= client.get_transaction_receipt(hash)
     end
 
+    # Forgets the memoized receipt so the next call to {#receipt} (or any method built on it) asks the node.
+    #
+    # @return [self]
     def reload
       @receipt = nil
       self
     end
 
+    # @return [Boolean] true when a receipt exists, i.e. the transaction is included in a block
     def mined? = !receipt.nil?
 
-    # One RPC round trip to classify the transaction (two while it is not mined):
-    #   :success / :reverted  mined, from the receipt status
-    #   :pending              known by the node, waiting in the mempool
-    #   :unknown              the node has never seen it, or dropped it: safe to re-broadcast
-    #                         the same signed bytes (see SignedTransaction#replacement)
+    # Classifies the transaction in one RPC round trip (two while it is not mined).
+    #
+    # - `:success` / `:reverted` when mined, from {Receipt#status}
+    # - `:pending` when not mined but `eth_getTransactionByHash` knows it (waiting in the mempool)
+    # - `:unknown` when the node has never seen it or dropped it; it is then safe to re-broadcast the same
+    #   signed bytes or a {SignedTransaction#replacement}
+    #
+    # @return [Symbol] one of `:success`, `:reverted`, `:pending`, `:unknown`
+    # @example
+    #   case tx.status
+    #   when :success  then record.confirmed!
+    #   when :reverted then record.failed!
+    #   when :pending  then wait_a_bit
+    #   when :unknown  then signed.broadcast
+    #   end
     def status
       return receipt.status if mined?
 
       details ? :pending : :unknown
     end
 
+    # @return [Boolean] true when mined with a successful receipt status
     def success? = mined? && receipt.success?
+
+    # @return [Boolean] true when mined with a failed receipt status
     def reverted? = mined? && receipt.reverted?
+
+    # @return [Boolean] true when {#status} is `:pending` (known by the node, not mined)
     def pending? = status == :pending
+
+    # @return [Boolean] true when {#status} is `:unknown` (never seen or dropped by the node)
     def unknown? = status == :unknown
 
-    # Blocks since inclusion, 1 when mined in the latest block, 0 while not mined.
+    # Number of blocks since inclusion: `head - block_number + 1`.
+    #
+    # 1 when mined in the latest block, 0 while not mined. Never negative, even if the node answers with a
+    # head behind the receipt's block (e.g. a lagging load-balanced provider).
+    #
+    # @return [Integer] the confirmation count
     def confirmations
       return 0 unless mined?
 
       [client.block_number - receipt.block_number + 1, 0].max
     end
 
-    # Non-blocking counterpart of wait(confirmations:). Defaults to BlockGiven.config.confirmations.
+    # Non-blocking counterpart of `wait(confirmations:)`.
+    #
+    # @param count [Integer, nil] required confirmations; defaults to `BlockGiven.config.confirmations`
+    # @return [Boolean] true when {#confirmations} is at least `count`
     def confirmed?(count = nil) = confirmations >= (count || BlockGiven.config.confirmations)
 
+    # Blocks until the transaction is mined and confirmed, then memoizes and returns the receipt.
+    #
+    # Polls `eth_getTransactionReceipt` through {Client#wait_for_transaction_receipt}. The receipt is returned
+    # whatever its status; use {#wait!} to raise on revert.
+    #
+    # @param confirmations [Integer, nil] blocks to wait for after inclusion; defaults to
+    #   `BlockGiven.config.confirmations`
+    # @param timeout [Numeric, nil] seconds before giving up; defaults to the client's timeout
+    #   (`BlockGiven.config.timeout`)
+    # @param polling_interval [Numeric, nil] seconds between two polls; defaults to the client's polling interval
+    #   (`BlockGiven.config.polling_interval`)
+    # @return [Receipt] the mined receipt
+    # @raise [BlockGiven::TimeoutError] when the receipt is not available (or not confirmed) within `timeout`
     def wait(confirmations: nil, timeout: nil, polling_interval: nil)
       @receipt = client.wait_for_transaction_receipt(
         hash, confirmations: confirmations, timeout: timeout, polling_interval: polling_interval
       )
     end
 
+    # Same as {#wait} but raises when the mined transaction reverted.
+    #
+    # @param options [Hash] forwarded to {#wait} (`confirmations:`, `timeout:`, `polling_interval:`)
+    # @return [Receipt] the mined receipt, guaranteed successful
+    # @raise [BlockGiven::TransactionRevertedError] when the receipt status is `:reverted`; the error exposes the
+    #   receipt
+    # @raise [BlockGiven::TimeoutError] when the receipt is not available within the timeout
     def wait!(**options)
       receipt = wait(**options)
       raise TransactionRevertedError, receipt if receipt.reverted?
@@ -69,13 +144,29 @@ module BlockGiven
       receipt
     end
 
-    # Raw transaction object from the node (nil while it is not yet known).
+    # The transaction object as the node knows it (`eth_getTransactionByHash`), never memoized.
+    #
+    # @return [Hash{Symbol => Object}, nil] the normalized transaction (snake_case symbol keys, Integer
+    #   quantities), or nil while the node does not know the hash
     def details = client.get_transaction(hash)
 
+    # Link to the transaction on the chain's block explorer.
+    #
+    # @return [String, nil] the URL, or nil when the client's chain has no explorer configured
     def explorer_url = client.chain&.explorer_tx_url(hash)
 
+    # @return [String] the transaction {#hash}
     def to_s = hash
+
+    # Two handles are equal when they point at the same hash, whatever their client.
+    #
+    # @param other [Object] the object to compare with
+    # @return [Boolean] true when `other` is a {Transaction} with the same {#hash}
     def ==(other) = other.is_a?(Transaction) && other.hash == hash
+
+    # Debug representation; includes block and status only when a receipt is already memoized (no RPC call).
+    #
+    # @return [String] e.g. `#<BlockGiven::Transaction 0x... mined block=123 status=success>`
     def inspect = "#<BlockGiven::Transaction #{hash}#{mined_flag}>"
 
     private

data/lib/block_given/transaction_envelope/fields.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module BlockGiven
+  module TransactionEnvelope
+    # Field-level rules shared by signing and decoding: access list conversion, sanity checks and the intrinsic
+    # gas a transaction must cover.
+    #
+    # @api private
+    module Fields
+      # Base cost of any transaction.
+      BASE_GAS = 21_000
+      # Extra cost of a contract creation.
+      CREATE_GAS = 32_000
+      # Calldata cost of a zero byte.
+      ZERO_BYTE_GAS = 4
+      # Calldata cost of a non-zero byte.
+      NON_ZERO_BYTE_GAS = 16
+      # Cost of each 32-byte word of init code (EIP-3860).
+      INITCODE_WORD_GAS = 2
+      # Cost of each address of an access list (EIP-2930).
+      ACCESS_LIST_ADDRESS_GAS = 2_400
+      # Cost of each storage key of an access list (EIP-2930).
+      ACCESS_LIST_KEY_GAS = 1_900
+
+      module_function
+
+      # Converts an access list into its RLP form.
+      #
+      # @param list [Array<Hash, Array>, nil] in one of the forms {TransactionEnvelope} accepts
+      # @return [Array<Array>] `[[address_bytes, [key_bytes...]]...]`
+      # @raise [BlockGiven::InvalidArgumentError] for an entry that is neither a Hash nor a pair
+      def rlp_access_list(list)
+        Array(list).map do |entry|
+          address, keys =
+            case entry
+            when Hash
+              entry = entry.transform_keys { |k| Utils.snake_case(k) }
+              [entry["address"], entry["storage_keys"]]
+            when Array then entry
+            else raise InvalidArgumentError, "invalid access list entry #{entry.inspect}"
+            end
+          [Utils.hex_to_bin(address.to_s), Array(keys).map { |key| Utils.hex_to_bin(Utils.pad_hex(key)) }]
+        end
+      end
+
+      # Converts a decoded RLP access list into Ruby values.
+      #
+      # @param list [Array] decoded RLP items
+      # @return [Array<Hash{Symbol => Object}>] `[{ address:, storage_keys: }]`
+      # @raise [BlockGiven::InvalidArgumentError] when the structure is not an access list
+      def parse_access_list(list)
+        raise InvalidArgumentError, "invalid access list" unless list.is_a?(Array)
+
+        list.map do |entry|
+          valid = entry.is_a?(Array) && entry.size == 2 && entry[0].is_a?(String) && entry[1].is_a?(Array)
+          raise InvalidArgumentError, "invalid access list" unless valid
+
+          { address: Utils.checksum_address(Utils.bin_to_hex(entry[0])),
+            storage_keys: entry[1].map { |key| Utils.bin_to_hex(key) } }
+        end
+      end
+
+      # Rejects parameters no node would accept.
+      #
+      # @param params [Hash{Symbol => Object}]
+      # @return [void]
+      # @raise [BlockGiven::InvalidArgumentError] for a negative or missing field, a chain id below 1 or a gas
+      #   limit under the intrinsic gas
+      def validate!(params)
+        fee_fields = params[:gas_price] ? %i[gas_price] : %i[max_fee_per_gas max_priority_fee_per_gas]
+        (%i[nonce gas value] + fee_fields).each do |field|
+          value = params[field]
+          next if value.is_a?(Integer) && !value.negative?
+
+          raise InvalidArgumentError, "invalid #{field}: #{value.inspect}"
+        end
+        chain_id = params[:chain_id]
+        unless chain_id.is_a?(Integer) && chain_id.positive?
+          raise InvalidArgumentError, "invalid chain_id: #{chain_id.inspect}"
+        end
+
+        minimum = intrinsic_gas(params)
+        return if params[:gas] >= minimum
+
+        raise InvalidArgumentError,
+              "gas limit #{params[:gas]} is below the intrinsic gas of the transaction (#{minimum})"
+      end
+
+      # Minimum gas a transaction pays before executing anything.
+      #
+      # @param params [Hash{Symbol => Object}]
+      # @return [Integer]
+      def intrinsic_gas(params)
+        data = Utils.hex_to_bin(params[:data].to_s)
+        zeros = data.count("\x00")
+        gas = BASE_GAS + (zeros * ZERO_BYTE_GAS) + ((data.bytesize - zeros) * NON_ZERO_BYTE_GAS)
+        gas += CREATE_GAS + (INITCODE_WORD_GAS * ((data.bytesize + 31) / 32)) if params[:to].nil?
+        gas + rlp_access_list(params[:access_list]).sum do |entry|
+          ACCESS_LIST_ADDRESS_GAS + (ACCESS_LIST_KEY_GAS * entry[1].size)
+        end
+      end
+    end
+  end
+end