bsv-sdk 0.12.1 → 0.14.0

data/lib/bsv/transaction/chain_trackers/whats_on_chain.rb

@@ -1,39 +1,45 @@
 # frozen_string_literal: true
 
 require 'net/http'
-require 'json'
-require 'uri'
 
 module BSV
   module Transaction
     module ChainTrackers
       # Chain tracker that verifies merkle roots using the WhatsOnChain API.
       #
-      # Queries the WoC block header endpoint to retrieve the merkle root for a
-      # given block height and compares it with the provided root.
+      # Delegates all HTTP communication to {BSV::Network::Protocols::WoCREST}.
+      # The constructor signature and {ChainTracker} contract are preserved.
+      #
+      # Note: the WoC API key is sent as a raw +Authorization+ header value
+      # (not Bearer-prefixed) to match the existing WoC API convention.
       #
       # @example
       #   tracker = BSV::Transaction::ChainTrackers::WhatsOnChain.new
       #   tracker.valid_root_for_height?('abcd...', 800_000)
       class WhatsOnChain < ChainTracker
-        BASE_URL = 'https://api.whatsonchain.com'
-
-        NETWORKS = {
-          main: 'main',
-          mainnet: 'main',
-          test: 'test',
-          testnet: 'test',
-          stn: 'stn'
-        }.freeze
+        # Returns a WhatsOnChain chain tracker 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 = BSV::Network::Providers::WhatsOnChain.default(testnet: testnet, **opts)
+          new(protocol: provider.protocol_for(:valid_root))
+        end
 
-        # @param network [Symbol] :main, :mainnet, :test, :testnet, or :stn
+        # @param network [Symbol] :main, :mainnet, :test, :testnet (legacy compat)
         # @param api_key [String, nil] optional WoC API key
         # @param http_client [#request, nil] injectable HTTP client for testing
-        def initialize(network: :main, api_key: nil, http_client: nil)
+        # @param protocol [BSV::Network::Protocols::WoCREST, nil] pre-configured protocol
+        def initialize(network: :main, api_key: nil, http_client: nil, protocol: nil)
           super()
-          @network = NETWORKS.fetch(network) { raise ArgumentError, "unknown network: #{network}" }
-          @api_key = api_key
-          @http_client = http_client
+          if protocol
+            @protocol = protocol
+          else
+            wrapped_client = api_key ? RawAuthClient.new(api_key, http_client) : http_client
+            provider = BSV::Network::Providers::WhatsOnChain.default(network: network, http_client: wrapped_client)
+            @protocol = provider.protocol_for(:valid_root)
+          end
         end
 
         # Verify that a merkle root is valid for the given block height.
@@ -41,51 +47,52 @@ module BSV
         # @param root [String] merkle root as a hex string
         # @param height [Integer] block height
         # @return [Boolean]
+        # @raise [BSV::Network::ChainProviderError] on network or API error
         def valid_root_for_height?(root, height)
-          response = get("/v1/bsv/#{@network}/block/#{height}/header")
-          return false if response.nil?
+          result = @protocol.call(:valid_root, root, height)
+          return false if result.not_found?
+
+          if result.error?
+            raise BSV::Network::ChainProviderError.new(
+              result.message.to_s,
+              status_code: result.metadata[:status_code]
+            )
+          end
 
-          data = JSON.parse(response.body)
-          data['merkleroot'].downcase == root.downcase
+          result.data == true
         end
 
         # Return the current blockchain height.
         #
         # @return [Integer]
+        # @raise [BSV::Network::ChainProviderError] on network or API error
         def current_height
-          response = get("/v1/bsv/#{@network}/chain/info", not_found_returns_nil: false)
-          data = JSON.parse(response.body)
-          data['blocks']
-        end
-
-        private
-
-        # @param path [String] API path
-        # @param not_found_returns_nil [Boolean] if true, return nil on 404 instead of raising
-        # @return [Net::HTTPResponse, nil]
-        def get(path, not_found_returns_nil: true)
-          uri = URI("#{BASE_URL}#{path}")
-          request = Net::HTTP::Get.new(uri)
-          request['Authorization'] = @api_key if @api_key
-
-          response = execute(uri, request)
-          code = response.code.to_i
-
-          return nil if not_found_returns_nil && code == 404
-          return response if (200..299).cover?(code)
+          result = @protocol.call(:current_height)
+          return result.data if result.success?
 
           raise BSV::Network::ChainProviderError.new(
-            response.body || "HTTP #{code}",
-            status_code: code
+            result.message.to_s,
+            status_code: result.metadata[:status_code]
           )
         end
 
-        def execute(uri, request)
-          if @http_client
-            @http_client.request(uri, request)
-          else
-            Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
-              http.request(request)
+        # Wraps an injectable HTTP client to set a raw Authorization header value
+        # before forwarding the request. This preserves the WoC convention of
+        # sending the API key without a Bearer prefix.
+        class RawAuthClient
+          def initialize(api_key, inner_client)
+            @api_key = api_key
+            @inner_client = inner_client
+          end
+
+          def request(uri, req)
+            req['Authorization'] = @api_key
+            if @inner_client
+              @inner_client.request(uri, req)
+            else
+              Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+                http.request(req)
+              end
             end
           end
         end

data/lib/bsv/transaction/chain_trackers.rb

@@ -10,11 +10,10 @@ module BSV
       # Return a default chain tracker backed by the Arcade/GorillaPool Chaintracks API.
       #
       # @param testnet [Boolean] use the testnet endpoint when true
-      # @param api_key [String, nil] optional Bearer API key
+      # @param opts [Hash] forwarded to the underlying tracker (e.g. +api_key:+)
       # @return [Chaintracks]
-      def self.default(testnet: false, api_key: nil)
-        url = testnet ? Chaintracks::TESTNET_URL : Chaintracks::MAINNET_URL
-        Chaintracks.new(url: url, api_key: api_key)
+      def self.default(testnet: false, **opts)
+        Chaintracks.default(testnet: testnet, **opts)
       end
     end
   end

data/lib/bsv/transaction/fee_models/live_policy.rb

@@ -32,7 +32,6 @@ module BSV
         # @return [Integer] cache TTL in seconds
         attr_reader :cache_ttl
 
-        DEFAULT_ARC_URL = BSV::MAINNET_URL
         DEFAULT_FALLBACK_RATE = 100
 
         # Returns a LivePolicy with sensible defaults (GorillaPool ARC,
@@ -41,7 +40,9 @@ module BSV
         # @param api_key [String, nil] optional ARC API key
         # @return [LivePolicy]
         def self.default(api_key: nil)
-          new(arc_url: DEFAULT_ARC_URL, fallback_rate: DEFAULT_FALLBACK_RATE, api_key: api_key)
+          provider = BSV::Network::Providers::GorillaPool.mainnet
+          arc_protocol = provider.protocol_for(:broadcast)
+          new(arc_url: arc_protocol.base_url, fallback_rate: DEFAULT_FALLBACK_RATE, api_key: api_key)
         end
 
         # @param arc_url [String] ARC base URL (e.g. 'https://arcade.gorillapool.io')

data/lib/bsv/transaction/transaction.rb

@@ -550,12 +550,30 @@ module BSV
       #    provided fee model.
       # 4. Checks that total outputs do not exceed total inputs.
       #
+      # == Semantic Divergences from Reference SDKs
+      #
+      # This implementation raises +VerificationError+ for all failure modes.
+      # The TypeScript and Python SDKs return +false+ for script failures and
+      # output overflow. The Go SDK propagates errors (not booleans) for script
+      # failures, aligning with the Ruby approach.
+      #
+      # Rationale: raising provides structured error information (+#code+,
+      # +#message+, +#cause+) that a boolean cannot convey. Consumers can
+      # rescue +VerificationError+ and inspect +#code+ for specifics.
+      #
+      # Divergence summary:
+      # - +:output_overflow+ — Ruby raises; TS/Python return +false+; Go omits the check
+      # - +:script_failure+ — Ruby raises; TS/Python return +false+; Go also propagates errors
+      # - +:missing_source+ — Ruby raises; consistent with TS/Go/Python (all raise/error)
+      #
       # @param chain_tracker [ChainTracker] chain tracker for merkle root validation
       # @param fee_model [FeeModel, nil] optional fee model to validate the root transaction's fee
       # @return [true] on successful verification
-      # @raise [ArgumentError] if a source transaction or unlocking script is missing
-      # @raise [BSV::Script::ScriptError] if script execution fails
-      # @raise [VerificationError] for merkle path failures, fee validation, or output overflow
+      # @raise [VerificationError] with code +:invalid_merkle_proof+ if a merkle proof is invalid
+      # @raise [VerificationError] with code +:insufficient_fee+ if the fee is below the model's threshold
+      # @raise [VerificationError] with code +:output_overflow+ if outputs exceed inputs
+      # @raise [VerificationError] with code +:script_failure+ if script execution fails
+      # @raise [VerificationError] with code +:missing_source+ if an input is missing required source data
       def verify(chain_tracker:, fee_model: nil)
         verified = {}
         queue = [self]
@@ -581,8 +599,26 @@ module BSV
 
           # Verify each input
           tx.inputs.each_with_index do |input, index|
+            # Populate source data from source_transaction when not already set.
+            # Matches the TS SDK pattern: sourceOutput is read directly from
+            # source_transaction.outputs[sourceOutputIndex] during verify.
+            if input.source_transaction
+              source_output = input.source_transaction.outputs[input.prev_tx_out_index]
+              if source_output
+                input.source_locking_script ||= source_output.locking_script
+                input.source_satoshis ||= source_output.satoshis
+              end
+            end
+
             verify_input_requirements(tx, input, index)
-            tx.verify_input(index)
+            begin
+              tx.verify_input(index)
+            rescue BSV::Script::ScriptError => e
+              raise VerificationError.new(
+                :script_failure,
+                "script verification failed for input #{index} of transaction #{tx.txid_hex}: #{e.message}"
+              )
+            end
 
             # Enqueue source transaction for verification if not yet verified
             source_tx = input.source_transaction
@@ -742,9 +778,18 @@ module BSV
 
       def verify_input_requirements(tx, input, index)
         tx_id = tx.txid_hex
-        raise ArgumentError, "input #{index} of transaction #{tx_id} has no unlocking script" if input.unlocking_script.nil?
-        raise ArgumentError, "input #{index} of transaction #{tx_id} has no source locking script" if input.source_locking_script.nil?
-        raise ArgumentError, "input #{index} of transaction #{tx_id} has no source satoshis" if input.source_satoshis.nil?
+        if input.unlocking_script.nil?
+          raise VerificationError.new(:missing_source,
+                                      "input #{index} of transaction #{tx_id} has no unlocking script")
+        end
+        if input.source_locking_script.nil?
+          raise VerificationError.new(:missing_source,
+                                      "input #{index} of transaction #{tx_id} has no source locking script")
+        end
+        return unless input.source_satoshis.nil?
+
+        raise VerificationError.new(:missing_source,
+                                    "input #{index} of transaction #{tx_id} has no source satoshis")
       end
 
       def verify_fee(fee_model)

data/lib/bsv/transaction/verification_error.rb

@@ -7,6 +7,15 @@ module BSV
     # Carries a machine-readable code alongside a human-readable message,
     # matching the typed error pattern used by the Go SDK
     # (ErrInvalidMerklePath, ErrFeeTooLow, ErrScriptVerificationFailed).
+    #
+    # == Error Codes
+    #
+    # - +:invalid_merkle_proof+ — merkle path verification failed against the chain tracker
+    # - +:insufficient_fee+ — transaction fee is below the fee model's requirement
+    # - +:output_overflow+ — total outputs exceed total inputs
+    # - +:script_failure+ — script interpreter rejected an input (original +ScriptError+ in +#cause+)
+    # - +:missing_source+ — required input data (unlocking script, source locking script,
+    #   or source satoshis) is absent
     class VerificationError < StandardError
       # @return [Symbol] the error code
       attr_reader :code
@@ -14,6 +23,8 @@ module BSV
       INVALID_MERKLE_PROOF = :invalid_merkle_proof
       INSUFFICIENT_FEE = :insufficient_fee
       OUTPUT_OVERFLOW = :output_overflow
+      SCRIPT_FAILURE = :script_failure
+      MISSING_SOURCE = :missing_source
 
       # @param code [Symbol] error code
       # @param message [String] human-readable description

data/lib/bsv/version.rb

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

data/lib/bsv-sdk.rb

@@ -3,19 +3,15 @@
 require_relative 'bsv/version'
 
 module BSV
-  MAINNET_URL = ENV['BSV_ARC_MAINNET_URL'] || 'https://arcade.gorillapool.io'
-  TESTNET_URL = ENV['BSV_ARC_TESTNET_URL'] || 'https://testnet.arcade.gorillapool.io'
-
   autoload :Primitives,  'bsv/primitives'
   autoload :Script,      'bsv/script'
   autoload :Transaction, 'bsv/transaction'
   autoload :Network,     'bsv/network'
-  autoload :Wallet,      'bsv/wallet'
   autoload :Auth,        'bsv/auth'
   autoload :Overlay,     'bsv/overlay'
   autoload :Identity,    'bsv/identity'
   autoload :Registry,    'bsv/registry'
   autoload :MCP,         'bsv/mcp'
-  autoload :Messages,    'bsv/messages'
+
   autoload :WireFormat,  'bsv/wire_format'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.14.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -67,12 +67,24 @@ files:
 - lib/bsv/mcp/tools/fetch_utxos.rb
 - lib/bsv/mcp/tools/generate_key.rb
 - lib/bsv/mcp/tools/helpers.rb
-- lib/bsv/messages.rb
 - lib/bsv/network.rb
 - lib/bsv/network/arc.rb
 - lib/bsv/network/broadcast_error.rb
 - lib/bsv/network/broadcast_response.rb
 - lib/bsv/network/chain_provider_error.rb
+- lib/bsv/network/protocol.rb
+- lib/bsv/network/protocols.rb
+- lib/bsv/network/protocols/arc.rb
+- lib/bsv/network/protocols/chaintracks.rb
+- lib/bsv/network/protocols/ordinals.rb
+- lib/bsv/network/protocols/taal_binary.rb
+- lib/bsv/network/protocols/woc_rest.rb
+- lib/bsv/network/provider.rb
+- lib/bsv/network/providers.rb
+- lib/bsv/network/providers/gorilla_pool.rb
+- lib/bsv/network/providers/taal.rb
+- lib/bsv/network/providers/whats_on_chain.rb
+- lib/bsv/network/result.rb
 - lib/bsv/network/utxo.rb
 - lib/bsv/network/whats_on_chain.rb
 - lib/bsv/overlay.rb
@@ -150,9 +162,6 @@ files:
 - lib/bsv/transaction/var_int.rb
 - lib/bsv/transaction/verification_error.rb
 - lib/bsv/version.rb
-- lib/bsv/wallet.rb
-- lib/bsv/wallet/insufficient_funds_error.rb
-- lib/bsv/wallet/wallet.rb
 - lib/bsv/wire_format.rb
 homepage: https://github.com/sgbett/bsv-ruby-sdk
 licenses:

data/lib/bsv/messages.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  # Namespace providing TS SDK naming parity for messaging primitives.
-  #
-  # Re-exports {BSV::Primitives::SignedMessage} and {BSV::Primitives::EncryptedMessage}
-  # under the +BSV::Messages+ namespace, matching the structure of the TypeScript SDK
-  # (ts-sdk/src/messages/index.ts).
-  #
-  # The canonical implementations remain in +BSV::Primitives+; this module is a
-  # lightweight re-export only.
-  module Messages
-    SignedMessage = BSV::Primitives::SignedMessage
-    EncryptedMessage = BSV::Primitives::EncryptedMessage
-  end
-end

data/lib/bsv/wallet/insufficient_funds_error.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module Wallet
-    class InsufficientFundsError < StandardError
-      attr_reader :required, :available
-
-      def initialize(message = nil, required: nil, available: nil)
-        @required = required
-        @available = available
-        super(message || "insufficient funds: need #{required}, have #{available}")
-      end
-    end
-  end
-end

data/lib/bsv/wallet/wallet.rb

@@ -1,120 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module Wallet
-    # Holds a private key, sources UTXOs via a chain data provider, and
-    # funds and signs P2PKH transactions.
-    #
-    # The provider is duck-typed — any object responding to
-    # #fetch_utxos(address) and #fetch_transaction(txid) qualifies.
-    class Wallet
-      DUST_THRESHOLD = 1
-
-      attr_reader :private_key, :provider
-
-      def initialize(private_key:, provider:)
-        @private_key = private_key
-        @provider = provider
-      end
-
-      def address(network: :mainnet)
-        @private_key.public_key.address(network: network)
-      end
-
-      def balance(network: :mainnet)
-        @provider.fetch_utxos(address(network: network)).sum(&:satoshis)
-      end
-
-      def fund(tx, network: :mainnet, satoshis_per_byte: 0.1)
-        utxos = @provider.fetch_utxos(address(network: network))
-        output_total = tx.total_output_satoshis
-
-        # Add a dummy change output so fee estimation accounts for its size
-        dummy_change = BSV::Transaction::TransactionOutput.new(
-          satoshis: 0, locking_script: locking_script
-        )
-        tx.add_output(dummy_change)
-
-        input_total = tx.total_input_satoshis
-        funded = false
-
-        utxos.each do |utxo|
-          tx.add_input(build_input(utxo))
-          input_total += utxo.satoshis
-
-          fee = tx.estimated_fee(satoshis_per_byte: satoshis_per_byte)
-          if input_total >= output_total + fee
-            funded = true
-            break
-          end
-        end
-
-        # Remove the dummy change output
-        tx.outputs.delete(dummy_change)
-
-        unless funded
-          fee = tx.estimated_fee(satoshis_per_byte: satoshis_per_byte)
-          raise InsufficientFundsError.new(required: output_total + fee, available: input_total)
-        end
-
-        add_change_if_needed(tx, input_total, output_total, satoshis_per_byte)
-
-        tx
-      end
-
-      def sign(tx)
-        tx.sign_all(@private_key)
-      end
-
-      def fund_and_sign(tx, network: :mainnet, satoshis_per_byte: 0.1)
-        fund(tx, network: network, satoshis_per_byte: satoshis_per_byte)
-        sign(tx)
-      end
-
-      private
-
-      def locking_script
-        @locking_script ||= BSV::Script::Script.p2pkh_lock(@private_key.public_key.hash160)
-      end
-
-      def build_input(utxo)
-        input = BSV::Transaction::TransactionInput.new(
-          prev_tx_id: BSV::Transaction::TransactionInput.txid_from_hex(utxo.tx_hash),
-          prev_tx_out_index: utxo.tx_pos
-        )
-        input.source_satoshis = utxo.satoshis
-        input.source_locking_script = locking_script
-        input.unlocking_script_template = BSV::Transaction::P2PKH.new(@private_key)
-        input
-      end
-
-      def add_change_if_needed(tx, input_total, output_total, satoshis_per_byte)
-        fee_without_change = tx.estimated_fee(satoshis_per_byte: satoshis_per_byte)
-        remainder = input_total - output_total - fee_without_change
-
-        return if remainder < DUST_THRESHOLD
-
-        change_output = BSV::Transaction::TransactionOutput.new(
-          satoshis: remainder, locking_script: locking_script
-        )
-        tx.add_output(change_output)
-
-        # Recalculate: adding the change output increases fee slightly
-        new_fee = tx.estimated_fee(satoshis_per_byte: satoshis_per_byte)
-        fee_increase = new_fee - fee_without_change
-        final_change = remainder - fee_increase
-
-        if final_change >= DUST_THRESHOLD
-          tx.outputs.delete(change_output)
-          tx.add_output(
-            BSV::Transaction::TransactionOutput.new(
-              satoshis: final_change, locking_script: locking_script
-            )
-          )
-        else
-          tx.outputs.delete(change_output) # change absorbed by fee
-        end
-      end
-    end
-  end
-end

data/lib/bsv/wallet.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module Wallet
-    autoload :InsufficientFundsError, 'bsv/wallet/insufficient_funds_error'
-    autoload :Wallet,                 'bsv/wallet/wallet'
-  end
-end