erc20 0.2.9 → 0.4.0

data/lib/erc20/checks.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'eth'
+require_relative 'erc20'
+
+# The checks that every wallet makes before it touches the network.
+#
+# A wallet deals with private keys, public addresses, and amounts of money. A
+# broken one of them either costs money or silently loses it, thus it is
+# rejected the moment it arrives. Both +ERC20::Wallet+ and +ERC20::FakeWallet+
+# make these very checks, so that a test that passes against the fake wallet
+# doesn't fail against a real provider.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2025 Yegor Bugayenko
+# License:: MIT
+module ERC20::Checks
+  HEX = /^0x[0-9a-fA-F]{40}$/
+  private_constant :HEX
+
+  MAX_AMOUNT = (2**256) - 1
+  private_constant :MAX_AMOUNT
+
+  private
+
+  def to_priv(priv)
+    raise(ArgumentError, 'Private key can\'t be nil') unless priv
+    raise(ArgumentError, 'Private key must be a String') unless priv.is_a?(String)
+    raise(ArgumentError, 'Invalid format of private key') unless /^[0-9a-fA-F]{64}$/.match?(priv)
+    priv
+  end
+
+  def to_address(address)
+    raise(ArgumentError, 'Address can\'t be nil') unless address
+    raise(ArgumentError, 'Address must be a String') unless address.is_a?(String)
+    raise(ArgumentError, 'Invalid format of the address') unless HEX.match?(address)
+    address
+  end
+
+  def to_addresses(addresses)
+    raise(ArgumentError, 'Addresses can\'t be nil') unless addresses
+    raise(ArgumentError, 'Addresses must respond to .to_a()') unless addresses.respond_to?(:to_a)
+    addresses.to_a.each do |a|
+      raise(ArgumentError, 'Each address must be a String') unless a.is_a?(String)
+      raise(ArgumentError, "Invalid format of the address (#{a})") unless HEX.match?(a)
+    end
+  end
+
+  def to_active(active)
+    raise(ArgumentError, 'Active can\'t be nil') unless active
+    raise(ArgumentError, 'Active must respond to .to_a()') unless active.respond_to?(:to_a)
+    raise(ArgumentError, 'Active must respond to .append()') unless active.respond_to?(:append)
+    raise(ArgumentError, 'Active must respond to .clear()') unless active.respond_to?(:clear)
+    active
+  end
+
+  def to_txn(txn)
+    raise(ArgumentError, 'Transaction hash can\'t be nil') unless txn
+    raise(ArgumentError, 'Transaction hash must be a String') unless txn.is_a?(String)
+    raise(ArgumentError, 'Invalid format of the transaction hash') unless /^0x[0-9a-fA-F]{64}$/.match?(txn)
+    txn
+  end
+
+  def to_amount(amount)
+    raise(ArgumentError, 'Amount can\'t be nil') unless amount
+    raise(ArgumentError, "Amount (#{amount}) must be an Integer") unless amount.is_a?(Integer)
+    raise(ArgumentError, "Amount (#{amount}) must be a positive Integer") unless amount.positive?
+    raise(ArgumentError, "Amount (#{amount}) must fit into uint256") if amount > MAX_AMOUNT
+    amount
+  end
+
+  def to_limit(limit)
+    raise(ArgumentError, 'Gas limit must be an Integer') unless limit.is_a?(Integer)
+    least = Eth::Tx::DEFAULT_GAS_LIMIT
+    raise(ArgumentError, "Gas limit #{limit} is below #{least}") if limit < least
+    most = Eth::Tx::BLOCK_GAS_LIMIT
+    raise(ArgumentError, "Gas limit #{limit} is above #{most}") if limit > most
+    limit
+  end
+
+  def to_price(price)
+    raise(ArgumentError, 'Gas price can\'t be nil') unless price
+    raise(ArgumentError, 'Gas price must be an Integer') unless price.is_a?(Integer)
+    raise(ArgumentError, 'Gas price must be a positive Integer') unless price.positive?
+    price
+  end
+
+  def to_delay(delay)
+    raise(ArgumentError, 'Delay must be a number') unless delay.is_a?(Numeric)
+    raise(ArgumentError, 'Delay must be a positive number') unless delay.positive?
+    delay
+  end
+
+  def to_subscription(id)
+    raise(ArgumentError, 'Subscription ID must be an Integer') unless id.is_a?(Integer)
+    raise(ArgumentError, 'Subscription ID must be a positive Integer') unless id.positive?
+    id
+  end
+end

data/lib/erc20/erc20.rb

@@ -24,6 +24,5 @@
 # Copyright:: Copyright (c) 2025 Yegor Bugayenko
 # License:: MIT
 module ERC20
-  # Current version of the gem (changed by the +.rultor.yml+ on every release)
-  VERSION = '0.2.9' unless defined?(VERSION)
+  VERSION = '0.4.0' unless defined?(VERSION)
 end

data/lib/erc20/fake_wallet.rb

@@ -3,23 +3,25 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
+require_relative 'checks'
 require_relative 'erc20'
 require_relative 'wallet'
 
 # A fake wallet that behaves like a +ERC20::Wallet+.
 #
+# It rejects exactly what the real wallet rejects, so that a broken private
+# key, address, or amount fails in a test the same way it would fail with a
+# real provider, where money is at stake.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2025 Yegor Bugayenko
 # License:: MIT
 class ERC20::FakeWallet
-  # Transaction hash always returned:
-  TXN_HASH = '0x172de9cda30537eae68ab4a96163ebbb8f8a85293b8737dd2e5deb4714b14623'
+  include ERC20::Checks
 
-  # Fakes:
-  attr_reader :host, :port, :ssl, :chain, :contract, :ws_path, :http_path
+  TXN_HASH = '0x172de9cda30537eae68ab4a96163ebbb8f8a85293b8737dd2e5deb4714b14623'
 
-  # Full history of all method calls:
-  attr_reader :history
+  attr_reader :host, :port, :ssl, :chain, :contract, :ws_path, :http_path, :history
 
   # Ctor.
   def initialize
@@ -54,6 +56,7 @@ class ERC20::FakeWallet
   # @param [String] address Public key, in hex, starting from '0x'
   # @return [Integer] Balance, in tokens
   def balance(address)
+    to_address(address)
     b = @balances[address] || 42_000_000
     @history << { method: :balance, address:, result: b }
     b
@@ -64,6 +67,7 @@ class ERC20::FakeWallet
   # @param [String] address Public key, in hex, starting from '0x'
   # @return [Integer] Balance, in tokens
   def eth_balance(address)
+    to_address(address)
     b = @eth_balances[address] || 77_000_000_000_000_000
     @history << { method: :eth_balance, address:, result: b }
     b
@@ -71,30 +75,43 @@ class ERC20::FakeWallet
 
   # Get ERC20 amount (in tokens) that was sent in the given transaction.
   #
-  # @param [String] _txn Hex of transaction
-  # @return [Integer] Balance, in ERC20 tokens
-  def sum_of(_txn)
-    42_000_000
+  # @param [String] txn Hex of transaction
+  # @param [String] to Public key of the receiver, in hex, starting from '0x'
+  # @return [Integer] Amount, in ERC20 tokens
+  def sum_of(txn, to: nil)
+    to_txn(txn)
+    to_address(to) unless to.nil?
+    tokens = 42_000_000
+    @history << { method: :sum_of, txn:, to:, result: tokens }
+    tokens
   end
 
-  # How much gas units is required in order to send ERC20 transaction.
+  # How many gas units are required to send an ERC20 transaction.
   #
   # @param [String] from The departing address, in hex
   # @param [String] to Arriving address, in hex
   # @param [Integer] amount How many ERC20 tokens to send
   # @return [Integer] How many gas units required
   def gas_estimate(from, to, amount)
+    to_address(from)
+    to_address(to)
+    to_amount(amount)
     gas = 66_000
     @history << { method: :gas_estimate, from:, to:, amount:, result: gas }
     gas
   end
 
-  # What is the price of gas unit in gwei?
-  # @return [Integer] Price of gas unit, in gwei (0.000000001 ETH)
+  # What is the price of gas unit in wei?
+  #
+  # The unit is the same as in +ERC20::Wallet#gas_price+: a price in gwei
+  # would be a billion times smaller and would make every fee computed in a
+  # test look affordable, while in production it wouldn't be.
+  #
+  # @return [Integer] Price of gas unit, in wei (1 gwei = 0.000000001 ETH)
   def gas_price
-    gwei = 55_555
-    @history << { method: :gas_price, result: gwei }
-    gwei
+    wei = 55_555_000_000
+    @history << { method: :gas_price, result: wei }
+    wei
   end
 
   # Send a single ERC20 payment from a private address to a public one.
@@ -103,9 +120,14 @@ class ERC20::FakeWallet
   # @param [String] address Public key, in hex
   # @param [Integer] amount The amount of ERC20 tokens to send
   # @param [Integer] limit Optional gas limit
-  # @param [Integer] price Optional gas price in gwei
+  # @param [Integer] price The most you pay per computation unit, in wei
   # @return [String] Transaction hash
-  def pay(priv, address, amount, limit: nil, price: nil)
+  def pay(priv, address, amount, limit: nil, price: gas_price)
+    to_priv(priv)
+    to_address(address)
+    to_amount(amount)
+    to_limit(limit) if limit
+    to_price(price)
     hex = TXN_HASH
     @history << { method: :pay, priv:, address:, amount:, limit:, price:, result: hex }
     hex
@@ -116,9 +138,13 @@ class ERC20::FakeWallet
   # @param [String] priv Private key, in hex
   # @param [String] address Public key, in hex
   # @param [Integer] amount The amount of ETHs to send
-  # @param [Integer] price Optional gas price in gwei
+  # @param [Integer] price The most you pay per computation unit, in wei
   # @return [String] Transaction hash
-  def eth_pay(priv, address, amount, price: nil)
+  def eth_pay(priv, address, amount, price: gas_price)
+    to_priv(priv)
+    to_address(address)
+    to_amount(amount)
+    to_price(price)
     hex = TXN_HASH
     @history << { method: :eth_pay, priv:, address:, amount:, price:, result: hex }
     hex
@@ -129,26 +155,34 @@ class ERC20::FakeWallet
   # @param [Array<String>] addresses Addresses to monitor
   # @param [Array] active List of addresses that we are actually listening to
   # @param [Boolean] raw TRUE if you need to get JSON events as they arrive from Websockets
-  # @param [Integer] delay How many seconds to wait between +eth_subscribe+ calls
-  def accept(addresses, active = [], raw: false, delay: 1)
-    @history << { method: :accept, addresses:, active:, raw:, delay: }
+  # @param [Numeric] delay How many seconds to wait between +eth_subscribe+ calls
+  # @param [Integer] subscription_id Unique ID of the subscription
+  def accept(addresses, active = [], raw: false, delay: 1, subscription_id: rand(1..99_999))
+    to_addresses(addresses)
+    to_active(active)
+    to_delay(delay)
+    to_subscription(subscription_id)
+    @history << { method: :accept, addresses:, active:, raw:, delay:, subscription_id: }
     addresses.to_a.each { |a| active.append(a) }
     loop do
       sleep(delay)
+      to_addresses(addresses)
       a = addresses.to_a.sample
       next if a.nil?
-      event =
+      yield(
         if raw
           {}
         else
           {
             amount: 424_242,
+            block: 42,
             from: '0xd5ff1bfcde7a03da61ad229d962c74f1ea2f16a5',
+            index: 0,
             to: a,
             txn: TXN_HASH
           }
         end
-      yield event
+      )
     end
   end
 end