erc20 0.2.9 → 0.4.0

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,10 +59,11 @@ require_relative 'erc20'
 # Copyright:: Copyright (c) 2025 Yegor Bugayenko
 # License:: MIT
 class ERC20::Wallet
-  # Address of USDT contract.
+  include ERC20::Checks
+
   USDT = '0xdac17f958d2ee523a2206206994597c13d831ec7'
+  TRANSFER = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
 
-  # These properties are read-only:
   attr_reader :host, :port, :ssl, :chain, :contract, :ws_path, :http_path
 
   # Constructor.
@@ -73,36 +75,50 @@ 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 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(contract: USDT, chain: 1, log: $stdout,
-                 host: nil, port: 443, http_path: '/', ws_path: '/',
-                 ssl: true, proxy: nil)
-    raise 'Contract can\'t be nil' unless contract
-    raise 'Contract must be a String' unless contract.is_a?(String)
-    raise 'Invalid format of the contract' unless /^0x[0-9a-fA-F]{40}$/.match?(contract)
+  def initialize(
+    contract: USDT, chain: 1, log: $stdout,
+    host: nil, port: 443, http_path: '/', ws_path: '/',
+    ssl: true, proxy: nil, attempts: 1, fallbacks: []
+  )
+    raise(ArgumentError, 'Contract can\'t be nil') unless contract
+    raise(ArgumentError, 'Contract must be a String') unless contract.is_a?(String)
+    raise(ArgumentError, 'Invalid format of the contract') unless /^0x[0-9a-fA-F]{40}$/.match?(contract)
     @contract = contract
-    raise 'Host can\'t be nil' unless host
-    raise 'Host must be a String' unless host.is_a?(String)
+    raise(ArgumentError, 'Host can\'t be nil') unless host
+    raise(ArgumentError, 'Host must be a String') unless host.is_a?(String)
     @host = host
-    raise 'Port can\'t be nil' unless port
-    raise 'Port must be an Integer' unless port.is_a?(Integer)
-    raise 'Port must be a positive Integer' unless port.positive?
+    raise(ArgumentError, 'Port can\'t be nil') unless port
+    raise(ArgumentError, 'Port must be an Integer') unless port.is_a?(Integer)
+    raise(ArgumentError, 'Port must be a positive Integer') unless port.positive?
     @port = port
-    raise 'Ssl can\'t be nil' if ssl.nil?
+    raise(ArgumentError, 'Ssl can\'t be nil') if ssl.nil?
     @ssl = ssl
-    raise 'Http_path can\'t be nil' unless http_path
-    raise 'Http_path must be a String' unless http_path.is_a?(String)
+    raise(ArgumentError, 'Http_path can\'t be nil') unless http_path
+    raise(ArgumentError, 'Http_path must be a String') unless http_path.is_a?(String)
     @http_path = http_path
-    raise 'Ws_path can\'t be nil' unless ws_path
-    raise 'Ws_path must be a String' unless ws_path.is_a?(String)
+    raise(ArgumentError, 'Ws_path can\'t be nil') unless ws_path
+    raise(ArgumentError, 'Ws_path must be a String') unless ws_path.is_a?(String)
     @ws_path = ws_path
-    raise 'Log can\'t be nil' unless log
+    raise(ArgumentError, 'Log can\'t be nil') unless log
     @log = log
-    raise 'Chain can\'t be nil' unless chain
-    raise 'Chain must be an Integer' unless chain.is_a?(Integer)
-    raise 'Chain must be a positive Integer' unless chain.positive?
+    raise(ArgumentError, 'Chain can\'t be nil') unless chain
+    raise(ArgumentError, 'Chain must be an Integer') unless chain.is_a?(Integer)
+    raise(ArgumentError, 'Chain must be a positive Integer') unless chain.positive?
     @chain = chain
     @proxy = proxy
+    raise(ArgumentError, 'Attempts can\'t be nil') unless attempts
+    raise(ArgumentError, 'Attempts must be an Integer') unless attempts.is_a?(Integer)
+    raise(ArgumentError, 'Attempts must be a positive Integer') unless attempts.positive?
+    @attempts = attempts
+    raise(ArgumentError, 'Fallbacks can\'t be nil') if fallbacks.nil?
+    raise(ArgumentError, 'Fallbacks must be an Array') unless fallbacks.is_a?(Array)
+    fallbacks.each do |f|
+      raise(ArgumentError, 'Each fallback must be a String') unless f.is_a?(String)
+    end
+    @fallbacks = fallbacks
     @mutex = Mutex.new
   end
 
@@ -112,19 +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 'Address can\'t be nil' unless address
-    raise 'Address must be a String' unless address.is_a?(String)
-    raise 'Invalid format of the address' unless /^0x[0-9a-fA-F]{40}$/.match?(address)
-    func = '70a08231' # balanceOf
-    data = "0x#{func}000000000000000000000000#{address[2..].downcase}"
-    r =
-      with_jsonrpc do |jr|
-        jr.eth_call({ to: @contract, data: data }, 'latest')
-      end
-    b = r[2..].to_i(16)
+    to_address(address)
+    data = "0x70a08231000000000000000000000000#{address[2..].downcase}"
+    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
@@ -137,41 +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 'Address can\'t be nil' unless address
-    raise 'Address must be a String' unless address.is_a?(String)
-    raise 'Invalid format of the address' unless /^0x[0-9a-fA-F]{40}$/.match?(address)
-    r =
-      with_jsonrpc do |jr|
-        jr.eth_getBalance(address, 'latest')
-      end
-    b = r[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 'Transaction hash can\'t be nil' unless txn
-    raise 'Transaction hash must be a String' unless txn.is_a?(String)
-    raise '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 "Transaction not found: #{txn}" if receipt.nil?
-    logs = receipt['logs'] || []
-    transfer_event = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
-    logs.each do |log|
-      next unless log['topics'] && log['topics'][0] == transfer_event
-      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 not found: #{txn}") if receipt.nil?
+    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 "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.
@@ -181,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 'Address can\'t be nil' unless from
-    raise 'Address must be a String' unless from.is_a?(String)
-    raise 'Invalid format of the address' unless /^0x[0-9a-fA-F]{40}$/.match?(from)
-    raise 'Address can\'t be nil' unless to
-    raise 'Address must be a String' unless to.is_a?(String)
-    raise 'Invalid format of the address' unless /^0x[0-9a-fA-F]{40}$/.match?(to)
-    raise 'Amount can\'t be nil' unless amount
-    raise "Amount (#{amount}) must be an Integer" unless amount.is_a?(Integer)
-    raise "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)
@@ -198,25 +228,41 @@ class ERC20::Wallet
     gas
   end
 
-  # What is the price of gas unit in gwei?
+  GAS_PRICE_TIP = 1_000_000_000
+
+  # What is the price of gas unit in wei?
   #
   # In Ethereum, gas is a unit that measures the computational work required to
   # execute operations on the network. Every transaction and smart contract
   # interaction consumes gas. Gas price is the amount of ETH you're willing to pay
-  # for each unit of gas, denominated in gwei (1 gwei = 0.000000001 ETH). Higher
+  # for each unit of gas, denominated in wei (1 gwei = 0.000000001 ETH). Higher
   # gas prices incentivize miners to include your transaction sooner, while lower
   # prices may result in longer confirmation times.
   #
-  # @return [Integer] Price of gas unit, in gwei (0.000000001 ETH)
+  # The returned price is not the bare EIP-1559 base fee. The base fee alone
+  # leaves a zero miner tip (+tip = gasPrice - baseFee = 0+), so proposers have
+  # no incentive to include the transaction, and it becomes unmineable the
+  # moment the base fee rises (it may grow up to 12.5% per block). To make the
+  # 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 =
       with_jsonrpc do |jr|
         jr.eth_getBlockByNumber('latest', false)
       end
-    raise "Can't get gas price, try again later" if block.nil?
-    gwei = block['baseFeePerGas'].to_i(16)
-    log_it(:debug, "The cost of one gas unit is #{gwei} gwei")
-    gwei
+    raise(StandardError, "Can't get gas price, try again later") if block.nil?
+    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
   end
 
   # Send a single ERC20 payment from a private address to a public one.
@@ -229,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 'Private key can\'t be nil' unless priv
-    raise 'Private key must be a String' unless priv.is_a?(String)
-    raise 'Invalid format of private key' unless /^[0-9a-fA-F]{64}$/.match?(priv)
-    raise 'Address can\'t be nil' unless address
-    raise 'Address must be a String' unless address.is_a?(String)
-    raise 'Invalid format of the address' unless /^0x[0-9a-fA-F]{40}$/.match?(address)
-    raise 'Amount can\'t be nil' unless amount
-    raise "Amount (#{amount}) must be an Integer" unless amount.is_a?(Integer)
-    raise "Amount (#{amount}) must be a positive Integer" unless amount.positive?
-    if limit
-      raise 'Gas limit must be an Integer' unless limit.is_a?(Integer)
-      raise "Gas limit #{limit} is below #{Eth::Tx::DEFAULT_GAS_LIMIT}" if limit < Eth::Tx::DEFAULT_GAS_LIMIT
-      raise "Gas limit #{limit} is above #{Eth::Tx::BLOCK_GAS_LIMIT}" if limit > Eth::Tx::BLOCK_GAS_LIMIT
-    end
-    if price
-      raise 'Gas price must be an Integer' unless price.is_a?(Integer)
-      raise '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|
-          nonce = jr.eth_getTransactionCount(from, 'pending').to_i(16)
-          h = {
-            nonce:,
-            gas_price: price,
+        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 = Eth::Tx.new(h)
-          tx.sign(key)
-          hex = "0x#{tx.hex}"
-          log_it(:debug, "Sending ERC20 transaction #{hex}")
-          jr.eth_sendRawTransaction(hex)
-        end
+        )
+        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
@@ -285,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 'Private key can\'t be nil' unless priv
-    raise 'Private key must be a String' unless priv.is_a?(String)
-    raise 'Invalid format of private key' unless /^[0-9a-fA-F]{64}$/.match?(priv)
-    raise 'Address can\'t be nil' unless address
-    raise 'Address must be a String' unless address.is_a?(String)
-    raise 'Invalid format of the address' unless /^0x[0-9a-fA-F]{40}$/.match?(address)
-    raise 'Amount can\'t be nil' unless amount
-    raise "Amount (#{amount}) must be an Integer" unless amount.is_a?(Integer)
-    raise "Amount (#{amount}) must be a positive Integer" unless amount.positive?
-    if price
-      raise 'Gas price must be an Integer' unless price.is_a?(Integer)
-      raise '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|
-          nonce = jr.eth_getTransactionCount(from, 'pending').to_i(16)
-          h = {
+        tx = Eth::Tx.new(
+          {
             chain_id: @chain,
-            nonce:,
-            gas_price: price,
+            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 = Eth::Tx.new(h)
-          tx.sign(key)
-          hex = "0x#{tx.hex}"
-          log_it(:debug, "Sending ETH transaction #{hex}")
-          jr.eth_sendRawTransaction(hex)
-        end
+        )
+        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
@@ -339,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()+ 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.
+  # 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.
+  #
+  # 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 'Addresses can\'t be nil' unless addresses
-    raise 'Addresses must respond to .to_a()' unless addresses.respond_to?(:to_a)
-    raise 'Active can\'t be nil' unless active
-    raise 'Active must respond to .to_a()' unless active.respond_to?(:to_a)
-    raise 'Active must respond to .append()' unless active.respond_to?(:append)
-    raise 'Active must respond to .clear()' unless active.respond_to?(:clear)
-    raise 'Delay must be an Integer' unless delay.is_a?(Integer)
-    raise 'Delay must be a positive Integer or positive Float' unless delay.positive?
-    raise 'Subscription ID must be an Integer' unless subscription_id.is_a?(Integer)
-    raise '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
@@ -372,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
@@ -389,28 +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
@@ -420,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
@@ -459,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
@@ -472,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
 
@@ -482,13 +597,13 @@ class ERC20::Wallet
     yield
   rescue StandardError => e
     log_it(:error, Backtrace.new(e).to_s)
-    raise e
+    raise(e)
   end
 
   def safe
     yield
   rescue StandardError
-    # ignore it
+    nil
   end
 
   def url(http: true)
@@ -503,25 +618,33 @@ class ERC20::Wallet
       opts[:connection] =
         Faraday.new do |f|
           f.adapter(Faraday.default_adapter)
-          f.proxy = {
-            uri: "#{uri.scheme}://#{uri.hostname}:#{uri.port}",
-            user: uri.user,
-            password: uri.password
-          }
+          f.proxy = { uri: "#{uri.scheme}://#{uri.hostname}:#{uri.port}", user: uri.user, password: uri.password }
         end
     end
-    elapsed(@log, good: "Talked to #{url.host}:#{url.port}") do
-      yield JSONRPC::Client.new(url.to_s, opts)
+    endpoints = [url.to_s] + @fallbacks
+    budget = @attempts * endpoints.size
+    tried = 0
+    begin
+      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 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)
-    func = 'a9059cbb' # transfer(address,uint256)
-    to_clean = address.downcase.sub(/^0x/, '')
-    to_padded = ('0' * (64 - to_clean.size)) + to_clean
-    amt_hex = amount.to_s(16)
-    amt_padded = ('0' * (64 - amt_hex.size)) + amt_hex
-    "0x#{func}#{to_padded}#{amt_padded}"
+    "0xa9059cbb#{format('%064x', address.to_i(16))}#{format('%064x', amount)}"
   end
 
   def log_it(method, msg)