bsv-sdk 0.17.0 → 0.18.0

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

@@ -1,31 +1,133 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module BSV
   module Network
     module Protocols
       # Ordinals implements the GorillaPool Ordinals API as a Protocol subclass.
       #
-      # Provides raw transaction hex lookup and Merkle path (proof) retrieval
-      # via the GorillaPool Ordinals REST API. Pure DSL — no escape hatches needed.
+      # Provides raw transaction lookup, Merkle path (proof) retrieval, UTXO
+      # queries, balance lookups, spend status, and chain tip via the GorillaPool
+      # Ordinals REST API.
+      #
+      # == get_tx vs get_tx_details
+      #
+      # +get_tx+ returns the raw transaction as a hex string (escape hatch
+      # converts binary response body to hex). +get_tx_details+ returns the full
+      # parsed transaction metadata as a JSON object.
+      #
+      # == get_balance
+      #
+      # The API returns the balance as a quoted integer string (e.g. +"1000000"+),
+      # not a bare JSON number. The lambda handler parses this to an Integer.
+      #
+      # == get_spend
+      #
+      # The API returns an empty quoted string +""+  for unspent outputs and a
+      # quoted txid string for spent outputs. The escape hatch normalises these
+      # to +{ spent: false }+ or +{ spent: true, spending_txid: "..." }+.
+      # The outpoint must be passed as +"txid_vout"+ (underscore-separated).
       #
       # == Usage
       #
       #   ord = BSV::Network::Protocols::Ordinals.new(base_url: 'https://ordinals.gorillapool.io')
       #   result = ord.call(:get_tx, 'abc123...')
-      #   result.data  # => "01000000..."  (raw hex string)
+      #   result.data  # => "01000000..."  (hex string)
       #
       #   result = ord.call(:get_merkle_path, 'abc123...')
-      #   result.data  # => { 'index' => 0, 'path' => [...] }
+      #   result.data  # => binary TSC proof bytes
+      #
+      #   result = ord.call(:get_spend, 'txid_0')
+      #   result.data  # => { spent: false } or { spent: true, spending_txid: "..." }
+      #
+      # @see https://ordinals.gorillapool.io/api/docs/ Ordinals API documentation
       class Ordinals < Protocol
-        endpoint :get_tx,          :get, '/api/tx/{txid}/hex'
-        endpoint :get_merkle_path, :get, '/api/tx/{txid}/proof', response: :json
+        # Transaction — raw binary body; escape hatch converts to hex
+        endpoint :get_tx,         :get, '/api/tx/{txid}/raw'
+
+        # Transaction — full metadata as JSON
+        endpoint :get_tx_details, :get, '/api/tx/{txid}', response: :json
+
+        # Transaction — confirmation status
+        endpoint :get_tx_status,  :get, '/api/tx/{txid}/status', response: :json
+
+        # Merkle path — binary TSC proof body; no JSON parsing
+        endpoint :get_merkle_path, :get, '/api/tx/{txid}/proof'
+
+        # UTXOs for an address — JSON array
+        endpoint :get_utxos, :get, '/api/txos/address/{address}/unspent', response: :json_array
+
+        # Balance for an address — quoted integer string; lambda parses to Integer
+        endpoint :get_balance, :get, '/api/txos/address/{address}/balance',
+                 response: ->(body) { JSON.parse(body).to_i }
+
+        # Spend status for an outpoint (format: "txid_vout") — escape hatch normalises
+        endpoint :get_spend, :get, '/api/spends/{outpoint}'
+
+        # Chain tip — latest block metadata as JSON
+        endpoint :get_chain_tip, :get, '/api/blocks/tip', response: :json
 
         # @param base_url    [String] base URL for the Ordinals API
-        # @param api_key     [String, nil] optional Bearer API key
+        # @param api_key     [String, nil] legacy Bearer API key shorthand — use +auth:+ for new code
+        # @param auth        [Hash, Symbol, nil] auth config; takes precedence over +api_key:+
         # @param http_client [Object, nil] injectable HTTP client for testing
-        def initialize(base_url:, api_key: nil, http_client: nil)
+        def initialize(base_url:, api_key: nil, auth: nil, http_client: nil)
           super
         end
+
+        private
+
+        # Fetches the raw transaction and converts the binary response body to hex.
+        #
+        # The Ordinals API serves +/api/tx/{txid}/raw+ as binary data, not hex text.
+        # This escape hatch unpacks the binary body to a lowercase hex string,
+        # matching the convention used by other protocol +get_tx+ implementations.
+        #
+        # Accepts +txid+ as a positional argument or as a +txid:+ keyword.
+        #
+        # @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]
+        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?
+
+          Result::Success.new(data: result.data.unpack1('H*'))
+        end
+
+        # Normalises the spend status response from the Ordinals API.
+        #
+        # The API returns a quoted empty string +""+  when the output is unspent,
+        # and a quoted txid string +"abc123..."+ when it is spent. This escape
+        # hatch parses the JSON string body and returns a structured hash.
+        #
+        # The +outpoint+ argument must use underscore-separated format: +"txid_vout"+.
+        # Accepts +outpoint+ as a positional argument or as an +outpoint:+ keyword.
+        #
+        # @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]
+        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?
+
+          spending_txid = JSON.parse(result.data).to_s.strip
+          if spending_txid.empty?
+            Result::Success.new(data: { spent: false })
+          else
+            Result::Success.new(data: { spent: true, spending_txid: spending_txid })
+          end
+        rescue JSON::ParserError => e
+          Result::Error.new(message: "spend response parse error: #{e.message}")
+        end
       end
     end
   end

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

@@ -8,7 +8,7 @@ module BSV
       #
       # TAAL quirks handled here:
       # - Content-Type is +application/octet-stream+ (not JSON)
-      # - Authorization header uses the API key directly with no "Bearer" prefix
+      # - Authorization header is applied via the standard +apply_auth+ mechanism
       # - A response containing +txn-already-known+ in the error field is treated
       #   as success (the transaction is already in the mempool — idempotent)
       #
@@ -16,13 +16,26 @@ module BSV
       #
       #   protocol = BSV::Network::Protocols::TAALBinary.new(
       #     base_url: 'https://api.taal.com',
-      #     api_key: 'mainnet_your_key_here'
+      #     auth: { api_key: 'mainnet_your_key_here' }
       #   )
       #   result = protocol.call(:broadcast, tx)
       #   puts result.data[:txid] if result.success?
+      #
+      # @see https://docs.taal.com TAAL API documentation
       class TAALBinary < BSV::Network::Protocol
         endpoint :broadcast, :post, '/api/v1/broadcast', response: :json
 
+        # @param base_url    [String] base URL for the TAAL binary API
+        # @param api_key     [String, nil] legacy API key shorthand (no Bearer prefix) — use +auth:+ for new code
+        # @param auth        [Hash, Symbol, nil] auth config; takes precedence over +api_key:+
+        # @param http_client [Object, nil] injectable HTTP client for testing
+        def initialize(base_url:, api_key: nil, auth: nil, http_client: nil)
+          # Translate legacy api_key: to auth: { api_key: } so the base class sends
+          # the raw key without a Bearer prefix, matching TAAL's expected auth format.
+          resolved_auth = auth || (api_key ? { api_key: api_key } : nil)
+          super(base_url: base_url, auth: resolved_auth, http_client: http_client)
+        end
+
         private
 
         # Escape hatch for broadcast: sends raw binary transaction bytes with
@@ -35,8 +48,8 @@ module BSV
 
           uri     = URI("#{@base_url}/api/v1/broadcast")
           request = Net::HTTP::Post.new(uri)
-          request['Content-Type']  = 'application/octet-stream'
-          request['Authorization'] = @api_key if @api_key
+          request['Content-Type'] = 'application/octet-stream'
+          apply_auth(request)
 
           request.body = body
 

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

@@ -7,9 +7,9 @@ module BSV
     module Protocols
       # WoCREST implements the WhatsOnChain REST API as a Protocol subclass.
       #
-      # Provides 30 endpoints covering chain info, block headers, transactions,
-      # UTXOs, scripts, address queries, broadcast, and health. Seven escape hatches
-      # handle WoC-specific body formats and field remapping.
+      # Provides endpoints covering chain info, block headers, transactions,
+      # UTXOs, scripts, address queries, broadcast, search, stats, and health.
+      # Escape hatches handle WoC-specific body formats and field remapping.
       #
       # == Network resolution
       #
@@ -22,6 +22,8 @@ module BSV
       #   woc = BSV::Network::Protocols::WoCREST.new(network: :main)
       #   result = woc.call(:get_tx, 'abc123...')
       #   puts result.data if result.success?
+      #
+      # @see https://developers.whatsonchain.com/ WhatsOnChain API documentation
       class WoCREST < Protocol
         NETWORKS = {
           'main' => 'main',
@@ -40,6 +42,9 @@ module BSV
         endpoint :get_chain_info,    :get, '/chain/info', response: :json
         endpoint :get_block_header,  :get, '/block/{height}/header', response: :json
         endpoint :get_block_headers, :get, '/block/headers', response: :json_array
+        endpoint :get_circulating_supply, :get, '/circulatingsupply'
+        endpoint :get_chain_tips,         :get, '/chain/tips', response: :json_array
+        endpoint :get_peer_info,          :get, '/peer/info',  response: :json_array
 
         # Transaction
         endpoint :get_tx,            :get,  '/tx/{txid}/hex'
@@ -51,15 +56,26 @@ module BSV
         endpoint :decode_tx,         :post, '/tx/decode', response: :json
         endpoint :get_tx_status,     :post, '/txs/status', response: :json
         endpoint :get_tx_hex_bulk,   :post, '/txs/hex', response: :json
+        endpoint :get_tx_binary,          :get,  '/tx/{txid}/bin'
+        endpoint :get_tx_by_block_index,  :get,  '/block/height/{height}/txindex/{txindex}', response: :json
+        endpoint :get_tx_propagation,     :get,  '/tx/hash/{txid}/propagation', response: :json
+        endpoint :get_bulk_tx_details,    :post, '/txs', response: :json
+        endpoint :get_bulk_output_scripts, :post, '/txs/vouts/hex', response: :json
 
         # UTXO / spent status
         endpoint :get_utxos,        :get,  '/address/{address}/confirmed/unspent',
                  response: :json_array
-        endpoint :get_utxos_all,    :get,  '/address/{address}/unspent',
+        endpoint :get_utxos_all,    :get,  '/address/{address}/unspent/all',
                  response: :json_array
         endpoint :is_utxo,          :get,  '/tx/{txid}/{vout}/spent', response: :json
         endpoint :is_utxo_bulk,     :post, '/utxos/spent', response: :json_array
         endpoint :valid_root,       :get,  '/block/{height}/header', response: :json
+        endpoint :get_unconfirmed_utxos,  :get,  '/address/{address}/unconfirmed/unspent',
+                 response: :json_array
+        endpoint :get_confirmed_spent,    :get,  '/tx/{txid}/{vout}/confirmed/spent', response: :json
+        endpoint :get_unconfirmed_spent,  :get,  '/tx/{txid}/{vout}/unconfirmed/spent', response: :json
+        endpoint :get_bulk_address_utxos, :post, '/addresses/confirmed/unspent', response: :json
+        endpoint :get_bulk_address_unconfirmed_utxos, :post, '/addresses/unconfirmed/unspent', response: :json
 
         # Script
         endpoint :get_script_unspent,     :get,  '/script/{script_hash}/confirmed/unspent',
@@ -69,6 +85,9 @@ module BSV
         endpoint :get_script_all_unspent, :get,  '/script/{script_hash}/unspent/all',
                  response: :json_array
         endpoint :get_script_unspent_bulk, :post, '/scripts/confirmed/unspent', response: :json
+        endpoint :get_script_unconfirmed_unspent, :get, '/script/{script_hash}/unconfirmed/unspent',
+                 response: :json_array
+        endpoint :get_bulk_script_unconfirmed_unspent, :post, '/scripts/unconfirmed/unspent', response: :json
 
         # Address balance / history
         endpoint :get_balance,             :get, '/address/{address}/confirmed/balance',
@@ -83,35 +102,46 @@ module BSV
         endpoint :get_exchange_rate,      :get, '/exchangerate',      response: :json
         endpoint :get_fee_recommendation, :get, '/feerecommendation', response: :json
         endpoint :get_mempool_info,       :get, '/mempool/info',      response: :json
+        endpoint :get_exchange_rate_historical, :get, '/exchangerate/historical', response: :json_array
+        endpoint :get_mempool_raw,              :get, '/mempool/raw', response: :json_array
+
+        # Search
+        endpoint :search_links, :post, '/search/links', response: :json
+
+        # Stats
+        endpoint :get_block_stats,          :get, '/block/height/{height}/stats', response: :json
+        endpoint :get_block_stats_by_hash,  :get, '/block/hash/{hash}/stats', response: :json
+        endpoint :get_miner_block_stats,    :get, '/miner/blocks/stats', response: :json
+        endpoint :get_miner_fees,           :get, '/miner/fees', response: :json
+        endpoint :get_miner_summary,        :get, '/miner/summary/stats', response: :json
+        endpoint :get_block_tag_count,      :get, '/block/tagcount/height/{height}/stats', response: :json
 
         # Health
-        endpoint :health, :get, '/health'
+        endpoint :health, :get, '/woc'
 
         attr_reader :network_name
 
         # @param base_url    [String] base URL for the WoC API; may contain
         #   +{network}+ which will be interpolated with the resolved network name
-        # @param network  [Symbol, String] :main, :mainnet, :test, :testnet, :stn
-        # @param api_key  [String, nil]    optional Bearer API key
+        # @param network     [Symbol, String] :main, :mainnet, :test, :testnet, :stn
+        # @param api_key     [String, nil] legacy API key — sends +Authorization: key+
+        #   (no Bearer prefix, matching WoC's expected auth format)
+        # @param auth        [Hash, Symbol, nil] auth config hash forwarded to Protocol;
+        #   when provided, takes precedence over +api_key:+
         # @param http_client [Object, nil] injectable HTTP client for testing
-        def initialize(base_url:, network: :main, api_key: nil, http_client: nil)
+        def initialize(base_url:, network: :main, api_key: nil, auth: nil, http_client: nil)
           @network_name = resolve_network(network)
+          # Translate legacy api_key: to auth: { api_key: } so the base class sends
+          # the raw key without a Bearer prefix, matching WoC's expected auth format.
+          resolved_auth = auth || (api_key ? { api_key: api_key } : nil)
           super(
             base_url: base_url,
-            api_key: api_key,
+            auth: resolved_auth,
             network: @network_name,
             http_client: http_client
           )
         end
 
-        # WoC expects a raw Authorization header (no Bearer prefix).
-        # Override the base class which adds "Bearer ".
-        def build_request(http_method, uri, body)
-          request = super
-          request['Authorization'] = @api_key if @api_key
-          request
-        end
-
         private
 
         # Resolves network aliases to the WoC URL segment string.
@@ -125,77 +155,40 @@ module BSV
           end
         end
 
-        # Fetches confirmed UTXOs for an address and remaps the +value+ field
-        # to +satoshis+ to match the SDK's UTXO convention.
-        #
-        # WoC returns entries with +{ tx_hash, tx_pos, value, height }+;
-        # callers and facades expect +satoshis+ in place of +value+.
-        #
-        # @param address [String] BSV address
-        # @return [Result::Success, Result::Error, Result::NotFound]
-        def call_get_utxos(address)
-          result = default_call(:get_utxos, address)
-          return result unless result.success?
-
-          Result::Success.new(data: remap_utxo_entries(result.data))
-        end
-
-        # Fetches all UTXOs (confirmed and unconfirmed) for an address and
-        # remaps the +value+ field to +satoshis+. Uses the legacy +/unspent+
-        # endpoint rather than +/confirmed/unspent+.
-        #
-        # @param address [String] BSV address
-        # @return [Result::Success, Result::Error, Result::NotFound]
-        def call_get_utxos_all(address)
-          result = default_call(:get_utxos_all, address)
-          return result unless result.success?
-
-          Result::Success.new(data: remap_utxo_entries(result.data))
-        end
-
-        # Remaps WoC UTXO entries from +{ 'value' => n }+ to +{ satoshis: n }+.
-        #
-        # @param entries [Array<Hash>]
-        # @return [Array<Hash>]
-        def remap_utxo_entries(entries)
-          entries.map do |entry|
-            {
-              tx_hash: entry['tx_hash'],
-              tx_pos: entry['tx_pos'],
-              satoshis: entry['value'],
-              height: entry['height']
-            }
-          end
-        end
-
         # Checks whether a specific output is unspent by querying the WoC
         # spent-status endpoint.
         #
-        # WoC returns a JSON object indicating whether the output has been spent.
+        # WoC returns 200 with spending transaction details when an output
+        # has been spent, or 404 when the output is unspent (no spending
+        # transaction found). This escape hatch maps both cases to a
+        # boolean: +true+ = unspent, +false+ = spent.
+        #
         # The +script_hash:+ keyword is accepted for future fallback support
         # but not used in this implementation.
         #
         # @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]
+        # @return [Result::Success<Boolean>, Result::Error]
         def call_is_utxo(txid, vout, script_hash: nil) # rubocop:disable Lint/UnusedMethodArgument
           result = default_call(:is_utxo, txid, vout)
-          return result unless result.success?
 
-          # WoC returns { "spent": true/false, ... } — unspent means NOT spent
-          unless result.data.is_a?(Hash) && result.data.key?('spent')
-            return Result::Error.new(message: 'missing spent field in response', retryable: false)
-          end
+          # 404 = no spending tx found = output is unspent
+          return Result::Success.new(data: true) if result.not_found?
+
+          # Non-success, non-404 = genuine error
+          return result unless result.success?
 
-          spent = result.data['spent']
-          Result::Success.new(data: !spent)
+          # 200 with spending tx details = output is spent
+          Result::Success.new(data: false)
         end
 
         # Bulk-checks whether a set of outputs are unspent.
         #
-        # WoC expects a JSON array of +{ txid, vout }+ objects. It returns an
-        # array of entries, each containing +txid+, +vout+, and +spent+ fields.
+        # WoC expects +{ "utxos": [{ "txid": "...", "vout": N }, ...] }+ as the
+        # request body. It returns an array of entries, each with:
+        #   +{ "utxo": { "txid": "...", "vout": N }, "spentIn": {...} | nil, "error": "" }+
+        # When +spentIn+ is present and non-empty the output is spent.
         # Entries absent from the response (unknown outputs) are treated as spent.
         #
         # @param outpoints [Array<Hash>] array of +{ txid:, vout: }+ hashes
@@ -205,22 +198,25 @@ module BSV
         def call_is_utxo_bulk(outpoints)
           return Result::Success.new(data: {}) if outpoints.empty?
 
-          body = JSON.generate(outpoints.map { |op| { 'txid' => op[:txid].to_s, 'vout' => op[:vout].to_i } })
+          body = JSON.generate(utxos: outpoints.map { |op| { 'txid' => op[:txid].to_s, 'vout' => op[:vout].to_i } })
           result = default_call(:is_utxo_bulk, body: body)
           return result unless result.success?
 
-          # Build a lookup from the response — unknown outpoints default to spent
-          spent_map = {}
-          result.data.each do |entry|
-            next unless entry.is_a?(Hash) && entry.key?('txid') && entry.key?('vout')
+          # Build a lookup from the response entries
+          # spentIn present and non-empty → spent (false); absent or empty → unspent (true)
+          normalised = result.data.each_with_object({}) do |entry, h|
+            next unless entry.is_a?(Hash) && entry.key?('utxo')
 
-            key = "#{entry['txid']}.#{entry['vout']}"
-            spent_map[key] = entry['spent']
+            utxo = entry['utxo']
+            key = "#{utxo['txid']}.#{utxo['vout']}"
+            spent_in = entry['spentIn']
+            h[key] = spent_in.nil? || !spent_in.is_a?(Hash) || spent_in.empty?
           end
 
-          normalised = outpoints.each_with_object({}) do |op, h|
+          # Unknown outpoints (absent from response) default to spent (false)
+          outpoints.each do |op|
             key = "#{op[:txid]}.#{op[:vout]}"
-            h[key] = spent_map.key?(key) ? !spent_map[key] : false
+            normalised[key] = false unless normalised.key?(key)
           end
 
           Result::Success.new(data: normalised)
@@ -260,26 +256,110 @@ module BSV
 
         # Fetches raw hex for multiple transactions in a single request.
         #
-        # WoC expects a bare JSON array of txid strings as the request body.
+        # WoC expects +{ "txids": [...] }+ as the request body.
         #
         # @param txids [Array<String>] list of transaction IDs
         # @return [Result::Success<Array>, Result::Error]
         def call_get_tx_hex_bulk(txids)
-          body = JSON.generate(txids)
+          body = JSON.generate(txids: txids)
           default_call(:get_tx_hex_bulk, body: body)
         end
 
         # Fetches confirmed UTXOs for multiple script hashes in a single request.
         #
-        # WoC expects a bare JSON array of script hash strings as the request body.
+        # WoC expects +{ "scripts": [...] }+ as the request body.
         #
         # @param script_hashes [Array<String>] list of script hashes
         # @return [Result::Success<Hash>, Result::Error]
         def call_get_script_unspent_bulk(script_hashes)
-          body = JSON.generate(script_hashes)
+          body = JSON.generate(scripts: script_hashes)
           default_call(:get_script_unspent_bulk, body: body)
         end
 
+        # Fetches full transaction details for multiple transactions.
+        #
+        # WoC expects +{ "txids": [...] }+ as the request body.
+        #
+        # @param txids [Array<String>] list of transaction IDs
+        # @return [Result::Success<Array>, Result::Error]
+        def call_get_bulk_tx_details(txids)
+          body = JSON.generate(txids: txids)
+          default_call(:get_bulk_tx_details, body: body)
+        end
+
+        # Fetches output scripts for specific vouts across multiple transactions.
+        #
+        # WoC expects +{ "txids": [{ "txid": "...", "vouts": [0, 1] }, ...] }+ as the request body.
+        #
+        # @param tx_vouts [Array<Hash>] array of +{ txid:, vouts: [Integer] }+ hashes
+        # @return [Result::Success<Array>, Result::Error]
+        def call_get_bulk_output_scripts(tx_vouts)
+          body = JSON.generate(txids: tx_vouts.map { |tv| { 'txid' => tv[:txid].to_s, 'vouts' => tv[:vouts] } })
+          default_call(:get_bulk_output_scripts, body: body)
+        end
+
+        # Fetches confirmed UTXOs for multiple addresses in a single request.
+        #
+        # WoC expects +{ "addresses": [...] }+ as the request body.
+        #
+        # @param addresses [Array<String>] list of addresses
+        # @return [Result::Success<Array>, Result::Error]
+        def call_get_bulk_address_utxos(addresses)
+          body = JSON.generate(addresses: addresses)
+          default_call(:get_bulk_address_utxos, body: body)
+        end
+
+        # Fetches unconfirmed UTXOs for multiple addresses in a single request.
+        #
+        # WoC expects +{ "addresses": [...] }+ as the request body.
+        #
+        # @param addresses [Array<String>] list of addresses
+        # @return [Result::Success<Array>, Result::Error]
+        def call_get_bulk_address_unconfirmed_utxos(addresses)
+          body = JSON.generate(addresses: addresses)
+          default_call(:get_bulk_address_unconfirmed_utxos, body: body)
+        end
+
+        # Fetches unconfirmed UTXOs for multiple script hashes in a single request.
+        #
+        # WoC expects +{ "scripts": [...] }+ as the request body.
+        #
+        # @param script_hashes [Array<String>] list of script hashes
+        # @return [Result::Success<Hash>, Result::Error]
+        def call_get_bulk_script_unconfirmed_unspent(script_hashes)
+          body = JSON.generate(scripts: script_hashes)
+          default_call(:get_bulk_script_unconfirmed_unspent, body: body)
+        end
+
+        # Searches WhatsOnChain for links matching a query.
+        #
+        # WoC expects +{ "query": "..." }+ as the request body.
+        #
+        # @param query [String] search term
+        # @return [Result::Success<Hash>, Result::Error]
+        def call_search_links(query)
+          body = JSON.generate(query: query)
+          default_call(:search_links, body: body)
+        end
+
+        # Fetches status for multiple transactions.
+        #
+        # WoC expects +{ "txids": [...] }+ as the request body. When called
+        # with a raw +body:+ keyword the body is forwarded as-is, which
+        # preserves backwards-compatibility with callers that build the body
+        # themselves.
+        #
+        # @param txids [Array<String>, nil] list of transaction IDs (positional)
+        # @param body  [String, nil] pre-serialised request body (keyword)
+        # @return [Result::Success<Array>, Result::Error]
+        # @raise [ArgumentError] when neither txids nor body is provided
+        def call_get_tx_status(txids = nil, body: nil)
+          raise ArgumentError, 'provide txids array or body: keyword' if txids.nil? && body.nil?
+
+          raw_body = body || JSON.generate(txids: txids)
+          default_call(:get_tx_status, body: raw_body)
+        end
+
         # Verifies that a merkle root matches the one recorded for a given
         # block height. Uses the get_block_header endpoint internally.
         #

data/lib/bsv/network/protocols.rb

@@ -9,6 +9,7 @@ module BSV
     module Protocols
       autoload :ARC,         'bsv/network/protocols/arc'
       autoload :Chaintracks, 'bsv/network/protocols/chaintracks'
+      autoload :JungleBus,   'bsv/network/protocols/jungle_bus'
       autoload :Ordinals,    'bsv/network/protocols/ordinals'
       autoload :TAALBinary,  'bsv/network/protocols/taal_binary'
       autoload :WoCREST,     'bsv/network/protocols/woc_rest'

data/lib/bsv/network/provider.rb

@@ -22,17 +22,30 @@ module BSV
     #   result = gorillapool.call(:broadcast, tx)
     #   result.success?  # => true
     class Provider
-      attr_reader :name
+      attr_reader :name, :auth, :rate_limit
 
-      # @param name  [String] human-readable provider name (e.g. 'GorillaPool')
-      # @param block [Proc]   optional configuration block — yields +self+
-      def initialize(name, &block)
+      # @param name       [String]        human-readable provider name (e.g. 'GorillaPool')
+      # @param auth       [Hash, Symbol]  authentication config or +:none+ (default: +:none+).
+      #                                   An empty hash or +nil+ is treated as +:none+.
+      # @param rate_limit [Numeric, nil]  maximum requests per second (+nil+ = unlimited)
+      # @param block      [Proc]          optional configuration block — yields +self+
+      def initialize(name, auth: :none, rate_limit: nil, &block)
         @name           = name
+        @auth           = normalise_auth(auth)
+        @rate_limit     = rate_limit
         @protocols      = []
         @command_index  = {}
         block&.call(self)
       end
 
+      # Returns +true+ when the provider is configured with authentication
+      # credentials (i.e. +auth+ is not +:none+ and not an empty hash).
+      #
+      # @return [Boolean]
+      def authenticated?
+        @auth != :none
+      end
+
       # Registers a protocol class with the provider.
       #
       # The class is instantiated with the supplied +kwargs+. Its commands are
@@ -100,7 +113,9 @@ module BSV
       # @return [String]
       def to_s
         protocol_summary = @protocols.map { |p| p.class.name&.split('::')&.last || p.class.to_s }.join(', ')
-        "#<#{self.class} name=#{@name.inspect} protocols=[#{protocol_summary}]>"
+        auth_status      = authenticated? ? 'authenticated' : 'unauthenticated'
+        rate_part        = @rate_limit.nil? ? '' : " rate_limit=#{@rate_limit}"
+        "#<#{self.class} name=#{@name.inspect} auth=#{auth_status}#{rate_part} protocols=[#{protocol_summary}]>"
       end
       alias inspect to_s
 
@@ -118,6 +133,22 @@ module BSV
 
         instance.call(sym, *args, **kwargs)
       end
+
+      private
+
+      # Normalises the +auth+ argument so that +nil+ and empty hashes are
+      # stored as +:none+, giving a single canonical sentinel value for
+      # "no authentication".
+      #
+      # @param auth [Hash, Symbol, nil]
+      # @return [Hash, Symbol]
+      def normalise_auth(auth)
+        return :none if auth.nil?
+        return :none if auth == :none
+        return :none if auth.is_a?(Hash) && (auth.empty? || (auth[:bearer].nil? && auth[:api_key].nil?))
+
+        auth
+      end
     end
   end
 end