erc20 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9719ca99febb05bab13326b5a1de126b73aa5d923ad7f091ef3c4493a6d4030f
-  data.tar.gz: b75de1bc31c3e1e1ac2b3167d92ac9d924841048035e190ec961dfebde81d9c5
+  metadata.gz: aae427d3d4d3c935aa7ea204031b9bdd85c67ce26fd182cb3a3d4ac8c2ed3cd4
+  data.tar.gz: 54fce4882a54f7de725bcc40ca234538900dfa67bcae210b23544ac0806d31d9
 SHA512:
-  metadata.gz: 6c306141b126499fe21d589809a596567439b7ec70ada449a0b7b4feee656fddb08d94f21943b10c6ea8c73526327a337cc056adc861a720fdee0bdce5e3a2f4
-  data.tar.gz: adc65e660ef7394c02f0d37979a7568c91b032a07620d25a40d3874e866468b3531e617e353d8bcd48b9e453d10891aa4977f67e21cbd41912123ce470ea3d79
+  metadata.gz: 8d49f09b1f3210391496b670aa467455584ba1cce21a19b2247bd6874438291803aef1e367e78c8027e2b6e1eb174ff7950eb002ae46ef272dcc59381948c7c0
+  data.tar.gz: ea308190d652a2f7747e24f93910e8d4a2c593acbc01edd53d60594e56f96652591a49281d6f784873f46c2474e99385292554eea66eb3cb6a856efd24c6796e

data/Gemfile

@@ -8,8 +8,9 @@ gemspec
 
 gem 'backtrace', '~>0.4', require: false
 gem 'concurrent-ruby', '~>1.2', require: false
-gem 'cucumber', '~>10.0', require: false
+gem 'cucumber', '~>11.0', require: false
 gem 'donce', '~>0.2', require: false
+gem 'em-websocket', '~>0.5', require: false
 gem 'faraday', '~>2.14', require: false
 gem 'loog', '~>0.6', require: false
 gem 'minitest', '~>6.0', require: false
@@ -18,14 +19,14 @@ gem 'minitest-retry', '~>0.2', require: false
 gem 'qbash', '~>0.4', require: false
 gem 'rake', '~>13.2', require: false
 gem 'random-port', '~>0.7', require: false
-gem 'rdoc', '~>7.0', require: false
+gem 'rdoc', '~>8.0', require: false
 gem 'rubocop', '~>1.75', require: false
 gem 'rubocop-elegant', '~>0.5', require: false
 gem 'rubocop-minitest', '~>0.38', require: false
 gem 'rubocop-performance', '~>1.25', require: false
 gem 'rubocop-rake', '~>0.7', require: false
-gem 'simplecov', '~>0.22', require: false
-gem 'simplecov-cobertura', '~>3.1', require: false
+gem 'simplecov', '~>1.0', require: false
+gem 'simplecov-cobertura', '~>4.0', require: false
 gem 'threads', '~>0.4', require: false
 gem 'typhoeus', '~>1.5', require: false
 gem 'webmock', '~>3.23', require: false

data/Gemfile.lock

@@ -21,22 +21,22 @@ GEM
     base64 (0.3.0)
     bigdecimal (4.1.2)
     builder (3.3.0)
-    concurrent-ruby (1.3.6)
+    concurrent-ruby (1.3.8)
     crack (1.0.1)
       bigdecimal
       rexml
-    cucumber (10.2.0)
+    cucumber (11.1.1)
       base64 (~> 0.2)
       builder (~> 3.2)
       cucumber-ci-environment (> 9, < 12)
-      cucumber-core (> 15, < 17)
+      cucumber-core (>= 16.2.0, < 17)
       cucumber-cucumber-expressions (> 17, < 20)
-      cucumber-html-formatter (> 21, < 23)
+      cucumber-html-formatter (> 21, < 24)
       diff-lcs (~> 1.5)
       logger (~> 1.6)
       mini_mime (~> 1.1)
       multi_test (~> 1.1)
-      sys-uname (~> 1.3)
+      sys-uname (~> 1.5)
     cucumber-ci-environment (11.0.0)
     cucumber-core (16.2.0)
       cucumber-gherkin (> 36, < 40)
@@ -46,13 +46,11 @@ GEM
       bigdecimal
     cucumber-gherkin (39.1.0)
       cucumber-messages (>= 31, < 33)
-    cucumber-html-formatter (22.3.0)
+    cucumber-html-formatter (23.1.0)
       cucumber-messages (> 23, < 33)
     cucumber-messages (32.3.1)
     cucumber-tag-expressions (8.1.0)
-    date (3.5.1)
     diff-lcs (1.6.2)
-    docile (1.4.1)
     donce (0.7.0)
       backtrace (~> 0.3)
       os (~> 1.1)
@@ -62,7 +60,10 @@ GEM
       loog (~> 0.6)
       tago (~> 0.1)
     ellipsized (0.3.0)
-    erb (6.0.4)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    erb (6.0.6)
     eth (0.5.13)
       forwardable (~> 1.3)
       keccak (~> 1.3)
@@ -74,11 +75,11 @@ GEM
       ffi (>= 1.15.0)
       logger
     eventmachine (1.2.7)
-    faraday (2.14.2)
+    faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.3)
+    faraday-net_http (3.4.4)
       net-http (~> 0.5)
     faye-websocket (0.12.0)
       eventmachine (>= 0.12.0)
@@ -92,13 +93,14 @@ GEM
       rake
     forwardable (1.4.0)
     hashdiff (1.2.1)
-    json (2.19.5)
+    http_parser.rb (0.8.1)
+    json (2.21.1)
     jsonrpc-client (0.1.4)
       faraday
       multi_json (>= 1.1.0)
     keccak (1.3.3)
     konstructor (1.0.2)
-    language_server-protocol (3.17.0.5)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     loog (0.8.0)
@@ -124,14 +126,11 @@ GEM
     openssl (3.3.3)
     os (1.1.4)
     parallel (2.1.0)
-    parser (3.3.11.1)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     pkg-config (1.6.5)
     prism (1.9.0)
-    psych (5.3.1)
-      date
-      stringio
     public_suffix (7.0.5)
     qbash (0.8.4)
       backtrace (> 0)
@@ -143,17 +142,22 @@ GEM
     rake (13.4.2)
     random-port (0.8.2)
       tago (~> 0.0)
+    rbs (4.1.0)
+      logger
+      prism (>= 1.6.0)
+      tsort
     rbsecp256k1 (6.0.0)
       mini_portile2 (~> 2.8)
       pkg-config (~> 1.5)
       rubyzip (~> 2.3)
-    rdoc (7.2.0)
+    rdoc (8.0.0)
       erb
-      psych (>= 4.0.0)
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
       tsort
     regexp_parser (2.12.0)
     rexml (3.4.4)
-    rubocop (1.86.2)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -164,13 +168,13 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
-    rubocop-elegant (0.5.1)
+    rubocop-elegant (0.7.1)
       lint_roller (~> 1.1)
       rubocop (~> 1.75)
-    rubocop-minitest (0.39.1)
+    rubocop-minitest (0.40.0)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
@@ -186,16 +190,10 @@ GEM
     scrypt (3.1.0)
       ffi-compiler (>= 1.0, < 2.0)
       rake (~> 13)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-cobertura (3.1.0)
+    simplecov (1.0.3)
+    simplecov-cobertura (4.0.0)
       rexml
-      simplecov (~> 0.19)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
-    stringio (3.2.0)
+      simplecov (~> 1.0)
     sys-uname (1.5.1)
       ffi (~> 1.1)
       memoist3 (~> 1.0.0)
@@ -219,12 +217,12 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    websocket-driver (0.8.0)
+    websocket-driver (0.8.2)
       base64
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
     win32ole (1.9.3)
-    yard (0.9.44)
+    yard (0.9.45)
 
 PLATFORMS
   arm64-darwin-22
@@ -238,8 +236,9 @@ PLATFORMS
 DEPENDENCIES
   backtrace (~> 0.4)
   concurrent-ruby (~> 1.2)
-  cucumber (~> 10.0)
+  cucumber (~> 11.0)
   donce (~> 0.2)
+  em-websocket (~> 0.5)
   erc20!
   faraday (~> 2.14)
   loog (~> 0.6)
@@ -249,14 +248,14 @@ DEPENDENCIES
   qbash (~> 0.4)
   rake (~> 13.2)
   random-port (~> 0.7)
-  rdoc (~> 7.0)
+  rdoc (~> 8.0)
   rubocop (~> 1.75)
   rubocop-elegant (~> 0.5)
   rubocop-minitest (~> 0.38)
   rubocop-performance (~> 1.25)
   rubocop-rake (~> 0.7)
-  simplecov (~> 0.22)
-  simplecov-cobertura (~> 3.1)
+  simplecov (~> 1.0)
+  simplecov-cobertura (~> 4.0)
   threads (~> 0.4)
   typhoeus (~> 1.5)
   webmock (~> 3.23)

data/README.md

@@ -40,7 +40,7 @@ w = ERC20::Wallet.new(
   host: 'mainnet.infura.io',
   http_path: '/v3/<your-infura-key>',
   ws_path: '/ws/v3/<your-infura-key>',
-  attempts: 3, # retry failed HTTP RPC calls up to 3 times, with backoff
+  attempts: 3, # try every endpoint up to 3 times, with backoff
   fallbacks: ['https://eth.drpc.org'], # alternative RPC endpoints to try
   log: $stdout
 )
@@ -58,9 +58,16 @@ w.accept(addresses) do |event|
   puts event[:amount] # how much, in tokens (1000000 = $1 USDT)
   puts event[:from] # who sent the payment
   puts event[:to] # who was the receiver
+  puts event[:block] # number of the block it was mined in
+  puts event[:index] # position of the log in the block
 end
 ```
 
+When the connection to the provider breaks, `accept` reconnects and fetches the
+logs of the blocks that were mined while it was away. A payment may reach the
+block twice because of that, so use `txn` and `index` together as the key of
+the payment and credit it only once.
+
 You can also check ETH balance and send ETH transactions:
 
 ```ruby
@@ -77,7 +84,8 @@ To check the price of a gas unit and the expected cost of a payment:
 # How many gas units required to send this payment:
 units = w.gas_estimate(from, to, amount)
 
-# What is the price of a gas unit, in wei:
+# What is the most a gas unit may cost, in wei (payments are type-2,
+# thus the network charges only the base fee plus the tip):
 price = w.gas_price
 ```
 

data/bin/erc20

@@ -43,7 +43,7 @@ class Bin < Thor
   class_option :proxy, type: :string,
     desc: 'HTTP/S proxy for all requests, e.g. "localhost:3128"'
   class_option :attempts, type: :numeric, default: 1,
-    desc: 'How many times should we try before failing'
+    desc: 'How many times should we try every endpoint before failing'
   class_option :fallbacks, type: :array,
     default: ['https://ethereum.publicnode.com', 'https://eth.drpc.org', 'https://rpc.ankr.com/eth'],
     desc: 'Fallback HTTP RPC endpoint URLs to try when the primary host fails'
@@ -151,10 +151,10 @@ class Bin < Thor
       amount = amount.to_i
       log.debug("The token amount equals to #{amount} ERC20 tokens (as provided)")
     elsif /^[0-9]+(\.[0-9]+)?usdt$/.match?(amount)
-      amount = (amount.gsub(/usdt$/, '').to_f * 1_000_000).to_i
+      amount = units(amount.gsub(/usdt$/, ''), 1_000_000)
       log.debug("The USDT amount equals to #{amount} ERC20 tokens")
     elsif /^\$[0-9]+(\.[0-9]+)?$/.match?(amount)
-      amount = (amount.gsub(/^\$/, '').to_f * 1_000_000).to_i
+      amount = units(amount.gsub(/^\$/, ''), 1_000_000)
       log.debug("The dollar amount equals to #{amount} ERC20 tokens")
     else
       raise "Can't understand amount: #{amount.inspect}"
@@ -165,16 +165,24 @@ class Bin < Thor
   def wei(amount)
     if /^[0-9]+$/.match?(amount)
       amount.to_i
-    elsif /[0-9]wei$/.match?(amount)
+    elsif /^[0-9]+wei$/.match?(amount)
       amount.gsub(/wei$/, '').to_i
-    elsif /[0-9]gwei$/.match?(amount)
-      (amount.gsub(/gwei$/, '').to_f * 1_000_000_000).to_i
-    elsif /[0-9]eth$/.match?(amount)
-      (amount.gsub(/eth$/, '').to_f * 1_000_000_000_000_000_000).to_i
+    elsif /^[0-9]+(\.[0-9]+)?gwei$/.match?(amount)
+      units(amount.gsub(/gwei$/, ''), 1_000_000_000)
+    elsif /^[0-9]+(\.[0-9]+)?eth$/.match?(amount)
+      units(amount.gsub(/eth$/, ''), 1_000_000_000_000_000_000)
     else
       raise "Can't understand amount: #{amount.inspect}"
     end
   end
+
+  def units(amount, factor)
+    exact = Rational(amount) * factor
+    unless exact.denominator == 1
+      raise "Amount #{amount.inspect} is too precise, while the smallest unit is 1/#{factor}"
+    end
+    exact.numerator
+  end
 end
 
 begin

data/features/dry.feature

@@ -21,13 +21,17 @@ Feature: Command Line Processing, in Dry Mode
     Then Exit code is zero
 
   Scenario: ERC20 payment can be sent in dollars
-    When I run bin/erc20 with "pay --dry --verbose 46feba063e9b59a8ae0dba68abd39a3cb8f52089e776576d6eb1bb5bfec123d1 0x7232148927F8a580053792f44D4d59d40Fd00ABD $10"
+    When I run bin/erc20 with "pay --dry --verbose 46feba063e9b59a8ae0dba68abd39a3cb8f52089e776576d6eb1bb5bfec123d1 0x7232148927F8a580053792f44D4d59d40Fd00ABD \$10"
     Then Exit code is zero
 
   Scenario: ERC20 payment can be sent in USDT
     When I run bin/erc20 with "pay --dry --verbose 46feba063e9b59a8ae0dba68abd39a3cb8f52089e776576d6eb1bb5bfec123d1 0x7232148927F8a580053792f44D4d59d40Fd00ABD 10usdt"
     Then Exit code is zero
 
+  Scenario: ERC20 payment in USDT keeps every token unit
+    When I run bin/erc20 with "pay --dry --verbose 46feba063e9b59a8ae0dba68abd39a3cb8f52089e776576d6eb1bb5bfec123d1 0x7232148927F8a580053792f44D4d59d40Fd00ABD 8.2usdt"
+    Then Stdout contains "Sending 8200000 ERC20 tokens"
+
   Scenario: ETH payment can be sent in wei
     When I run bin/erc20 with "eth_pay --dry --verbose 46feba063e9b59a8ae0dba68abd39a3cb8f52089e776576d6eb1bb5bfec123d1 0x7232148927F8a580053792f44D4d59d40Fd00ABD 10000000"
     Then Exit code is zero
@@ -35,3 +39,7 @@ Feature: Command Line Processing, in Dry Mode
   Scenario: ETH payment can be sent in ETH
     When I run bin/erc20 with "eth_pay --dry --verbose 46feba063e9b59a8ae0dba68abd39a3cb8f52089e776576d6eb1bb5bfec123d1 0x7232148927F8a580053792f44D4d59d40Fd00ABD 1eth"
     Then Exit code is zero
+
+  Scenario: ETH payment smaller than one wei is rejected
+    When I run bin/erc20 with "eth_pay --dry 46feba063e9b59a8ae0dba68abd39a3cb8f52089e776576d6eb1bb5bfec123d1 0x7232148927F8a580053792f44D4d59d40Fd00ABD 0.0000000000000000001eth"
+    Then Exit code is not zero

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,5 +24,5 @@
 # Copyright:: Copyright (c) 2025 Yegor Bugayenko
 # License:: MIT
 module ERC20
-  VERSION = '0.3.0' unless defined?(VERSION)
+  VERSION = '0.4.0' unless defined?(VERSION)
 end

data/lib/erc20/fake_wallet.rb

@@ -3,15 +3,22 @@
 # 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
+  include ERC20::Checks
+
   TXN_HASH = '0x172de9cda30537eae68ab4a96163ebbb8f8a85293b8737dd2e5deb4714b14623'
 
   attr_reader :host, :port, :ssl, :chain, :contract, :ws_path, :http_path, :history
@@ -49,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
@@ -59,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
@@ -66,10 +75,15 @@ 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 many gas units are required to send an ERC20 transaction.
@@ -79,17 +93,25 @@ class ERC20::FakeWallet
   # @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.
@@ -98,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
@@ -111,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
@@ -124,12 +155,18 @@ 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?
       yield(
@@ -138,7 +175,9 @@ class ERC20::FakeWallet
         else
           {
             amount: 424_242,
+            block: 42,
             from: '0xd5ff1bfcde7a03da61ad229d962c74f1ea2f16a5',
+            index: 0,
             to: a,
             txn: TXN_HASH
           }

data/lib/erc20/wallet.rb

@@ -11,6 +11,7 @@ require 'json'
 require 'jsonrpc/client'
 require 'loog'
 require 'uri'
+require_relative 'checks'
 require_relative 'erc20'
 
 # A wallet with ERC20 tokens on Ethereum.
@@ -58,6 +59,8 @@ require_relative 'erc20'
 # Copyright:: Copyright (c) 2025 Yegor Bugayenko
 # License:: MIT
 class ERC20::Wallet
+  include ERC20::Checks
+
   USDT = '0xdac17f958d2ee523a2206206994597c13d831ec7'
   TRANSFER = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
 
@@ -72,7 +75,7 @@ class ERC20::Wallet
   # @param [String] ws_path The path in the connection URL, for Websockets
   # @param [Boolean] ssl Should we use SSL (for https and wss)
   # @param [String] proxy The URL of the proxy to use
-  # @param [Integer] attempts How many times to retry a failed HTTP RPC call before giving up
+  # @param [Integer] attempts How many times to try every HTTP RPC endpoint before giving up
   # @param [Array<String>] fallbacks Alternative HTTP RPC endpoint URLs to try when the primary one fails
   # @param [Object] log The destination for logs
   def initialize(
@@ -125,14 +128,26 @@ class ERC20::Wallet
   # balance in ETH crypto. Another balance is the one kept by the ERC20 contract
   # in its own ledger in root storage. This balance is checked by this method.
   #
+  # An address that has no tokens has a balance of zero, but so does an address
+  # asked at the wrong contract or in the wrong chain: there, +eth_call+ succeeds
+  # with empty return data. A +balanceOf+ always answers with a single 32-byte
+  # word, thus anything shorter is a misconfiguration and an error is raised,
+  # instead of a zero that nobody may tell from a genuinely empty balance.
+  #
   # @param [String] address Public key, in hex, starting from '0x'
   # @return [Integer] Balance, in tokens
   def balance(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 /^0x[0-9a-fA-F]{40}$/.match?(address)
+    to_address(address)
     data = "0x70a08231000000000000000000000000#{address[2..].downcase}"
-    b = with_jsonrpc { |jr| jr.eth_call({ to: @contract, data: data }, 'latest') }[2..].to_i(16)
+    hex = with_jsonrpc { |jr| jr.eth_call({ to: @contract, data: data }, 'latest') }
+    unless /^0x[0-9a-fA-F]{64}$/.match?(hex)
+      raise(
+        StandardError,
+        "The #{@contract} contract in chain #{@chain} answered #{hex.inspect} instead of " \
+        'a 32-byte word, it may not be an ERC20 contract at all'
+      )
+    end
+    b = hex[2..].to_i(16)
     log_it(:debug, "The balance of #{address} is #{b} ERC20 tokens")
     b
   end
@@ -145,36 +160,54 @@ class ERC20::Wallet
   # @param [String] address Public key, in hex, starting from '0x'
   # @return [Integer] Balance, in ETH
   def eth_balance(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 /^0x[0-9a-fA-F]{40}$/.match?(address)
-    b = with_jsonrpc { |jr| jr.eth_getBalance(address, 'latest') }[2..].to_i(16)
+    to_address(address)
+    hex = with_jsonrpc { |jr| jr.eth_getBalance(address, 'latest') }
+    unless /^0x[0-9a-fA-F]+$/.match?(hex)
+      raise(StandardError, "The node answered #{hex.inspect} instead of a hex quantity, for the balance of #{address}")
+    end
+    b = hex[2..].to_i(16)
     log_it(:debug, "The balance of #{address} is #{b} ETHs")
     b
   end
 
   # Get ERC20 amount (in tokens) that was sent in the given transaction.
   #
+  # One transaction may carry many transfers of the same token: batch payouts,
+  # multisend contracts, swaps, and fee splits all do that. When the +to+ is
+  # given, only the transfers to that address are counted and their sum is
+  # returned. When it is not given and the transaction carries more than one
+  # transfer, the amount is ambiguous and an error is raised.
+  #
   # @param [String] txn Hex of transaction
-  # @return [Integer] Balance, in ERC20 tokens
-  def sum_of(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)
+  # @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?
     receipt =
       with_jsonrpc do |jr|
         jr.eth_getTransactionReceipt(txn)
       end
     raise(StandardError, "Transaction not found: #{txn}") if receipt.nil?
-    logs = receipt['logs'] || []
-    logs.each do |log|
-      next unless log['topics'] && log['topics'][0] == TRANSFER
-      next unless log['address'].downcase == @contract.downcase
-      amount = log['data'].to_i(16)
-      log_it(:debug, "Found transfer of #{amount} tokens in transaction #{txn}")
-      return amount
+    raise(StandardError, "Transaction #{txn} is reverted, its status is #{receipt['status']}") \
+      unless receipt['status'] == '0x1'
+    amounts =
+      (receipt['logs'] || []).filter_map do |log|
+        next unless log['topics'] && log['topics'][0] == TRANSFER
+        next unless log['address'].downcase == @contract.downcase
+        next unless to.nil? || log['topics'][2].to_s.downcase == "0x000000000000000000000000#{to[2..].downcase}"
+        log['data'].to_i(16)
+      end
+    raise(StandardError, "No transfer event found in transaction #{txn}") if amounts.empty?
+    if to.nil? && amounts.size > 1
+      raise(
+        StandardError,
+        "Transaction #{txn} carries #{amounts.size} transfers, tell me the receiving address to pick the right ones"
+      )
     end
-    raise(StandardError, "No transfer event found in transaction #{txn}")
+    sum = amounts.sum
+    log_it(:debug, "Found transfer of #{sum} tokens in transaction #{txn}")
+    sum
   end
 
   # How many gas units are required to send an ERC20 transaction.
@@ -184,15 +217,9 @@ class ERC20::Wallet
   # @param [Integer] amount How many ERC20 tokens to send
   # @return [Integer] Number of gas units required
   def gas_estimate(from, to, amount)
-    raise(ArgumentError, 'Address can\'t be nil') unless from
-    raise(ArgumentError, 'Address must be a String') unless from.is_a?(String)
-    raise(ArgumentError, 'Invalid format of the address') unless /^0x[0-9a-fA-F]{40}$/.match?(from)
-    raise(ArgumentError, 'Address can\'t be nil') unless to
-    raise(ArgumentError, 'Address must be a String') unless to.is_a?(String)
-    raise(ArgumentError, 'Invalid format of the address') unless /^0x[0-9a-fA-F]{40}$/.match?(to)
-    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?
+    to_address(from)
+    to_address(to)
+    to_amount(amount)
     gas =
       with_jsonrpc do |jr|
         jr.eth_estimateGas({ from:, to: @contract, data: to_pay_data(to, amount) }, 'latest').to_i(16)
@@ -219,6 +246,10 @@ class ERC20::Wallet
   # price mineable, we double the base fee (a buffer that absorbs several blocks
   # of base-fee growth) and add a priority tip (+GAS_PRICE_TIP+).
   #
+  # The price is a ceiling, not a payment: it lands in the +maxFeePerGas+ of a
+  # type-2 transaction, where the network charges only +baseFee + tip+ per gas
+  # unit and refunds the rest of the buffer.
+  #
   # @return [Integer] Price of gas unit, in wei (1 gwei = 0.000000001 ETH)
   def gas_price
     block =
@@ -226,7 +257,9 @@ class ERC20::Wallet
         jr.eth_getBlockByNumber('latest', false)
       end
     raise(StandardError, "Can't get gas price, try again later") if block.nil?
-    base = block['baseFeePerGas'].to_i(16)
+    fee = block['baseFeePerGas']
+    raise(StandardError, 'The latest block has no baseFeePerGas, the chain is not EIP-1559 capable') if fee.nil?
+    base = fee.to_i(16)
     price = (base * 2) + GAS_PRICE_TIP
     log_it(:debug, "The base fee is #{base} wei, the cost of one gas unit is #{price} wei")
     price
@@ -242,52 +275,47 @@ class ERC20::Wallet
   # decrease your balance and increase the recipient's balance. This requires more
   # gas than ETH transfers since it involves executing contract code.
   #
+  # The nonce is fetched and the transaction is signed before the broadcast,
+  # outside of the retry loop. A broadcast that fails is repeated with the very
+  # same signed transaction, which the network either mines once or rejects as
+  # already known. Thus, no number of +attempts+ may pay twice.
+  #
+  # The transaction is a type-2 one (EIP-1559): the +price+ is the most the
+  # sender agrees to pay per gas unit, while the actual payment is only
+  # +baseFee + GAS_PRICE_TIP+.
+  #
   # @param [String] priv Private key, in hex
   # @param [String] address Public key, in hex
   # @param [Integer] amount The amount of ERC20 tokens to send
   # @param [Integer] limit How much gas you're ready to spend
-  # @param [Integer] price How much gas you pay per computation unit
+  # @param [Integer] price The most you pay per computation unit
   # @return [String] Transaction hash
   def pay(priv, address, amount, limit: nil, price: gas_price)
-    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)
-    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 /^0x[0-9a-fA-F]{40}$/.match?(address)
-    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?
-    if limit
-      raise(ArgumentError, 'Gas limit must be an Integer') unless limit.is_a?(Integer)
-      raise(ArgumentError, "Gas limit #{limit} is below #{Eth::Tx::DEFAULT_GAS_LIMIT}") if limit < Eth::Tx::DEFAULT_GAS_LIMIT
-      raise(ArgumentError, "Gas limit #{limit} is above #{Eth::Tx::BLOCK_GAS_LIMIT}") if limit > Eth::Tx::BLOCK_GAS_LIMIT
-    end
-    if 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?
-    end
+    to_priv(priv)
+    to_address(address)
+    to_amount(amount)
+    to_limit(limit) if limit
+    to_price(price)
     key = Eth::Key.new(priv: priv)
     from = key.address.to_s
     tnx =
       @mutex.synchronize do
-        with_jsonrpc do |jr|
-          tx = Eth::Tx.new(
-            {
-              nonce: jr.eth_getTransactionCount(from, 'pending').to_i(16),
-              gas_price: price,
-              gas_limit: limit || gas_estimate(from, address, amount),
-              to: @contract,
-              value: 0,
-              data: to_pay_data(address, amount),
-              chain_id: @chain
-            }
-          )
-          tx.sign(key)
-          hex = "0x#{tx.hex}"
-          log_it(:debug, "Sending ERC20 transaction #{hex}")
-          jr.eth_sendRawTransaction(hex)
-        end
+        tx = Eth::Tx.new(
+          {
+            nonce: with_jsonrpc { |jr| jr.eth_getTransactionCount(from, 'pending').to_i(16) },
+            max_gas_fee: price,
+            priority_fee: tip(price),
+            gas_limit: limit || gas_estimate(from, address, amount),
+            to: @contract,
+            value: 0,
+            data: to_pay_data(address, amount),
+            chain_id: @chain
+          }
+        )
+        tx.sign(key)
+        hex = "0x#{tx.hex}"
+        log_it(:debug, "Sending ERC20 transaction #{hex}")
+        with_jsonrpc { |jr| jr.eth_sendRawTransaction(hex) }
       end
     log_it(:debug, "Sent #{amount} ERC20 tokens from #{from} to #{address}: #{tnx}")
     tnx.downcase
@@ -298,42 +326,32 @@ class ERC20::Wallet
   # @param [String] priv Private key, in hex
   # @param [String] address Public key, in hex
   # @param [Integer] amount The amount of ETH to send
-  # @param [Integer] price How much gas you pay per computation unit
+  # @param [Integer] price The most you pay per computation unit
   # @return [String] Transaction hash
   def eth_pay(priv, address, amount, price: gas_price)
-    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)
-    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 /^0x[0-9a-fA-F]{40}$/.match?(address)
-    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?
-    if 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?
-    end
+    to_priv(priv)
+    to_address(address)
+    to_amount(amount)
+    to_price(price)
     key = Eth::Key.new(priv: priv)
     from = key.address.to_s
     tnx =
       @mutex.synchronize do
-        with_jsonrpc do |jr|
-          tx = Eth::Tx.new(
-            {
-              chain_id: @chain,
-              nonce: jr.eth_getTransactionCount(from, 'pending').to_i(16),
-              gas_price: price,
-              gas_limit: 22_000,
-              to: address,
-              value: amount
-            }
-          )
-          tx.sign(key)
-          hex = "0x#{tx.hex}"
-          log_it(:debug, "Sending ETH transaction #{hex}")
-          jr.eth_sendRawTransaction(hex)
-        end
+        tx = Eth::Tx.new(
+          {
+            chain_id: @chain,
+            nonce: with_jsonrpc { |jr| jr.eth_getTransactionCount(from, 'pending').to_i(16) },
+            max_gas_fee: price,
+            priority_fee: tip(price),
+            gas_limit: 22_000,
+            to: address,
+            value: amount
+          }
+        )
+        tx.sign(key)
+        hex = "0x#{tx.hex}"
+        log_it(:debug, "Sending ETH transaction #{hex}")
+        with_jsonrpc { |jr| jr.eth_sendRawTransaction(hex) }
       end
     log_it(:debug, "Sent #{amount} ETHs from #{from} to #{address}: #{tnx}")
     tnx.downcase
@@ -352,29 +370,51 @@ class ERC20::Wallet
   #
   # The +addresses+ must have +to_a()+ implemented. This method will be
   # called every +delay+ seconds. It is expected that it returns the list
-  # of Ethereum public addresses that must be monitored.
+  # of Ethereum public addresses that must be monitored. Every address must
+  # be a hex with the +0x+ prefix, both at the start and later, when the list
+  # changes: a malformed address makes the filter of the subscription target
+  # a different address, thus payments are never seen.
+  #
+  # The +active+ must have +append()+, +clear()+ and +to_a()+ implemented. This
+  # array holds the addresses that the node has confirmed a subscription for,
+  # and it is rebuilt on every confirmation. This array is used mostly for
+  # testing. It is suggested to always provide an empty array.
+  #
+  # When the node answers a subscribe request with an error, the addresses stay
+  # out of +active+, the error goes to the log, and the next subscribe attempt
+  # happens +delay+ seconds later.
+  #
+  # A dropped connection leaves a gap: the blocks mined between the disconnect
+  # and the confirmation of the new subscription are not streamed by the node.
+  # After a reconnect, the logs of that gap are fetched with +eth_getLogs+ and
+  # yielded before the live ones. A payment may arrive twice this way, because
+  # the gap starts at the block of the last payment seen, and the block must be
+  # ready for it: use +txn+ and +index+ of the event as the key of the payment.
+  #
+  # An exception from the block does not stop the stream: it goes to the log
+  # and the event is gone, since the node has no way of sending it again. The
+  # block must handle its own errors, if the payment must not be lost.
   #
-  # The +active+ must have +append()+ and +to_a()+ implemented. This array
-  # maintains the list of addresses that were mentioned in incoming transactions.
-  # This array is used mostly for testing. It is suggested to always provide
-  # an empty array.
+  # A reorganization of the chain may revert a payment that was already mined.
+  # The node then re-sends its log with the +removed+ flag set. Such an event
+  # is not yielded, since the payment never happened. In +raw+ mode the event
+  # is yielded as it arrives and the +removed+ flag must be checked by the
+  # consumer.
+  #
+  # Events are yielded with zero confirmations, the moment they arrive from the
+  # node. A payment must not be treated as settled until enough blocks are
+  # mined on top of it.
   #
   # @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
+  # @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(99_999), &)
-    raise(ArgumentError, 'Addresses can\'t be nil') unless addresses
-    raise(ArgumentError, 'Addresses must respond to .to_a()') unless addresses.respond_to?(:to_a)
-    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)
-    raise(ArgumentError, 'Delay must be an Integer') unless delay.is_a?(Integer)
-    raise(ArgumentError, 'Delay must be a positive Integer or positive Float') unless delay.positive?
-    raise(ArgumentError, 'Subscription ID must be an Integer') unless subscription_id.is_a?(Integer)
-    raise(ArgumentError, 'Subscription ID must be a positive Integer') unless subscription_id.positive?
+  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)
     EventMachine.run do
       reaccept(addresses, active, raw:, delay:, subscription_id:, &)
     end
@@ -385,16 +425,19 @@ class ERC20::Wallet
   # @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
+  # @param [Numeric] delay How many seconds to wait between +eth_subscribe+ calls
   # @param [Integer] subscription_id Unique ID of the subscription
+  # @param [Integer] since The number of the last block we have seen a payment in
   # @return [Websocket]
-  def reaccept(addresses, active, raw:, delay:, subscription_id:, &)
+  def reaccept(addresses, active, raw:, delay:, subscription_id:, since: nil, &)
     u = url(http: false)
     log_it(:debug, "Connecting ##{subscription_id} to #{u.hostname}:#{u.port}...")
-    contract = @contract
     log_url = "ws#{'s' if @ssl}://#{u.hostname}:#{u.port}"
     ws = Faye::WebSocket::Client.new(u.to_s, [], proxy: @proxy ? { origin: @proxy } : {}, ping: 60)
     timer = nil
+    subscription = nil
+    wanted = nil
+    height = since
     ws.on(:open) do
       safe do
         verbose do
@@ -402,30 +445,33 @@ class ERC20::Wallet
           timer =
             EventMachine.add_periodic_timer(delay) do
               next if active.to_a.sort == addresses.to_a.sort
+              wanted = to_addresses(addresses).dup
               # rubocop:disable Style/Send
+              if subscription
+                ws.send(
+                  {
+                    jsonrpc: '2.0',
+                    id: subscription_id + 1,
+                    method: 'eth_unsubscribe',
+                    params: [subscription]
+                  }.to_json
+                )
+                log_it(:debug, "Requested to unsubscribe ##{subscription_id} from #{subscription}")
+                subscription = nil
+              end
               ws.send(
                 {
                   jsonrpc: '2.0',
                   id: subscription_id,
                   method: 'eth_subscribe',
-                  params: [
-                    'logs',
-                    {
-                      address: contract,
-                      topics: [
-                        '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
-                        nil,
-                        addresses.to_a.map { |a| "0x000000000000000000000000#{a[2..]}" }
-                      ]
-                    }
-                  ]
+                  params: ['logs', to_filter(wanted)]
                 }.to_json
               )
               # rubocop:enable Style/Send
               log_it(
                 :debug,
-                "Requested to subscribe ##{subscription_id} to #{addresses.to_a.size} addresses: " \
-                "#{addresses.to_a.map { |a| a[0..6] }.join(', ')}"
+                "Requested to subscribe ##{subscription_id} to #{wanted.size} addresses: " \
+                "#{wanted.map { |a| a[0..6] }.join(', ')}"
               )
             end
         end
@@ -435,35 +481,41 @@ class ERC20::Wallet
       safe do
         verbose do
           data = to_json(msg)
-          if data['id']
-            before = active.to_a.uniq
-            addresses.to_a.each do |a|
-              next if before.include?(a)
-              active.append(a)
-            end
+          if data['error']
+            active.clear if data['id'] == subscription_id
+            log_it(:error, "Request ##{data['id']} was rejected by #{log_url}: #{data['error']}")
+          elsif data['id'] == subscription_id
+            subscription = data['result']
+            active.clear
+            wanted&.each { |a| active.append(a) }
             log_it(
               :debug,
               "Subscribed ##{subscription_id} to #{active.to_a.size} addresses at #{log_url}: " \
               "#{active.to_a.map { |a| a[0..6] }.join(', ')}"
             )
-          elsif data['method'] == 'eth_subscription' && data.dig('params', 'result')
-            event = data['params']['result']
-            if raw
-              log_it(:debug, "New event arrived from #{event['address']}")
-            else
-              event = {
-                amount: event['data'].to_i(16),
-                from: "0x#{event['topics'][1][26..].downcase}",
-                to: "0x#{event['topics'][2][26..].downcase}",
-                txn: event['transactionHash'].downcase
-              }
-              log_it(
-                :debug,
-                "Payment of #{event[:amount]} tokens arrived at ##{subscription_id} " \
-                "from #{event[:from]} to #{event[:to]} in #{event[:txn]}"
+            if since
+              # rubocop:disable Style/Send
+              ws.send(
+                {
+                  jsonrpc: '2.0',
+                  id: subscription_id + 2,
+                  method: 'eth_getLogs',
+                  params: [to_filter(wanted).merge(fromBlock: format('0x%x', since + 1), toBlock: 'latest')]
+                }.to_json
               )
+              # rubocop:enable Style/Send
+              log_it(:debug, "Requested ##{subscription_id} the logs of the blocks after ##{since}")
+              since = nil
             end
-            yield(event)
+          elsif data['id'] == subscription_id + 2
+            log_it(:debug, "Received #{data['result'].size} logs mined while ##{subscription_id} was offline")
+            data['result'].each do |log|
+              height = [height, log['blockNumber'].to_s.to_i(16)].compact.max
+              deliver(log, raw:, id: subscription_id, &)
+            end
+          elsif data['method'] == 'eth_subscription' && data.dig('params', 'result')
+            height = [height, data['params']['result']['blockNumber'].to_s.to_i(16)].compact.max
+            deliver(data['params']['result'], raw:, id: subscription_id, &)
           end
         end
       end
@@ -474,7 +526,9 @@ class ERC20::Wallet
           log_it(:debug, "Disconnected ##{subscription_id} from #{log_url}")
           active.clear
           timer&.cancel
-          reaccept(addresses, active, raw:, delay:, subscription_id: subscription_id + 1, &)
+          EventMachine.add_timer(delay) do
+            reaccept(addresses, active, raw:, delay:, subscription_id: subscription_id + 1, since: height, &)
+          end
         end
       end
     end
@@ -487,9 +541,55 @@ class ERC20::Wallet
     end
   end
 
+  def to_filter(addresses)
+    {
+      address: @contract,
+      topics: [
+        TRANSFER,
+        nil,
+        addresses.to_a.map { |a| "0x000000000000000000000000#{a[2..]}" }
+      ]
+    }
+  end
+
+  def to_event(log)
+    {
+      amount: log['data'].to_i(16),
+      block: log['blockNumber'].to_s.to_i(16),
+      from: "0x#{log['topics'][1][26..].downcase}",
+      index: log['logIndex'].to_s.to_i(16),
+      to: "0x#{log['topics'][2][26..].downcase}",
+      txn: log['transactionHash'].downcase
+    }
+  end
+
+  def deliver(log, raw:, id:, &)
+    if raw
+      log_it(:debug, "New event arrived from #{log['address']}")
+      digest(log, log['transactionHash'], &)
+    elsif log['removed']
+      log_it(:debug, "Payment in #{log['transactionHash']} is reverted by a reorganization of the chain, ignoring it")
+    else
+      event = to_event(log)
+      log_it(
+        :debug,
+        "Payment of #{event[:amount]} tokens arrived at ##{id} " \
+        "from #{event[:from]} to #{event[:to]} in #{event[:txn]}"
+      )
+      digest(event, event[:txn], &)
+    end
+  end
+
+  def digest(event, txn)
+    yield(event)
+  rescue StandardError => e
+    log_it(:error, "The block failed to process the payment in #{txn}, the event is lost (#{e.class}): #{e.message}")
+  end
+
   def to_json(msg)
     JSON.parse(msg.data)
-  rescue StandardError
+  rescue StandardError => e
+    log_it(:error, "Failed to parse a frame of #{msg.data.to_s.length} bytes (#{e.message}): #{msg.data}")
     {}
   end
 
@@ -522,26 +622,29 @@ class ERC20::Wallet
         end
     end
     endpoints = [url.to_s] + @fallbacks
-    attempt = 0
+    budget = @attempts * endpoints.size
+    tried = 0
     begin
-      attempt += 1
-      u = URI.parse(endpoints[(attempt - 1) % endpoints.size])
+      u = URI.parse(endpoints[tried % endpoints.size])
+      tried += 1
       elapsed(@log, good: "Talked to #{u.host}:#{u.port}") do
         yield(JSONRPC::Client.new(u.to_s, opts))
       end
     rescue StandardError => e
-      raise if attempt >= @attempts
-      pause = 2**(attempt - 1)
-      log_it(:debug, "Attempt #{attempt}/#{@attempts} to #{u.host} failed (#{e.class}), retrying in #{pause}s")
+      raise if tried >= budget
+      pause = (tried % endpoints.size).zero? ? 2**((tried / endpoints.size) - 1) : 0
+      log_it(:debug, "Attempt #{tried}/#{budget} to #{u.host} failed (#{e.class}), retrying in #{pause}s")
       sleep(pause)
       retry
     end
   end
 
+  def tip(price)
+    [GAS_PRICE_TIP, price].min
+  end
+
   def to_pay_data(address, amount)
-    to_clean = address.downcase.sub(/^0x/, '')
-    amt_hex = amount.to_s(16)
-    "0xa9059cbb#{('0' * (64 - to_clean.size)) + to_clean}#{('0' * (64 - amt_hex.size)) + amt_hex}"
+    "0xa9059cbb#{format('%064x', address.to_i(16))}#{format('%064x', amount)}"
   end
 
   def log_it(method, msg)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: erc20
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -141,6 +141,7 @@ files:
 - hardhat/ignition/modules/Foo.ts
 - hardhat/package.json
 - lib/erc20.rb
+- lib/erc20/checks.rb
 - lib/erc20/erc20.rb
 - lib/erc20/fake_wallet.rb
 - lib/erc20/wallet.rb