openreceive 0.2.1

data/lib/openreceive/keccak256.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  # Keccak-256 (the pre-NIST-padding variant Ethereum uses, which is NOT
+  # Digest::SHA3). Needed only to verify EIP-55 checksums on refund addresses,
+  # so this is a compact reference implementation rather than a dependency —
+  # the core gem stays dependency-free.
+  module Keccak256
+    ROUNDS = 24
+    RATE_BYTES = 136 # 1088-bit rate for Keccak-256.
+    MASK = 0xffffffffffffffff
+
+    ROUND_CONSTANTS = [
+      0x0000000000000001, 0x0000000000008082, 0x800000000000808a, 0x8000000080008000,
+      0x000000000000808b, 0x0000000080000001, 0x8000000080008081, 0x8000000000008009,
+      0x000000000000008a, 0x0000000000000088, 0x0000000080008009, 0x000000008000000a,
+      0x000000008000808b, 0x800000000000008b, 0x8000000000008089, 0x8000000000008003,
+      0x8000000000008002, 0x8000000000000080, 0x000000000000800a, 0x800000008000000a,
+      0x8000000080008081, 0x8000000000008080, 0x0000000080000001, 0x8000000080008008
+    ].freeze
+
+    ROTATION_OFFSETS = [
+      [0, 36, 3, 41, 18],
+      [1, 44, 10, 45, 2],
+      [62, 6, 43, 15, 61],
+      [28, 55, 25, 21, 56],
+      [27, 20, 39, 8, 14]
+    ].freeze
+
+    module_function
+
+    def digest(message)
+      state = Array.new(25, 0)
+      padded = pad(message.to_s.b)
+      padded.bytes.each_slice(RATE_BYTES) do |block|
+        block.each_slice(8).with_index do |lane_bytes, lane|
+          state[lane] ^= lane_bytes.each_with_index.sum { |byte, index| byte << (8 * index) }
+        end
+        keccak_f!(state)
+      end
+      # Keccak-256 output is the first 32 bytes of the rate portion.
+      state[0, 4].flat_map { |lane| (0...8).map { |index| (lane >> (8 * index)) & 0xff } }.pack("C*")
+    end
+
+    def pad(message)
+      # Keccak padding is 0x01 … 0x80 (SHA-3 would use 0x06 here).
+      padding_length = RATE_BYTES - (message.bytesize % RATE_BYTES)
+      padding = +"\x01" + ("\x00" * (padding_length - 1))
+      padding[-1] = (padding[-1].ord | 0x80).chr
+      message + padding
+    end
+
+    def keccak_f!(state)
+      ROUNDS.times do |round|
+        theta!(state)
+        rho_pi_chi!(state)
+        state[0] ^= ROUND_CONSTANTS[round]
+      end
+      state
+    end
+
+    def theta!(state)
+      columns = (0...5).map do |x|
+        (0...5).reduce(0) { |acc, y| acc ^ state[x + 5 * y] }
+      end
+      (0...5).each do |x|
+        d = columns[(x + 4) % 5] ^ rotl(columns[(x + 1) % 5], 1)
+        (0...5).each { |y| state[x + 5 * y] ^= d }
+      end
+    end
+
+    def rho_pi_chi!(state)
+      rotated = Array.new(25, 0)
+      (0...5).each do |x|
+        (0...5).each do |y|
+          rotated[y + 5 * ((2 * x + 3 * y) % 5)] = rotl(state[x + 5 * y], ROTATION_OFFSETS[x][y])
+        end
+      end
+      (0...5).each do |y|
+        row = (0...5).map { |x| rotated[x + 5 * y] }
+        (0...5).each do |x|
+          state[x + 5 * y] = row[x] ^ (~row[(x + 1) % 5] & MASK & row[(x + 2) % 5])
+        end
+      end
+    end
+
+    def rotl(value, offset)
+      offset %= 64
+      return value if offset.zero?
+
+      ((value << offset) | (value >> (64 - offset))) & MASK
+    end
+  end
+end

data/lib/openreceive/nwc_ruby.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# require_relative (not `require "openreceive/core"`): the gemspec loads
+# version.rb only, and a load-path require here could resolve to an installed
+# copy of the gem instead of this working tree. The core file — never the
+# `openreceive` umbrella, which loads this adapter — carries everything the
+# adapter calls, so requiring this file directly keeps working.
+require_relative "core"
+
+module OpenReceive
+  # Thin adapter binding the engine to the nwc-ruby gem (NwcRuby::Client).
+  # The engine speaks NIP-47 wire names in string-keyed hashes; nwc-ruby
+  # declares snake_case keyword arguments, and spells the list_transactions
+  # window `until_ts` because `until` is a Ruby keyword.
+  class NwcRubyReceiveClient
+    attr_reader :redacted_connection_uri
+
+    def initialize(client:, connection_uri: nil)
+      @client = client
+      @redacted_connection_uri = connection_uri.nil? ? nil : OpenReceive.redact_nwc_uri(connection_uri)
+      OpenReceive.parse_nwc_uri(connection_uri) unless connection_uri.nil?
+    end
+
+    def make_invoice(request)
+      params = symbolize_keys(OpenReceive.make_invoice_nip47_request(request))
+      OpenReceive.normalize_make_invoice_response(@client.make_invoice(**params))
+    end
+
+    def list_transactions(request)
+      params = symbolize_keys(OpenReceive.list_transactions_nip47_request(request))
+      params[:until_ts] = params.delete(:until) if params.key?(:until)
+      OpenReceive.normalize_list_transactions_response(@client.list_transactions(**params))
+    end
+
+    def preflight
+      OpenReceive.stringify(@client.get_info)
+    end
+
+    # Opt-in NWC-02 notifications, forwarded from the wrapped client.
+    #
+    # nwc-ruby yields a NwcRuby::NIP47::Notification value object, while every
+    # other method in that gem returns the NIP-47 payload as a hash and
+    # OpenReceive.listen_for_notifications! consumes the NWC-02 wire shape
+    # (`notification_type` plus the transaction-shaped `notification`). This
+    # translates the object back to that shape, so the shared settlement rule
+    # reads the same fields it reads on a list_transactions row —
+    # `state`/`settled_at`, never a preimage alone. Every notification type is
+    # forwarded; the engine filters `payment_received` itself, because an
+    # NWC-02 subscription is not type-filtered — the wallet decides what it
+    # publishes.
+    #
+    # Returns whatever subscribe_to_notifications returns; nwc-ruby's blocks
+    # until the subscription ends, which is the contract
+    # listen_for_notifications! documents for blocking clients.
+    def subscribe_notifications(&handler)
+      @client.subscribe_to_notifications do |notification|
+        handler.call(
+          "notification_type" => notification.type.to_s,
+          "notification" => OpenReceive.stringify(notification.data)
+        )
+      end
+    end
+
+    private
+
+    def symbolize_keys(value)
+      value.each_pair.each_with_object({}) do |(key, item), result|
+        result[key.to_sym] = item
+      end
+    end
+  end
+end

data/lib/openreceive/rates.rb

@@ -0,0 +1,498 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "json"
+require "net/http"
+require "uri"
+
+module OpenReceive
+  # Raised when a live price feed cannot serve a usable rate (network failure,
+  # bad HTTP status, refresh fail-closed windows). Mirrors the plain Error the
+  # JS feed throws; validation problems raise ArgumentError instead (the Ruby
+  # spelling of the JS RangeError).
+  class PriceFeedError < StandardError; end
+
+  # Ruby port of packages/js/core/src/rates/index.ts: the built-in BTC price
+  # feed (static provider plus cached live feed with primary/fallback
+  # failover). Constants are hand-written and drift-checked against
+  # spec/data/rates/price-sources.json by test/rates_test.rb, exactly like the
+  # JS constants are checked by tests/rates.test.mjs.
+  module Rates
+    # How long a cached price-feed read stays usable before a live refresh.
+    PRICE_FEED_CACHE_SECONDS = 60
+    INVOICE_QUOTE_TTL_SECONDS = 600
+    # A cache stamp this far in the future means the clock stepped backwards:
+    # treat the stamp as stale rather than "fresh until wall-clock catches up".
+    PRICE_FEED_CLOCK_SKEW_SECONDS = 5
+
+    # The primary feed must answer within this window before the fallback is tried.
+    PRICE_FEED_PRIMARY_TIMEOUT_MS = 5000
+
+    PRICE_SOURCE_IDS = %w[static_mock primary fallback].freeze
+    STATIC_PRICE_SOURCE_ID = "static_mock"
+
+    STATIC_BTC_FIAT_RATES = {
+      "bitcoin" => {
+        "usd" => "50000.00"
+      }.freeze
+    }.freeze
+
+    # The fixed fiat list both live feeds price Bitcoin against. Hard-coded so
+    # the primary and fallback URLs always request the same currencies.
+    PRICE_FEED_VS_CURRENCIES =
+      "usd,aed,ars,aud,bdt,bhd,bmd,brl,cad,chf,clp,cny,czk,dkk,eur,gbp,gel,hkd,huf,idr,ils,inr,jpy,krw,kwd,lkr,mmk,mxn,myr,ngn,nok,nzd,php,pkr,pln,rub,sar,sek,sgd,thb,try,twd,uah,vef,vnd,zar"
+
+    PRICE_FEED_CURRENCIES = PRICE_FEED_VS_CURRENCIES.split(",").freeze
+
+    SIMPLE_PRICE_BASE_URL = "https://api.coingecko.com/api/v3/simple/price"
+
+    # Primary live feed: the canonical public Simple Price endpoint.
+    PRIMARY_PRICE_FEED_URL =
+      "#{SIMPLE_PRICE_BASE_URL}?ids=bitcoin&vs_currencies=#{PRICE_FEED_VS_CURRENCIES}"
+
+    # Fallback live feed: the OpenReceive mirror, in the same response shape.
+    FALLBACK_PRICE_FEED_URL =
+      "https://openreceive.org/api/v3/simple/price?ids=bitcoin&vs_currencies=#{PRICE_FEED_VS_CURRENCIES}"
+
+    # Dev override env var names. Hosts read these (see
+    # read_price_feed_url_overrides) and pass any override into the factory;
+    # the feed itself never reads the environment.
+    PRICE_FEED_PRIMARY_URL_ENV = "OPENRECEIVE_PRICE_FEED_PRIMARY_URL"
+    PRICE_FEED_FALLBACK_URL_ENV = "OPENRECEIVE_PRICE_FEED_FALLBACK_URL"
+
+    CURRENCY_PATTERN = /\A[A-Z]{3}\z/
+    RATE_KEY_PATTERN = /\A[a-z]{3}\z/
+
+    module_function
+
+    def normalize_fiat_currency(currency)
+      unless currency.is_a?(String) && CURRENCY_PATTERN.match?(currency)
+        raise ArgumentError, "fiat.currency must be an ISO 4217 uppercase code"
+      end
+      currency.downcase
+    end
+
+    def static_btc_fiat_price(currency)
+      rate = STATIC_BTC_FIAT_RATES.fetch("bitcoin")[normalize_fiat_currency(currency)]
+      raise ArgumentError, "unsupported static fiat currency: #{currency}" if rate.nil?
+      rate
+    end
+
+    # Strict select: every requested currency must be present and well formed.
+    def parse_simple_price_response(response, currencies)
+      bitcoin = as_record(as_record(response)["bitcoin"])
+      rates = {}
+      currencies.each do |currency|
+        key = normalize_fiat_currency(currency)
+        rates[key] = normalize_btc_fiat_rate(bitcoin[key], "bitcoin.#{key}")
+      end
+      { "bitcoin" => rates }
+    end
+
+    # Tolerant parse for caching the whole feed: keeps every well-formed
+    # currency the response carries and skips ones an upstream returned
+    # unusably (so a single dropped currency never fails the refresh). Raises
+    # only when the response is not Simple Price shaped or carries no usable
+    # rate at all.
+    def parse_available_simple_price_response(response)
+      bitcoin = as_record(as_record(response)["bitcoin"])
+      rates = {}
+      bitcoin.each do |key, value|
+        rate_key = key.to_s.downcase
+        next unless RATE_KEY_PATTERN.match?(rate_key)
+        begin
+          rates[rate_key] = normalize_btc_fiat_rate(value, "bitcoin.#{key}")
+        rescue ArgumentError
+          # Skip a currency the upstream returned in an unusable form.
+        end
+      end
+      raise ArgumentError, "price response contained no usable BTC fiat rates" if rates.empty?
+      { "bitcoin" => rates }
+    end
+
+    def normalize_btc_fiat_rate(value, field)
+      if value.is_a?(Numeric)
+        unless value.finite? && value.positive?
+          raise ArgumentError, "#{field} must be a positive number"
+        end
+        normalized = number_to_plain_decimal_string(value)
+        Money.decimal(normalized, field)
+        return normalized
+      end
+
+      if value.is_a?(String)
+        Money.decimal(value, field)
+        return value
+      end
+
+      raise ArgumentError, "#{field} must be a number or decimal string"
+    end
+
+    # Expand any JSON number an upstream price source returns to plain decimal
+    # notation (never exponent form), matching JS numberToPlainDecimalString.
+    def number_to_plain_decimal_string(value)
+      return value.to_s if value.is_a?(Integer)
+      decimal = BigDecimal(value.to_s)
+      text = decimal.to_s("F")
+      decimal.frac.zero? ? text.sub(/\.0+\z/, "") : text
+    end
+
+    def as_record(value)
+      raise ArgumentError, "expected object" unless value.is_a?(Hash)
+      value
+    end
+
+    # Builds the primary and fallback live feed providers from the hard-coded
+    # URLs (or caller overrides). The primary provider carries the 5s timeout.
+    def create_live_price_feed_providers(http: nil, primary_url: nil, fallback_url: nil, primary_timeout_ms: nil)
+      {
+        primary: HttpSimplePriceProvider.new(
+          url: primary_url || PRIMARY_PRICE_FEED_URL,
+          source: "primary",
+          http: http,
+          timeout_ms: primary_timeout_ms || PRICE_FEED_PRIMARY_TIMEOUT_MS
+        ),
+        fallback: HttpSimplePriceProvider.new(
+          url: fallback_url || FALLBACK_PRICE_FEED_URL,
+          source: "fallback",
+          http: http
+        )
+      }
+    end
+
+    # Wires the hard-coded (or overridden) feeds to a disposable local cache.
+    def create_cached_live_price_feed(currencies:, http: nil, clock: nil, cache_seconds: nil,
+                                      primary_url: nil, fallback_url: nil, primary_timeout_ms: nil)
+      providers = create_live_price_feed_providers(
+        http: http,
+        primary_url: primary_url,
+        fallback_url: fallback_url,
+        primary_timeout_ms: primary_timeout_ms
+      )
+      CachedPriceFeed.new(
+        currencies: currencies,
+        primary: providers.fetch(:primary),
+        fallback: providers.fetch(:fallback),
+        cache_seconds: cache_seconds,
+        clock: clock
+      )
+    end
+
+    # Host-side helper (the Ruby analogue of the node service's env reader):
+    # returns non-empty URL overrides from the well-known env var names.
+    def read_price_feed_url_overrides(env = ENV)
+      {
+        primary_url: presence(env[PRICE_FEED_PRIMARY_URL_ENV]),
+        fallback_url: presence(env[PRICE_FEED_FALLBACK_URL_ENV])
+      }
+    end
+
+    def presence(value)
+      text = value.to_s.strip
+      text.empty? ? nil : text
+    end
+
+    # Default HTTP transport on stdlib Net::HTTP. Injectable replacements must
+    # be callable as call(url, headers, timeout_ms) and return a Hash with
+    # :status (Integer) and :body (String).
+    def default_http_get(url, headers, timeout_ms)
+      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 = Net::HTTP::Get.new(uri.request_uri)
+      headers.each { |key, value| request[key] = value }
+      response = http.start { |connection| connection.request(request) }
+      { status: Integer(response.code), body: response.body.to_s }
+    end
+
+    # Serves the fixed static_mock table (same semantics as JS
+    # StaticPriceProvider). Satisfies the openreceive-server price_provider
+    # contract via btc_fiat_price(currency).
+    class StaticPriceProvider
+      def source
+        STATIC_PRICE_SOURCE_ID
+      end
+
+      def btc_fiat_rates(currencies)
+        rates = {}
+        currencies.each do |currency|
+          rates[Rates.normalize_fiat_currency(currency)] = Rates.static_btc_fiat_price(currency)
+        end
+        { "bitcoin" => rates }
+      end
+
+      def btc_fiat_rates_with_source(currencies)
+        { "source" => source, "rates" => btc_fiat_rates(currencies) }
+      end
+
+      def btc_fiat_price(currency)
+        Rates.static_btc_fiat_price(currency)
+      end
+    end
+
+    # Fetches a Simple Price compatible HTTP endpoint and selects the
+    # requested fiat currencies. When timeout_ms is set, a slow endpoint fails
+    # within that window so the caller can fall through to another feed.
+    class HttpSimplePriceProvider
+      attr_reader :url, :source, :timeout_ms
+
+      def initialize(url:, source:, http: nil, timeout_ms: nil)
+        @url = url
+        @source = source
+        @http = http
+        @timeout_ms = timeout_ms
+      end
+
+      def btc_fiat_rates(currencies)
+        Rates.parse_simple_price_response(fetch_json, currencies)
+      end
+
+      # Returns every well-formed currency the endpoint carries, for caching
+      # the whole feed in one read.
+      def all_btc_fiat_rates
+        Rates.parse_available_simple_price_response(fetch_json)
+      end
+
+      private
+
+      def fetch_json
+        response = perform_request
+        status = response[:status] || response["status"]
+        body = response[:body] || response["body"]
+        unless (200..299).cover?(status)
+          raise PriceFeedError, "price source #{@source} returned HTTP #{status}"
+        end
+        JSON.parse(body.to_s)
+      end
+
+      def perform_request
+        transport = @http || Rates.method(:default_http_get)
+        transport.call(@url, { "accept" => "application/json" }, @timeout_ms)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error => e
+        raise PriceFeedError, timeout_message(e)
+      rescue PriceFeedError
+        raise
+      rescue StandardError => e
+        raise PriceFeedError, "price source #{@source} request failed: #{e.message}"
+      end
+
+      def timeout_message(error)
+        return "price source #{@source} did not respond within #{@timeout_ms}ms" unless @timeout_ms.nil?
+        "price source #{@source} request failed: #{error.message}"
+      end
+    end
+
+    # Serves BTC fiat rates from a disposable process-local cache, refreshing
+    # from the primary feed first and the fallback second. Port of the JS
+    # CachedPriceFeed state machine: fresh entries are served for
+    # cache_seconds; a refresh failure fails closed for cache_seconds; a
+    # concurrent in-flight refresh serves the stale entry only while it is
+    # younger than the invoice quote TTL. Satisfies the openreceive-server
+    # price_provider contract via btc_fiat_price(currency).
+    class CachedPriceFeed
+      # Representative source for the plain source reader; the true origin is
+      # reported per-call by btc_fiat_rates_with_source.
+      attr_reader :source
+
+      def initialize(currencies:, primary:, fallback:, cache_seconds: nil, clock: nil)
+        raise ArgumentError, "CachedPriceFeed requires at least one currency" if currencies.empty?
+        cache_seconds ||= PRICE_FEED_CACHE_SECONDS
+        unless cache_seconds.is_a?(Integer) && cache_seconds.positive?
+          raise ArgumentError, "CachedPriceFeed cache_seconds must be a positive integer"
+        end
+        # A cache window wider than the quote TTL would let a read be reported
+        # as fresh that is already too old to price an invoice.
+        if cache_seconds > INVOICE_QUOTE_TTL_SECONDS
+          raise ArgumentError,
+                "CachedPriceFeed cache_seconds must not exceed the #{INVOICE_QUOTE_TTL_SECONDS}s invoice quote TTL"
+        end
+        @currencies = currencies.map(&:to_s).freeze
+        @primary = primary
+        @fallback = fallback
+        @cache_seconds = cache_seconds
+        @clock = clock || -> { Time.now.to_i }
+        @source = "primary"
+        @mutex = Mutex.new
+        @refresh_done = ConditionVariable.new
+        @state = nil
+        @in_flight = nil
+      end
+
+      def btc_fiat_rates(currencies)
+        btc_fiat_rates_with_source(currencies).fetch("rates")
+      end
+
+      def btc_fiat_rates_with_source(currencies)
+        now = @clock.call
+        claim = read_or_claim_refresh(now)
+        entry =
+          case claim.fetch(:status)
+          when :served then claim.fetch(:entry)
+          when :pending then await_refresh(claim.fetch(:pending))
+          else tracked_refresh(now, claim.fetch(:previous_entry), claim.fetch(:pending))
+          end
+        {
+          "source" => entry.fetch("source"),
+          "rates" => Rates.parse_simple_price_response(entry.fetch("rates"), currencies)
+        }
+      end
+
+      # The openreceive-server price_provider contract: one decimal price
+      # string for one uppercase ISO 4217 currency.
+      def btc_fiat_price(currency)
+        btc_fiat_rates([currency]).fetch("bitcoin").fetch(Rates.normalize_fiat_currency(currency))
+      end
+
+      # Forces a live refresh, ignoring the cache, for explicit operational
+      # probes. Raises if both feeds fail. Tolerant of an upstream that drops
+      # an individual currency (pass no currencies to get everything cached).
+      def health_check(currencies = nil)
+        now = @clock.call
+        pending = { "owner" => Thread.current, "done" => false }
+        previous_entry = @mutex.synchronize do
+          @in_flight = pending
+          @state && @state["entry"]
+        end
+        entry = tracked_refresh(now, previous_entry, pending)
+        rates =
+          if currencies.nil? || currencies.empty?
+            entry.fetch("rates")
+          else
+            Rates.parse_simple_price_response(entry.fetch("rates"), currencies)
+          end
+        { "source" => entry.fetch("source"), "rates" => rates }
+      end
+
+      private
+
+      def read_or_claim_refresh(now)
+        @mutex.synchronize do
+          state = @state
+          entry = state && state["entry"]
+
+          entry_age = entry && stamp_age(entry.fetch("fetched_at"), now)
+          if entry_age && entry_age < @cache_seconds
+            return { status: :served, entry: entry }
+          end
+
+          # Stale-while-revalidate is bounded by the invoice quote TTL: a rate
+          # observed longer ago than a quote may live must never price a new
+          # invoice — fail closed instead of serving it.
+          quotable = entry if entry_age && entry_age < INVOICE_QUOTE_TTL_SECONDS
+
+          if state && recent?(state["refresh_failed_at"], now)
+            # One failed refresh must not hard-down quoting for the whole
+            # backoff while a still-quotable observation is in hand.
+            return { status: :served, entry: quotable } unless quotable.nil?
+            message = "price feed refresh already failed within #{@cache_seconds}s"
+            message += ": #{state["refresh_error"]}" unless state["refresh_error"].to_s.empty?
+            raise PriceFeedError, message
+          end
+
+          if state && recent?(state["refresh_started_at"], now)
+            return { status: :served, entry: quotable } unless quotable.nil?
+            # Cold cache: join the refresh already running in this process
+            # rather than failing every concurrent caller but the one that
+            # claimed it. The claiming thread itself cannot wait on its own
+            # refresh, so a re-entrant read still fails closed.
+            pending = @in_flight
+            if !pending.nil? && !pending["owner"].equal?(Thread.current)
+              return { status: :pending, pending: pending }
+            end
+            raise PriceFeedError, "price feed refresh already started within #{@cache_seconds}s"
+          end
+
+          claimed = { "refresh_started_at" => now }
+          claimed["entry"] = entry unless entry.nil?
+          @state = claimed
+          pending = { "owner" => Thread.current, "done" => false }
+          @in_flight = pending
+          { status: :claimed, previous_entry: entry, pending: pending }
+        end
+      end
+
+      def recent?(timestamp, now)
+        age = stamp_age(timestamp, now)
+        !age.nil? && age < @cache_seconds
+      end
+
+      # Age of a cache stamp, or nil when the stamp is unusable because it sits
+      # beyond the clock-skew tolerance in the future (mirrors the JS cache).
+      def stamp_age(timestamp, now)
+        return nil if timestamp.nil?
+
+        age = now - timestamp
+        return nil if age < -PRICE_FEED_CLOCK_SKEW_SECONDS
+
+        age.negative? ? 0 : age
+      end
+
+      def tracked_refresh(now, previous_entry, pending)
+        entry = refresh(now, previous_entry)
+        settle(pending, entry, nil)
+        entry
+      rescue StandardError => e
+        settle(pending, nil, e)
+        raise
+      end
+
+      def settle(pending, entry, error)
+        @mutex.synchronize do
+          pending["entry"] = entry
+          pending["error"] = error
+          pending["done"] = true
+          @in_flight = nil if @in_flight.equal?(pending)
+          @refresh_done.broadcast
+        end
+      end
+
+      def await_refresh(pending)
+        @mutex.synchronize do
+          @refresh_done.wait(@mutex) until pending["done"]
+        end
+        error = pending["error"]
+        raise error unless error.nil?
+        pending["entry"]
+      end
+
+      def refresh(now, previous_entry)
+        failures = []
+        [@primary, @fallback].each do |provider|
+          begin
+            rates = fetch_provider_rates(provider)
+            entry = { "rates" => rates, "source" => provider.source, "fetched_at" => now }
+            @mutex.synchronize { @state = { "entry" => entry } }
+            return entry
+          rescue StandardError => e
+            failures << "#{provider.source}: #{e.message}"
+          end
+        end
+
+        message = "all price feeds failed: #{failures.join("; ")}"
+        @mutex.synchronize do
+          failed = {
+            "refresh_started_at" => now,
+            "refresh_failed_at" => now,
+            "refresh_error" => message
+          }
+          failed["entry"] = previous_entry unless previous_entry.nil?
+          @state = failed
+        end
+        raise PriceFeedError, message
+      end
+
+      # Cache the whole feed when the provider can serve it tolerantly;
+      # otherwise request just the configured currencies.
+      def fetch_provider_rates(provider)
+        return provider.all_btc_fiat_rates if provider.respond_to?(:all_btc_fiat_rates)
+        provider.btc_fiat_rates(@currencies)
+      end
+    end
+  end
+end