bsv-sdk 0.12.1 → 0.14.0

data/lib/bsv/network/providers/taal.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module BSV
+  module Network
+    module Providers
+      # TAAL returns pre-configured Provider instances using the TAAL infrastructure.
+      #
+      # Mainnet composes two protocols:
+      # - ARC at +https://arc.taal.com+ for standard ARC operations
+      # - TAALBinary at +https://api.taal.com+ for binary broadcast
+      #
+      # ARC is registered first, so +:broadcast+ is served by ARC (first-registered wins).
+      # TAALBinary registers its own +:broadcast+ command but will not win the index.
+      # To use TAALBinary directly, call +provider.protocol_for(:broadcast)+ on the
+      # TAALBinary instance via +provider.protocols.last+, or build a custom Provider.
+      #
+      # There is no TAAL testnet default — TAAL does not publish a supported testnet ARC URL.
+      #
+      # == Example
+      #
+      #   provider = BSV::Network::Providers::TAAL.mainnet(api_key: 'mainnet_...')
+      #   provider.call(:broadcast, tx)
+      class TAAL
+        # Returns a mainnet Provider configured with ARC and TAALBinary.
+        #
+        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @return [Provider]
+        def self.mainnet(**opts)
+          common = opts.slice(:api_key, :http_client)
+          Provider.new('TAAL') do |p|
+            p.protocol Protocols::ARC, base_url: 'https://arc.taal.com', **opts
+            p.protocol Protocols::TAALBinary, base_url: 'https://api.taal.com', **common
+          end
+        end
+
+        # Returns a testnet Provider configured with ARC only.
+        #
+        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @return [Provider]
+        def self.testnet(**opts)
+          Provider.new('TAAL') do |p|
+            p.protocol Protocols::ARC, base_url: 'https://arc-test.taal.com', **opts
+          end
+        end
+
+        # Returns a mainnet or testnet Provider depending on the +testnet:+ flag.
+        #
+        # @param testnet [Boolean] when true, returns the testnet Provider
+        # @param opts    [Hash]    keyword arguments forwarded to each protocol constructor
+        # @return [Provider]
+        def self.default(testnet: false, **opts)
+          testnet ? testnet(**opts) : mainnet(**opts)
+        end
+      end
+    end
+  end
+end

data/lib/bsv/network/providers/whats_on_chain.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module BSV
+  module Network
+    module Providers
+      # WhatsOnChain returns pre-configured Provider instances using the
+      # WhatsOnChain REST API (WoCREST protocol).
+      #
+      # The base URL is fully resolved per network — no +{network}+ template
+      # is used in provider defaults. The WoCREST protocol's +network:+ param
+      # is omitted since the URL already encodes the network segment.
+      #
+      # == Example
+      #
+      #   provider = BSV::Network::Providers::WhatsOnChain.mainnet
+      #   provider.call(:get_tx, 'abc123...')
+      #
+      #   provider = BSV::Network::Providers::WhatsOnChain.testnet(api_key: 'my-key')
+      #   provider.call(:broadcast, tx)
+      class WhatsOnChain
+        # Returns a mainnet Provider configured with WoCREST.
+        #
+        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @return [Provider]
+        def self.mainnet(**opts)
+          Provider.new('WhatsOnChain') do |p|
+            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/main', **opts
+          end
+        end
+
+        # Returns a testnet Provider configured with WoCREST.
+        #
+        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @return [Provider]
+        def self.testnet(**opts)
+          Provider.new('WhatsOnChain') do |p|
+            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/test', **opts
+          end
+        end
+
+        # Returns a Provider for the BSV Scaling Test Network (STN).
+        #
+        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @return [Provider]
+        def self.stn(**opts)
+          Provider.new('WhatsOnChain') do |p|
+            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/stn', **opts
+          end
+        end
+
+        # Returns a Provider for the given network.
+        #
+        # @param testnet [Boolean] when true, returns the testnet Provider
+        # @param network [Symbol, nil] explicit network (:main, :test, :stn) — overrides +testnet:+
+        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @return [Provider]
+        def self.default(testnet: false, network: nil, **opts)
+          if network
+            case network.to_sym
+            when :main, :mainnet then mainnet(**opts)
+            when :test, :testnet then testnet(**opts)
+            when :stn then stn(**opts)
+            else raise ArgumentError, "unknown network: #{network}"
+            end
+          else
+            testnet ? testnet(**opts) : mainnet(**opts)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/network/providers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module BSV
+  module Network
+    # Providers is a namespace module for pre-configured Provider factory classes.
+    #
+    # Each provider class has +.mainnet+ and +.testnet+ class methods that return
+    # a fully-configured +Provider+ instance with the appropriate protocol set.
+    # Both methods accept +**opts+ which are forwarded to each protocol constructor
+    # (e.g. +api_key:+, +http_client:+).
+    #
+    # == Example
+    #
+    #   provider = BSV::Network::Providers::GorillaPool.mainnet
+    #   result   = provider.call(:broadcast, tx)
+    #
+    #   provider = BSV::Network::Providers::TAAL.mainnet(api_key: 'my-key')
+    #   result   = provider.call(:broadcast, tx)
+    module Providers
+      autoload :GorillaPool,   'bsv/network/providers/gorilla_pool'
+      autoload :WhatsOnChain,  'bsv/network/providers/whats_on_chain'
+      autoload :TAAL,          'bsv/network/providers/taal'
+    end
+  end
+end

data/lib/bsv/network/result.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module BSV
+  module Network
+    # Result module provides three immutable value types for Protocol dispatch outcomes.
+    #
+    # All three types share a Predicates mixin with default false implementations.
+    # Each type overrides only the predicate that returns true for that type.
+    module Result
+      # Mixin providing default false implementations for all query predicates.
+      module Predicates
+        def success?
+          false
+        end
+
+        def error?
+          false
+        end
+
+        def not_found?
+          false
+        end
+      end
+
+      # Represents a successful outcome. Carries the response payload in +data+
+      # and optional protocol-specific extras in +metadata+.
+      class Success
+        include Predicates
+
+        attr_reader :data, :metadata
+
+        def initialize(data:, metadata: {})
+          @data = data
+          @metadata = metadata.freeze
+          freeze
+        end
+
+        def success?
+          true
+        end
+
+        def ==(other)
+          other.is_a?(Success) && data == other.data && metadata == other.metadata
+        end
+
+        alias eql? ==
+
+        def hash
+          [self.class, data, metadata].hash
+        end
+      end
+
+      # Represents a failed outcome. Carries a human-readable +message+, a boolean
+      # +retryable+ flag indicating whether the caller should retry, and optional
+      # +metadata+ for structured protocol-specific details (e.g. +arc_status+).
+      class Error
+        include Predicates
+
+        attr_reader :message, :retryable, :metadata
+
+        def initialize(message:, retryable: false, metadata: {})
+          @message = message
+          @retryable = retryable
+          @metadata = metadata.freeze
+          freeze
+        end
+
+        def error?
+          true
+        end
+
+        def retryable?
+          @retryable
+        end
+
+        def ==(other)
+          other.is_a?(Error) &&
+            message == other.message &&
+            retryable == other.retryable &&
+            metadata == other.metadata
+        end
+
+        alias eql? ==
+
+        def hash
+          [self.class, message, retryable, metadata].hash
+        end
+      end
+
+      # Represents a resource-not-found outcome. Carries an optional human-readable
+      # +message+ and optional +metadata+.
+      class NotFound
+        include Predicates
+
+        attr_reader :message, :metadata
+
+        def initialize(message: nil, metadata: {})
+          @message = message
+          @metadata = metadata.freeze
+          freeze
+        end
+
+        def not_found?
+          true
+        end
+
+        def ==(other)
+          other.is_a?(NotFound) && message == other.message && metadata == other.metadata
+        end
+
+        alias eql? ==
+
+        def hash
+          [self.class, message, metadata].hash
+        end
+      end
+    end
+  end
+end

data/lib/bsv/network/whats_on_chain.rb

@@ -1,41 +1,56 @@
 # frozen_string_literal: true
 
-require 'net/http'
-require 'json'
-require 'uri'
-
 module BSV
   module Network
     # WhatsOnChain chain data provider for reading transactions and UTXOs
     # from the BSV network.
     #
-    # Any object responding to #fetch_utxos(address) and
-    # #fetch_transaction(txid) can serve as a chain data provider;
-    # this class implements that contract using the WhatsOnChain API.
+    # 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.
     class WhatsOnChain
-      BASE_URL = 'https://api.whatsonchain.com'
+      # 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
 
-      def initialize(network: :mainnet, http_client: nil)
-        @network = network == :mainnet ? 'main' : 'test'
-        @http_client = http_client
+      # @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)
-        response = get("/v1/bsv/#{@network}/address/#{address}/unspent")
-        body = JSON.parse(response.body)
+        result = @protocol.call(:get_utxos_all, address)
+        raise_on_error(result)
 
-        body.map do |entry|
+        result.data.map do |entry|
           UTXO.new(
-            tx_hash: entry['tx_hash'],
-            tx_pos: entry['tx_pos'],
-            satoshis: entry['value'],
-            height: entry['height']
+            tx_hash: entry[:tx_hash],
+            tx_pos: entry[:tx_pos],
+            satoshis: entry[:satoshis],
+            height: entry[:height]
           )
         end
       end
@@ -44,37 +59,60 @@ module BSV
       # @param txid [String] transaction ID (hex)
       # @return [BSV::Transaction::Transaction]
       def fetch_transaction(txid)
-        response = get("/v1/bsv/#{@network}/tx/#{txid}/hex")
-        BSV::Transaction::Transaction.from_hex(response.body)
+        result = @protocol.call(:get_tx, txid)
+        raise_on_error(result)
+
+        BSV::Transaction::Transaction.from_hex(result.data)
       end
 
-      private
+      # 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)
 
-      def get(path)
-        uri = URI("#{BASE_URL}#{path}")
-        request = Net::HTTP::Get.new(uri)
-        response = execute(uri, request)
-        handle_response(response)
-        response
+        result.data
       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)
-          end
-        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
 
-      def handle_response(response)
-        code = response.code.to_i
-        return if (200..299).cover?(code)
+      # 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(
-          response.body || "HTTP #{code}",
-          status_code: code
+          result.message || 'Request failed',
+          status_code: result.metadata[:status_code]
         )
       end
     end

data/lib/bsv/network.rb

@@ -2,6 +2,11 @@
 
 module BSV
   module Network
+    autoload :Result,             'bsv/network/result'
+    autoload :Protocol,           'bsv/network/protocol'
+    autoload :Protocols,          'bsv/network/protocols'
+    autoload :Providers,          'bsv/network/providers'
+    autoload :Provider,           'bsv/network/provider'
     autoload :BroadcastError,     'bsv/network/broadcast_error'
     autoload :BroadcastResponse,  'bsv/network/broadcast_response'
     autoload :ChainProviderError, 'bsv/network/chain_provider_error'

data/lib/bsv/overlay/admin_token_template.rb

@@ -24,7 +24,7 @@ module BSV
     #   <derived_pubkey> OP_CHECKSIG
     #
     # @example Lock a SHIP advertisement
-    #   wallet = BSV::Wallet::ProtoWallet.new(private_key)
+    #   wallet = BSV::Wallet::Client.new(private_key, storage: BSV::Wallet::Store::Memory.new)
     #   template = BSV::Overlay::AdminTokenTemplate.new(wallet)
     #   locking_script = template.lock('SHIP', 'myhost.example.com', 'tm_payments')
     #   decoded = BSV::Overlay::AdminTokenTemplate.decode(locking_script)
@@ -144,7 +144,7 @@ module BSV
       # Construct a new AdminTokenTemplate instance.
       #
       # @param wallet [#get_public_key, #create_signature] any object implementing
-      #   the BRC-100 wallet interface (e.g. {BSV::Wallet::ProtoWallet})
+      #   the BRC-100 wallet interface (e.g. {BSV::Wallet::Client})
       # @param originator [String, nil] optional FQDN of the originating application
       def initialize(wallet, originator: nil)
         @wallet = wallet

data/lib/bsv/script/push_drop_template.rb

@@ -39,7 +39,7 @@ module BSV
     #    keyrings from +prove_certificate+) for field-level integrity.
     #
     # @example Lock a token
-    #   wallet   = BSV::Wallet::ProtoWallet.new(private_key)
+    #   wallet   = BSV::Wallet::Client.new(private_key, storage: BSV::Wallet::Store::Memory.new)
     #   template = BSV::Script::PushDropTemplate.new(wallet:)
     #   script   = template.lock(
     #     fields:       ['hello'.b, 'world'.b],

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

@@ -1,16 +1,12 @@
 # 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 Chaintracks API (Arcade/GorillaPool).
       #
-      # Queries the Chaintracks v2 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::Chaintracks}.
+      # The constructor signature and {ChainTracker} contract are preserved.
       #
       # @example
       #   tracker = BSV::Transaction::ChainTrackers::Chaintracks.new
@@ -20,17 +16,37 @@ module BSV
       #   tracker = BSV::Transaction::ChainTrackers::Chaintracks.new(api_key: 'my-key')
       #   tracker.current_height
       class Chaintracks < ChainTracker
-        MAINNET_URL = BSV::MAINNET_URL
-        TESTNET_URL = BSV::TESTNET_URL
+        # Returns a Chaintracks instance using the GorillaPool 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 [Chaintracks]
+        def self.default(testnet: false, **opts)
+          provider = BSV::Network::Providers::GorillaPool.default(testnet: testnet, **opts)
+          protocol = provider.protocol_for(:current_height)
+          new(protocol: protocol)
+        end
 
-        # @param url [String] base URL for the Chaintracks API
+        # @param url [String, nil] base URL (legacy compat — prefer .default or protocol:)
         # @param api_key [String, nil] optional Bearer API key
         # @param http_client [#request, nil] injectable HTTP client for testing
-        def initialize(url: MAINNET_URL, api_key: nil, http_client: nil)
+        # @param protocol [BSV::Network::Protocols::Chaintracks, nil] pre-configured protocol
+        def initialize(url: nil, api_key: nil, http_client: nil, protocol: nil)
           super()
-          @url = url.chomp('/')
-          @api_key = api_key
-          @http_client = http_client
+          if protocol
+            @protocol = protocol
+          elsif url
+            @url = url.chomp('/')
+            @api_key = api_key
+            @protocol = BSV::Network::Protocols::Chaintracks.new(
+              base_url: @url,
+              api_key: api_key,
+              http_client: http_client
+            )
+          else
+            provider = BSV::Network::Providers::GorillaPool.default(api_key: api_key, http_client: http_client)
+            @protocol = provider.protocol_for(:current_height)
+          end
         end
 
         # Verify that a merkle root is valid for the given block height.
@@ -38,12 +54,19 @@ 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("/chaintracks/v2/header/height/#{height}")
-          return false if response.nil?
+          result = @protocol.call(:get_block_header, 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)
-          merkle_root = data['merkleRoot']
+          merkle_root = result.data['merkleRoot']
           return false unless merkle_root
 
           merkle_root.downcase == root.downcase
@@ -52,43 +75,16 @@ module BSV
         # Return the current blockchain height.
         #
         # @return [Integer]
+        # @raise [BSV::Network::ChainProviderError] on network or API error
         def current_height
-          response = get('/chaintracks/v2/tip', not_found_returns_nil: false)
-          data = JSON.parse(response.body)
-          data['height']
-        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("#{@url}#{path}")
-          request = Net::HTTP::Get.new(uri)
-          request['Authorization'] = "Bearer #{@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)
-            end
-          end
-        end
       end
     end
   end