bsv-sdk 0.15.0 → 0.17.0

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

@@ -49,8 +49,17 @@ module BSV
 
         def self.call(txid:, network: nil, server_context: nil)
           net_sym = Helpers.resolve_network_sym(network, server_context)
-          woc = BSV::Network::WhatsOnChain.new(network: net_sym)
-          tx = woc.fetch_transaction(txid)
+          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]
+            msg = fetch_result.message
+            msg = "#{msg} (HTTP #{code})" if code
+            return Helpers.error_response(msg)
+          end
+
+          tx = BSV::Transaction::Transaction.from_hex(fetch_result.data)
 
           result = {
             hex: tx.to_hex,
@@ -61,8 +70,6 @@ module BSV
             [::MCP::Content::Text.new(result.to_json)],
             structured_content: result
           )
-        rescue BSV::Network::ChainProviderError => e
-          Helpers.error_response("#{e.message} (HTTP #{e.status_code})")
         rescue ArgumentError => e
           Helpers.error_response(e.message)
         end

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

@@ -50,8 +50,22 @@ module BSV
 
         def self.call(address:, network: nil, server_context: nil)
           net_sym = Helpers.resolve_network_sym(network, server_context)
-          woc = BSV::Network::WhatsOnChain.new(network: net_sym)
-          utxos = woc.fetch_utxos(address)
+          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]
+            msg = utxo_result.message
+            msg = "#{msg} (HTTP #{code})" if code
+            return Helpers.error_response(msg)
+          end
+
+          utxos = utxo_result.data.map do |entry|
+            BSV::Network::UTXO.new(
+              tx_hash: entry[:tx_hash], tx_pos: entry[:tx_pos],
+              satoshis: entry[:satoshis], height: entry[:height]
+            )
+          end
 
           result = {
             address: address,
@@ -63,8 +77,6 @@ module BSV
             [::MCP::Content::Text.new(result.to_json)],
             structured_content: result
           )
-        rescue BSV::Network::ChainProviderError => e
-          Helpers.error_response("#{e.message} (HTTP #{e.status_code})")
         end
       end
     end

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

@@ -25,7 +25,7 @@ module BSV
         # @return [Hash]
         def self.transaction_to_h(tx)
           {
-            txid: tx.txid_hex,
+            txid: tx.txid_hex, # MCP tool boundary: display-order hex for human consumption
             version: tx.version,
             lock_time: tx.lock_time,
             inputs: tx.inputs.each_with_index.map { |inp, i| input_to_h(inp, i) },
@@ -38,7 +38,7 @@ module BSV
         def self.input_to_h(input, _index)
           unlock_script = input.unlocking_script
           {
-            prev_txid: input.prev_tx_id.reverse.unpack1('H*'),
+            prev_txid: input.dtxid_hex,
             vout: input.prev_tx_out_index,
             script_hex: unlock_script ? unlock_script.to_hex : '',
             script_asm: unlock_script ? unlock_script.to_asm : '',

data/lib/bsv/network/arc.rb

@@ -2,164 +2,24 @@
 
 module BSV
   module Network
-    # ARC broadcaster for submitting transactions to the BSV network.
-    #
-    # This facade preserves the legacy public API contract while delegating all
-    # HTTP logic to +Protocols::ARC+. It translates +Result+ objects returned by
-    # the protocol into +BroadcastResponse+ instances or raised +BroadcastError+
-    # exceptions as required by consumer code.
-    #
-    # Any object responding to #broadcast(tx) can serve as a broadcaster;
-    # this class implements that contract using the ARC API.
+    # @deprecated Use {BSV::Network::Protocols::ARC} directly instead.
+    #   The facade converted clean Result objects into exceptions — every
+    #   consumer immediately caught them and converted back to data.
+    #   Use the protocol layer, which returns Result objects natively.
     class ARC
-      # Returns an ARC instance pointed at the GorillaPool public ARC endpoint.
-      #
-      # @param testnet [Boolean] when true, uses the GorillaPool testnet endpoint
-      # @param api_key [String, nil] optional bearer token for Authorization
-      # @param http_client [#request, nil] injectable HTTP client for testing
-      # @param opts [Hash] ARC-specific options forwarded to the protocol
-      #   (e.g. +deployment_id:+, +callback_url:+, +callback_token:+)
-      # @return [ARC]
-      def self.default(testnet: false, api_key: nil, http_client: nil, **opts)
-        provider = Providers::GorillaPool.default(testnet: testnet)
-        arc_protocol = provider.protocol_for(:broadcast)
-        base_url = arc_protocol.base_url
-        new(
-          base_url,
-          api_key: api_key,
-          http_client: http_client,
-          **opts
-        )
-      end
-
-      # ARC response statuses that indicate the transaction was NOT accepted.
-      REJECTED_STATUSES = %w[
-        REJECTED
-        DOUBLE_SPEND_ATTEMPTED
-        INVALID
-        MALFORMED
-        MINED_IN_STALE_BLOCK
-      ].freeze
-
-      # @param url_or_protocol [String, Protocols::ARC] ARC base URL (without
-      #   trailing slash) or a pre-configured +Protocols::ARC+ instance. When a
-      #   URL string is supplied, the remaining keyword arguments are forwarded to
-      #   the underlying protocol constructor. When a protocol instance is supplied,
-      #   all keyword arguments are ignored.
-      # @param api_key [String, nil] optional bearer token for Authorization
-      # @param deployment_id [String, nil] optional deployment identifier for
-      #   the +XDeployment-ID+ header; defaults to a per-instance random value
-      # @param callback_url [String, nil] optional +X-CallbackUrl+ for ARC
-      #   status callbacks
-      # @param callback_token [String, nil] optional +X-CallbackToken+ for
-      #   ARC status callback authentication
-      # @param http_client [#request, nil] injectable HTTP client for testing
-      def initialize(url_or_protocol, api_key: nil, deployment_id: nil, callback_url: nil,
-                     callback_token: nil, http_client: nil)
-        @protocol =
-          if url_or_protocol.is_a?(String)
-            Protocols::ARC.new(
-              base_url: url_or_protocol,
-              api_key: api_key,
-              deployment_id: deployment_id,
-              callback_url: callback_url,
-              callback_token: callback_token,
-              http_client: http_client
-            )
-          else
-            url_or_protocol
-          end
-      end
-
-      # Submit a transaction to ARC.
-      #
-      # @param tx [Transaction] the transaction to broadcast
-      # @param wait_for [String, nil] ARC wait condition
-      # @param skip_fee_validation [Boolean, nil] when truthy, sends X-SkipFeeValidation header
-      # @param skip_script_validation [Boolean, nil] when truthy, sends X-SkipScriptValidation header
-      # @return [BroadcastResponse]
-      # @raise [BroadcastError] when ARC returns a non-2xx HTTP status or a
-      #   rejected/orphan +txStatus+
-      def broadcast(tx, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
-        result = @protocol.call(
-          :broadcast, tx,
-          wait_for: wait_for,
-          skip_fee_validation: skip_fee_validation,
-          skip_script_validation: skip_script_validation
-        )
-        result_to_response!(result)
-      end
-
-      # Submit multiple transactions to ARC in a single batch request.
-      #
-      # Returns a mixed array of {BroadcastResponse} and {BroadcastError} objects.
-      # Per-transaction rejections are returned as {BroadcastError} values rather
-      # than raised. Only HTTP-level errors raise a {BroadcastError} for the whole batch.
-      #
-      # @param txs [Array<Transaction>] transactions to broadcast
-      # @param wait_for [String, nil] ARC wait condition
-      # @param skip_fee_validation [Boolean, nil]
-      # @param skip_script_validation [Boolean, nil]
-      # @return [Array<BroadcastResponse, BroadcastError>]
-      # @raise [BroadcastError] when ARC returns a non-2xx HTTP status
-      def broadcast_many(txs, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
-        result = @protocol.call(
-          :broadcast_many, txs,
-          wait_for: wait_for,
-          skip_fee_validation: skip_fee_validation,
-          skip_script_validation: skip_script_validation
-        )
+      # Raised when deprecated facade classes are instantiated.
+      class DeprecationError < StandardError; end
 
-        case result
-        when Result::Success
-          result.data.map { |item| item_to_response_or_error(item) }
-        else
-          raise broadcast_error_from_result(result)
-        end
-      end
-
-      # Query the status of a previously submitted transaction.
-      #
-      # @param txid [String] transaction ID to query
-      # @return [BroadcastResponse]
-      # @raise [BroadcastError] on failure
-      def status(txid)
-        result = @protocol.call(:get_tx_status, txid)
-        result_to_response!(result)
-      end
-
-      private
-
-      # Translate a single-tx Result into a BroadcastResponse or raise BroadcastError.
-      def result_to_response!(result)
-        case result
-        when Result::Success
-          BroadcastResponse.new(result.data)
-        else
-          raise broadcast_error_from_result(result)
-        end
-      end
+      MESSAGE = 'BSV::Network::ARC is deprecated. ' \
+                'Use BSV::Network::Protocols::ARC directly — it returns Result objects ' \
+                'instead of raising exceptions. See BSV::Network::Protocols::ARC for usage.'
 
-      # Translate a per-item batch Result into a BroadcastResponse or BroadcastError
-      # (returned, not raised).
-      def item_to_response_or_error(item)
-        case item
-        when Result::Success
-          BroadcastResponse.new(item.data)
-        else
-          broadcast_error_from_result(item)
-        end
+      def self.default(**)
+        raise DeprecationError, MESSAGE
       end
 
-      # Build a BroadcastError from a Result::Error or Result::NotFound.
-      def broadcast_error_from_result(result)
-        meta = result.metadata || {}
-        BroadcastError.new(
-          result.message,
-          status_code: meta[:status_code],
-          txid: meta[:txid],
-          arc_status: meta[:arc_status]
-        )
+      def initialize(*)
+        raise DeprecationError, MESSAGE
       end
     end
   end

data/lib/bsv/network/broadcast_error.rb

@@ -3,6 +3,7 @@
 module BSV
   module Network
     class BroadcastError < StandardError
+      # ARC API boundary: display-order hex txid as returned by the ARC error response.
       attr_reader :status_code, :txid, :arc_status
 
       def initialize(message, status_code: nil, txid: nil, arc_status: nil)

data/lib/bsv/network/broadcast_response.rb

@@ -3,6 +3,7 @@
 module BSV
   module Network
     class BroadcastResponse
+      # ARC API boundary: display-order hex txid as returned by the ARC broadcast endpoint.
       attr_reader :txid, :tx_status, :message, :extra_info, :block_hash, :block_height, :timestamp, :competing_txs
 
       def initialize(attrs = {})

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

@@ -138,7 +138,8 @@ module BSV
         # lacks source_satoshis / source_locking_script.
         def ef_hex_with_fallback(tx)
           tx.to_ef_hex
-        rescue ArgumentError
+        rescue ArgumentError => e
+          BSV.logger&.debug { "[ARC] EF serialisation failed: #{e.message} — falling back to raw hex" }
           tx.to_hex
         end
 
@@ -269,7 +270,7 @@ module BSV
         # same field set as broadcast responses rather than the raw parsed JSON.
         # Also checks for rejection status and missing txid (malformed 2xx).
         #
-        # @param txid [String] the transaction ID to query
+        # @param txid [String] ARC API boundary: display-order hex transaction ID to query
         # @return [Result::Success, Result::Error, Result::NotFound]
         def call_get_tx_status(txid, **)
           response = default_call(:get_tx_status, txid)
@@ -306,7 +307,7 @@ module BSV
         # @return [Hash]
         def arc_data_from(body)
           {
-            txid: body['txid'],
+            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'],

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

@@ -53,6 +53,7 @@ module BSV
           code = response.code.to_i
           body = parse_json_body(response.body)
 
+          # TAAL API boundary: display-order hex txid from the TAAL broadcast response
           return Result::Success.new(data: { txid: body['txid'] }) if already_known?(body) && body['txid']
 
           retryable = code == 429 || (500..599).cover?(code)

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

@@ -175,7 +175,7 @@ module BSV
         # The +script_hash:+ keyword is accepted for future fallback support
         # but not used in this implementation.
         #
-        # @param txid        [String]  transaction ID
+        # @param txid        [String]  WoC API boundary: display-order hex transaction ID
         # @param vout        [Integer] output index
         # @param script_hash [String, nil] ignored
         # @return [Result::Success<Boolean>, Result::Error, Result::NotFound]
@@ -242,6 +242,7 @@ module BSV
           return result unless result.success?
 
           # WoC returns plain-text txid — result.data is the raw body string
+          # WoC API boundary: display-order hex txid returned as plain text
           Result::Success.new(data: { txid: result.data.to_s.strip })
         end
 

data/lib/bsv/network/whats_on_chain.rb

@@ -2,118 +2,24 @@
 
 module BSV
   module Network
-    # WhatsOnChain chain data provider for reading transactions and UTXOs
-    # from the BSV network.
-    #
-    # Any object responding to #fetch_utxos(address),
-    # #fetch_transaction(txid), #current_height,
-    # #get_block_header(height), and optionally
-    # #valid_root_for_height?(root_hex, height) can serve as a chain
-    # data source;
-    # this class implements that contract by delegating to
-    # Protocols::WoCREST.
-    #
-    # The HTTP client is injectable for testability. It must respond to
-    # #request(uri, request) and return an object with #code and #body.
+    # @deprecated Use {BSV::Network::Protocols::WoCREST} directly instead.
+    #   The facade converted clean Result objects into exceptions — every
+    #   consumer immediately caught them and converted back to data.
+    #   Use the protocol layer, which returns Result objects natively.
     class WhatsOnChain
-      # Returns a WhatsOnChain instance using the provider default.
-      #
-      # @param testnet [Boolean] when true, uses the testnet endpoint
-      # @param opts [Hash] forwarded to the underlying protocol (e.g. +api_key:+, +http_client:+)
-      # @return [WhatsOnChain]
-      def self.default(testnet: false, **opts)
-        provider = Providers::WhatsOnChain.default(testnet: testnet, **opts)
-        new(protocol: provider.protocol_for(:get_tx))
-      end
-
-      # @param network [Symbol] :main, :mainnet, :test, :testnet, :stn (legacy compat)
-      # @param http_client [#request, nil] injectable HTTP client
-      # @param protocol [BSV::Network::Protocols::WoCREST, nil] pre-configured protocol
-      def initialize(network: :mainnet, http_client: nil, protocol: nil)
-        if protocol
-          @protocol = protocol
-        else
-          provider = Providers::WhatsOnChain.default(network: network, http_client: http_client)
-          @protocol = provider.protocol_for(:get_tx)
-        end
-      end
-
-      # Fetch unspent transaction outputs for an address.
-      # @param address [String] BSV address
-      # @return [Array<UTXO>]
-      def fetch_utxos(address)
-        result = @protocol.call(:get_utxos_all, address)
-        raise_on_error(result)
-
-        result.data.map do |entry|
-          UTXO.new(
-            tx_hash: entry[:tx_hash],
-            tx_pos: entry[:tx_pos],
-            satoshis: entry[:satoshis],
-            height: entry[:height]
-          )
-        end
-      end
-
-      # Fetch a raw transaction by its txid and parse it.
-      # @param txid [String] transaction ID (hex)
-      # @return [BSV::Transaction::Transaction]
-      def fetch_transaction(txid)
-        result = @protocol.call(:get_tx, txid)
-        raise_on_error(result)
-
-        BSV::Transaction::Transaction.from_hex(result.data)
-      end
+      # Raised when deprecated facade classes are instantiated.
+      class DeprecationError < StandardError; end
 
-      # Return the current blockchain height.
-      # @return [Integer]
-      # @raise [BSV::Network::ChainProviderError] on network or API error
-      def current_height
-        result = @protocol.call(:current_height)
-        raise_on_error(result)
+      MESSAGE = 'BSV::Network::WhatsOnChain is deprecated. ' \
+                'Use BSV::Network::Protocols::WoCREST directly — it returns Result objects ' \
+                'instead of raising exceptions. See BSV::Network::Protocols::WoCREST for usage.'
 
-        result.data
+      def self.default(**)
+        raise DeprecationError, MESSAGE
       end
 
-      # Fetch the block header for a given height.
-      # @param height [Integer] block height
-      # @return [Hash] parsed block header JSON
-      # @raise [BSV::Network::ChainProviderError] on network or API error
-      def get_block_header(height)
-        result = @protocol.call(:get_block_header, height)
-        raise_on_error(result)
-
-        result.data
-      end
-
-      # Verify that a merkle root is valid for the given block height.
-      # Returns +false+ when the block is not found (404); raises on other errors.
-      # @param root [String] expected merkle root as hex
-      # @param height [Integer] block height
-      # @return [Boolean]
-      # @raise [BSV::Network::ChainProviderError] on network or non-404 API error
-      def valid_root_for_height?(root, height)
-        result = @protocol.call(:valid_root, root, height)
-        return false if result.not_found?
-
-        raise_on_error(result)
-
-        result.data == true
-      end
-
-      private
-
-      # Translates a non-success Protocol result into a raised ChainProviderError.
-      #
-      # @param result [Result::Error, Result::NotFound]
-      # @raise [ChainProviderError]
-      def raise_on_error(result)
-        return if result.success?
-
-        raise ChainProviderError.new(
-          result.message || 'Request failed',
-          status_code: result.metadata[:status_code]
-        )
+      def initialize(*)
+        raise DeprecationError, MESSAGE
       end
     end
   end

data/lib/bsv/overlay/admin_token_template.rb

@@ -90,7 +90,7 @@ module BSV
 
           sig_args = { hash_to_directly_sign: hash_bytes, protocol_id: @protocol_id, key_id: '1', counterparty: 'self' }
           sig_args[:originator] = @originator if @originator
-          result = @wallet.create_signature(sig_args)
+          result = @wallet.create_signature(**sig_args)
 
           sig_bytes = result[:signature].pack('C*')
           sig_with_hashtype = sig_bytes + [sighash_type].pack('C')
@@ -171,14 +171,14 @@ module BSV
         # Fetch the wallet's identity key (compressed public key hex)
         id_args = { identity_key: true }
         id_args[:originator] = @originator if @originator
-        identity_result = @wallet.get_public_key(id_args)
+        identity_result = @wallet.get_public_key(**id_args)
         identity_key_hex = identity_result[:public_key]
         identity_key_bytes = [identity_key_hex].pack('H*')
 
         # Derive the locking public key for this protocol
         lock_args = { protocol_id: protocol_id, key_id: '1', counterparty: 'self' }
         lock_args[:originator] = @originator if @originator
-        locking_result = @wallet.get_public_key(lock_args)
+        locking_result = @wallet.get_public_key(**lock_args)
         locking_pubkey_hex = locking_result[:public_key]
         locking_pubkey_bytes = [locking_pubkey_hex].pack('H*')
 
@@ -192,7 +192,7 @@ module BSV
         data_to_sign = (field_protocol + field_identity + field_domain + field_topic).unpack('C*')
         sig_args = { data: data_to_sign, protocol_id: protocol_id, key_id: '1', counterparty: 'self' }
         sig_args[:originator] = @originator if @originator
-        sig_result = @wallet.create_signature(sig_args)
+        sig_result = @wallet.create_signature(**sig_args)
         field_sig = sig_result[:signature].pack('C*')
 
         fields = [field_protocol, field_identity, field_domain, field_topic, field_sig]

data/lib/bsv/overlay/lookup_resolver.rb

@@ -334,6 +334,7 @@ module BSV
         beef_data    = output['beef'] || output[:beef]
         output_index = (output['outputIndex'] || output[:output_index] || 0).to_i
 
+        # Overlay API boundary: outpoint key uses display-order txid bytes (via Transaction#txid)
         txid =
           begin
             beef = parse_beef(beef_data)

data/lib/bsv/overlay/topic_broadcaster.rb

@@ -110,7 +110,7 @@ module BSV
 
         OverlayBroadcastResult.new(
           status: 'success',
-          txid: tx.txid_hex,
+          txid: tx.txid_hex, # Overlay API boundary: display-order hex txid for the broadcast result
           message: "Sent to #{successful.size} Overlay Service host(s)."
         )
       end

data/lib/bsv/overlay/types.rb

@@ -82,6 +82,7 @@ module BSV
       # @return [String] result status ('success' or 'error')
       attr_reader :status
 
+      # Overlay API boundary: display-order hex txid echoed from the broadcast response.
       # @return [String, nil] transaction identifier (present on success)
       attr_reader :txid
 

data/lib/bsv/primitives/hex.rb

@@ -72,6 +72,70 @@ module BSV
       def self.encode(bytes)
         bytes.unpack1('H*')
       end
+
+      # Validate that +value+ is a 32-byte wire-order transaction ID.
+      #
+      # @param value [String] expected 32-byte binary string
+      # @param name [String] label for the error message (e.g. +'prev_wtxid'+)
+      # @return [String] the input value (pass-through for chaining)
+      # @raise [ArgumentError] if +value+ is not a 32-byte binary string
+      def self.validate_wtxid!(value, name: 'wtxid')
+        unless value.is_a?(String) && value.bytesize == 32
+          hint = if value.is_a?(String) && value.bytesize == 64 && value.match?(HEX_RE)
+                   ' (looks like a hex txid — use wtxid_from_hex to convert)'
+                 else
+                   ''
+                 end
+          size = value.is_a?(String) ? "#{value.bytesize}-byte string" : value.class.to_s
+          raise ArgumentError,
+                "expected 32-byte wire-order wtxid for #{name}, got #{size}#{hint}"
+        end
+        value
+      end
+
+      # Validate that +value+ is a 32-byte binary hash.
+      #
+      # General-purpose validator for any 32-byte hash (merkle nodes, roots,
+      # etc.) — not specific to transaction IDs. For txid-specific validation
+      # use {.validate_wtxid!} or {.validate_dtxid_hex!} instead.
+      #
+      # @param value [String] expected 32-byte binary string
+      # @param name [String] label for the error message
+      # @return [String] the input value (pass-through for chaining)
+      # @raise [ArgumentError] if +value+ is not a 32-byte binary string
+      def self.validate_hash32!(value, name: 'hash')
+        unless value.is_a?(String) && value.bytesize == 32
+          hint = if value.is_a?(String) && value.bytesize == 64 && value.match?(HEX_RE)
+                   ' (looks like hex — decode it first)'
+                 else
+                   ''
+                 end
+          size = value.is_a?(String) ? "#{value.bytesize}-byte string" : value.class.to_s
+          raise ArgumentError,
+                "expected 32-byte hash for #{name}, got #{size}#{hint}"
+        end
+        value
+      end
+
+      # Validate that +value+ is a 64-character display-order hex transaction ID.
+      #
+      # @param value [String] expected 64-char hex string
+      # @param name [String] label for the error message (e.g. +'dtxid_hex'+)
+      # @return [String] the input value (pass-through for chaining)
+      # @raise [ArgumentError] if +value+ is not a 64-char hex string
+      def self.validate_dtxid_hex!(value, name: 'dtxid_hex')
+        unless value.is_a?(String) && value.length == 64 && value.match?(HEX_RE)
+          hint = if value.is_a?(String) && value.bytesize == 32 && !value.match?(HEX_RE)
+                   ' (looks like binary bytes — use dtxid_hex or unpack to convert)'
+                 else
+                   ''
+                 end
+          size = value.is_a?(String) ? "#{value.length}-char string" : value.class.to_s
+          raise ArgumentError,
+                "expected 64-char display-order hex for #{name}, got #{size}#{hint}"
+        end
+        value
+      end
     end
   end
 end