nwc-ruby 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d541ad9af31629ad26492d8da61d56b0a63980cc8597a460cca9949df56f382d
-  data.tar.gz: 8d48fbbe532bdcf56d889f68f9d7878fa2958381c1ea285fb572aebb70d17d7e
+  metadata.gz: 9b1fb35da37743ef772eac5368822e3656d24a8f1b081fa02174f52084ea0d03
+  data.tar.gz: '086309565529631e6525c95a22736b86423969216bc12f7ea2e63c65c9cc713e'
 SHA512:
-  metadata.gz: bbc5e4a3efdac9b24a4a2c5fc183f3945ba9987fd5312c78a7e8c4ba8cff625af5c08521094cc10101fd24a0bef5f35261eb29720d533d7e0167a236ee59d106
-  data.tar.gz: fb2c7a1ed8d7785a886b38e250432466354b257cef1e4c8552ef24c493c304dbd446bf4c17e57debcce8bc6875666686c16f901d29474ef08541194e6e2a97f3
+  metadata.gz: 54b83902f9b0f3a0cd3df5f453d07d90e31a72b18cb81c888b9635ea44c7d34f804b15a0c6d77ab5fca3bad85be99adb73cf91cc22fb76fed94da35300d63f37
+  data.tar.gz: 1871b89d77fbac48fb8731ed8ae56c99a3555289313af614b2b1bf13704fca12a64c4233b92ac0fafcd469db1b0fb501b841eba202b21b528698f919eee06183

data/CHANGELOG.md

@@ -7,6 +7,99 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-10-05
+
+### Changed
+
+- **Failures now say whether the request reached the wallet.** Anything that
+  fails before the request EVENT is written to the relay — DNS, TCP connect,
+  TLS, the websocket upgrade, the info fetch — raises the new
+  `NwcRuby::NotSentError` (a `TransportError` subclass, so existing rescues
+  still match), with the original exception as `#cause` and only the relay
+  host in the message. Failures after the write stay ambiguous:
+  `TransportError` or `TimeoutError`. Previously a DNS failure surfaced as a
+  raw `Socket::ResolutionError`, so callers could not tell "never sent, safe
+  to retry" from "maybe paid".
+- Public `Client` methods no longer leak raw `SocketError` / `Errno::*` /
+  `OpenSSL::SSL::SSLError` / `Async::TimeoutError` / `Protocol::WebSocket`
+  exceptions; everything is an `NwcRuby::Error`.
+- A relay closing the connection after the request was sent now raises
+  `TransportError` instead of a misleading `TimeoutError`.
+- A relay answering the request with `["OK", id, false, reason]` now raises
+  `TransportError` immediately instead of waiting out `request_timeout`. It is
+  still treated as maybe-sent, since the relay is untrusted.
+- "No info event" is now `InfoUnavailableError` (a `NotSentError`) instead of a
+  plain `TransportError`.
+- `request_timeout` now bounds the whole call, including connecting and the
+  info fetch. Before, a relay that went silent could block a request
+  indefinitely because the deadline was only checked when a message arrived.
+- Errors are classified inside the Async task, so Async no longer logs
+  "Task may have ended with unhandled exception" for request failures.
+
+### Added
+
+- `connect_retries:` (default 2): pre-send failures are retried with 0.25 s /
+  1 s backoff inside `request_timeout`. Nothing is retried after the request is
+  written.
+- Requests and info fetches fall through to the next `relay` in the connection
+  string on a pre-send failure (previously only the first relay was used).
+- `NwcRuby::Error#sent?` — `false` for `NotSentError` and
+  `UnsupportedMethodError`, `true` for `TransportError`, `TimeoutError` and
+  `WalletServiceError`, `nil` where it doesn't apply.
+
+## [0.2.4] — 2026-07-17
+
+### Security
+
+- **Event ids are now recomputed before the signature is trusted.**
+  `Event#valid_signature?` verified the signature against the `id` supplied by
+  the relay without checking that the `id` actually described the event body.
+  Because a Nostr signature only ever commits to the `id`, nothing bound that
+  `id` to the event it arrived with: a relay could lift a genuine
+  `(id, sig, pubkey)` triple from any real wallet event and re-attach it to
+  arbitrary `content`, `tags`, `kind` or `created_at`, and the result verified.
+  The id is now recomputed from the canonical serialization first, via the new
+  `Event#valid_id?`. Reported by @riccardobl in
+  [#1](https://github.com/MegalithicBTC/nwc-ruby/issues/1).
+
+  The sharpest edge was the kind 13194 info event, whose content and tags are
+  plaintext: stripping its `encryption` tag silently downgraded every
+  subsequent request from NIP-44 v2 to NIP-04, since the spec reads an absent
+  tag as "nip04 only".
+
+- **Responses are now bound to the request that asked for them.** `call` trusted
+  the relay to honour the `#e` REQ filter and never checked the response's `e`
+  tag itself, so a relay could replay an older but genuine response — a past
+  "payment succeeded" answering a fresh `pay_invoice`, for instance.
+
+- **`fetch_info` now verifies the event author.** It previously checked only
+  `valid_signature?` and never compared the pubkey to the wallet's, so a relay
+  could sign an info event with its own key and have it accepted — forcing the
+  encryption downgrade above without needing to tamper with anything.
+
+### Fixed
+
+- The notification listener no longer tears down when a relay delivers an event
+  of an unexpected kind. `Notification.parse` raises `ArgumentError` on a
+  non-notification kind, but only `EncryptionError` was rescued, so a relay
+  echoing a kind 23195 response onto the subscription killed the listener.
+- A rejected info event no longer ends the `fetch_info` read loop, so one junk
+  event cannot deny service while a genuine info event is still inbound.
+- Corrected `source_code_uri` and `changelog_uri` in the gemspec, which pointed
+  at a `main` branch that does not exist — both links 404'd from the RubyGems
+  page. This repo uses `master`; `PUBLISHING.md` has been corrected to match.
+- `PUBLISHING.md` no longer claims releases publish automatically on tag. There
+  is no `release.yml` in this repo — only `ci.yml`, which tests but never
+  publishes — so releases are manual.
+
+### Added
+
+- Documented a gentle `lookup_invoice` backup polling cadence for invoices so
+  apps can recover from missed notifications without getting rate limited by the
+  backing NWC service.
+
+## [0.2.3] — 2026-04-23
+
 ### Fixed
 
 - Silenced the noisy `Async::Task` warn log ("Task may have ended with

data/README.md

@@ -224,6 +224,67 @@ to keep middleboxes from idle-closing the socket, reconnects with capped
 exponential backoff on failure, and force-recycles the connection every 5 minutes
 as a belt-and-suspenders check against silently dead TCP streams.
 
+#### Polling as a backup
+
+Notifications should be your primary settlement path, but production checkout
+flows should also run a small `lookup_invoice` poller after creating an invoice.
+Treat it as a backup for missed notifications, relay interruptions, app restarts,
+or wallet services that deliver notifications slowly.
+
+Do not poll every second until the invoice expires. Backing NWC services often
+enforce rate limits, and aggressive polling can get your app throttled right
+when a customer is trying to pay. Start soon after invoice creation, then poll
+less often as the invoice gets older, and stop when it is paid or expired.
+
+One reasonable cadence:
+
+```ruby
+def next_lookup_delay(elapsed)
+  return 3.seconds  if elapsed < 2.minutes
+  return 6.seconds  if elapsed < 5.minutes
+  12.seconds
+end
+
+invoice = client.make_invoice(amount: 10_000, description: "coffee")
+record = Invoice.create!(
+  payment_hash: invoice["payment_hash"],
+  bolt11: invoice["invoice"],
+  state: "pending",
+  expires_at: Time.current + 10.minutes,
+  next_lookup_at: Time.current + 3.seconds
+)
+
+# In a continuously running rake task / worker:
+loop do
+  Invoice.where(state: "pending")
+         .where("next_lookup_at <= ?", Time.current)
+         .find_each do |inv|
+    if inv.expires_at <= Time.current
+      inv.update!(state: "expired", next_lookup_at: nil)
+      next
+    end
+
+    response = client.lookup_invoice(payment_hash: inv.payment_hash)
+    settled = response["settled"] || response["paid"] ||
+              response["state"] == "settled" || response["state"] == "SETTLED" ||
+              response["settled_at"]
+
+    if settled
+      inv.update!(state: "paid", paid_at: Time.current, next_lookup_at: nil)
+    else
+      elapsed = Time.current - inv.created_at
+      inv.update!(next_lookup_at: Time.current + next_lookup_delay(elapsed))
+    end
+  end
+
+  sleep 2
+end
+```
+
+Keep the notification handler and the poller idempotent. Either one might mark
+the invoice paid first, and the other should see an already-paid row and do
+nothing.
+
 #### Resuming after a restart
 
 Persist the `created_at` of the last notification you processed and pass it as
@@ -461,6 +522,12 @@ Constructor:
 | `Client.from_uri(uri)`          | `Client` — parses the `nostr+walletconnect://` URI  |
 | `Client.new(connection_string)` | `Client` — if you already have a `ConnectionString` |
 
+Both accept `request_timeout:` (seconds, default 30, covering the info fetch,
+connect and response wait) and `connect_retries:` (default 2). Failures before
+the request is written to the relay are retried across every `relay` in the
+connection string, with 0.25 s / 1 s backoff, inside `request_timeout`.
+Nothing is ever retried after the request is written.
+
 Introspection:
 
 | Method            | Returns                                  |
@@ -504,19 +571,42 @@ Listener:
 
 ### Errors
 
-All gem errors inherit from `NwcRuby::Error`:
+All gem errors inherit from `NwcRuby::Error`. Public `Client` methods never
+let a raw `SocketError` / `Errno::*` / `OpenSSL` / `Async` exception escape;
+the original is kept as `#cause`.
 
 - `InvalidConnectionStringError` — the URI couldn't be parsed.
 - `EncryptionError` — bad MAC / bad padding / unknown version byte / bad key.
 - `InvalidSignatureError` — an event's signature did not verify.
-- `TransportError` — the WebSocket couldn't connect or died unrecoverably.
-- `TimeoutError` — no response within the timeout window.
+- `TransportError` — the connection failed **after** the request was written
+  to the relay. The wallet may have acted on it: reconcile with
+  `lookup_invoice` / `list_transactions` rather than retrying a payment.
+  - `NotSentError` — the request never left this process (DNS, connect, TLS,
+    websocket upgrade, info fetch). Always safe to retry.
+    - `InfoUnavailableError` — the relay holds no kind 13194 info event for
+      this wallet; usually a wrong relay or pubkey.
+- `TimeoutError` — the request was sent but no response arrived in time. The
+  wallet may have acted on it.
 - `UnsupportedMethodError` — wallet service doesn't advertise this method.
+  A configuration problem; retrying won't help.
 - `WalletServiceError` — the wallet returned an error envelope. Check `#code`
   for `RATE_LIMITED`, `NOT_IMPLEMENTED`, `INSUFFICIENT_BALANCE`,
   `QUOTA_EXCEEDED`, `RESTRICTED`, `UNAUTHORIZED`, `INTERNAL`,
   `UNSUPPORTED_ENCRYPTION`, `PAYMENT_FAILED`, `NOT_FOUND`, or `OTHER`.
 
+Every error also answers `#sent?`: `false` means the request provably never
+reached the wallet; `true` or `nil` mean it may have.
+
+```ruby
+begin
+  client.pay_invoice(invoice: bolt11)
+rescue NwcRuby::NotSentError
+  # Nothing reached the wallet. Safe to retry later.
+rescue NwcRuby::TransportError, NwcRuby::TimeoutError
+  # Ambiguous: the payment may have gone out. Reconcile before retrying.
+end
+```
+
 ---
 
 ## Security notes

data/lib/nwc_ruby/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'async'
+require 'async/clock'
 require 'async/http/endpoint'
 require 'async/websocket/client'
 
@@ -19,7 +20,10 @@ module NwcRuby
   #     puts "Got #{notification.amount_msats} msats"
   #   end
   class Client
-    DEFAULT_TIMEOUT = 30
+    DEFAULT_TIMEOUT         = 30
+    DEFAULT_CONNECT_RETRIES = 2
+    # Pause before each retry round; the last value repeats.
+    CONNECT_BACKOFF = [0.25, 1.0].freeze
 
     attr_reader :connection_string, :logger
 
@@ -27,10 +31,16 @@ module NwcRuby
       new(ConnectionString.parse(uri_string), **)
     end
 
-    def initialize(connection_string, logger: nil, request_timeout: DEFAULT_TIMEOUT)
+    # @param request_timeout [Numeric] overall budget per public call, covering
+    #   the info fetch, connecting, and waiting for the wallet's response.
+    # @param connect_retries [Integer] extra rounds through the relay list when
+    #   a request fails before it is sent. Never applies after sending.
+    def initialize(connection_string, logger: nil, request_timeout: DEFAULT_TIMEOUT,
+                   connect_retries: DEFAULT_CONNECT_RETRIES)
       @connection_string = connection_string
       @logger            = logger || default_logger
       @request_timeout   = request_timeout
+      @connect_retries   = connect_retries
       @info              = nil
     end
 
@@ -38,10 +48,11 @@ module NwcRuby
 
     # Fetch and cache the kind 13194 info event. This tells us which methods
     # the wallet service supports and which encryption schemes it accepts.
+    # Raises NotSentError (never anything lower-level) if it can't be fetched.
     def info(refresh: false)
       return @info if @info && !refresh
 
-      @info = fetch_info
+      @info = fetch_info(new_deadline)
     end
 
     def capabilities
@@ -187,8 +198,10 @@ module NwcRuby
 
       conn.on_event do |_sub, event_hash|
         event = Event.from_hash(event_hash)
-        next unless event.valid_signature?
-        next unless event.pubkey == @connection_string.wallet_pubkey
+        next unless authentic?(event)
+        # Notification.parse raises on any other kind, which would tear down
+        # the listener; the relay chooses what it sends us, not the filter.
+        next unless kinds.include?(event.kind)
 
         # Advance the poll watermark so we don't re-fetch old events.
         last_seen_at = event.created_at if event.created_at && event.created_at > last_seen_at
@@ -219,123 +232,230 @@ module NwcRuby
 
     private
 
-    # rubocop:disable Metrics/MethodLength
+    # Every event arriving from a relay must clear this before it is parsed.
+    # `valid_signature?` recomputes the id, so a passing event is byte-for-byte
+    # what the wallet signed — which is what makes the kind and tag checks
+    # below meaningful.
+    def authentic?(event)
+      event.valid_signature? && event.pubkey == @connection_string.wallet_pubkey
+    end
+
+    # A relay is not trusted to honour the REQ filter it was sent, so the
+    # response is bound to the request here. Without this an older but genuine
+    # response (say, a past "payment succeeded") can be replayed against a new
+    # request.
+    def response_to?(event, request_id)
+      e_tag = event.tags.find { |t| t[0] == 'e' }
+      !e_tag.nil? && e_tag[1] == request_id
+    end
+
+    # Advisory only — the relay decides what it actually sends, so `fetch_info`
+    # re-checks the author and kind on whatever comes back.
+    def info_filter
+      {
+        'authors' => [@connection_string.wallet_pubkey],
+        'kinds' => [NIP47::Methods::KIND_INFO],
+        'limit' => 1
+      }
+    end
+
+    def response_filter(request_id)
+      {
+        'authors' => [@connection_string.wallet_pubkey],
+        'kinds' => [NIP47::Methods::KIND_RESPONSE],
+        '#e' => [request_id],
+        '#p' => [@connection_string.client_pubkey]
+      }
+    end
+
+    # Every request has two phases. Phase 1 (info fetch, DNS, connect, TLS,
+    # upgrade, REQ write) cannot have reached the wallet, so its failures raise
+    # NotSentError and are retried. Phase 2 starts at the EVENT write: the
+    # wallet may have acted, so failures there are ambiguous and never retried.
     def call(method, params)
-      ensure_supports!(method)
-      encryption = info.preferred_encryption
-
-      deadline = Time.now + @request_timeout
-      result   = nil
-
-      Async do
-        endpoint = Async::HTTP::Endpoint.parse(@connection_string.relays.first, alpn_protocols: ['http/1.1'])
-        Async::WebSocket::Client.connect(endpoint) do |conn|
-          request_event = NIP47::Request.build(
-            method: method,
-            params: params,
-            client_privkey: @connection_string.secret,
-            wallet_pubkey: @connection_string.wallet_pubkey,
-            encryption: encryption
-          )
-
-          sub_id = "rsp-#{SecureRandom.hex(4)}"
-          conn.write(Protocol::WebSocket::TextMessage.generate(['REQ', sub_id, {
-                                                                 'authors' => [@connection_string.wallet_pubkey],
-                                                                 'kinds' => [NIP47::Methods::KIND_RESPONSE],
-                                                                 '#e' => [request_event.id],
-                                                                 '#p' => [@connection_string.client_pubkey]
-                                                               }]))
-          conn.write(Protocol::WebSocket::TextMessage.generate(['EVENT', request_event.to_h]))
-          conn.flush
-
-          while (msg = conn.read)
-            break if Time.now > deadline
-
-            parsed = begin
-              JSON.parse(msg.buffer)
-            rescue JSON::ParserError
-              next
-            end
-
-            next unless parsed[0] == 'EVENT' && parsed[1] == sub_id
-
-            event = Event.from_hash(parsed[2])
-            next unless event.valid_signature?
-            next unless event.pubkey == @connection_string.wallet_pubkey
-
-            result = NIP47::Response.parse(event, @connection_string.secret, @connection_string.wallet_pubkey)
-            break
-          end
-        ensure
-          begin
-            conn&.close
-          rescue StandardError
-            nil
-          end
-        end
-      end.wait
-
-      raise TimeoutError, "no response to #{method} within #{@request_timeout}s" if result.nil?
-      raise WalletServiceError.new(result.error_code || 'UNKNOWN', result.error_message || '') unless result.success?
-
-      result.result
-    end
-    # rubocop:enable Metrics/MethodLength
-
-    def fetch_info
-      endpoint  = Async::HTTP::Endpoint.parse(@connection_string.relays.first, alpn_protocols: ['http/1.1'])
-      deadline  = Time.now + @request_timeout
-      result    = nil
-
-      Async do
-        Async::WebSocket::Client.connect(endpoint) do |conn|
-          sub_id = "info-#{SecureRandom.hex(4)}"
-          conn.write(Protocol::WebSocket::TextMessage.generate(['REQ', sub_id, {
-                                                                 'authors' => [@connection_string.wallet_pubkey],
-                                                                 'kinds' => [NIP47::Methods::KIND_INFO],
-                                                                 'limit' => 1
-                                                               }]))
-          conn.flush
-
-          while (msg = conn.read)
-            break if Time.now > deadline
-
-            parsed = begin
-              JSON.parse(msg.buffer)
-            rescue JSON::ParserError
-              next
-            end
-
-            if parsed[0] == 'EVENT' && parsed[1] == sub_id
-              event  = Event.from_hash(parsed[2])
-              result = NIP47::Info.parse(event) if event.valid_signature?
-              break
-            elsif parsed[0] == 'EOSE' && parsed[1] == sub_id
-              break
-            end
-          end
-        ensure
-          begin
-            conn&.close
-          rescue StandardError
-            nil
-          end
+      deadline = new_deadline
+      ensure_supports!(method, deadline)
+
+      # Built once so every relay and retry carries the same event id.
+      request_event = NIP47::Request.build(
+        method: method,
+        params: params,
+        client_privkey: @connection_string.secret,
+        wallet_pubkey: @connection_string.wallet_pubkey,
+        encryption: @info.preferred_encryption
+      )
+
+      response = with_relays(deadline) { |url| send_request(url, deadline, method, request_event) }
+      unless response.success?
+        raise WalletServiceError.new(response.error_code || 'UNKNOWN', response.error_message || '')
+      end
+
+      response.result
+    end
+
+    def send_request(url, deadline, method, request_event)
+      sent = false
+      response, failure = websocket_session(url, deadline) do |conn|
+        sub_id = "rsp-#{SecureRandom.hex(4)}"
+        write_frame(conn, ['REQ', sub_id, response_filter(request_event.id)])
+        # Set before the write: a write that fails part-way may still deliver.
+        sent = true
+        write_frame(conn, ['EVENT', request_event.to_h])
+        read_response(conn, sub_id, request_event.id)
+      end
+      return response if response
+
+      raise_not_sent(url, failure) unless sent
+      raise failure if failure.is_a?(Error)
+      if failure.is_a?(Async::TimeoutError)
+        raise TimeoutError, "no response to #{method} within #{@request_timeout}s", cause: failure
+      end
+
+      raise TransportError,
+            "connection to relay #{relay_host(url)} failed after #{method} was sent " \
+            "(#{failure.class}: #{failure.message})",
+            cause: failure
+    end
+
+    def read_response(conn, sub_id, request_id)
+      while (msg = conn.read)
+        parsed = parse_frame(msg)
+        # Still ambiguous: the relay is untrusted and may have forwarded it anyway.
+        if parsed && parsed[0] == 'OK' && parsed[1] == request_id && parsed[2] == false
+          raise TransportError, "relay rejected the request: #{parsed[3].to_s[0, 200]}"
         end
-      end.wait
 
-      if result.nil?
-        raise TransportError,
-              "wallet service published no info event (kind 13194) on #{@connection_string.relays.first}"
+        event = relay_event(parsed, sub_id)
+        next unless event && event.kind == NIP47::Methods::KIND_RESPONSE && response_to?(event, request_id)
+
+        return NIP47::Response.parse(event, @connection_string.secret, @connection_string.wallet_pubkey)
       end
+      raise TransportError, 'relay closed the connection before the wallet responded'
+    end
+
+    # Entirely phase 1: nothing has been sent to the wallet yet.
+    def fetch_info(deadline)
+      with_relays(deadline) { |url| fetch_info_from(url, deadline) }
+    end
+
+    def fetch_info_from(url, deadline)
+      info, failure = websocket_session(url, deadline) do |conn|
+        sub_id = "info-#{SecureRandom.hex(4)}"
+        write_frame(conn, ['REQ', sub_id, info_filter])
+        read_info(conn, sub_id)
+      end
+      return info if info
+
+      raise_not_sent(url, failure) if failure
+      raise InfoUnavailableError,
+            "wallet service published no info event (kind 13194) on relay #{relay_host(url)}"
+    end
 
-      result
+    def read_info(conn, sub_id)
+      while (msg = conn.read)
+        parsed = parse_frame(msg)
+        return nil if parsed && parsed[0] == 'EOSE' && parsed[1] == sub_id
+
+        # A rejected event must not end the read: a genuine info event may
+        # still follow, and the deadline bounds the wait.
+        event = relay_event(parsed, sub_id)
+        return NIP47::Info.parse(event) if event&.kind == NIP47::Methods::KIND_INFO
+      end
+      nil
     end
 
-    def ensure_supports!(method)
-      return if info.supports?(method)
+    def ensure_supports!(method, deadline)
+      @info ||= fetch_info(deadline)
+      return if @info.supports?(method)
 
       raise UnsupportedMethodError,
-            "wallet service does not advertise `#{method}`. Supported: #{info.methods.join(', ')}"
+            "wallet service does not advertise `#{method}`. Supported: #{@info.methods.join(', ')}"
+    end
+
+    # Tries each relay in turn, then up to @connect_retries more rounds with
+    # backoff, all inside `deadline`. Only NotSentError is retried.
+    def with_relays(deadline)
+      last_failure = nil
+      (@connect_retries + 1).times do |round|
+        if round.positive?
+          pause = CONNECT_BACKOFF[round - 1] || CONNECT_BACKOFF.last
+          break if Async::Clock.now + pause >= deadline
+
+          sleep pause
+        end
+
+        @connection_string.relays.each do |url|
+          break if Async::Clock.now >= deadline
+
+          return yield(url)
+        rescue NotSentError => e
+          last_failure = e
+          @logger.warn("[nwc] #{e.message}")
+        end
+      end
+      raise last_failure if last_failure
+
+      raise NotSentError, "not sent: #{@request_timeout}s deadline passed before a relay could be tried"
+    end
+
+    # One websocket session bounded by `deadline`. Exceptions are rescued
+    # inside the task and returned so Async never logs them as unhandled.
+    # @return [Array(Object, Exception)] the block's value and any failure
+    def websocket_session(url, deadline)
+      value   = nil
+      failure = nil
+      Sync do |task|
+        task.with_timeout(remaining(deadline)) do
+          endpoint = Async::HTTP::Endpoint.parse(url, alpn_protocols: ['http/1.1'])
+          Async::WebSocket::Client.connect(endpoint) { |conn| value = yield(conn) }
+        end
+      rescue StandardError => e
+        failure = e
+      end
+      [value, failure]
+    end
+
+    def raise_not_sent(url, failure)
+      raise failure if failure.is_a?(NotSentError)
+
+      reason = failure.is_a?(Async::TimeoutError) ? 'timed out' : "#{failure.class}: #{failure.message}"
+      raise NotSentError, "not sent: relay #{relay_host(url)} failed before the request was written (#{reason})",
+            cause: failure
+    end
+
+    # An authentic wallet event delivered on `sub_id`, or nil.
+    def relay_event(parsed, sub_id)
+      return unless parsed && parsed[0] == 'EVENT' && parsed[1] == sub_id && parsed[2].is_a?(Hash)
+
+      event = Event.from_hash(parsed[2])
+      event if authentic?(event)
+    end
+
+    def parse_frame(msg)
+      parsed = JSON.parse(msg.buffer)
+      parsed if parsed.is_a?(Array)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def write_frame(conn, message)
+      conn.write(Protocol::WebSocket::TextMessage.generate(message))
+      conn.flush
+    end
+
+    # Host only: relay URLs can carry auth tokens in the path or query.
+    def relay_host(url)
+      URI.parse(url).host || 'unknown'
+    rescue URI::InvalidURIError
+      'unparseable relay URL'
+    end
+
+    def new_deadline
+      Async::Clock.now + @request_timeout
+    end
+
+    def remaining(deadline)
+      [deadline - Async::Clock.now, 0].max
     end
 
     def default_logger

data/lib/nwc_ruby/errors.rb

@@ -2,7 +2,11 @@
 
 module NwcRuby
   # Base class for all gem errors. Rescue this to catch anything the gem raises.
-  class Error < StandardError; end
+  class Error < StandardError
+    # Whether the request reached the relay. Only `false` is a safe-to-retry
+    # signal; `true` and `nil` mean the wallet may have acted on it.
+    def sent? = nil # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+  end
 
   # The connection string is missing or malformed.
   class InvalidConnectionStringError < Error; end
@@ -13,9 +17,24 @@ module NwcRuby
   # Signature verification failed on an inbound event.
   class InvalidSignatureError < Error; end
 
-  # The relay could not be reached, or the connection died and did not recover
-  # within the configured timeout.
-  class TransportError < Error; end
+  # The connection to the relay failed after the request was written to it.
+  # The wallet may have acted on the request, so do not blindly retry
+  # payments; reconcile with `lookup_invoice` / `list_transactions` instead.
+  # (`NotSentError` below is the safe-to-retry subclass.)
+  class TransportError < Error
+    def sent? = true
+  end
+
+  # The request never left this process: DNS, TCP connect, TLS, the websocket
+  # upgrade, or the info fetch failed first. Always safe to retry. `#cause`
+  # holds the original low-level exception.
+  class NotSentError < TransportError
+    def sent? = false
+  end
+
+  # The relay answered but holds no kind 13194 info event for this wallet.
+  # Usually a wrong relay or wallet pubkey rather than a transient fault.
+  class InfoUnavailableError < NotSentError; end
 
   # The wallet service returned an error envelope. `#code` is the NIP-47 error
   # code (one of RATE_LIMITED, NOT_IMPLEMENTED, INSUFFICIENT_BALANCE,
@@ -28,12 +47,20 @@ module NwcRuby
       @code = code
       super("#{code}: #{message}")
     end
+
+    def sent? = true
   end
 
-  # A request was sent but no response arrived within the timeout window.
-  class TimeoutError < Error; end
+  # A request was sent but no response arrived within the timeout window. The
+  # wallet may have acted on it.
+  class TimeoutError < Error
+    def sent? = true
+  end
 
   # The wallet service does not support the method we tried to call. Check
-  # `Client#capabilities` first, or use a read+write NWC string.
-  class UnsupportedMethodError < Error; end
+  # `Client#capabilities` first, or use a read+write NWC string. A
+  # configuration problem: retrying will not help.
+  class UnsupportedMethodError < Error
+    def sent? = false
+  end
 end

data/lib/nwc_ruby/event.rb

@@ -50,8 +50,20 @@ module NwcRuby
       self
     end
 
+    # True when the id is the SHA-256 of this event's canonical serialization.
+    def valid_id?
+      return false unless @id.is_a?(String)
+
+      @id == OpenSSL::Digest::SHA256.hexdigest(serialize_for_id)
+    end
+
+    # The signature only commits to the id, so the id must be recomputed from
+    # the event body before the signature means anything. Without that check a
+    # relay can graft a genuine (id, sig) pair from one event onto arbitrary
+    # pubkey/created_at/kind/tags/content and still verify.
     def valid_signature?
       return false unless @id && @sig && @pubkey
+      return false unless valid_id?
 
       digest_bytes = Crypto::Keys.hex_to_bytes(@id)
       Crypto::Schnorr.verify(digest_bytes, @sig, @pubkey)

data/lib/nwc_ruby/test_runner.rb

@@ -303,7 +303,7 @@ module NwcRuby
       rescue TimeoutError => e
         fail!("#{label}: #{e.message}")
         fail!('  → The wallet service accepted the request but never responded. The service may be down or overloaded.')
-      rescue UnsupportedMethodError => e
+      rescue UnsupportedMethodError, TransportError => e
         fail!("#{label}: #{e.message}")
       rescue EncryptionError => e
         fail!("#{label}: decryption failed — #{e.message}")

data/lib/nwc_ruby/transport/relay_connection.rb

@@ -120,7 +120,7 @@ module NwcRuby
       # Send raw client->relay message (e.g. REQ, EVENT, CLOSE). Safe to call
       # from within on_open / on_event callbacks.
       def send_message(message)
-        raise TransportError, 'not connected' unless @conn
+        raise NotSentError, 'not connected' unless @conn
 
         @conn.write(Protocol::WebSocket::TextMessage.generate(message))
         @conn.flush

data/lib/nwc_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NwcRuby
-  VERSION = '0.2.3'
+  VERSION = '0.3.0'
 end

data/nwc-ruby.gemspec

@@ -23,9 +23,9 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.2.0'
 
   spec.metadata['homepage_uri']          = spec.homepage
-  spec.metadata['source_code_uri']       = "#{spec.homepage}/tree/main"
+  spec.metadata['source_code_uri']       = "#{spec.homepage}/tree/master"
   spec.metadata['bug_tracker_uri']       = "#{spec.homepage}/issues"
-  spec.metadata['changelog_uri']         = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['changelog_uri']         = "#{spec.homepage}/blob/master/CHANGELOG.md"
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir[

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nwc-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - MegalithicBTC
@@ -204,9 +204,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/MegalithicBTC/nwc-ruby
-  source_code_uri: https://github.com/MegalithicBTC/nwc-ruby/tree/main
+  source_code_uri: https://github.com/MegalithicBTC/nwc-ruby/tree/master
   bug_tracker_uri: https://github.com/MegalithicBTC/nwc-ruby/issues
-  changelog_uri: https://github.com/MegalithicBTC/nwc-ruby/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/MegalithicBTC/nwc-ruby/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -222,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client for Nostr Wallet Connect (NIP-47) with safe long-running relay
   connections.