openreceive-server 0.2.1

data/lib/openreceive/server/swap/rates_feed.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require "json"
+require "openreceive/server/swap/assets"
+
+module OpenReceive
+  module Server
+    module Swap
+      # Ruby port of packages/js/node/src/swap/fixedfloat-rates.ts (plus the
+      # rates-cache key/TTL constants from rates-cache.ts): the FixedFloat
+      # public XML rates export — the bulk feed for all pairs.
+      #
+      # GET https://ff.io/rates/fixed.xml (and float.xml). No API key, no
+      # weight budget. OpenReceive keeps only Lightning-payout pairs that match
+      # its small pay-in asset list in disposable process memory and derives
+      # indicative quotes / min-max locally. /create remains authoritative.
+      #
+      # All amount math is exact integer fixed-point (Ruby Integers are
+      # arbitrary precision), mirroring the JS BigInt implementation digit for
+      # digit — never binary floats.
+      module FixedFloatRates
+        DECIMAL_PATTERN = /\A[0-9]+(\.[0-9]+)?\z/
+        SATS_PER_BTC = 100_000_000
+        MAX_SAFE_INTEGER = 9_007_199_254_740_991
+
+        # How often a warm rates blob is refreshed from the provider bulk feed
+        # (mirrors SWAP_RATES_REFRESH_SECONDS / SWAP_RATES_MAX_STALE_SECONDS).
+        REFRESH_SECONDS = 15
+        MAX_STALE_SECONDS = REFRESH_SECONDS
+
+        module_function
+
+        def pair_key(from, to)
+          "#{from.to_s.strip.upcase}:#{to.to_s.strip.upcase}"
+        end
+
+        def xml_path(rate_type = "fixed")
+          "/rates/#{rate_type}.xml"
+        end
+
+        # Process-local key for a provider's bulk rates snapshot,
+        # e.g. "swap_rates:fixedfloat:fixed".
+        def rates_meta_key(provider_name, rate_type = "fixed")
+          "swap_rates:#{provider_name}:#{rate_type}"
+        end
+
+        # Fetch and parse the XML export. `http` is the injectable transport
+        # (see Swap.default_http_request); `now` is a callable returning unix
+        # seconds. Raises on transport/HTTP failures with the same messages as
+        # the JS fetchFixedFloatRatesIndex.
+        def fetch_index(base_url:, now:, http: nil, rate_type: "fixed", request_timeout_ms: 10_000)
+          url = "#{base_url.to_s.sub(%r{/+\z}, '')}#{xml_path(rate_type)}"
+          transport = http || Swap.method(:default_http_request)
+          begin
+            response = transport.call(
+              method: "GET",
+              url: url,
+              headers: { "Accept" => "application/xml, text/xml, */*" },
+              body: nil,
+              timeout_ms: request_timeout_ms
+            )
+          rescue StandardError => e
+            raise "FixedFloat rates #{rate_type}.xml request timed out." if Swap.timeout_error?(e)
+
+            raise "FixedFloat rates #{rate_type}.xml request failed before a response was received."
+          end
+          status = response[:status] || response["status"]
+          unless (200..299).cover?(status)
+            raise "FixedFloat rates #{rate_type}.xml failed with HTTP #{status}."
+          end
+          xml = (response[:body] || response["body"]).to_s
+          {
+            # Provider dumps include thousands of non-LN market pairs;
+            # OpenReceive only ever pays out over Lightning, so drop everything
+            # else before caching.
+            "fetched_at" => now.call,
+            "pairs" => retain_lightning_payout_pairs(parse_xml(xml))
+          }
+        end
+
+        # Keep only pairs whose `to` side is a Lightning BTC payout code.
+        def retain_lightning_payout_pairs(pairs)
+          pairs.select { |_key, pair| Assets.lightning_network?(pair.fetch("to")) }
+        end
+
+        # Keep only the from→Lightning keys that match resolved OpenReceive
+        # pay-in currencies. Typically a handful of pairs out of the dump.
+        def retain_pairs_for_keys(index, pair_keys)
+          return { "fetched_at" => index.fetch("fetched_at"), "pairs" => {} } if pair_keys.empty?
+
+          pairs = {}
+          pair_keys.each do |key|
+            pair = index.fetch("pairs")[key]
+            pairs[key] = pair unless pair.nil?
+          end
+          { "fetched_at" => index.fetch("fetched_at"), "pairs" => pairs }
+        end
+
+        def parse_xml(xml)
+          pairs = {}
+          match_tags(xml, "item").each do |item_xml|
+            from = read_tag_text(item_xml, "from")
+            to = read_tag_text(item_xml, "to")
+            in_amount = read_tag_text(item_xml, "in")
+            out_amount = read_tag_text(item_xml, "out")
+            amount = read_tag_text(item_xml, "amount")
+            minamount = read_tag_text(item_xml, "minamount")
+            maxamount = read_tag_text(item_xml, "maxamount")
+            next if [from, to, in_amount, out_amount, amount, minamount, maxamount].any?(&:nil?)
+
+            tofee = read_tag_text(item_xml, "tofee")
+            pair = {
+              "from" => from.strip,
+              "to" => to.strip,
+              "in" => strip_currency_suffix(in_amount),
+              "out" => strip_currency_suffix(out_amount),
+              "amount" => strip_currency_suffix(amount),
+              "minamount" => strip_currency_suffix(minamount),
+              "maxamount" => strip_currency_suffix(maxamount)
+            }
+            pair["tofee"] = tofee.strip unless tofee.nil?
+            pairs[pair_key(pair.fetch("from"), pair.fetch("to"))] = pair
+          end
+          pairs
+        end
+
+        def serialize_index(index)
+          JSON.generate("fetched_at" => index.fetch("fetched_at"), "pairs" => index.fetch("pairs"))
+        end
+
+        def deserialize_index(value)
+          parsed = JSON.parse(value)
+          fetched_at = parsed.is_a?(Hash) ? parsed["fetched_at"] : nil
+          raw_pairs = parsed.is_a?(Hash) ? parsed["pairs"] : nil
+          unless fetched_at.is_a?(Integer) && raw_pairs.is_a?(Hash)
+            raise "Invalid FixedFloat rates cache blob."
+          end
+          pairs = {}
+          raw_pairs.each do |key, raw|
+            pair = read_stored_pair(raw)
+            pairs[key] = pair unless pair.nil?
+          end
+          { "fetched_at" => fetched_at, "pairs" => pairs }
+        end
+
+        # Indicative pay-in amount for a Lightning payout of
+        # invoice_amount_msats, using the XML reference rate (in/out) and
+        # optional BTC tofee.
+        #
+        # Formula (direction=to): pay_from = (invoice_btc + tofee_btc) × (in / out).
+        # Rounds the pay-in amount up at 8 decimal places so the UI never
+        # understates what /create is likely to require.
+        def quote_pay_amount(pair:, invoice_amount_msats:)
+          return nil unless invoice_amount_msats.is_a?(Integer) && invoice_amount_msats.positive?
+
+          rate_in = parse_positive_decimal(pair["in"])
+          rate_out = parse_positive_decimal(pair["out"])
+          return nil if rate_in.nil? || rate_out.nil?
+
+          invoice_sats = (invoice_amount_msats + 999) / 1000
+          tofee_sats = parse_tofee_btc_sats(pair["tofee"]) || 0
+          total_sats = invoice_sats + tofee_sats
+          return nil unless rate_out[0].positive?
+
+          # pay_from = total_btc * (in/out) = total_sats * in / (out * 1e8).
+          # Compute ceil(total_sats * in / out) as an 8-decimal fixed-point
+          # integer of the from currency (units of 1e-8), then format.
+          pay_at_8dp = ceil_div(
+            total_sats * rate_in[0] * rate_out[1],
+            rate_in[1] * rate_out[0]
+          )
+          format_decimal(pay_at_8dp, SATS_PER_BTC, 8)
+        end
+
+        # Maps XML from-side min/max into invoice-side msats using the pair's
+        # reference rate. Minimum rounds up, maximum rounds down, so borderline
+        # invoices are never reported as inside a range the provider rejects.
+        def invoice_limits(pair)
+          minimum_pay_amount = pair.fetch("minamount")
+          maximum_pay_amount = pair.fetch("maxamount")
+          limits = {
+            "minimum_pay_amount" => minimum_pay_amount,
+            "maximum_pay_amount" => maximum_pay_amount
+          }
+          minimum = pay_amount_to_invoice_msats(pair, minimum_pay_amount, :ceil)
+          maximum = pay_amount_to_invoice_msats(pair, maximum_pay_amount, :floor)
+          limits["minimum_invoice_amount_msats"] = minimum unless minimum.nil?
+          limits["maximum_invoice_amount_msats"] = maximum unless maximum.nil?
+          limits
+        end
+
+        # Compare two positive decimal strings. Returns -1/0/1, or nil when
+        # either is not a positive decimal (caller treats that as "cannot
+        # compare").
+        def compare_decimal_amounts(left, right)
+          a = parse_positive_decimal(left)
+          b = parse_positive_decimal(right)
+          return nil if a.nil? || b.nil?
+
+          (a[0] * b[1]) <=> (b[0] * a[1])
+        end
+
+        # Inverse of the direction=to quote (ignoring tofee so the reported
+        # invoice floor is conservative): invoice_sats = pay_from × out × 1e8 / in.
+        def pay_amount_to_invoice_msats(pair, pay_amount, rounding)
+          pay = parse_positive_decimal(pay_amount)
+          rate_in = parse_positive_decimal(pair["in"])
+          rate_out = parse_positive_decimal(pair["out"])
+          return nil if pay.nil? || rate_in.nil? || rate_out.nil?
+          return nil unless rate_in[0].positive?
+
+          numerator = pay[0] * rate_out[0] * SATS_PER_BTC * rate_in[1]
+          denominator = pay[1] * rate_out[1] * rate_in[0]
+          return nil unless denominator.positive?
+
+          invoice_sats = rounding == :ceil ? ceil_div(numerator, denominator) : numerator / denominator
+          return nil unless invoice_sats.positive?
+          return nil if invoice_sats > MAX_SAFE_INTEGER
+
+          msats = invoice_sats * 1000
+          msats > MAX_SAFE_INTEGER ? nil : msats
+        end
+
+        def parse_tofee_btc_sats(tofee)
+          return nil if tofee.nil?
+
+          # Examples: "0.0004967000 BTC", "0.0005 BTCLN". Non-BTC fees are
+          # ignored — payout is always Lightning BTC, so only BTC network fees
+          # fold into pay-in.
+          match = tofee.to_s.strip.match(/\A([0-9]+(?:\.[0-9]+)?)\s*([A-Za-z]+)?\z/)
+          return nil if match.nil?
+
+          unit = (match[2] || "BTC").upcase
+          return nil unless %w[BTC BTCLN].include?(unit)
+
+          parsed = parse_positive_decimal(match[1])
+          return nil if parsed.nil?
+
+          # Fees carrying more than 8 decimals are reduced to whole sats with
+          # ceil rounding — rejecting them would silently treat a real network
+          # fee as zero and understate the indicative pay amount.
+          ceil_div(parsed[0] * SATS_PER_BTC, parsed[1])
+        end
+
+        # Returns [integer, scale] for a positive decimal string, else nil.
+        def parse_positive_decimal(value)
+          return nil unless value.is_a?(String) && DECIMAL_PATTERN.match?(value)
+
+          whole, fraction = value.split(".")
+          fraction ||= ""
+          integer = "#{whole}#{fraction}".to_i
+          return nil unless integer.positive?
+
+          [integer, 10**fraction.length]
+        end
+
+        def format_decimal(integer, scale, max_fraction_digits)
+          whole = integer / scale
+          fraction = integer % scale
+          # Truncate/pad to max_fraction_digits, rounding up any discarded remainder.
+          target_scale = 10**max_fraction_digits
+          if scale > target_scale
+            divisor = scale / target_scale
+            remainder = fraction % divisor
+            fraction /= divisor
+            fraction += 1 if remainder.positive?
+            if fraction >= target_scale
+              return format_decimal(whole * target_scale + fraction, target_scale, max_fraction_digits)
+            end
+          elsif scale < target_scale
+            fraction *= target_scale / scale
+          end
+          fraction_text = fraction.to_s.rjust(max_fraction_digits, "0").sub(/0+\z/, "")
+          fraction_text.empty? ? whole.to_s : "#{whole}.#{fraction_text}"
+        end
+
+        def ceil_div(numerator, denominator)
+          (numerator + denominator - 1) / denominator
+        end
+
+        def strip_currency_suffix(value)
+          match = value.strip.match(/\A([0-9]+(?:\.[0-9]+)?)/)
+          match.nil? ? value.strip : match[1]
+        end
+
+        def match_tags(xml, tag)
+          xml.scan(%r{<#{tag}\b[^>]*>(.*?)</#{tag}>}im).map { |captures| captures[0] || "" }
+        end
+
+        def read_tag_text(xml, tag)
+          match = xml.match(%r{<#{tag}\b[^>]*>(.*?)</#{tag}>}im)
+          return nil if match.nil?
+
+          text = (match[1] || "").strip
+          text.empty? ? nil : text
+        end
+
+        def read_stored_pair(value)
+          return nil unless value.is_a?(Hash)
+
+          required = %w[from to in out amount minamount maxamount]
+          return nil unless required.all? { |key| value[key].is_a?(String) }
+
+          pair = required.to_h { |key| [key, value.fetch(key)] }
+          pair["tofee"] = value["tofee"] if value["tofee"].is_a?(String)
+          pair
+        end
+      end
+    end
+  end
+end

data/lib/openreceive/server/swap/transient_cache.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module OpenReceive
+  module Server
+    module Swap
+      # Ruby port of packages/js/node/src/swap/limits-cache.ts: a disposable,
+      # process-local provider catalog/rate cache. It has no storage adapter.
+      #
+      # Like the Node in-flight promise map, concurrent resolves of the same
+      # key join one fetch: the first caller claims the key under the monitor,
+      # runs fetch outside it, and writes back under the monitor; joiners wait
+      # on a per-key condition. Different keys never block each other.
+      class TransientSwapCache
+        MAX_STALE_SECONDS = 48 * 60 * 60
+        REFRESH_CLAIM_SECONDS = 60
+
+        def self.limits_meta_key(provider_name)
+          "swap_limits:#{provider_name}"
+        end
+
+        def initialize(clock, warn: nil)
+          @clock = clock
+          @warn = warn
+          @states = {}
+          @inflight = {}
+          @monitor = Monitor.new
+        end
+
+        def resolve(key, refresh_seconds:, max_stale_seconds:, fetch:, serialize:, deserialize:,
+                    claim_seconds: REFRESH_CLAIM_SECONDS, serve_stale_on_failure: true)
+          now = nil
+          state = nil
+          claim = nil
+          @monitor.synchronize do
+            now = @clock.call
+            state = @states[key]
+            if state && state[:value] && state[:fetched_at] && now - state[:fetched_at] < refresh_seconds
+              return deserialize.call(state[:value])
+            end
+            if state && state[:failed_at] && now - state[:failed_at] < claim_seconds
+              return stale_or_raise(key, state, now, max_stale_seconds, serve_stale_on_failure, deserialize)
+            end
+
+            active = @inflight[key]
+            if active
+              active[:cond].wait_until { active[:settled] }
+              raise active[:error] unless active[:error].nil?
+
+              return active[:value]
+            end
+            claim = { settled: false, cond: @monitor.new_cond }
+            @inflight[key] = claim
+          end
+
+          begin
+            result = begin
+              value = fetch.call
+              @monitor.synchronize { @states[key] = { value: serialize.call(value), fetched_at: now } }
+              value
+            rescue StandardError => e
+              failed = {
+                failed_at: now,
+                error: e.message
+              }
+              failed[:value] = state[:value] if state && state[:value]
+              failed[:fetched_at] = state[:fetched_at] if state && state[:fetched_at]
+              @monitor.synchronize { @states[key] = failed }
+              stale_or_raise(key, failed, now, max_stale_seconds, serve_stale_on_failure, deserialize, cause: e)
+            end
+            settle(key, claim, value: result)
+            result
+          rescue StandardError => e
+            settle(key, claim, error: e)
+            raise
+          end
+        end
+
+        private
+
+        def settle(key, claim, value: nil, error: nil)
+          @monitor.synchronize do
+            claim[:value] = value
+            claim[:error] = error
+            claim[:settled] = true
+            claim[:cond].broadcast
+            @inflight.delete(key) if @inflight[key].equal?(claim)
+          end
+        end
+
+        def stale_or_raise(key, state, now, max_stale_seconds, serve_stale_on_failure, deserialize, cause: nil)
+          if serve_stale_on_failure && state[:value] && state[:fetched_at] &&
+             now - state[:fetched_at] < max_stale_seconds
+            @warn&.call("Serving stale swap provider data after refresh failed.",
+                        "key" => key, "error" => state[:error])
+            return deserialize.call(state[:value])
+          end
+          raise cause unless cause.nil?
+
+          raise state[:error] || "Swap provider cache refresh failed."
+        end
+      end
+    end
+  end
+end

data/lib/openreceive/server/swap/weight_budget.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module OpenReceive
+  module Server
+    module Swap
+      # Raised when a reservation would exceed the process-local weight budget.
+      # Marked (weight_budget?) so quote classification can map it to
+      # provider_rate_limited, mirroring the JS weightBudget error tag.
+      class WeightBudgetError < StandardError
+        # The denial diagnostics (provider, path, reason, used/cost/gate,
+        # window start, backoff) ride the error itself.
+        attr_reader :denial
+
+        def initialize(message, denial = {})
+          super(message)
+          @denial = denial
+        end
+
+        def weight_budget?
+          true
+        end
+      end
+
+      # Ruby port of packages/js/node/src/swap/weight-budget.ts: a disposable
+      # per-process request guard; the provider remains the global rate-limit
+      # authority.
+      class SwapProviderWeightBudget
+        WINDOW_SECONDS = 60
+        SOFT_CAP = 200
+        CREATE_GATE = 150
+        CREATE_WEIGHT = 50
+        DEFAULT_WEIGHT = 1
+        BACKOFF_SECONDS = 60
+
+        def initialize(provider_id, clock)
+          @provider_id = provider_id
+          @clock = clock
+          @window_start = clock.call
+          @used = 0
+          @backoff_until = nil
+          @monitor = Monitor.new
+        end
+
+        def weight_for_path(path)
+          path == "create" ? CREATE_WEIGHT : DEFAULT_WEIGHT
+        end
+
+        def reserve(path)
+          @monitor.synchronize do
+            roll_window
+            now = @clock.call
+            cost = weight_for_path(path)
+            limit = gate(path)
+            if !@backoff_until.nil? && @backoff_until > now
+              deny(path, "backoff", cost, limit,
+                   "Swap provider API is in backoff until #{@backoff_until}.")
+            end
+            if @used + cost > limit
+              deny(path, "exhausted", cost, limit,
+                   "Swap provider API weight budget exhausted (#{@used}+#{cost} > #{limit}).")
+            end
+            @used += cost
+          end
+          nil
+        end
+
+        def mark_rate_limited
+          @monitor.synchronize do
+            now = @clock.call
+            @used = [@used, SOFT_CAP].max
+            @backoff_until = now + BACKOFF_SECONDS
+          end
+          nil
+        end
+
+        private
+
+        # The weight window rolls; the 429 backoff does NOT ride along with it.
+        # Clearing it here cut a backoff arbitrarily short — mark_rate_limited
+        # at second 59 of the window was forgiven one second later — so the
+        # backoff expires on its own clock, checked in reserve. Mirrors JS.
+        def roll_window
+          now = @clock.call
+          return if now - @window_start < WINDOW_SECONDS
+
+          @window_start = now
+          @used = 0
+        end
+
+        def gate(path)
+          path == "create" ? CREATE_GATE : SOFT_CAP
+        end
+
+        # The denial carries its own diagnostics on the raised error: there is
+        # no observer hook, because there was never a caller for one. Mirrors JS.
+        def deny(path, reason, cost, limit, message)
+          denial = {
+            "provider" => @provider_id,
+            "path" => path,
+            "reason" => reason,
+            "message" => message,
+            "used" => @used,
+            "cost" => cost,
+            "gate" => limit,
+            "window_start" => @window_start,
+            **(@backoff_until.nil? ? {} : { "backoff_until" => @backoff_until })
+          }
+          raise WeightBudgetError.new(message, denial)
+        end
+      end
+    end
+  end
+end

data/lib/openreceive/server/swap.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "timeout"
+require "uri"
+
+require "openreceive/server/lsc_uri"
+require "openreceive/server/swap/assets"
+require "openreceive/server/swap/rates_feed"
+require "openreceive/server/swap/transient_cache"
+require "openreceive/server/swap/weight_budget"
+require "openreceive/server/swap/fixedfloat"
+
+module OpenReceive
+  module Server
+    # Automated swaps: the FixedFloat(-compatible) provider, the asset
+    # catalog, rates/limits caching, and the LSC connection factories.
+    # Ruby port of packages/js/node/src/swap/ plus the LSC provider factory
+    # from packages/js/node/src/lsc-uri.ts.
+    module Swap
+      module_function
+
+      def fixedfloat_provider(**options)
+        FixedFloatProvider.new(**options)
+      end
+
+      # Build one provider per parsed LSC connection (the hashes produced by
+      # OpenReceive::Server::LscUri.parse / read_environment).
+      def providers_from_connections(connections, http: nil, now: nil)
+        Array(connections).map do |connection|
+          FixedFloatProvider.new(
+            id: connection.fetch("provider_id"),
+            base_url: connection.fetch("base_url"),
+            key: connection.fetch("key"),
+            secret: connection.fetch("secret"),
+            http: http,
+            now: now
+          )
+        end
+      end
+
+      # Mirror of createLscSwapProvidersFromEnvironment: LSC_URI_PRIMARY first,
+      # LSC_URI_BACKUP second — the order the service fails over in.
+      def providers_from_environment(env = ENV, http: nil, now: nil)
+        providers_from_connections(LscUri.read_environment(env), http: http, now: now)
+      end
+
+      # Default HTTP transport on stdlib Net::HTTP. Injectable replacements
+      # must be callable as call(method:, url:, headers:, body:, timeout_ms:)
+      # and return a Hash with :status (Integer) and :body (String).
+      def default_http_request(method:, url:, headers:, body: nil, timeout_ms: nil)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        unless timeout_ms.nil?
+          seconds = timeout_ms / 1000.0
+          http.open_timeout = seconds
+          http.read_timeout = seconds
+          http.write_timeout = seconds if http.respond_to?(:write_timeout=)
+        end
+        request =
+          if method.to_s.upcase == "POST"
+            Net::HTTP::Post.new(uri.request_uri)
+          else
+            Net::HTTP::Get.new(uri.request_uri)
+          end
+        headers.each { |key, value| request[key] = value }
+        request.body = body unless body.nil?
+        response = http.start { |connection| connection.request(request) }
+        { status: Integer(response.code), body: response.body.to_s }
+      end
+
+      # Timeout classification shared by the API client and the rates feed
+      # (the Ruby analogue of the JS AbortError check).
+      def timeout_error?(error)
+        return true if defined?(Net::OpenTimeout) && error.is_a?(Net::OpenTimeout)
+        return true if defined?(Net::ReadTimeout) && error.is_a?(Net::ReadTimeout)
+        return true if error.is_a?(Timeout::Error)
+
+        error.is_a?(StandardError) && error.message.to_s.downcase.include?("abort")
+      end
+
+      def weight_budget_error?(error)
+        error.respond_to?(:weight_budget?) && error.weight_budget? == true
+      end
+
+      # Payer-facing copy per availability reason (mirrors
+      # fixedFloatAvailabilityMessage).
+      def availability_message(reason)
+        return "This invoice is below the provider minimum." if reason == "amount_too_small"
+        return "This invoice is above the provider maximum." if reason == "amount_too_large"
+        return "The swap provider is rate limited." if reason == "provider_rate_limited"
+        return "The swap provider is temporarily unreachable." if reason == "provider_unreachable"
+
+        "This payment route is temporarily unavailable."
+      end
+
+      # Map a quote-path failure to a SwapAvailabilityReason. The Ruby quote
+      # math reads its limits with fetch, so unlike the JS twin (whose
+      # pair math returns an unavailable quote instead of raising) this path
+      # is reachable and keeps its classifier.
+      def classify_fixedfloat_quote_error(error)
+        return "provider_rate_limited" if weight_budget_error?(error)
+
+        if error.is_a?(FixedFloatApiError)
+          return "provider_rate_limited" if error.kind == "rate_limited" || error.http_status == 429
+          if %w[timeout network invalid_json].include?(error.kind) ||
+             (!error.http_status.nil? && error.http_status >= 500)
+            return "provider_unreachable"
+          end
+          message = (error.fixedfloat_message || error.message).downcase
+          return "amount_too_small" if amount_too_small_message?(message)
+          return "amount_too_large" if amount_too_large_message?(message)
+
+          return "pair_temporarily_unavailable"
+        end
+
+        message = (error.is_a?(StandardError) ? error.message : error.to_s).downcase
+        if message.include?("rate") || message.include?("429") || message.include?("weight budget")
+          return "provider_rate_limited"
+        end
+        if message.include?("fetch") || message.include?("network") || message.include?("timeout")
+          return "provider_unreachable"
+        end
+        return "amount_too_small" if amount_too_small_message?(message)
+        return "amount_too_large" if amount_too_large_message?(message)
+
+        "pair_temporarily_unavailable"
+      end
+
+      def amount_too_small_message?(message)
+        message.include?("min") || message.include?("small") ||
+          message.include?("out of limits") || message.include?("limit_min")
+      end
+
+      def amount_too_large_message?(message)
+        message.include?("max") || message.include?("large") || message.include?("limit_max")
+      end
+    end
+  end
+end

data/lib/openreceive/server/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  module Server
+    VERSION = "0.2.1"
+  end
+end