polarloop 1.0.0

data/lib/polarloop/abi.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PolarLoop
+  module Abi
+    ABI_PATH = File.expand_path("abi/polar_loop.json", __dir__)
+
+    def self.abi
+      @abi ||= JSON.parse(File.read(ABI_PATH))
+    end
+
+    # keccak256("OPERATOR_ROLE") — matches Solidity keccak256("OPERATOR_ROLE")
+    OPERATOR_ROLE = Eth::Util.keccak256("OPERATOR_ROLE")
+
+    # bytes32(0) — DEFAULT_ADMIN_ROLE in AccessControl
+    DEFAULT_ADMIN_ROLE = "\x00" * 32
+
+    # Event topic hashes (keccak256 of event signature)
+    MANDATE_CREATED_TOPIC = Eth::Util.keccak256(
+      "MandateCreated(bytes32,address,address,address,uint128,uint32,uint128,bytes32)"
+    )
+
+    MANDATE_CHARGED_TOPIC = Eth::Util.keccak256(
+      "MandateCharged(bytes32,address,address,uint128,uint48)"
+    )
+
+    MANDATE_REVOKED_TOPIC = Eth::Util.keccak256(
+      "MandateRevoked(bytes32,address)"
+    )
+
+    def self.topic_hex(topic)
+      "0x" + topic.unpack1("H*")
+    end
+
+    # Precomputed error selectors from ABI for decoding revert data
+    def self.error_selectors
+      @error_selectors ||= abi.select { |e| e["type"] == "error" }.each_with_object({}) do |entry, hash|
+        sig = "#{entry["name"]}(#{(entry["inputs"] || []).map { |i| i["type"] }.join(",")})"
+        selector = Eth::Util.keccak256(sig)[0, 4].unpack1("H*")
+        hash[selector] = { name: entry["name"], types: (entry["inputs"] || []).map { |i| i["type"] } }
+      end
+    end
+
+    # Standard Solidity error selectors (not in ABI)
+    ERROR_STRING_SELECTOR = "08c379a0" # Error(string) — require(false, "msg")
+    PANIC_SELECTOR = "4e487b71"        # Panic(uint256) — assert failures
+
+    # Decode hex revert data into human-readable error string
+    def self.decode_revert(hex_data)
+      return nil unless hex_data.is_a?(String) && hex_data.sub(/\A0x/i, "").length >= 8
+
+      raw = hex_data.sub(/\A0x/i, "")
+      selector = raw[0, 8]
+
+      # Standard Error(string)
+      if selector == ERROR_STRING_SELECTOR
+        encoded = [raw[8..]].pack("H*")
+        decoded = Eth::Abi.decode(["string"], encoded)
+        return decoded[0]
+      end
+
+      # Standard Panic(uint256)
+      if selector == PANIC_SELECTOR
+        encoded = [raw[8..]].pack("H*")
+        decoded = Eth::Abi.decode(["uint256"], encoded)
+        return "Panic(0x#{decoded[0].to_s(16).rjust(2, '0')})"
+      end
+
+      # Custom errors from contract ABI
+      error_info = error_selectors[selector]
+      return "Unknown error (0x#{selector})" unless error_info
+      return error_info[:name] if error_info[:types].empty?
+
+      encoded = [raw[8..]].pack("H*")
+      decoded = Eth::Abi.decode(error_info[:types], encoded)
+
+      args = decoded.map do |v|
+        if v.is_a?(String) && v.encoding == Encoding::BINARY
+          "0x" + v.unpack1("H*")
+        else
+          v.to_s
+        end
+      end
+
+      "#{error_info[:name]}(#{args.join(', ')})"
+    rescue
+      "Unknown error: #{hex_data}"
+    end
+  end
+end

data/lib/polarloop/client.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module PolarLoop
+  class Client
+    attr_reader :chain_config, :contract_caller, :event_parser
+
+    def initialize(chain_config:, key:)
+      @chain_config = chain_config
+      @key = key
+      @contract_caller = ContractCaller.new(chain_config: chain_config, key: key)
+      @event_parser = EventParser.new(@contract_caller)
+    end
+
+    # --- Signature for mandate creation (off-chain, no gas) ---
+
+    def sign_create_mandate(payer:, merchant:, token:, amount:, interval:, max_total_amount:, reference_id:)
+      struct_hash = Eth::Util.keccak256(
+        Eth::Abi.encode(
+          ["address", "address", "address", "uint128", "uint32", "uint128", "bytes32", "uint256", "address"],
+          [payer, merchant, token, amount, interval, max_total_amount,
+           normalize_bytes32(reference_id), @chain_config.chain_id, @chain_config.contract_address]
+        )
+      )
+
+      @key.personal_sign(struct_hash)
+    end
+
+    # --- Write methods ---
+
+    def charge(mandate_id)
+      @contract_caller.send_tx("charge", normalize_bytes32(mandate_id))
+    end
+
+    def batch_charge(mandate_ids)
+      @contract_caller.send_batch_tx("batchCharge", mandate_ids.map { |id| normalize_bytes32(id) })
+    end
+
+    def revoke_mandate(mandate_id)
+      @contract_caller.send_tx("revokeMandate", normalize_bytes32(mandate_id))
+    end
+
+    def batch_revoke_mandate(mandate_ids)
+      @contract_caller.send_batch_tx("batchRevokeMandate", mandate_ids.map { |id| normalize_bytes32(id) })
+    end
+
+    def pause
+      @contract_caller.send_tx("pause")
+    end
+
+    def unpause
+      @contract_caller.send_tx("unpause")
+    end
+
+    def grant_operator_role(address)
+      @contract_caller.send_tx("grantRole", Abi::OPERATOR_ROLE, address)
+    end
+
+    def revoke_operator_role(address)
+      @contract_caller.send_tx("revokeRole", Abi::OPERATOR_ROLE, address)
+    end
+
+    def rescue_eth
+      @contract_caller.send_tx("rescueETH")
+    end
+
+    def rescue_erc20(token, amount)
+      @contract_caller.send_tx("rescueERC20", token, amount)
+    end
+
+    # --- View methods (no gas) ---
+
+    def get_mandate(mandate_id)
+      result = @contract_caller.call_view("getMandate", normalize_bytes32(mandate_id))
+      Types::Mandate.from_abi(result)
+    end
+
+    def get_mandate_by_reference_id(reference_id)
+      result = @contract_caller.call_view("getMandateByReferenceId", normalize_bytes32(reference_id))
+      mandate_id = to_hex_bytes32(result[0])
+      mandate = Types::Mandate.from_abi(result[1])
+      [mandate_id, mandate]
+    end
+
+    def get_payer_mandates(payer)
+      result = @contract_caller.call_view("getPayerMandates", payer)
+      Array(result).map { |id| to_hex_bytes32(id) }
+    end
+
+    def charge_ready?(mandate_id)
+      result = @contract_caller.call_view("isChargeReady", normalize_bytes32(mandate_id))
+      Types::ChargeReadyResult.new(ready: result[0], reason: result[1])
+    end
+
+    def batch_charge_ready?(mandate_ids)
+      result = @contract_caller.call_view("batchIsChargeReady", mandate_ids.map { |id| normalize_bytes32(id) })
+      ready_arr = result[0]
+      reasons_arr = result[1]
+      ready_arr.zip(reasons_arr).map do |ready, reason|
+        Types::ChargeReadyResult.new(ready: ready, reason: reason)
+      end
+    end
+
+    def min_interval
+      @contract_caller.call_view("minInterval").to_i
+    end
+
+    def paused?
+      @contract_caller.call_view("paused")
+    end
+
+    def latest_block_number
+      @contract_caller.latest_block_number
+    end
+
+    # --- Events ---
+
+    def mandate_created_events(from_block:, to_block: "latest")
+      @event_parser.mandate_created_events(from_block: from_block, to_block: to_block)
+    end
+
+    def mandate_charged_events(from_block:, to_block: "latest")
+      @event_parser.mandate_charged_events(from_block: from_block, to_block: to_block)
+    end
+
+    def mandate_revoked_events(from_block:, to_block: "latest")
+      @event_parser.mandate_revoked_events(from_block: from_block, to_block: to_block)
+    end
+
+    def events_for_tx(tx_hash)
+      @event_parser.events_for_tx(tx_hash)
+    end
+
+    # --- Helpers ---
+
+    def normalize_bytes32(hex_str)
+      if hex_str.is_a?(String)
+        if hex_str.bytesize == 32 && (hex_str.encoding == Encoding::BINARY || !hex_str.valid_encoding?)
+          return hex_str.b
+        end
+
+        hex = hex_str.sub(/\A0x/i, "").rjust(64, "0")
+        return [hex].pack("H*")
+      end
+
+      hex = hex_str.to_s.sub(/\A0x/i, "").rjust(64, "0")
+      [hex].pack("H*")
+    end
+
+    def to_hex_bytes32(binary)
+      if binary.is_a?(String) && binary.start_with?("0x")
+        binary.downcase
+      elsif binary.is_a?(String)
+        "0x" + binary.unpack1("H*")
+      else
+        "0x" + binary.to_s(16).rjust(64, "0")
+      end
+    end
+  end
+end

data/lib/polarloop/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PolarLoop
+  ChainConfig = Struct.new(
+    :rpc_url,
+    :contract_address,
+    :chain_id,
+    :gas_multiplier,
+    :tx_timeout,
+    keyword_init: true
+  )
+
+  class Configuration
+    attr_accessor :mnemonic, :index, :logger
+    attr_reader :chains
+
+    def initialize
+      @chains = {}
+      @logger = nil
+      @mnemonic = nil
+      @index = 0
+    end
+
+    def register(chain_name, rpc_url:, contract_address:, chain_id:, gas_multiplier: 1.2, tx_timeout: 120)
+      @chains[chain_name.to_sym] = ChainConfig.new(
+        rpc_url: rpc_url,
+        contract_address: contract_address,
+        chain_id: chain_id,
+        gas_multiplier: gas_multiplier,
+        tx_timeout: tx_timeout
+      )
+    end
+
+    def chain(name)
+      @chains[name.to_sym] || raise(ChainNotRegisteredError, "Chain :#{name} not registered")
+    end
+
+    def validate!
+      raise ConfigurationError, "Mnemonic is required" if mnemonic.nil? || mnemonic.strip.empty?
+      raise ConfigurationError, "At least one chain must be registered" if chains.empty?
+    end
+  end
+end

data/lib/polarloop/contract_caller.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module PolarLoop
+  module EthHttpRawBodyCapture
+    def send_request(payload)
+      body = super
+      Thread.current[:polarloop_last_raw_response] = body
+      body
+    end
+  end
+  Eth::Client::Http.prepend(EthHttpRawBodyCapture) unless Eth::Client::Http.ancestors.include?(EthHttpRawBodyCapture)
+
+  class ContractCaller
+    attr_reader :eth_client, :contract
+
+    def initialize(chain_config:, key:)
+      @chain_config = chain_config
+      @key = key
+      @eth_client = Eth::Client.create(chain_config.rpc_url)
+      @contract = Eth::Contract.from_abi(
+        name: "PolarLoop",
+        address: chain_config.contract_address,
+        abi: Abi.abi
+      )
+      @gas_strategy = GasStrategy.new(chain_config.chain_id, @eth_client)
+    end
+
+    def call_view(function_name, *args)
+      result = @eth_client.call(@contract, function_name, *args)
+      raise RpcError, "Empty response from node in call_view: #{function_name}" if result.nil?
+      result
+    rescue Eth::Client::ContractExecutionError => e
+      raise ContractRevertError, e.message
+    rescue Eth::Client::RpcError => e
+      raise_from_rpc_error(e)
+    rescue Errno::ECONNREFUSED => e
+      raise RpcError, "RPC connection failed: #{e.message}"
+    rescue JSON::ParserError
+      raw = Thread.current[:polarloop_last_raw_response]
+      raise RpcError, "RPC connection failed: #{raw || 'non-JSON response from node'}"
+    rescue NoMethodError => e
+      raise RpcError, "Unexpected node response in call_view: #{e.message}"
+    end
+
+    def send_tx(function_name, *args)
+      gas = estimate_gas(function_name, *args)
+      tx_hash, _success = @eth_client.transact_and_wait(
+        @contract,
+        function_name,
+        *args,
+        **tx_opts,
+        gas_limit: gas
+      )
+      build_tx_result(tx_hash)
+    rescue Eth::Client::ContractExecutionError => e
+      raise ContractRevertError, e.message
+    rescue Eth::Client::RpcError => e
+      raise_from_rpc_error(e)
+    rescue Errno::ECONNREFUSED => e
+      raise RpcError, "RPC connection failed: #{e.message}"
+    rescue JSON::ParserError
+      raw = Thread.current[:polarloop_last_raw_response]
+      raise RpcError, "RPC connection failed: #{raw || 'non-JSON response from node'}"
+    rescue NoMethodError => e
+      raise RpcError, "Unexpected node response in send_tx: #{e.message}"
+    end
+
+    def send_batch_tx(function_name, *args)
+      simulation = @eth_client.call(@contract, function_name, *args)
+      batch_results = Types::BatchResult.from_abi_array(
+        simulation.is_a?(Array) ? simulation : [simulation]
+      )
+
+      gas = estimate_gas(function_name, *args)
+      tx_hash, _success = @eth_client.transact_and_wait(
+        @contract,
+        function_name,
+        *args,
+        **tx_opts,
+        gas_limit: gas
+      )
+      result = build_tx_result(tx_hash)
+      result.batch_results = batch_results
+      result
+    rescue Eth::Client::ContractExecutionError => e
+      raise ContractRevertError, e.message
+    rescue Eth::Client::RpcError => e
+      raise_from_rpc_error(e)
+    rescue Errno::ECONNREFUSED => e
+      raise RpcError, "RPC connection failed: #{e.message}"
+    rescue JSON::ParserError
+      raw = Thread.current[:polarloop_last_raw_response]
+      raise RpcError, "RPC connection failed: #{raw || 'non-JSON response from node'}"
+    rescue NoMethodError => e
+      raise RpcError, "Unexpected node response in send_batch_tx: #{e.message}"
+    end
+
+    def latest_block_number
+      response = @eth_client.eth_block_number
+      response["result"].to_i(16)
+    rescue IOError, Errno::ECONNREFUSED => e
+      raise RpcError, "RPC connection failed: #{e.message}"
+    rescue JSON::ParserError
+      raw = Thread.current[:polarloop_last_raw_response]
+      raise RpcError, "RPC connection failed: #{raw || 'non-JSON response from node'}"
+    rescue NoMethodError => e
+      raise RpcError, "Unexpected node response in latest_block_number: #{e.message}"
+    end
+
+    def get_logs(topics:, from_block:, to_block:)
+      filter = {
+        address: @chain_config.contract_address,
+        topics: topics,
+        fromBlock: hex_block(from_block),
+        toBlock: hex_block(to_block)
+      }
+      response = @eth_client.eth_get_logs(filter)
+      response["result"] || []
+    rescue IOError, Errno::ECONNREFUSED => e
+      raise RpcError, "RPC connection failed: #{e.message}"
+    rescue JSON::ParserError
+      raw = Thread.current[:polarloop_last_raw_response]
+      raise RpcError, "RPC connection failed: #{raw || 'non-JSON response from node'}"
+    end
+
+    def get_transaction_receipt(tx_hash)
+      @eth_client.eth_get_transaction_receipt(tx_hash)
+    end
+
+    private
+
+    def raise_from_rpc_error(err)
+      if err.message.include?("revert")
+        revert_data = extract_revert_data(err)
+        decoded = Abi.decode_revert(revert_data) if revert_data
+        reason = decoded || err.message
+        raise ContractRevertError, reason
+      else
+        raise RpcError, err.message
+      end
+    end
+
+    def extract_revert_data(err)
+      # Some nodes put data in err.data, others embed it in the message
+      return err.data if err.data && err.data != "0x" && err.data.length > 2
+      if err.message =~ /0x[0-9a-fA-F]{8,}/
+        err.message[/0x[0-9a-fA-F]{8,}/]
+      end
+    end
+
+    def tx_opts
+      { sender_key: @key, legacy: @gas_strategy.legacy? }
+    end
+
+    def build_calldata(function_name, *args)
+      fun = @contract.function(function_name, args: args.size)
+      types = fun.inputs.map(&:type)
+      encoded_args = Eth::Abi.encode(types, args)
+      "0x" + fun.signature + encoded_args.unpack1("H*")
+    end
+
+    def call_params(function_name, *args)
+      {
+        from: @key.address.to_s,
+        to: @chain_config.contract_address,
+        data: build_calldata(function_name, *args)
+      }
+    end
+
+    def estimate_gas(function_name, *args)
+      params = call_params(function_name, *args)
+
+      # Dry-run via eth_call first — returns full revert data on failure
+      @eth_client.eth_call(params)
+
+      # If eth_call passed, get gas estimate
+      response = @eth_client.eth_estimate_gas(params)
+      gas = response["result"].to_i(16)
+      (gas * @chain_config.gas_multiplier).to_i
+    end
+
+    def build_tx_result(tx_hash)
+      receipt = @eth_client.eth_get_transaction_receipt(tx_hash)
+      receipt_data = receipt["result"] || {}
+
+      Types::TxResult.new(
+        tx_hash: tx_hash,
+        block_number: receipt_data["blockNumber"]&.to_i(16),
+        gas_used: receipt_data["gasUsed"]&.to_i(16),
+        status: receipt_data["status"] == "0x1"
+      )
+    rescue
+      Types::TxResult.new(tx_hash: tx_hash, status: true)
+    end
+
+    def hex_block(number)
+      return number if number.is_a?(String) && number.start_with?("0x")
+      return number if number.is_a?(String) && %w[latest earliest pending].include?(number)
+
+      "0x" + number.to_i.to_s(16)
+    end
+  end
+end

data/lib/polarloop/errors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PolarLoop
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+  class ChainNotRegisteredError < Error; end
+  class WalletError < Error; end
+
+  class RpcError < Error
+    attr_reader :code, :data
+
+    def initialize(message, code: nil, data: nil)
+      @code = code
+      @data = data
+      super(message)
+    end
+  end
+
+  class ContractRevertError < Error
+    attr_reader :reason
+
+    def initialize(reason)
+      @reason = reason
+      super("Contract reverted: #{reason}")
+    end
+  end
+
+  class TransactionFailedError < Error
+    attr_reader :tx_hash, :receipt
+
+    def initialize(message, tx_hash: nil, receipt: nil)
+      @tx_hash = tx_hash
+      @receipt = receipt
+      super(message)
+    end
+  end
+
+  class TransactionTimeoutError < Error; end
+end

data/lib/polarloop/event_parser.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module PolarLoop
+  class EventParser
+    def initialize(contract_caller)
+      @caller = contract_caller
+    end
+
+    def mandate_created_events(from_block:, to_block: "latest")
+      logs = @caller.get_logs(
+        topics: [Abi.topic_hex(Abi::MANDATE_CREATED_TOPIC)],
+        from_block: from_block,
+        to_block: to_block
+      )
+
+      logs.map { |log| parse_mandate_created(log) }
+    end
+
+    def mandate_charged_events(from_block:, to_block: "latest")
+      logs = @caller.get_logs(
+        topics: [Abi.topic_hex(Abi::MANDATE_CHARGED_TOPIC)],
+        from_block: from_block,
+        to_block: to_block
+      )
+
+      logs.map { |log| parse_mandate_charged(log) }
+    end
+
+    def mandate_revoked_events(from_block:, to_block: "latest")
+      logs = @caller.get_logs(
+        topics: [Abi.topic_hex(Abi::MANDATE_REVOKED_TOPIC)],
+        from_block: from_block,
+        to_block: to_block
+      )
+
+      logs.map { |log| parse_mandate_revoked(log) }
+    end
+
+    def events_for_tx(tx_hash)
+      receipt = @caller.get_transaction_receipt(tx_hash)
+      logs = receipt.dig("result", "logs") || []
+
+      created_topic = Abi.topic_hex(Abi::MANDATE_CREATED_TOPIC)
+      charged_topic = Abi.topic_hex(Abi::MANDATE_CHARGED_TOPIC)
+      revoked_topic = Abi.topic_hex(Abi::MANDATE_REVOKED_TOPIC)
+
+      logs.filter_map do |log|
+        topic0 = log["topics"]&.first
+        case topic0
+        when created_topic then parse_mandate_created(log)
+        when charged_topic then parse_mandate_charged(log)
+        when revoked_topic then parse_mandate_revoked(log)
+        end
+      end
+    end
+
+    private
+
+    def parse_mandate_created(log)
+      topics = log["topics"]
+      data = decode_data(log["data"])
+
+      # Indexed: mandateId, payer, merchant
+      # Non-indexed data: token(address), amount(uint128), interval(uint32), maxTotalAmount(uint128), referenceId(bytes32)
+      decoded = Eth::Abi.decode(
+        ["address", "uint128", "uint32", "uint128", "bytes32"],
+        data
+      )
+
+      Types::MandateCreatedEvent.new(
+        mandate_id: topics[1],
+        payer: address_from_topic(topics[2]),
+        merchant: address_from_topic(topics[3]),
+        token: decoded[0],
+        amount: decoded[1].to_i,
+        interval: decoded[2].to_i,
+        max_total_amount: decoded[3].to_i,
+        reference_id: bytes32_to_hex(decoded[4]),
+        block_number: log["blockNumber"]&.to_i(16),
+        tx_hash: log["transactionHash"],
+        log_index: log["logIndex"]&.to_i(16)
+      )
+    end
+
+    def parse_mandate_charged(log)
+      topics = log["topics"]
+      data = decode_data(log["data"])
+
+      # Indexed: mandateId, payer, merchant
+      # Non-indexed data: amount(uint128), timestamp(uint48)
+      decoded = Eth::Abi.decode(["uint128", "uint48"], data)
+
+      Types::MandateChargedEvent.new(
+        mandate_id: topics[1],
+        payer: address_from_topic(topics[2]),
+        merchant: address_from_topic(topics[3]),
+        amount: decoded[0].to_i,
+        timestamp: decoded[1].to_i,
+        block_number: log["blockNumber"]&.to_i(16),
+        tx_hash: log["transactionHash"],
+        log_index: log["logIndex"]&.to_i(16)
+      )
+    end
+
+    def parse_mandate_revoked(log)
+      topics = log["topics"]
+
+      # Indexed: mandateId, payer
+      # No non-indexed data
+      Types::MandateRevokedEvent.new(
+        mandate_id: topics[1],
+        payer: address_from_topic(topics[2]),
+        block_number: log["blockNumber"]&.to_i(16),
+        tx_hash: log["transactionHash"],
+        log_index: log["logIndex"]&.to_i(16)
+      )
+    end
+
+    def address_from_topic(topic)
+      return nil unless topic
+
+      "0x" + topic[-40..]
+    end
+
+    def bytes32_to_hex(binary)
+      if binary.is_a?(String) && binary.start_with?("0x")
+        binary.downcase
+      elsif binary.is_a?(String)
+        "0x" + binary.unpack1("H*")
+      else
+        "0x" + binary.to_s(16).rjust(64, "0")
+      end
+    end
+
+    def decode_data(hex_data)
+      return "" if hex_data.nil? || hex_data == "0x"
+
+      [hex_data.sub(/\A0x/, "")].pack("H*")
+    end
+  end
+end