bsv-sdk 0.17.0 → 0.18.0

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

@@ -4,56 +4,78 @@ module BSV
   module Network
     module Providers
       # GorillaPool returns pre-configured Provider instances using the GorillaPool
-      # ARCADE infrastructure for ARC and Chaintracks, and the GorillaPool Ordinals
-      # API for transaction and merkle path lookups.
+      # ARCADE infrastructure for ARC and Chaintracks, the GorillaPool Ordinals
+      # API for transaction and merkle path lookups, and JungleBus for indexed
+      # transaction data and block headers.
       #
-      # Mainnet composes three protocols:
+      # Mainnet composes four protocols:
       # - ARC at +https://arcade.gorillapool.io+
       # - Chaintracks at +https://arcade.gorillapool.io+
       # - Ordinals at +https://ordinals.gorillapool.io+
+      # - JungleBus at +https://junglebus.gorillapool.io+
       #
-      # Testnet provides ARC only at +https://testnet.arcade.gorillapool.io+.
+      # Testnet provides ARC and Chaintracks at +https://testnet.arcade.gorillapool.io+.
       #
       # == Example
       #
       #   provider = BSV::Network::Providers::GorillaPool.mainnet
       #   provider.call(:broadcast, tx)
       #
-      #   provider = BSV::Network::Providers::GorillaPool.testnet(api_key: 'my-key')
+      #   provider = BSV::Network::Providers::GorillaPool.mainnet(auth: { bearer: 'token' })
       #   provider.call(:broadcast, tx)
+      #
+      #   # Legacy api_key: shorthand — still supported
+      #   provider = BSV::Network::Providers::GorillaPool.testnet(api_key: 'my-key')
       class GorillaPool
-        # Returns a mainnet Provider configured with ARC, Chaintracks, and Ordinals.
+        # Default requests-per-second limit for unauthenticated use.
+        DEFAULT_RATE_LIMIT = 3
+
+        # Returns a mainnet Provider configured with ARC, Chaintracks, Ordinals, and JungleBus.
+        #
+        # Auth is forwarded to all four protocols so each can authenticate independently.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @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('GorillaPool') do |p|
-            p.protocol Protocols::ARC,         base_url: 'https://arcade.gorillapool.io', **opts
+        def self.mainnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { bearer: opts[:api_key] } : :none)
+          common = opts.slice(:api_key, :http_client).merge(auth: auth)
+          Provider.new('GorillaPool', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::ARC,         base_url: 'https://arcade.gorillapool.io', auth: auth, **opts
             p.protocol Protocols::Chaintracks, base_url: 'https://arcade.gorillapool.io', **common
             p.protocol Protocols::Ordinals,    base_url: 'https://ordinals.gorillapool.io', **common
+            p.protocol Protocols::JungleBus,   base_url: 'https://junglebus.gorillapool.io', **common
           end
         end
 
         # Returns a testnet Provider configured with ARC and Chaintracks.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # Auth is forwarded to both protocols.
+        #
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to each protocol constructor
         # @return [Provider]
-        def self.testnet(**opts)
-          common = opts.slice(:api_key, :http_client)
-          Provider.new('GorillaPool') do |p|
-            p.protocol Protocols::ARC,         base_url: 'https://testnet.arcade.gorillapool.io', **opts
+        def self.testnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { bearer: opts[:api_key] } : :none)
+          common = opts.slice(:api_key, :http_client).merge(auth: auth)
+          Provider.new('GorillaPool', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::ARC,         base_url: 'https://testnet.arcade.gorillapool.io', auth: auth, **opts
             p.protocol Protocols::Chaintracks, base_url: 'https://testnet.arcade.gorillapool.io', **common
           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
+        # @param testnet    [Boolean] when true, returns the testnet Provider
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to each protocol constructor
         # @return [Provider]
-        def self.default(testnet: false, **opts)
-          testnet ? testnet(**opts) : mainnet(**opts)
+        def self.default(testnet: false, auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          kwargs = { auth: auth, rate_limit: rate_limit, **opts }
+          testnet ? testnet(**kwargs) : mainnet(**kwargs)
         end
       end
     end

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

@@ -14,42 +14,65 @@ module BSV
       # To use TAALBinary directly, call +provider.protocol_for(:broadcast)+ on the
       # TAALBinary instance via +provider.protocols.last+, or build a custom Provider.
       #
+      # TAAL requires an API key for production use. The default rate limit is +nil+
+      # (unconstrained) because the effective limit depends on the subscription tier.
+      #
       # 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 = BSV::Network::Providers::TAAL.mainnet(auth: { bearer: 'mainnet_...' })
       #   provider.call(:broadcast, tx)
+      #
+      #   # Legacy api_key: shorthand — still supported
+      #   provider = BSV::Network::Providers::TAAL.mainnet(api_key: 'mainnet_...')
       class TAAL
+        # Default requests-per-second limit.
+        # +nil+ because the effective limit depends on the TAAL subscription tier.
+        DEFAULT_RATE_LIMIT = nil
+
         # Returns a mainnet Provider configured with ARC and TAALBinary.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # Auth is forwarded to both protocols. ARC uses Bearer tokens;
+        # TAALBinary uses raw API keys. Each protocol's constructor handles
+        # the translation appropriate to its endpoint.
+        #
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+ (nil)
+        # @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
+        def self.mainnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { bearer: opts[:api_key] } : :none)
+          common = opts.slice(:api_key, :http_client).merge(auth: auth)
+          Provider.new('TAAL', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::ARC,        base_url: 'https://arc.taal.com',  auth: auth, **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
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and ARC protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+ (nil)
+        # @param opts       [Hash] keyword arguments forwarded to the ARC 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
+        def self.testnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { bearer: opts[:api_key] } : :none)
+          Provider.new('TAAL', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::ARC, base_url: 'https://arc-test.taal.com', auth: auth, **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
+        # @param testnet    [Boolean] when true, returns the testnet Provider
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+ (nil)
+        # @param opts       [Hash] keyword arguments forwarded to each protocol constructor
         # @return [Provider]
-        def self.default(testnet: false, **opts)
-          testnet ? testnet(**opts) : mainnet(**opts)
+        def self.default(testnet: false, auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          kwargs = { auth: auth, rate_limit: rate_limit, **opts }
+          testnet ? testnet(**kwargs) : mainnet(**kwargs)
         end
       end
     end

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

@@ -15,55 +15,76 @@ module BSV
       #   provider = BSV::Network::Providers::WhatsOnChain.mainnet
       #   provider.call(:get_tx, 'abc123...')
       #
-      #   provider = BSV::Network::Providers::WhatsOnChain.testnet(api_key: 'my-key')
+      #   provider = BSV::Network::Providers::WhatsOnChain.mainnet(auth: { api_key: 'my-key' })
       #   provider.call(:broadcast, tx)
+      #
+      #   # Legacy api_key: shorthand — still supported
+      #   provider = BSV::Network::Providers::WhatsOnChain.testnet(api_key: 'my-key')
       class WhatsOnChain
+        # Default requests-per-second limit for unauthenticated use.
+        DEFAULT_RATE_LIMIT = 3
+
         # Returns a mainnet Provider configured with WoCREST.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and WoCREST protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to the WoCREST 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
+        def self.mainnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { api_key: opts[:api_key] } : :none)
+          Provider.new('WhatsOnChain', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/main',
+                                           auth: auth, **opts
           end
         end
 
         # Returns a testnet Provider configured with WoCREST.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and WoCREST protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to the WoCREST 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
+        def self.testnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { api_key: opts[:api_key] } : :none)
+          Provider.new('WhatsOnChain', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/test',
+                                           auth: auth, **opts
           end
         end
 
         # Returns a Provider for the BSV Scaling Test Network (STN).
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and WoCREST protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to the WoCREST 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
+        def self.stn(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { api_key: opts[:api_key] } : :none)
+          Provider.new('WhatsOnChain', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/stn',
+                                           auth: auth, **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
+        # @param testnet    [Boolean] when true, returns the testnet Provider
+        # @param network    [Symbol, nil] explicit network (:main, :test, :stn) — overrides +testnet:+
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and WoCREST protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to the WoCREST protocol constructor
         # @return [Provider]
-        def self.default(testnet: false, network: nil, **opts)
+        def self.default(testnet: false, network: nil, auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          kwargs = { auth: auth, rate_limit: rate_limit, **opts }
           if network
             case network.to_sym
-            when :main, :mainnet then mainnet(**opts)
-            when :test, :testnet then testnet(**opts)
-            when :stn then stn(**opts)
+            when :main, :mainnet then mainnet(**kwargs)
+            when :test, :testnet then testnet(**kwargs)
+            when :stn then stn(**kwargs)
             else raise ArgumentError, "unknown network: #{network}"
             end
           else
-            testnet ? testnet(**opts) : mainnet(**opts)
+            testnet ? testnet(**kwargs) : mainnet(**kwargs)
           end
         end
       end

data/lib/bsv/network/utxo.rb

@@ -5,10 +5,16 @@ module BSV
     class UTXO
       attr_reader :tx_hash, :tx_pos, :satoshis, :height
 
-      def initialize(tx_hash:, tx_pos:, satoshis:, height: nil)
+      # @param tx_hash  [String]  transaction ID
+      # @param tx_pos   [Integer] output index
+      # @param satoshis [Integer] output value in satoshis (accepts +value+ as alias)
+      # @param height   [Integer, nil] block height (0 or nil = unconfirmed)
+      def initialize(tx_hash:, tx_pos:, satoshis: nil, value: nil, height: nil)
         @tx_hash = tx_hash
         @tx_pos = tx_pos
-        @satoshis = satoshis
+        @satoshis = satoshis || value
+        raise ArgumentError, 'satoshis or value is required' if @satoshis.nil?
+
         @height = height
       end
 

data/lib/bsv/overlay/lookup_resolver.rb

@@ -203,7 +203,7 @@ module BSV
 
         # Get the last (subject) transaction — typically the most recent entry
         beef_tx = beef.transactions.last
-        return nil unless beef_tx&.transaction
+        return nil if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
 
         tx     = beef_tx.transaction
         txout  = tx.outputs[output_index]
@@ -334,17 +334,17 @@ module BSV
         beef_data    = output['beef'] || output[:beef]
         output_index = (output['outputIndex'] || output[:output_index] || 0).to_i
 
-        # Overlay API boundary: outpoint key uses display-order txid bytes (via Transaction#txid)
-        txid =
+        # Overlay API boundary: outpoint key uses display-order hex txid
+        dtxid_hex =
           begin
             beef = parse_beef(beef_data)
             last = beef&.transactions&.last
-            last&.transaction&.txid
+            last&.dtxid
           rescue StandardError
             nil
           end
 
-        txid ? "#{txid}.#{output_index}" : output.object_id.to_s
+        dtxid_hex ? "#{dtxid_hex}.#{output_index}" : output.object_id.to_s
       end
 
       # ---- Validation ----

data/lib/bsv/overlay/topic_broadcaster.rb

@@ -199,7 +199,7 @@ module BSV
         return nil unless beef
 
         beef_tx = beef.transactions.last
-        return nil unless beef_tx&.transaction
+        return nil if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
 
         tx    = beef_tx.transaction
         txout = tx.outputs[output_index]

data/lib/bsv/overlay/types.rb

@@ -102,6 +102,7 @@ module BSV
       # @param description [String, nil]
       def initialize(status:, txid: nil, message: nil, code: nil, description: nil)
         @status = status
+        BSV::Primitives::Hex.validate_dtxid_hex!(txid, name: 'overlay broadcast txid') if txid
         @txid = txid
         @message = message
         @code = code

data/lib/bsv/registry/client.rb

@@ -406,21 +406,21 @@ module BSV
         return nil if output_idx.negative? || beef_raw.nil?
 
         beef = BSV::Transaction::Beef.from_binary(beef_raw)
-        tx   = beef.transactions.last&.transaction
-        return nil unless tx
+        beef_tx = beef.transactions.last
+        return nil if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
 
-        locking_script = tx.outputs[output_idx]&.locking_script
+        locking_script = beef_tx.transaction.outputs[output_idx]&.locking_script
         return nil unless locking_script
 
         definition_data = parse_locking_script(definition_type, locking_script)
 
         RegisteredDefinition.new(
           definition_data: definition_data,
-          txid: tx.txid_hex, # Registry API boundary: display-order hex txid
+          txid: beef_tx.transaction.txid_hex, # Registry API boundary: display-order hex txid
           output_index: output_idx,
           locking_script: locking_script.to_hex,
           beef: beef_raw,
-          satoshis: tx.outputs[output_idx].satoshis
+          satoshis: beef_tx.transaction.outputs[output_idx].satoshis
         )
       end
 
@@ -439,10 +439,10 @@ module BSV
         txid, output_idx_str = outpoint_str.split('.')
         output_idx = output_idx_str.to_i
 
-        tx = beef.transactions.last&.transaction
-        return nil unless tx
+        beef_tx = beef.transactions.last
+        return nil if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
 
-        locking_script = tx.outputs[output_idx]&.locking_script
+        locking_script = beef_tx.transaction.outputs[output_idx]&.locking_script
         return nil unless locking_script
 
         definition_data = parse_locking_script(definition_type, locking_script)

data/lib/bsv/registry/types.rb

@@ -217,6 +217,7 @@ module BSV
       def initialize(definition_data:, txid:, output_index:, locking_script:, beef:, satoshis: 1)
         @definition_data = definition_data
         @definition_type = definition_data.definition_type
+        BSV::Primitives::Hex.validate_dtxid_hex!(txid, name: 'registry definition txid')
         @txid            = txid
         @output_index    = output_index
         @locking_script  = locking_script