bsv-sdk 0.15.0 → 0.16.0

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/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/registry/client.rb

@@ -66,18 +66,16 @@ module BSV
 
         basket_name = basket_name_for(definition_type)
         create_result = @wallet.create_action(
-          {
-            description: "Register a new #{definition_type} definition",
-            outputs: [
-              {
-                satoshis: Constants::TOKEN_AMOUNT,
-                locking_script: locking_script.to_hex,
-                output_description: "New #{definition_type} registration token",
-                basket: basket_name
-              }
-            ],
-            options: { randomize_outputs: false }
-          },
+          description: "Register a new #{definition_type} definition",
+          outputs: [
+            {
+              satoshis: Constants::TOKEN_AMOUNT,
+              locking_script: locking_script.to_hex,
+              output_description: "New #{definition_type} registration token",
+              basket: basket_name
+            }
+          ],
+          options: { randomize_outputs: false },
           originator: @originator
         )
 
@@ -122,7 +120,7 @@ module BSV
       def list_own_registry_entries(definition_type)
         basket_name = basket_name_for(definition_type)
         list_result = @wallet.list_outputs(
-          { basket: basket_name, include: 'entire transactions' },
+          basket: basket_name, include: 'entire transactions',
           originator: @originator
         )
 
@@ -160,18 +158,16 @@ module BSV
         outpoint = "#{registered_definition.txid}.#{registered_definition.output_index}"
 
         create_result = @wallet.create_action(
-          {
-            description: "Revoke #{definition_type} definition: #{item_identifier(registered_definition)}",
-            input_beef: registered_definition.beef,
-            inputs: [
-              {
-                outpoint: outpoint,
-                unlocking_script_length: BSV::Script::PushDropTemplate::Unlocker::ESTIMATED_LENGTH,
-                input_description: "Revoking #{definition_type} token"
-              }
-            ],
-            options: { randomize_outputs: false, no_send: true }
-          },
+          description: "Revoke #{definition_type} definition: #{item_identifier(registered_definition)}",
+          input_beef: registered_definition.beef,
+          inputs: [
+            {
+              outpoint: outpoint,
+              unlocking_script_length: BSV::Script::PushDropTemplate::Unlocker::ESTIMATED_LENGTH,
+              input_description: "Revoking #{definition_type} token"
+            }
+          ],
+          options: { randomize_outputs: false, no_send: true },
           originator: @originator
         )
 
@@ -210,7 +206,7 @@ module BSV
       def identity_key
         return @identity_key if defined?(@identity_key)
 
-        result = @wallet.get_public_key({ identity_key: true }, originator: @originator)
+        result = @wallet.get_public_key(identity_key: true, originator: @originator)
         @identity_key = result[:public_key] || result['public_key'] || result['publicKey'] || result[:publicKey]
       end
 
@@ -561,7 +557,7 @@ module BSV
       #
       # @return [Symbol] :mainnet or :testnet
       def wallet_network
-        result  = @wallet.get_network({}, originator: @originator)
+        result  = @wallet.get_network(originator: @originator)
         net_str = result[:network] || result['network'] || 'mainnet'
         net_str.to_sym
       end

data/lib/bsv/script/push_drop_template.rb

@@ -108,14 +108,14 @@ module BSV
             counterparty: @counterparty
           }
           orig_kw = @originator ? { originator: @originator } : {}
-          result = @wallet.create_signature(sig_args, **orig_kw)
+          result = @wallet.create_signature(**sig_args, **orig_kw)
 
           sig_bytes = result[:signature].pack('C*')
           sig_with_hashtype = sig_bytes + [sighash_type].pack('C')
 
           # Fetch the derived public key so the P2PKH unlock can include it
           pub_args = { protocol_id: @protocol_id, key_id: @key_id, counterparty: @counterparty }
-          pub_result = @wallet.get_public_key(pub_args, **orig_kw)
+          pub_result = @wallet.get_public_key(**pub_args, **orig_kw)
           pubkey_bytes = [pub_result[:public_key]].pack('H*')
 
           BSV::Script::Script.pushdrop_unlock(
@@ -176,7 +176,7 @@ module BSV
                        else
                          pub_args = { protocol_id: protocol_id, key_id: key_id, counterparty: counterparty }
                          orig_kw = @originator ? { originator: @originator } : {}
-                         pub_result = @wallet.get_public_key(pub_args, **orig_kw)
+                         pub_result = @wallet.get_public_key(**pub_args, **orig_kw)
                          [pub_result[:public_key]].pack('H*')
                        end
 
@@ -187,7 +187,7 @@ module BSV
           data_to_sign = all_fields.reduce(''.b) { |acc, f| acc + f }.unpack('C*')
           sig_args = { data: data_to_sign, protocol_id: protocol_id, key_id: key_id, counterparty: counterparty }
           orig_kw = @originator ? { originator: @originator } : {}
-          sig_result = @wallet.create_signature(sig_args, **orig_kw)
+          sig_result = @wallet.create_signature(**sig_args, **orig_kw)
           all_fields << sig_result[:signature].pack('C*')
         end
 

data/lib/bsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BSV
-  VERSION = '0.15.0'
+  VERSION = '0.16.0'
 end

data/lib/bsv/wallet/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Base error for all wallet operations. Carries a machine-readable code
+    # per the BRC-100 error structure.
+    class Error < StandardError
+      attr_reader :code
+
+      def initialize(message, code = 1)
+        @code = code
+        super(message)
+      end
+    end
+
+    # Raised when a required parameter is missing or invalid.
+    class InvalidParameterError < Error
+      attr_reader :parameter
+
+      def initialize(parameter, must_be = 'valid')
+        @parameter = parameter
+        super("the #{parameter} parameter must be #{must_be}", 6)
+      end
+    end
+
+    # Raised when an HMAC fails to verify.
+    class InvalidHmacError < Error
+      def initialize(message = 'the provided HMAC is invalid')
+        super(message, 3)
+      end
+    end
+
+    # Raised when a signature fails to verify.
+    class InvalidSignatureError < Error
+      def initialize(message = 'the provided signature is invalid')
+        super(message, 4)
+      end
+    end
+
+    # Raised when an operation is not supported by this wallet implementation.
+    class UnsupportedActionError < Error
+      def initialize(method_name = 'this method')
+        super("#{method_name} is not supported by this wallet implementation", 2)
+      end
+    end
+  end
+end