bsv-sdk 0.19.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffaea2263b4744cda53ec2ad10f1f842fbd19b6baf07ed0268788a2411a5f42a
-  data.tar.gz: 34ea44a136351a85aa373e6cd8e089dd0cf52d273bf162b3f029f8fd1091448c
+  metadata.gz: d666b0e5af3155dbe92f4298f5448a5792275848f6e3c08fcc1bbfa09d9a20bd
+  data.tar.gz: c4f3beba29031b049afe90a967b5d982ee473cea57ee077c09ba9c263385c067
 SHA512:
-  metadata.gz: 6eb51aad42cb0ff70bd210c01ac8bada4d32ca38ce574ec9d63ef944d6e75f78902974ffcd35eb290260a81efc375d1bac9b40a82ab083bdbdfa5fb541fc10d4
-  data.tar.gz: 87a040c985ef1d70b131db723c58367b67ce7b6d3cc68d42d70e37a74b573fabd9354dcffc521214671f49bb75d2635cbee89fcc4c3870b5da4292587f84854e
+  metadata.gz: ce7d22f5b2267f44909e871e15c619af28e0055db71f84a5fc7529c70c7c030d0314f466d328a2154c476530a6485b19588e09a96ce7ae3f406f29cfd6ec8569
+  data.tar.gz: 46cfee8000801ffd398d659b6174b9ac48cc2e4fc098c93e367634f06cfc9d9c659211ef51c452fd7c83262121e8923c6ab7240588fe01782c3002a6fa4f8075

data/CHANGELOG.md

@@ -5,6 +5,95 @@ All notable changes to the `bsv-sdk` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.22.0 — 2026-05-30
+
+### Added
+- BRC-103 wire layer: `WalletWire` transport abstraction, `WalletWireTransceiver` (client), `WalletWireProcessor` (server), `Substrates::HTTPWalletWire` (binary HTTP transport), and `Substrates::HTTPWalletJSON` (JSON-over-HTTP, MetaNet Desktop compatible)
+- Full BRC-103 serialisers for all 28 BRC-100 methods; wire format compatible with go-sdk byte-for-byte
+- `BSV::Wallet.error_from_wire` helper rehydrates error frames into typed `BSV::Wallet::Error` subclasses (codes 1–7)
+- New guide: `docs/guides/brc-103-wire.md` — end-to-end walkthrough of the wire layer
+- Wire layer reference section added to `docs/sdk/wallet.md`
+- `BSV::Transaction::ChainTracker.default(testnet: false)` — provider-routed chain tracker backed by GorillaPool + JungleBus by default; no credentials required (closes #783)
+- `BSV::Network::Protocols::JungleBus` declares `:current_height` so the GorillaPool provider can satisfy chain-tip queries (#784)
+- `BSV::Network::Providers::GorillaPool.testnet` now registers `Protocols::JungleBus` alongside `Protocols::Arcade` so chain-header lookups work on testnet
+
+### Changed
+- `BSV::Transaction::ChainTracker` is now a working default implementation when constructed with a `Provider`; subclasses that override `valid_root_for_height?` and `current_height` continue to work unchanged (constructor now accepts an optional positional `provider` argument: `ChainTracker.new(provider)`, with `provider = nil` preserved for subclass-only use)
+
+### Removed (breaking)
+- **`BSV::Transaction::ChainTrackers::Chaintracks`** is removed. Migrate to
+  `BSV::Transaction::ChainTracker.default` for general use (GorillaPool), or construct
+  a single-protocol Provider explicitly for own-server use:
+
+  ```ruby
+  own = BSV::Network::Provider.new('local') do |p|
+    p.protocol BSV::Network::Protocols::Chaintracks, base_url: 'http://my-server'
+  end
+  tracker = BSV::Transaction::ChainTracker.new(own)
+  ```
+
+- **`BSV::Transaction::ChainTrackers.default`** (the namespace-level factory method) is
+  removed. Use `BSV::Transaction::ChainTracker.default` (the singular class-level
+  method) instead. The `ChainTrackers` namespace is now a pure autoload container for
+  concrete protocol-specific wrappers; `ChainTracker` (singular) is the porcelain entry
+  point.
+
+- Closes #778 — GorillaPool chaintracks connectivity: chain data is now reachable
+  through the provider via JungleBus; the open question dissolves.
+
+### Note
+- The default `ChainTracker` in the Ruby SDK resolves against GorillaPool/JungleBus,
+  which diverges from the TS SDK (WhatsOnChain) and Go/Python SDK defaults. This
+  reflects the broader pattern of GorillaPool being the default broadcast provider in
+  the Ruby SDK.
+
+## 0.21.0 — 2026-05-29 (not separately released — see 0.22.0)
+
+### Added
+- `Protocols::Arcade` for `bsv-blockchain/arcade` services (run by GorillaPool at
+  `arcade.gorillapool.io`). Commands: `broadcast` (`POST /tx`), `get_tx_status`
+  (`GET /tx/{txid}`), `health` (`GET /health`). Distinct from `Protocols::ARC` —
+  paths, response bodies, and status taxonomies do not overlap. (#775)
+- Shared `BSV::Network::Util` helpers: `safe_parse_json`, `resolve_tx_hex` —
+  available to all protocol classes without copy-paste. (#775)
+
+### Changed
+- `ARC#call_broadcast` and `ARC#call_broadcast_many` now read their broadcast and
+  batch-broadcast paths from the endpoint table rather than hardcoding `/v1/tx` and
+  `/v1/txs`. Behaviour is unchanged; subclasses can now declare a different path. (#775)
+- `LivePolicy.default` now points at `https://arc.taal.com` for fee-policy queries
+  rather than GorillaPool's Arcade endpoint, which does not expose `/v1/policy`. (#775)
+- `broadcast_p2pkh` MCP tool updated to handle Arcade's `{"status": "submitted"}`
+  response shape from GorillaPool. (#775)
+
+### Breaking Changes
+- **`Providers::GorillaPool` no longer registers `Protocols::ARC` or
+  `Protocols::Chaintracks`.** Mainnet now registers `Protocols::Arcade` instead.
+  Consumers calling `provider.call(:broadcast, ...)` against GorillaPool and
+  expecting an ARC-shaped response (`{txid, txStatus, ...}`) must migrate to
+  Arcade's response shape (`{status: "submitted"}`). No compatibility shim is
+  provided — pre-1.0 clean break. (#775)
+- **`BSV_TESTNET_ARC_URL` environment variable renamed to `BSV_TESTNET_ARCADE_URL`.**
+  Update any scripts or CI configuration that set this variable. Default value:
+  `https://testnet.arcade.gorillapool.io`. (#775, #779)
+- **`Providers::GorillaPool` no longer provides `:current_height` or
+  `:get_block_header` commands** (previously routed through the broken
+  `Protocols::Chaintracks` registration). A follow-up issue (#778) tracks correctly
+  wiring GorillaPool's chaintracks_server at its actual separate URL/port.
+
+### Removed
+- `Protocols::Chaintracks` registration from `Providers::GorillaPool` (mainnet and
+  testnet). The registration was broken — GorillaPool's chaintracks_server runs as
+  a separate service on a separate port; the `/chaintracks/v2/` paths were returning
+  404. See #778 for the follow-up to wire it correctly.
+
+## 0.20.0 — 2026-05-24
+
+### Changed
+- Raise minimum Ruby version from 2.7 to 3.3; add Ruby 4.0 to CI matrix
+- Remove Ruby 2.7 compatibility workarounds (Point#add fallback, OpenSSL.fixed_length_secure_compare fallback)
+- Apply RuboCop modernisations unlocked by Ruby 3.3 target (anonymous forwarding, redundant `require 'set'`, `Hash#except`)
+
 ## 0.19.1 — 2026-05-13
 
 ### Fixed

data/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/sgbett/bsv-ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/sgbett/bsv-ruby-sdk/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/sgbett/bsv-ruby-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/sgbett/bsv-ruby-sdk)
 [![Gem Version](https://img.shields.io/gem/v/bsv-sdk)](https://rubygems.org/gems/bsv-sdk)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-red)](https://rubygems.org/gems/bsv-sdk)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-red)](https://rubygems.org/gems/bsv-sdk)
 
 Welcome to the BSV Blockchain Libraries Project, the comprehensive Ruby SDK designed to provide an updated and unified layer for developing scalable applications on the BSV Blockchain. This SDK addresses the limitations of previous tools by offering a fresh, peer-to-peer approach, adhering to SPV, and ensuring privacy and scalability.
 
@@ -44,7 +44,7 @@ Elliptic curve operations (secp256k1) are provided by the [`secp256k1-native`](h
 
 ### Requirements
 
-- Ruby >= 2.7
+- Ruby >= 3.3
 - No external dependencies beyond Ruby's standard library (`openssl` for hashing, HMAC, PBKDF2, and AES)
 
 ### Installation

data/lib/bsv/auth/transport.rb

@@ -37,7 +37,7 @@ module BSV
       #
       # @yieldparam message [Hash] the incoming auth message
       # @return [void]
-      def on_data(&_block)
+      def on_data(&)
         raise NotImplementedError, "#{self.class}#on_data not implemented"
       end
     end

data/lib/bsv/mcp/tools/broadcast_p2pkh.rb

@@ -115,11 +115,13 @@ module BSV
           arc_result = arc.call(:broadcast, tx)
           return Helpers.error_response("Broadcast failed: #{arc_result.message}") unless arc_result.http_success?
 
+          data = arc_result.data || {}
           result = {
-            txid: arc_result.data['txid'], # MCP tool boundary: display-order hex from ARC response
-            tx_status: arc_result.data['txStatus'],
+            txid: data['txid'], # MCP tool boundary: display-order hex from Arcade response (present on re-submission)
+            tx_status: data['status'],
+            state: data['state'],
             hex: tx.to_hex
-          }
+          }.compact
 
           ::MCP::Tool::Response.new(
             [::MCP::Content::Text.new(result.to_json)],

data/lib/bsv/network/protocol.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
 require 'net/http'
 require 'json'
 require 'uri'
@@ -132,11 +131,11 @@ module BSV
       # Subscriptions are not callable; calling one raises +NotImplementedError+.
       #
       # @param command_name [Symbol, String] command to invoke
-      # @param args   [Array]  positional arguments forwarded to path interpolation
+      # @param *      [Array]  positional arguments forwarded to path interpolation
       # @param kwargs [Hash]   keyword arguments forwarded to path interpolation
       # @return [ProtocolResponse]
       # @raise [ArgumentError] when command_name is not registered
-      def call(command_name, *args, **kwargs)
+      def call(command_name, *, **kwargs)
         name = command_name.to_sym
 
         if self.class.subscriptions.key?(name)
@@ -147,10 +146,10 @@ module BSV
         escape = :"call_#{name}"
         if respond_to?(escape, true)
           BSV.logger&.debug { "[Protocol] #{self.class.name} :#{name} → escape hatch" }
-          return kwargs.empty? ? send(escape, *args) : send(escape, *args, **kwargs)
+          return kwargs.empty? ? send(escape, *) : send(escape, *, **kwargs)
         end
 
-        default_call(name, *args, **kwargs)
+        default_call(name, *, **kwargs)
       end
 
       # Dispatches a command directly via HTTP, bypassing any escape hatch.

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

@@ -92,7 +92,7 @@ module BSV
             callback_batch: callback_batch
           )
 
-          response = post_with_headers('/v1/tx', body, extra_headers)
+          response = post_with_headers(self.class.endpoints[:broadcast][:path], body, extra_headers)
           parse_single_broadcast_response(response)
         end
 
@@ -124,7 +124,7 @@ module BSV
             callback_batch: callback_batch
           )
 
-          response = post_with_headers('/v1/txs', body, extra_headers)
+          response = post_with_headers(self.class.endpoints[:broadcast_many][:path], body, extra_headers)
           parse_batch_broadcast_response(response)
         end
 
@@ -135,30 +135,8 @@ module BSV
           request
         end
 
-        # Coerce a transaction input to hex for the ARC JSON body.
-        #
-        # Accepts (in order of preference):
-        # 1. Hex string — pass-through, zero conversion
-        # 2. Binary string — convert to hex
-        # 3. Transaction object — prefer EF hex (BRC-30), fall back to raw hex
-        #
-        # Detection uses content, not encoding: a string is hex if it has even
-        # length and contains only hex characters. This handles hex strings
-        # tagged as ASCII-8BIT (e.g. read from IO in binary mode).
-        #
-        # @param tx [String, #to_ef_hex, #to_hex] transaction in any supported form
-        # @return [String] hex-encoded transaction
         def resolve_tx_hex(tx)
-          if tx.is_a?(String)
-            return tx if tx.match?(/\A[0-9a-fA-F]*\z/) && tx.length.even?
-
-            return tx.unpack1('H*')
-          end
-
-          tx.to_ef_hex
-        rescue ArgumentError => e
-          BSV.logger&.debug { "[ARC] EF serialisation failed: #{e.message} — falling back to raw hex" }
-          tx.to_hex
+          BSV::Network::Util.resolve_tx_hex(tx)
         end
 
         # Build the hash of ARC-specific extra headers.
@@ -296,12 +274,8 @@ module BSV
           false
         end
 
-        # Parse JSON, returning a hash with a 'detail' key on parse failure.
-        # When the raw input is nil or empty the detail is nil (not an empty string).
         def safe_parse_json(raw)
-          JSON.parse(raw.to_s)
-        rescue JSON::ParserError
-          { 'detail' => (raw.to_s.empty? ? nil : raw.to_s) }
+          BSV::Network::Util.safe_parse_json(raw)
         end
       end
     end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module BSV
+  module Network
+    module Protocols
+      # Arcade protocol implementation for submitting transactions to the BSV network.
+      #
+      # Arcade is a sibling to ARC — both subclass Protocol directly. The request
+      # and response shapes diverge enough to rule out a shared abstract base:
+      # Arcade uses a narrower status taxonomy and a different broadcast response
+      # structure (no txid on fresh submission; idempotent re-submit returns
+      # status plus txid plus state).
+      #
+      # == Example
+      #
+      #   arcade = BSV::Network::Protocols::Arcade.new(
+      #     base_url: 'https://arcade.gorillapool.io'
+      #   )
+      #   result = arcade.call(:broadcast, tx)
+      #   result.http_success? # => true
+      #   result.data['status'] # => "submitted"
+      #
+      # @see https://github.com/bsv-blockchain/arcade Arcade repository
+      class Arcade < Protocol
+        # Arcade response statuses that indicate a transaction was NOT accepted.
+        # Narrower than ARC's taxonomy — Arcade has a single explicit rejection signal.
+        REJECTED_STATUSES = %w[REJECTED].freeze
+
+        endpoint :broadcast,     :post, '/tx',        response: :json
+        endpoint :get_tx_status, :get,  '/tx/{txid}', response: :json
+        endpoint :health,        :get,  '/health',    response: :json
+
+        # @param base_url    [String]      Arcade base URL
+        # @param api_key     [String, nil] legacy bearer token shorthand
+        # @param auth        [Hash, Symbol, nil] auth config; takes precedence over +api_key:+
+        # @param network     [String, nil] network name for base URL interpolation
+        # @param http_client [#request, nil] injectable HTTP client for testing
+        # @param callback_url   [String, nil] optional X-CallbackUrl header value
+        # @param callback_token [String, nil] optional X-CallbackToken header value
+        def initialize(base_url:, api_key: nil, auth: nil, network: nil, http_client: nil,
+                       callback_url: nil, callback_token: nil)
+          super(base_url: base_url, api_key: api_key, auth: auth, network: network, http_client: http_client)
+          @callback_url   = callback_url
+          @callback_token = callback_token
+        end
+
+        private
+
+        # Broadcast escape hatch: Arcade-specific headers and response shape.
+        #
+        # @param tx [#to_ef_hex, #to_hex, String] transaction object, hex string,
+        #   or binary string
+        # @param callback_url          [String, nil]
+        # @param callback_token        [String, nil]
+        # @param full_status_updates   [Boolean, nil]
+        # @param skip_fee_validation   [Boolean, nil]
+        # @param skip_script_validation [Boolean, nil]
+        # @return [ProtocolResponse]
+        def call_broadcast(tx, callback_url: nil, callback_token: nil,
+                           full_status_updates: nil, skip_fee_validation: nil,
+                           skip_script_validation: nil, **)
+          hex  = BSV::Network::Util.resolve_tx_hex(tx)
+          body = JSON.generate(rawTx: hex)
+
+          extra_headers = build_broadcast_headers(
+            callback_url: callback_url || @callback_url,
+            callback_token: callback_token || @callback_token,
+            full_status_updates: full_status_updates,
+            skip_fee_validation: skip_fee_validation,
+            skip_script_validation: skip_script_validation
+          )
+
+          path     = self.class.endpoints[:broadcast][:path]
+          uri      = URI("#{@base_url}#{path}")
+          request  = build_request(:post, uri, body)
+          extra_headers.each { |k, v| request[k] = v }
+          response = execute(uri, request)
+
+          parse_broadcast_response(response)
+        end
+
+        # get_tx_status: pass-through to default_call plus rejection check.
+        #
+        # @param txid [String] display-order hex transaction ID
+        # @return [ProtocolResponse]
+        def call_get_tx_status(txid, **)
+          response = default_call(:get_tx_status, txid)
+          return response unless response.http_success?
+
+          body = response.data
+          return response unless body.is_a?(Hash)
+
+          if rejected_status?(body)
+            return response.with(
+              http_success: false,
+              error_message: body['txStatus'] || 'REJECTED'
+            )
+          end
+
+          response
+        end
+
+        def build_broadcast_headers(callback_url:, callback_token:, full_status_updates:,
+                                    skip_fee_validation:, skip_script_validation:)
+          headers = {}
+          headers['X-CallbackUrl']          = callback_url    if callback_url
+          headers['X-CallbackToken']        = callback_token  if callback_token
+          headers['X-FullStatusUpdates']    = 'true'          if full_status_updates
+          headers['X-SkipFeeValidation']    = 'true'          if skip_fee_validation
+          headers['X-SkipScriptValidation'] = 'true'          if skip_script_validation
+          headers
+        end
+
+        def parse_broadcast_response(response)
+          code = response.code.to_i
+
+          if code == 503
+            retry_after = response['Retry-After']
+            msg = retry_after ? "Arcade backpressure; retry after #{retry_after}s" : 'Arcade backpressure'
+            return ProtocolResponse.new(response, http_success: false, error_message: msg)
+          end
+
+          unless (200..299).cover?(code)
+            body = BSV::Network::Util.safe_parse_json(response.body)
+            return ProtocolResponse.new(
+              response,
+              http_success: false,
+              error_message: body.is_a?(Hash) ? (body['reason'] || body['detail'] || "HTTP #{code}") : "HTTP #{code}"
+            )
+          end
+
+          body = BSV::Network::Util.safe_parse_json(response.body)
+
+          unless body.is_a?(Hash)
+            return ProtocolResponse.new(
+              response,
+              http_success: false,
+              error_message: 'Arcade returned a malformed 2xx response'
+            )
+          end
+
+          status = body['status']
+          unless status
+            return ProtocolResponse.new(
+              response,
+              http_success: false,
+              error_message: 'Arcade returned a malformed 2xx response'
+            )
+          end
+
+          ProtocolResponse.new(response, data: body)
+        end
+
+        def rejected_status?(body)
+          tx_status = body['txStatus'].to_s.upcase
+          REJECTED_STATUSES.include?(tx_status)
+        end
+      end
+    end
+  end
+end

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

@@ -16,15 +16,18 @@ module BSV
       #
       # == Usage
       #
-      #   ct = BSV::Network::Protocols::Chaintracks.new(base_url: 'https://arcade.gorillapool.io')
+      #   ct = BSV::Network::Protocols::Chaintracks.new(base_url: 'http://localhost:8080')
       #   result = ct.call(:current_height)
       #   result.data  # => 800000
       #
       #   result = ct.call(:get_block_header, 800_000)
       #   result.data  # => { 'hash' => '...', 'height' => 800000, 'merkleRoot' => '...' }
       #
-      # @note Chaintracks is an internal GorillaPool service; no public API documentation
-      #   is available.
+      # @note No public Chaintracks instance is hosted by major providers — GorillaPool
+      #   serves chain data via JungleBus instead. For general chain-tracking against
+      #   GorillaPool, use the porcelain interface:
+      #   +BSV::Transaction::ChainTracker.new(BSV::Network::Providers::GorillaPool.mainnet)+
+      #   which routes through JungleBus automatically.
       class Chaintracks < Protocol
         endpoint :get_block_header, :get, '/chaintracks/v2/header/height/{height}', response: :json
         endpoint :current_height,   :get, '/chaintracks/v2/tip',

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module BSV
   module Network
     module Protocols
@@ -39,6 +41,10 @@ module BSV
         # Block headers from a given height (supports ?limit=N, max 10000)
         endpoint :get_block_headers, :get, '/v1/block_header/list/{height}', response: :json_array
 
+        # Current chain tip height
+        endpoint :current_height, :get, '/v1/block_header/tip',
+                 response: ->(body) { JSON.parse(body)['height'] }
+
         # @param base_url    [String] base URL for the JungleBus API
         # @param api_key     [String, nil] legacy API key shorthand — use +auth:+ for new code
         # @param auth        [Hash, Symbol, nil] auth config; takes precedence over +api_key:+

data/lib/bsv/network/protocols.rb

@@ -7,6 +7,7 @@ module BSV
     # JungleBus, Ordinals, TAALBinary, and WoCREST.
     module Protocols
       autoload :ARC,         'bsv/network/protocols/arc'
+      autoload :Arcade,      'bsv/network/protocols/arcade'
       autoload :Chaintracks, 'bsv/network/protocols/chaintracks'
       autoload :JungleBus,   'bsv/network/protocols/jungle_bus'
       autoload :Ordinals,    'bsv/network/protocols/ordinals'

data/lib/bsv/network/provider.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
-
 module BSV
   module Network
     # Provider is a named configuration container that hosts one or more Protocol
@@ -56,10 +54,10 @@ module BSV
       # execution.
       #
       # @param klass  [Class]  a Protocol subclass
-      # @param kwargs [Hash]   keyword arguments forwarded to +klass.new+
+      # @param **     [Hash]   keyword arguments forwarded to +klass.new+
       # @return [Protocol] the newly created protocol instance
-      def protocol(klass, **kwargs)
-        instance = klass.new(**kwargs)
+      def protocol(klass, **)
+        instance = klass.new(**)
         @protocols << instance
         klass.commands.each do |cmd|
           @command_index[cmd] ||= instance
@@ -122,16 +120,16 @@ module BSV
       # 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
+      # @param *      [Array]  positional arguments forwarded to the protocol
+      # @param **     [Hash]   keyword arguments forwarded to the protocol
       # @return [ProtocolResponse]
       # @raise [ArgumentError] when no registered protocol serves the command
-      def call(command_name, *args, **kwargs)
+      def call(command_name, *, **)
         sym      = command_name.to_sym
         instance = @command_index[sym]
         raise ArgumentError, "#{@name} does not provide command :#{sym}" unless instance
 
-        instance.call(sym, *args, **kwargs)
+        instance.call(sym, *, **)
       end
 
       private

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

@@ -4,17 +4,18 @@ module BSV
   module Network
     module Providers
       # GorillaPool returns pre-configured Provider instances using the GorillaPool
-      # 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.
+      # Arcade infrastructure for broadcasting, the GorillaPool Ordinals API for
+      # transaction and merkle path lookups, and JungleBus for indexed transaction
+      # data and block headers.
       #
-      # Mainnet composes four protocols:
-      # - ARC at +https://arcade.gorillapool.io+
-      # - Chaintracks at +https://arcade.gorillapool.io+
+      # Mainnet composes three protocols:
+      # - Arcade at +https://arcade.gorillapool.io+
       # - Ordinals at +https://ordinals.gorillapool.io+
       # - JungleBus at +https://junglebus.gorillapool.io+
       #
-      # Testnet provides ARC and Chaintracks at +https://testnet.arcade.gorillapool.io+.
+      # Testnet composes two protocols:
+      # - Arcade at +https://testnet.arcade.gorillapool.io+
+      # - JungleBus at +https://testnet.junglebus.gorillapool.io+
       #
       # == Example
       #
@@ -30,9 +31,9 @@ module BSV
         # Default requests-per-second limit for unauthenticated use.
         DEFAULT_RATE_LIMIT = 3
 
-        # Returns a mainnet Provider configured with ARC, Chaintracks, Ordinals, and JungleBus.
+        # Returns a mainnet Provider configured with Arcade, Ordinals, and JungleBus.
         #
-        # Auth is forwarded to all four protocols so each can authenticate independently.
+        # Auth is forwarded to all three protocols so each can authenticate independently.
         #
         # @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+
@@ -42,16 +43,14 @@ module BSV
           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
+            p.protocol Protocols::Arcade,    base_url: 'https://arcade.gorillapool.io', auth: auth, **opts
+            # TODO: re-register chaintracks_server at separate URL/port — see issue #778
+            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.
-        #
-        # Auth is forwarded to both protocols.
+        # Returns a testnet Provider configured with Arcade only.
         #
         # @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+
@@ -61,8 +60,9 @@ module BSV
           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
+            p.protocol Protocols::Arcade,    base_url: 'https://testnet.arcade.gorillapool.io', auth: auth, **opts
+            p.protocol Protocols::JungleBus, base_url: 'https://testnet.junglebus.gorillapool.io', **common
+            # TODO: re-register chaintracks_server at separate URL/port — see issue #778
           end
         end
 

data/lib/bsv/network/util.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module BSV
+  module Network
+    # Shared utility methods for protocol implementations.
+    module Util
+      # Parse JSON, returning a hash with a 'detail' key on parse failure.
+      # When the raw input is nil or empty the detail is nil (not an empty string).
+      def self.safe_parse_json(raw)
+        JSON.parse(raw.to_s)
+      rescue JSON::ParserError
+        { 'detail' => (raw.to_s.empty? ? nil : raw.to_s) }
+      end
+
+      # Coerce a transaction input to hex.
+      #
+      # Accepts (in order of preference):
+      # 1. Hex string — pass-through, zero conversion
+      # 2. Binary string — convert to hex
+      # 3. Transaction object — prefer EF hex (BRC-30), fall back to raw hex
+      #
+      # Detection uses content, not encoding: a string is hex if it has even
+      # length and contains only hex characters. This handles hex strings
+      # tagged as ASCII-8BIT (e.g. read from IO in binary mode).
+      #
+      # @param tx [String, #to_ef_hex, #to_hex] transaction in any supported form
+      # @return [String] hex-encoded transaction
+      def self.resolve_tx_hex(tx)
+        if tx.is_a?(String)
+          return tx if tx.match?(/\A[0-9a-fA-F]*\z/) && tx.length.even?
+
+          return tx.unpack1('H*')
+        end
+
+        tx.to_ef_hex
+      rescue ArgumentError => e
+        BSV.logger&.debug { "[Network::Util] EF serialisation failed: #{e.message} — falling back to raw hex" }
+        tx.to_hex
+      end
+    end
+  end
+end

data/lib/bsv/network.rb

@@ -8,5 +8,6 @@ module BSV
     autoload :Providers,          'bsv/network/providers'
     autoload :Provider,           'bsv/network/provider'
     autoload :UTXO,               'bsv/network/utxo'
+    autoload :Util,               'bsv/network/util'
   end
 end

data/lib/bsv/overlay/lookup_resolver.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
 require 'uri'
 
 module BSV

data/lib/bsv/overlay/topic_broadcaster.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
 require 'json'
 require 'uri'