bsv-sdk 0.12.1 → 0.14.0

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module BSV
+  module Network
+    module Protocols
+      # Chaintracks implements the GorillaPool Chaintracks API as a Protocol subclass.
+      #
+      # Provides block header lookup and current chain tip height via the
+      # GorillaPool Chaintracks v2 REST API. Pure DSL — no escape hatches needed.
+      #
+      # Chaintracks does not use a +{network}+ placeholder in the URL. Mainnet
+      # and testnet are served from separate base URLs; the provider defaults
+      # supply the correct URL for each network.
+      #
+      # == Usage
+      #
+      #   ct = BSV::Network::Protocols::Chaintracks.new(base_url: 'https://arcade.gorillapool.io')
+      #   result = ct.call(:current_height)
+      #   result.data  # => 800000
+      #
+      #   result = ct.call(:get_block_header, 800_000)
+      #   result.data  # => { 'hash' => '...', 'height' => 800000, 'merkleRoot' => '...' }
+      class Chaintracks < Protocol
+        endpoint :get_block_header, :get, '/chaintracks/v2/header/height/{height}', response: :json
+        endpoint :current_height,   :get, '/chaintracks/v2/tip',
+                 response: ->(body) { JSON.parse(body)['height'] }
+
+        # @param base_url    [String] base URL for the Chaintracks API
+        # @param api_key     [String, nil] optional Bearer API key
+        # @param http_client [Object, nil] injectable HTTP client for testing
+        def initialize(base_url:, api_key: nil, http_client: nil)
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # == 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 = ord.call(:get_merkle_path, 'abc123...')
+      #   result.data  # => { 'index' => 0, 'path' => [...] }
+      class Ordinals < Protocol
+        endpoint :get_tx,          :get, '/api/tx/{txid}/hex'
+        endpoint :get_merkle_path, :get, '/api/tx/{txid}/proof', response: :json
+
+        # @param base_url    [String] base URL for the Ordinals API
+        # @param api_key     [String, nil] optional Bearer API key
+        # @param http_client [Object, nil] injectable HTTP client for testing
+        def initialize(base_url:, api_key: nil, http_client: nil)
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module BSV
+  module Network
+    module Protocols
+      # TAALBinary implements the TAAL broadcast API using raw binary transaction
+      # submission over HTTP.
+      #
+      # TAAL quirks handled here:
+      # - Content-Type is +application/octet-stream+ (not JSON)
+      # - Authorization header uses the API key directly with no "Bearer" prefix
+      # - A response containing +txn-already-known+ in the error field is treated
+      #   as success (the transaction is already in the mempool — idempotent)
+      #
+      # == Example
+      #
+      #   protocol = BSV::Network::Protocols::TAALBinary.new(
+      #     base_url: 'https://api.taal.com',
+      #     api_key: 'mainnet_your_key_here'
+      #   )
+      #   result = protocol.call(:broadcast, tx)
+      #   puts result.data[:txid] if result.success?
+      class TAALBinary < BSV::Network::Protocol
+        endpoint :broadcast, :post, '/api/v1/broadcast', response: :json
+
+        private
+
+        # Escape hatch for broadcast: sends raw binary transaction bytes with
+        # TAAL-specific headers and applies TAAL-specific response quirk handling.
+        #
+        # @param tx [#to_binary, String] transaction object or raw binary string
+        # @return [Result::Success, Result::Error]
+        def call_broadcast(tx)
+          body = tx.respond_to?(:to_binary) ? tx.to_binary : tx
+
+          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.body = body
+
+          response = execute(uri, request)
+          parse_broadcast_response(response)
+        end
+
+        # Maps the HTTP response from TAAL broadcast to a Result, applying the
+        # +txn-already-known+ idempotency quirk.
+        #
+        # @param response [Net::HTTPResponse]
+        # @return [Result::Success, Result::Error]
+        def parse_broadcast_response(response)
+          code = response.code.to_i
+          body = parse_json_body(response.body)
+
+          return Result::Success.new(data: { txid: body['txid'] }) if already_known?(body) && body['txid']
+
+          retryable = code == 429 || (500..599).cover?(code)
+
+          if (200..299).cover?(code)
+            return Result::Error.new(message: 'TAAL returned a malformed 2xx response', retryable: false) unless body['txid']
+
+            Result::Success.new(data: { txid: body['txid'] })
+          else
+            message = (body.is_a?(Hash) && body['error']) || "HTTP #{code}"
+            Result::Error.new(message: message, retryable: retryable)
+          end
+        end
+
+        # Returns true when the response body indicates the transaction is already
+        # known to the network — TAAL treats this as a non-error.
+        #
+        # @param body [Hash, nil]
+        # @return [Boolean]
+        def already_known?(body)
+          body.is_a?(Hash) &&
+            body['error'].is_a?(String) &&
+            body['error'].include?('txn-already-known')
+        end
+
+        # Parses a JSON response body, returning an empty Hash on failure or nil input.
+        #
+        # Always returns a Hash so callers can safely index the result without
+        # a nil-guard.
+        #
+        # @param raw [String, nil]
+        # @return [Hash]
+        def parse_json_body(raw)
+          return {} if raw.nil? || raw.empty?
+
+          parsed = JSON.parse(raw)
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue JSON::ParserError
+          {}
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module BSV
+  module Network
+    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.
+      #
+      # == Network resolution
+      #
+      # WoC uses +main+ and +test+ in its URL paths. The constructor accepts
+      # symbolic aliases (:mainnet, :testnet, :stn) and resolves them to the
+      # correct string.
+      #
+      # == Usage
+      #
+      #   woc = BSV::Network::Protocols::WoCREST.new(network: :main)
+      #   result = woc.call(:get_tx, 'abc123...')
+      #   puts result.data if result.success?
+      class WoCREST < Protocol
+        NETWORKS = {
+          'main' => 'main',
+          'test' => 'test',
+          'stn' => 'stn',
+          main: 'main',
+          test: 'test',
+          stn: 'stn',
+          mainnet: 'main',
+          testnet: 'test'
+        }.freeze
+
+        # Chain
+        endpoint :current_height,   :get, '/chain/info',
+                 response: ->(body) { JSON.parse(body)['blocks'] }
+        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
+
+        # Transaction
+        endpoint :get_tx,            :get,  '/tx/{txid}/hex'
+        endpoint :get_tx_details,    :get,  '/tx/hash/{txid}', response: :json
+        endpoint :get_output_script, :get,  '/tx/{txid}/out/{index}/hex'
+        endpoint :get_opreturn,      :get,  '/tx/{txid}/opreturn', response: :json
+        endpoint :get_merkle_path,   :get,  '/tx/{txid}/proof/tsc', response: :json
+        endpoint :broadcast,         :post, '/tx/raw'
+        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
+
+        # UTXO / spent status
+        endpoint :get_utxos,        :get,  '/address/{address}/confirmed/unspent',
+                 response: :json_array
+        endpoint :get_utxos_all,    :get,  '/address/{address}/unspent',
+                 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
+
+        # Script
+        endpoint :get_script_unspent,     :get,  '/script/{script_hash}/confirmed/unspent',
+                 response: :json_array
+        endpoint :get_script_history,     :get,  '/script/{script_hash}/confirmed/history',
+                 response: :json_array
+        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
+
+        # Address balance / history
+        endpoint :get_balance,             :get, '/address/{address}/confirmed/balance',
+                 response: :json
+        endpoint :get_unconfirmed_balance, :get, '/address/{address}/unconfirmed/balance',
+                 response: :json
+        endpoint :get_history,             :get, '/address/{address}/confirmed/history',
+                 response: :json_array
+        endpoint :is_address_used,         :get, '/address/{address}/used', response: :json
+
+        # Exchange rate / fees / mempool
+        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
+
+        # Health
+        endpoint :health, :get, '/health'
+
+        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 http_client [Object, nil] injectable HTTP client for testing
+        def initialize(base_url:, network: :main, api_key: nil, http_client: nil)
+          @network_name = resolve_network(network)
+          super(
+            base_url: base_url,
+            api_key: api_key,
+            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.
+        #
+        # @param network [Symbol, String]
+        # @return [String] 'main', 'test', or 'stn'
+        # @raise [ArgumentError] when the network value is not recognised
+        def resolve_network(network)
+          NETWORKS.fetch(network) do
+            raise ArgumentError, "unknown network: #{network.inspect}"
+          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.
+        # The +script_hash:+ keyword is accepted for future fallback support
+        # but not used in this implementation.
+        #
+        # @param txid        [String]  transaction ID
+        # @param vout        [Integer] output index
+        # @param script_hash [String, nil] ignored
+        # @return [Result::Success<Boolean>, Result::Error, Result::NotFound]
+        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
+
+          spent = result.data['spent']
+          Result::Success.new(data: !spent)
+        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.
+        # Entries absent from the response (unknown outputs) are treated as spent.
+        #
+        # @param outpoints [Array<Hash>] array of +{ txid:, vout: }+ hashes
+        # @return [Result::Success<Hash{String => Boolean}>, Result::Error]
+        #   On success, data is a hash mapping +"txid.vout"+ keys to booleans
+        #   (+true+ = unspent, +false+ = spent).
+        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 } })
+          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')
+
+            key = "#{entry['txid']}.#{entry['vout']}"
+            spent_map[key] = entry['spent']
+          end
+
+          normalised = outpoints.each_with_object({}) do |op, h|
+            key = "#{op[:txid]}.#{op[:vout]}"
+            h[key] = spent_map.key?(key) ? !spent_map[key] : false
+          end
+
+          Result::Success.new(data: normalised)
+        end
+
+        # Broadcasts a raw transaction to WhatsOnChain.
+        #
+        # WoC expects the body as +{ txhex: "..." }+ (JSON). On success it
+        # returns the txid as a plain-text string (not JSON). The response is
+        # stripped and wrapped in a Hash for caller convenience.
+        #
+        # @param tx [#to_hex, String] transaction object or raw hex string
+        # @return [Result::Success<{ txid: String }>, Result::Error]
+        def call_broadcast(tx)
+          hex  = tx.respond_to?(:to_hex) ? tx.to_hex : tx.to_s
+          body = JSON.generate(txhex: hex)
+
+          result = default_call(:broadcast, body: body)
+          return result unless result.success?
+
+          # WoC returns plain-text txid — result.data is the raw body string
+          Result::Success.new(data: { txid: result.data.to_s.strip })
+        end
+
+        # Decodes a raw transaction hex by posting to the WoC decode endpoint.
+        #
+        # WoC expects the body as +{ txhex: "..." }+ (JSON) and returns a
+        # full decoded transaction object.
+        #
+        # @param txhex [String] raw transaction hex string
+        # @return [Result::Success<Hash>, Result::Error]
+        def call_decode_tx(txhex)
+          body = JSON.generate(txhex: txhex.to_s)
+          default_call(:decode_tx, body: body)
+        end
+
+        # Fetches raw hex for multiple transactions in a single request.
+        #
+        # WoC expects a bare JSON array of txid strings 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)
+          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.
+        #
+        # @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)
+          default_call(:get_script_unspent_bulk, body: body)
+        end
+
+        # Verifies that a merkle root matches the one recorded for a given
+        # block height. Uses the get_block_header endpoint internally.
+        #
+        # Comparison is case-insensitive to tolerate mixed-case hex from
+        # different providers.
+        #
+        # @param root   [String]  expected merkle root as hex
+        # @param height [Integer] block height
+        # @return [Result::Success<Boolean>, Result::Error, Result::NotFound]
+        def call_valid_root(root, height)
+          result = default_call(:valid_root, height)
+          return result unless result.success?
+
+          actual = result.data['merkleroot']
+          Result::Success.new(data: actual.to_s.downcase == root.to_s.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/bsv/network/protocols.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module BSV
+  module Network
+    # Protocols is a namespace module for concrete Protocol subclasses.
+    #
+    # Protocol implementations (e.g. ARC, WhatsOnChain adapters built on
+    # the Protocol base class) will be autoloaded here in Phase B.
+    module Protocols
+      autoload :ARC,         'bsv/network/protocols/arc'
+      autoload :Chaintracks, 'bsv/network/protocols/chaintracks'
+      autoload :Ordinals,    'bsv/network/protocols/ordinals'
+      autoload :TAALBinary,  'bsv/network/protocols/taal_binary'
+      autoload :WoCREST,     'bsv/network/protocols/woc_rest'
+    end
+  end
+end

data/lib/bsv/network/provider.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module BSV
+  module Network
+    # Provider is a named configuration container that hosts one or more Protocol
+    # instances and dispatches commands to the appropriate protocol.
+    #
+    # Protocols are registered via a block DSL or by calling +#protocol+ directly
+    # after construction. For each command symbol, the first-registered protocol
+    # that serves it wins (first-registered-wins, no warning on duplicates).
+    #
+    # == Example
+    #
+    #   gorillapool = BSV::Network::Provider.new('GorillaPool') do |p|
+    #     p.protocol Protocols::ARC,         base_url: 'https://arcade.gorillapool.io'
+    #     p.protocol Protocols::Chaintracks, base_url: 'https://arcade.gorillapool.io'
+    #     p.protocol Protocols::Ordinals,    base_url: 'https://ordinals.gorillapool.io'
+    #   end
+    #
+    #   result = gorillapool.call(:broadcast, tx)
+    #   result.success?  # => true
+    class Provider
+      attr_reader :name
+
+      # @param name  [String] human-readable provider name (e.g. 'GorillaPool')
+      # @param block [Proc]   optional configuration block — yields +self+
+      def initialize(name, &block)
+        @name           = name
+        @protocols      = []
+        @command_index  = {}
+        block&.call(self)
+      end
+
+      # Registers a protocol class with the provider.
+      #
+      # The class is instantiated with the supplied +kwargs+. Its commands are
+      # indexed: each command not yet in the index is mapped to this instance.
+      # Commands already in the index are left unchanged (first-registered wins).
+      #
+      # The provider remains mutable — +protocol+ may be called after block
+      # execution.
+      #
+      # @param klass  [Class]  a Protocol subclass
+      # @param kwargs [Hash]   keyword arguments forwarded to +klass.new+
+      # @return [Protocol] the newly created protocol instance
+      def protocol(klass, **kwargs)
+        instance = klass.new(**kwargs)
+        @protocols << instance
+        klass.commands.each do |cmd|
+          @command_index[cmd] ||= instance
+        end
+        instance
+      end
+
+      # Returns a frozen copy of the registered protocol instances, in
+      # registration order.
+      #
+      # @return [Array<Protocol>]
+      def protocols
+        @protocols.dup.freeze
+      end
+
+      # Returns the set of all command symbols available on this provider.
+      #
+      # @return [Set<Symbol>]
+      def commands
+        Set.new(@command_index.keys)
+      end
+
+      # Returns the protocol instance that serves a given command, or nil if no
+      # registered protocol handles it.
+      #
+      # @param command_name [Symbol, String]
+      # @return [Protocol, nil]
+      def protocol_for(command_name)
+        @command_index[command_name.to_sym]
+      end
+
+      # Returns a hash mapping each protocol instance to the sorted list of
+      # commands it actually serves within this provider (respecting
+      # first-registered-wins — a protocol that lost a command to an earlier
+      # registration is not listed for that command).
+      #
+      # Protocols that serve no commands in this provider are omitted.
+      #
+      # @return [Hash{Protocol => Array<Symbol>}]
+      def capability_matrix
+        matrix = {}
+        @protocols.each do |proto|
+          served = proto.class.commands.select { |cmd| @command_index[cmd] == proto }
+          matrix[proto] = served.sort unless served.empty?
+        end
+        matrix
+      end
+
+      # Returns a human-readable representation of the provider.
+      #
+      # @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}]>"
+      end
+      alias inspect to_s
+
+      # Dispatches a command to the first-registered protocol that serves it.
+      #
+      # @param command_name [Symbol, String] command to invoke
+      # @param args   [Array]  positional arguments forwarded to the protocol
+      # @param kwargs [Hash]   keyword arguments forwarded to the protocol
+      # @return [Result::Success, Result::Error, Result::NotFound]
+      # @raise [ArgumentError] when no registered protocol serves the command
+      def call(command_name, *args, **kwargs)
+        sym      = command_name.to_sym
+        instance = @command_index[sym]
+        raise ArgumentError, "#{@name} does not provide command :#{sym}" unless instance
+
+        instance.call(sym, *args, **kwargs)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # Mainnet composes three protocols:
+      # - ARC at +https://arcade.gorillapool.io+
+      # - Chaintracks at +https://arcade.gorillapool.io+
+      # - Ordinals at +https://ordinals.gorillapool.io+
+      #
+      # Testnet provides ARC only 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.call(:broadcast, tx)
+      class GorillaPool
+        # Returns a mainnet Provider configured with ARC, Chaintracks, and Ordinals.
+        #
+        # @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
+            p.protocol Protocols::Chaintracks, base_url: 'https://arcade.gorillapool.io', **common
+            p.protocol Protocols::Ordinals,    base_url: 'https://ordinals.gorillapool.io', **common
+          end
+        end
+
+        # Returns a testnet Provider configured with ARC and Chaintracks.
+        #
+        # @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
+            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
+        # @return [Provider]
+        def self.default(testnet: false, **opts)
+          testnet ? testnet(**opts) : mainnet(**opts)
+        end
+      end
+    end
+  end
+end