bsv-sdk 0.18.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e425cc46fca3c3db1d2dc79702491600ec302625132ba10c95ee8dee7242ed9
-  data.tar.gz: 1839e24be2d7ebea84478b54526f7793839681cd385fb9de962f118826220338
+  metadata.gz: ade93923526aab66c548ffc2326e09e439e73a8403748afe3bcd2c1e6e04d58d
+  data.tar.gz: aff5ede00eb02991dca9daa171f0f21d04d975f6ad3f012a817cfc5b46710ceb
 SHA512:
-  metadata.gz: 285dd4fc51b19fef84f31071cec373b43c70347de9cd5bf904c17fff65ff1c964b62d49969de79b98caa241198b6e689c7e50551a66aac2c1c593b1b9f491dc9
-  data.tar.gz: 3e5536f21302a75992e221967fa5de233cb4200a9efc34cd71b6d892f714955fd2dda73625a998a9943110274d63925e044690a99fe8870ef5a09323d6c1d901
+  metadata.gz: 32271e4c61f304555853790682f9008f4789e34059d6d868207f0ef07cf9744cf87ae67e5589ad451d22bebc7a435ae4989deaa48f9254b900691b303b961a7d
+  data.tar.gz: f51f7b37da7a8388606763df33bf71900592f37f7cb2ca6690337a7dfd04821eca14d78153f8dc470ad01c377b1b0e8fa300a661686e54255dac54d9a90ae190

data/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to the `bsv-sdk` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.19.0 — 2026-05-11
+
+### Breaking Changes
+- `Result::Success/Error/NotFound` replaced by single `ProtocolResponse` class composing `Net::HTTPResponse`
+- Predicates renamed: `success?` → `http_success?`, `not_found?` → `http_not_found?`, `error?` removed (use `!http_success?`)
+- Constructor keyword `ok:` → `http_success:`
+- ARC `arc_data_from` key remapping removed — `.data` returns raw API JSON with string keys (`'txid'` not `:txid`)
+- Batch broadcast `.data` returns raw JSON array (no per-item `Result` wrapping)
+- `BroadcastError`, `BroadcastResponse`, `ChainProviderError`, deprecated `BSV::Network::ARC` and `BSV::Network::WhatsOnChain` facades removed
+
+### Added
+- `ProtocolResponse` class with progressive enhancement: `.body`/`.code` (raw HTTP) → `.data` (parsed) → `.canonical` (placeholder)
+- `ProtocolResponse#with(**overrides)` for escape hatch post-processing
+- `fake_http_response` shared test helper for building real `Net::HTTPResponse` subclass instances
+- Debug logging in Protocol (`call`, `default_call`, `build_response`) and `ProtocolResponse#with`
+
+### Changed
+- `Protocol#map_response` renamed to `build_response`
+- Chain trackers raise `RuntimeError` instead of deleted `ChainProviderError`
+- `ChainTracker` doc rewritten to explain the declarative/imperative split
+- MCP tools updated: `.metadata[:status_code]` → `.code`, symbol keys → string keys
+
+### Fixed
+- `http_success?` returns `false` (not `nil`) when `http_response` is nil
+- `Ordinals#call_get_spend` rescues `TypeError` alongside `JSON::ParserError`
+- ARC malformed-2xx error messages include diagnostic detail
+- WoC `call_is_utxo` clears stale `error_message` when overriding 404 to success
+
 ## 0.18.1 — 2026-05-09
 
 ### Added

data/lib/bsv/mcp/tools/broadcast_p2pkh.rb

@@ -93,7 +93,7 @@ module BSV
 
           woc = BSV::Network::Providers::WhatsOnChain.default(network: net_sym)
           utxo_result = woc.call(:get_utxos_all, sender_address)
-          return Helpers.error_response("UTXO fetch failed: #{utxo_result.message}") unless utxo_result.success?
+          return Helpers.error_response("UTXO fetch failed: #{utxo_result.message}") unless utxo_result.http_success?
 
           all_utxos = utxo_result.data.map do |entry|
             BSV::Network::UTXO.new(
@@ -113,11 +113,11 @@ module BSV
 
           arc = build_arc(net_sym, server_context)
           arc_result = arc.call(:broadcast, tx)
-          return Helpers.error_response("Broadcast failed: #{arc_result.message}") unless arc_result.success?
+          return Helpers.error_response("Broadcast failed: #{arc_result.message}") unless arc_result.http_success?
 
           result = {
-            txid: arc_result.data[:txid], # MCP tool boundary: display-order hex from ARC response
-            tx_status: arc_result.data[:tx_status],
+            txid: arc_result.data['txid'], # MCP tool boundary: display-order hex from ARC response
+            tx_status: arc_result.data['txStatus'],
             hex: tx.to_hex
           }
 

data/lib/bsv/mcp/tools/check_balance.rb

@@ -62,8 +62,8 @@ module BSV
           provider = BSV::Network::Providers::WhatsOnChain.default(network: net_sym)
           utxo_result = provider.call(:get_utxos_all, address)
 
-          unless utxo_result.success?
-            code = utxo_result.metadata[:status_code]
+          unless utxo_result.http_success?
+            code = utxo_result.code
             msg = utxo_result.message
             msg = "#{msg} (HTTP #{code})" if code
             return Helpers.error_response(msg)

data/lib/bsv/mcp/tools/fetch_tx.rb

@@ -52,8 +52,8 @@ module BSV
           provider = BSV::Network::Providers::WhatsOnChain.default(network: net_sym)
           fetch_result = provider.call(:get_tx, txid)
 
-          unless fetch_result.success?
-            code = fetch_result.metadata[:status_code]
+          unless fetch_result.http_success?
+            code = fetch_result.code
             msg = fetch_result.message
             msg = "#{msg} (HTTP #{code})" if code
             return Helpers.error_response(msg)

data/lib/bsv/mcp/tools/fetch_utxos.rb

@@ -53,8 +53,8 @@ module BSV
           provider = BSV::Network::Providers::WhatsOnChain.default(network: net_sym)
           utxo_result = provider.call(:get_utxos_all, address)
 
-          unless utxo_result.success?
-            code = utxo_result.metadata[:status_code]
+          unless utxo_result.http_success?
+            code = utxo_result.code
             msg = utxo_result.message
             msg = "#{msg} (HTTP #{code})" if code
             return Helpers.error_response(msg)

data/lib/bsv/network/protocol.rb

@@ -20,8 +20,8 @@ module BSV
     #
     # HTTP dispatch routes through +call+: if a +call_<name>+ escape hatch
     # method exists on the instance, it is called; otherwise +default_call+
-    # interpolates the URL template, makes the HTTP request, and maps the
-    # response to a +Result+.
+    # interpolates the URL template, makes the HTTP request, and wraps the
+    # response in a +ProtocolResponse+.
     #
     # == Example
     #
@@ -127,14 +127,14 @@ module BSV
       #
       # If a method named +call_<command_name>+ exists on the instance it is
       # used as an escape hatch — that method receives +args+ and +kwargs+
-      # and MUST return a +Result+. Otherwise +default_call+ is invoked.
+      # and MUST return a +ProtocolResponse+. Otherwise +default_call+ is invoked.
       #
       # Subscriptions are not callable; calling one raises +NotImplementedError+.
       #
       # @param command_name [Symbol, String] command to invoke
       # @param args   [Array]  positional arguments forwarded to path interpolation
       # @param kwargs [Hash]   keyword arguments forwarded to path interpolation
-      # @return [Result::Success, Result::Error, Result::NotFound]
+      # @return [ProtocolResponse]
       # @raise [ArgumentError] when command_name is not registered
       def call(command_name, *args, **kwargs)
         name = command_name.to_sym
@@ -146,6 +146,7 @@ module BSV
 
         escape = :"call_#{name}"
         if respond_to?(escape, true)
+          BSV.logger&.debug { "[Protocol] #{self.class.name} :#{name} → escape hatch" }
           return kwargs.empty? ? send(escape, *args) : send(escape, *args, **kwargs)
         end
 
@@ -164,7 +165,7 @@ module BSV
       # @param command_name [Symbol] registered command name
       # @param args   [Array]  positional path parameters
       # @param kwargs [Hash]   named path parameters (and optional +:body+)
-      # @return [Result::Success, Result::Error, Result::NotFound]
+      # @return [ProtocolResponse]
       # @raise [ArgumentError] when command_name is not registered or a
       #   required path parameter is missing
       def default_call(command_name, *args, **kwargs)
@@ -176,9 +177,12 @@ module BSV
         path       = interpolate_path(defn[:path], args, kwargs)
         uri        = URI("#{@base_url}#{path}")
         request    = build_request(defn[:method], uri, body)
-        response   = execute(uri, request)
 
-        map_response(response, defn[:response])
+        BSV.logger&.debug { "[Protocol] #{defn[:method].upcase} #{uri}" }
+
+        response = execute(uri, request)
+
+        build_response(response, defn[:response])
       end
 
       private
@@ -313,38 +317,47 @@ module BSV
         end
       end
 
-      # Maps an HTTP response to a Result type, applying the response handler
-      # on 2xx bodies.
+      # Wraps an HTTP response in a +ProtocolResponse+, applying the response
+      # handler on 2xx bodies.
       #
-      # All non-2xx results carry +status_code:+ in their +metadata+ hash so
-      # that facades can construct domain exceptions with the original HTTP code.
+      # On 2xx responses, the handler is applied and the result stored in +data+.
+      # If the handler raises +JSON::ParserError+ or +TypeError+, the response
+      # is marked as an error with the exception message.
+      #
+      # On non-2xx responses, the raw body is stored as +error_message+.
       #
       # @param response [Net::HTTPResponse]
       # @param handler  [Symbol, #call]
-      # @return [Result::Success, Result::Error, Result::NotFound]
-      def map_response(response, handler)
-        code = response.code.to_i
-
-        case code
-        when 200..299
-          data = apply_handler(response.body, handler)
-          return data if data.is_a?(Result::Error)
-
-          Result::Success.new(data: data)
-        when 404
-          Result::NotFound.new(message: response.body, metadata: { status_code: code })
-        when 429, 500..599
-          Result::Error.new(message: response.body, retryable: true, metadata: { status_code: code })
-        else
-          Result::Error.new(message: response.body, retryable: false, metadata: { status_code: code })
+      # @return [ProtocolResponse]
+      def build_response(response, handler)
+        result = if response.is_a?(Net::HTTPSuccess)
+                   begin
+                     data = apply_handler(response.body, handler)
+                     ProtocolResponse.new(response, data: data)
+                   rescue JSON::ParserError, TypeError => e
+                     ProtocolResponse.new(response, http_success: false,
+                                                    error_message: "JSON/response error: #{e.message}")
+                   end
+                 else
+                   ProtocolResponse.new(response, error_message: response.body)
+                 end
+
+        BSV.logger&.debug do
+          "[Protocol] HTTP #{response.code} → http_success=#{result.http_success?}" \
+            "#{" error=#{result.error_message[0, 80]}" if result.error_message}"
         end
+
+        result
       end
 
       # Applies the response handler to a raw body string.
       #
+      # Exceptions from JSON parsing or type mismatches propagate to the caller
+      # (+build_response+) which handles them uniformly.
+      #
       # @param body    [String, nil]
       # @param handler [Symbol, #call]
-      # @return [Object, Result::Error]
+      # @return [Object]
       def apply_handler(body, handler)
         return body if body.nil?
 
@@ -365,8 +378,6 @@ module BSV
 
           handler.call(body)
         end
-      rescue JSON::ParserError, TypeError => e
-        Result::Error.new(message: "JSON/response error: #{e.message}", retryable: false)
       end
     end
   end

data/lib/bsv/network/protocol_response.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module BSV
+  module Network
+    class ProtocolResponse
+      attr_reader :data, :error_message
+
+      def initialize(http_response, data: nil, http_success: nil, error_message: nil)
+        @http_response = http_response
+        @data = data
+        @http_success = http_success.nil? ? http_response.is_a?(Net::HTTPSuccess) : http_success
+        @error_message = error_message
+        freeze
+      end
+
+      # Delegated from Net::HTTPResponse (nil-safe)
+      def body
+        @http_response&.body
+      end
+
+      def code
+        @http_response&.code
+      end
+
+      def content_type
+        @http_response&.content_type
+      end
+
+      # Two layers of status predicates:
+      #
+      # HTTP logical status — did the operation succeed? Driven by the +http_success:+
+      # parameter, which defaults to the RFC 9110 success class check
+      # (+Net::HTTPSuccess+, i.e. 2xx) but can be overridden by escape
+      # hatches that reinterpret HTTP status (e.g. ARC REJECTED on 2xx
+      # sets http_success: false; WoC is_utxo 404 sets http_success: true).
+      #
+      # Transport status — what did the HTTP layer actually return?
+      # These always reflect the +Net::HTTPResponse+ class hierarchy
+      # regardless of the +http_success:+ override. +http_not_found?+ maps
+      # directly to +Net::HTTPNotFound+ (404). +retryable?+ is a
+      # domain composite: 429 (+Net::HTTPTooManyRequests+) or 5xx
+      # (+Net::HTTPServerError+) — not an RFC 9110 category itself,
+      # but a useful signal for retry logic.
+
+      def http_success?
+        @http_success
+      end
+
+      def http_not_found?
+        @http_response.is_a?(Net::HTTPNotFound)
+      end
+
+      def retryable?
+        @http_response.is_a?(Net::HTTPTooManyRequests) ||
+          @http_response.is_a?(Net::HTTPServerError)
+      end
+
+      # Canonical form (placeholder — delegates to data until shapes are defined)
+      def canonical
+        data
+      end
+
+      # Compatibility: chain trackers + MCP tools call .message
+      alias message error_message
+
+      # Derive new response with overrides (same HTTP response, different interpretation)
+      def with(**overrides)
+        derived = self.class.new(
+          @http_response,
+          data: overrides.fetch(:data, @data),
+          http_success: overrides.fetch(:http_success, @http_success),
+          error_message: overrides.fetch(:error_message, @error_message)
+        )
+
+        BSV.logger&.debug do
+          changes = overrides.keys.map { |k| "#{k}=#{overrides[k].inspect[0, 40]}" }.join(' ')
+          "[ProtocolResponse] with(#{changes})"
+        end
+
+        derived
+      end
+    end
+  end
+end

data/lib/bsv/network/protocols/arc.rb

@@ -11,9 +11,7 @@ module BSV
       # Extends Protocol with five endpoints and two escape hatches for broadcast
       # logic: EF format preference, rejection detection, and custom headers.
       #
-      # The protocol returns Result objects (never raises). The facade layer
-      # (Phase D) is responsible for translating Results to BroadcastResponse /
-      # BroadcastError as needed by consumer code.
+      # The protocol returns ProtocolResponse objects (never raises).
       #
       # == Example
       #
@@ -22,8 +20,8 @@ module BSV
       #     api_key: 'my-api-key'
       #   )
       #   result = arc.call(:broadcast, tx)
-      #   result.success? # => true
-      #   result.data[:txid] # => "abc123..."
+      #   result.http_success? # => true
+      #   result.data['txid'] # => "abc123..."
       #
       # @see https://docs.gorillapool.io/arc/api.html ARC API v1 documentation
       class ARC < Protocol
@@ -77,7 +75,7 @@ module BSV
         # @param callback_url [String, nil] per-call callback URL override
         # @param callback_token [String, nil] per-call callback token override
         # @param callback_batch [Boolean, nil] when truthy, sends X-CallbackBatch header
-        # @return [Result::Success, Result::Error]
+        # @return [ProtocolResponse]
         def call_broadcast(tx, wait_for: nil, skip_fee_validation: nil,
                            skip_script_validation: nil, skip_tx_validation: nil,
                            callback_url: nil, callback_token: nil, callback_batch: nil, **)
@@ -98,7 +96,7 @@ module BSV
           parse_single_broadcast_response(response)
         end
 
-        # Broadcast-many escape hatch: batch broadcast with per-item rejection detection.
+        # Broadcast-many escape hatch: batch broadcast with raw JSON array result.
         #
         # @param txs [Array<#to_ef_hex, #to_hex, String>]
         # @param wait_for [String, nil]
@@ -108,11 +106,11 @@ module BSV
         # @param callback_url [String, nil]
         # @param callback_token [String, nil]
         # @param callback_batch [Boolean, nil]
-        # @return [Result::Success, Result::Error]
+        # @return [ProtocolResponse]
         def call_broadcast_many(txs, wait_for: nil, skip_fee_validation: nil,
                                 skip_script_validation: nil, skip_tx_validation: nil,
                                 callback_url: nil, callback_token: nil, callback_batch: nil, **)
-          return Result::Success.new(data: []) if txs.empty?
+          return ProtocolResponse.new(nil, data: [], http_success: true) if txs.empty?
 
           body = JSON.generate(txs.map { |tx| { rawTx: resolve_tx_hex(tx) } })
 
@@ -188,159 +186,98 @@ module BSV
         end
 
         # Parse and validate a single-transaction ARC response.
+        #
+        # @return [ProtocolResponse]
         def parse_single_broadcast_response(response)
           code = response.code.to_i
           body = safe_parse_json(response.body)
 
           unless body.is_a?(Hash)
-            return Result::Error.new(
-              message: "HTTP #{code}",
-              retryable: retryable_code?(code),
-              metadata: { status_code: code }
-            )
+            return ProtocolResponse.new(response, http_success: false,
+                                                  error_message: "ARC returned #{body.class}, expected Hash")
           end
 
           unless (200..299).cover?(code)
-            return Result::Error.new(
-              message: body['detail'] || body['title'] || "HTTP #{code}",
-              retryable: retryable_code?(code),
-              metadata: { status_code: code, arc_status: body['txStatus'].to_s.upcase, txid: body['txid'] }
+            return ProtocolResponse.new(
+              response,
+              http_success: false,
+              error_message: body['detail'] || body['title'] || "HTTP #{code}"
             )
           end
 
           if rejected_status?(body)
-            return Result::Error.new(
-              message: body['detail'] || body['title'] || body['txStatus'],
-              retryable: false,
-              metadata: { status_code: code, arc_status: body['txStatus'].to_s.upcase, txid: body['txid'] }
+            return ProtocolResponse.new(
+              response,
+              http_success: false,
+              error_message: body['detail'] || body['title'] || body['txStatus'],
+              data: body
             )
           end
 
           unless body['txid']
-            return Result::Error.new(
-              message: 'ARC returned a malformed 2xx response',
-              retryable: false,
-              metadata: { status_code: code }
+            return ProtocolResponse.new(
+              response,
+              http_success: false,
+              error_message: body['detail'] || 'ARC returned a malformed 2xx response'
             )
           end
 
-          Result::Success.new(
-            data: arc_data_from(body),
-            metadata: { arc_status: body['txStatus'].to_s.upcase }
-          )
+          ProtocolResponse.new(response, data: body)
         end
 
         # Parse and validate a batch ARC response. HTTP-level errors return a
-        # single Result::Error; per-item rejections are embedded in the data array.
+        # single error ProtocolResponse; success data is a raw JSON array of hashes.
+        #
+        # @return [ProtocolResponse]
         def parse_batch_broadcast_response(response)
           code = response.code.to_i
           body = safe_parse_json(response.body)
 
           unless (200..299).cover?(code)
-            return Result::Error.new(
-              message: body.is_a?(Hash) ? (body['detail'] || body['title'] || "HTTP #{code}") : "HTTP #{code}",
-              retryable: retryable_code?(code),
-              metadata: { status_code: code }
+            return ProtocolResponse.new(
+              response,
+              http_success: false,
+              error_message: body.is_a?(Hash) ? (body['detail'] || body['title'] || "HTTP #{code}") : "HTTP #{code}"
             )
           end
 
           unless body.is_a?(Array)
-            return Result::Error.new(
-              message: 'ARC returned a malformed batch response',
-              retryable: false,
-              metadata: { status_code: code }
+            return ProtocolResponse.new(
+              response,
+              http_success: false,
+              error_message: 'ARC returned a malformed batch response'
             )
           end
 
-          items = body.map { |item| build_item_result(item) }
-          Result::Success.new(data: items, metadata: {})
+          ProtocolResponse.new(response, data: body)
         end
 
-        # Build a per-item result for a batch response entry.
-        def build_item_result(item)
-          unless item.is_a?(Hash)
-            return Result::Error.new(
-              message: 'malformed batch item',
-              retryable: false,
-              metadata: {}
-            )
-          end
-
-          if rejected_status?(item)
-            Result::Error.new(
-              message: item['detail'] || item['title'] || item['txStatus'],
-              retryable: false,
-              metadata: { status_code: 200, arc_status: item['txStatus'].to_s.upcase, txid: item['txid'] }
-            )
-          elsif !item['txid']
-            Result::Error.new(
-              message: 'ARC returned a malformed 2xx response',
-              retryable: false,
-              metadata: { status_code: 200 }
-            )
-          else
-            Result::Success.new(
-              data: arc_data_from(item),
-              metadata: { arc_status: item['txStatus'].to_s.upcase }
-            )
-          end
-        end
-
-        # Escape hatch for get_tx_status: returns a normalised data hash using the
-        # same field set as broadcast responses rather than the raw parsed JSON.
-        # Also checks for rejection status and missing txid (malformed 2xx).
+        # Escape hatch for get_tx_status: checks for rejection status and missing
+        # txid (malformed 2xx). Returns raw JSON data (string keys).
         #
         # @param txid [String] ARC API boundary: display-order hex transaction ID to query
-        # @return [Result::Success, Result::Error, Result::NotFound]
+        # @return [ProtocolResponse]
         def call_get_tx_status(txid, **)
           response = default_call(:get_tx_status, txid)
-          return response unless response.is_a?(Result::Success)
+          return response unless response.http_success?
 
           body = response.data
 
           if rejected_status?(body)
-            return Result::Error.new(
-              message: body['detail'] || body['title'] || body['txStatus'],
-              retryable: false,
-              metadata: { arc_status: body['txStatus'].to_s.upcase, txid: body['txid'], status_code: 200 }
+            return response.with(
+              http_success: false,
+              error_message: body['detail'] || body['title'] || body['txStatus']
             )
           end
 
           unless body['txid']
-            return Result::Error.new(
-              message: 'ARC returned a malformed 2xx response',
-              retryable: false,
-              metadata: { status_code: 200 }
+            return response.with(
+              http_success: false,
+              error_message: 'ARC returned a malformed 2xx response'
             )
           end
 
-          Result::Success.new(
-            data: arc_data_from(body),
-            metadata: { arc_status: body['txStatus'].to_s.upcase }
-          )
-        end
-
-        # Build the normalised ARC data hash from a parsed JSON response body.
-        # Includes all 8 fields that BroadcastResponse expects.
-        #
-        # @param body [Hash] parsed ARC JSON response
-        # @return [Hash]
-        def arc_data_from(body)
-          {
-            txid: body['txid'], # ARC API boundary: display-order hex from the ARC JSON response
-            tx_status: body['txStatus'],
-            message: body['title'],
-            extra_info: body['extraInfo'],
-            block_hash: body['blockHash'],
-            block_height: body['blockHeight'],
-            timestamp: body['timestamp'],
-            competing_txs: body['competingTxs']
-          }
-        end
-
-        # Determine whether a status code indicates a retryable failure.
-        def retryable_code?(code)
-          code == 429 || (500..599).cover?(code)
+          response
         end
 
         # Determine whether an ARC response body represents a rejected transaction.

data/lib/bsv/network/protocols/ordinals.rb

@@ -88,16 +88,16 @@ module BSV
         #
         # @param pos_txid [String, nil] transaction ID (positional form)
         # @param txid     [String, nil] transaction ID (keyword form)
-        # @return [Result::Success<String>, Result::Error, Result::NotFound]
+        # @return [ProtocolResponse]
         def call_get_tx(pos_txid = nil, txid: nil)
           resolved = pos_txid || txid
           raise ArgumentError, 'txid is required' if resolved.nil? || resolved.empty?
 
           result = default_call(:get_tx, resolved)
-          return result unless result.success?
-          return Result::Error.new(message: 'empty response body') if result.data.nil? || result.data.empty?
+          return result unless result.http_success?
+          return result.with(http_success: false, error_message: 'empty response body') if result.data.nil? || result.data.empty?
 
-          Result::Success.new(data: result.data.unpack1('H*'))
+          result.with(data: result.data.unpack1('H*'))
         end
 
         # Normalises the spend status response from the Ordinals API.
@@ -111,22 +111,22 @@ module BSV
         #
         # @param pos_outpoint [String, nil] outpoint in +"txid_vout"+ format (positional form)
         # @param outpoint     [String, nil] outpoint in +"txid_vout"+ format (keyword form)
-        # @return [Result::Success<Hash>, Result::Error, Result::NotFound]
+        # @return [ProtocolResponse]
         def call_get_spend(pos_outpoint = nil, outpoint: nil)
           resolved = pos_outpoint || outpoint
           raise ArgumentError, 'outpoint is required' if resolved.nil? || resolved.empty?
 
           result = default_call(:get_spend, resolved)
-          return result unless result.success?
+          return result unless result.http_success?
 
           spending_txid = JSON.parse(result.data).to_s.strip
           if spending_txid.empty?
-            Result::Success.new(data: { spent: false })
+            result.with(data: { spent: false })
           else
-            Result::Success.new(data: { spent: true, spending_txid: spending_txid })
+            result.with(data: { spent: true, spending_txid: spending_txid })
           end
-        rescue JSON::ParserError => e
-          Result::Error.new(message: "spend response parse error: #{e.message}")
+        rescue JSON::ParserError, TypeError => e
+          result.with(http_success: false, error_message: "spend response parse error: #{e.message}")
         end
       end
     end