bsv-sdk 0.20.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7066943d0a9d1aa217f1ed97a3dc0390fd5c1bdbad845183bf7ccbc87f582f3
-  data.tar.gz: e4914b71001219c5144433f2481097e141096fcbd82a969f655fe1afae242133
+  metadata.gz: d666b0e5af3155dbe92f4298f5448a5792275848f6e3c08fcc1bbfa09d9a20bd
+  data.tar.gz: c4f3beba29031b049afe90a967b5d982ee473cea57ee077c09ba9c263385c067
 SHA512:
-  metadata.gz: a6497f1705a3e87d5e5cf2e4f7b20150440475463461e3ef15fdb31b33d4a602beb0b2fe30852ea6da3c19c18f44dc4348fbc596008dfd101c3e2ae9de9fccdb
-  data.tar.gz: 21cdf72face3b0748442322a8b506f821432dc72d465a126b410e182e7ca4da17f29573f5b3c999c121ff2e5c4e5d284c790974f825bf547ec2ee36ff1417e5f
+  metadata.gz: ce7d22f5b2267f44909e871e15c619af28e0055db71f84a5fc7529c70c7c030d0314f466d328a2154c476530a6485b19588e09a96ce7ae3f406f29cfd6ec8569
+  data.tar.gz: 46cfee8000801ffd398d659b6174b9ac48cc2e4fc098c93e367634f06cfc9d9c659211ef51c452fd7c83262121e8923c6ab7240588fe01782c3002a6fa4f8075

data/CHANGELOG.md

@@ -5,6 +5,88 @@ 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

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/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/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/transaction/chain_tracker.rb

@@ -10,18 +10,21 @@ module BSV
     # chain tracker is the data source: an object the consumer provides
     # that can answer "is this merkle root valid for this block height?"
     #
-    # The SDK is deliberately unopinionated about where that answer comes
-    # from. A chain tracker backed by an in-memory hash is declarative.
-    # One that fetches from the network on cache miss and writes to a
-    # database is imperative. The verify methods don't care — they just
-    # ask the question. All imperative behaviour (fetching, caching,
-    # persisting) lives in the consumer's chain tracker implementation,
-    # not in the SDK.
+    # This class is a working default implementation that wraps a
+    # {BSV::Network::Provider} and dispatches via {Provider#call}. The
+    # provider must serve the +:get_block_header+ and +:current_height+
+    # commands (e.g. a provider configured with {Protocols::JungleBus}).
+    #
+    # Subclasses may override either or both methods to supply their own
+    # data source (in-memory hash, database cache, etc.) without touching
+    # the provider at all. The +provider+ argument is optional precisely to
+    # preserve this pattern — a subclass that overrides both methods never
+    # reaches the provider-dispatch path.
     #
     # Any object responding to +valid_root_for_height?+ and
     # +current_height+ satisfies this interface. Inheriting from this
     # class is optional — it exists to document the contract and provide
-    # clear error messages when methods are missing.
+    # a ready-to-use provider-backed implementation.
     #
     # @example In-memory chain tracker (test / declarative)
     #   class HashTracker < BSV::Transaction::ChainTracker
@@ -38,23 +41,81 @@ module BSV
     #       header.merkle_root == root
     #     end
     #   end
+    #
+    # @example Provider-backed (default impl)
+    #   tracker = BSV::Transaction::ChainTracker.default
+    #   tracker.valid_root_for_height?('abcd...', 800_000)
+    #
+    # @example Testnet
+    #   tracker = BSV::Transaction::ChainTracker.default(testnet: true)
+    #   tracker.current_height
     class ChainTracker
+      # @return [BSV::Network::Provider, nil] the underlying provider, if any
+      attr_reader :provider
+
+      # Return a default ChainTracker backed by the GorillaPool provider.
+      #
+      # @param testnet [Boolean] when true, uses the testnet provider
+      # @return [ChainTracker]
+      def self.default(testnet: false)
+        new(BSV::Network::Providers::GorillaPool.default(testnet: testnet))
+      end
+
+      # @param provider [BSV::Network::Provider, nil] provider serving +:get_block_header+
+      #   and +:current_height+. Optional when the subclass overrides both methods.
+      def initialize(provider = nil)
+        @provider = provider
+      end
+
       # Verify that a merkle root is valid for the given block height.
       #
+      # Dispatches +:get_block_header+ to the configured provider. Returns +false+
+      # on 404 (block not found). Normalises the merkle root field name from any
+      # of +merkleroot+, +merkleRoot+, or +merkle_root+.
+      #
       # @param root [String] merkle root as a hex string
       # @param height [Integer] block height
       # @return [Boolean] true if the root matches the block at the given height
-      # @raise [NotImplementedError] if not overridden by a subclass
-      def valid_root_for_height?(_root, _height)
-        raise NotImplementedError, "#{self.class}#valid_root_for_height? must be implemented"
+      # @raise [RuntimeError] when no provider is configured
+      # @raise [RuntimeError] on network or API error
+      def valid_root_for_height?(root, height)
+        raise 'ChainTracker requires a provider when used directly' if @provider.nil?
+
+        result = @provider.call(:get_block_header, height)
+        return false if result.http_not_found?
+        raise result.error_message.to_s unless result.http_success?
+
+        actual = normalise_merkle_root(result.data)
+        return false unless actual
+
+        actual.casecmp(root).zero?
       end
 
       # Return the current blockchain height.
       #
+      # Dispatches +:current_height+ to the configured provider.
+      #
       # @return [Integer] the height of the chain tip
-      # @raise [NotImplementedError] if not overridden by a subclass
+      # @raise [RuntimeError] when no provider is configured
+      # @raise [RuntimeError] on network or API error
       def current_height
-        raise NotImplementedError, "#{self.class}#current_height must be implemented"
+        raise 'ChainTracker requires a provider when used directly' if @provider.nil?
+
+        result = @provider.call(:current_height)
+        return result.data if result.http_success?
+
+        raise result.error_message.to_s
+      end
+
+      private
+
+      # Field-name diversity belongs at the Protocols::* layer; this is a
+      # transitional shim until the wire protocols return canonical shapes.
+      # See #791.
+      def normalise_merkle_root(body)
+        return nil unless body.is_a?(Hash)
+
+        body['merkleroot'] || body['merkleRoot'] || body['merkle_root']
       end
     end
   end

data/lib/bsv/transaction/chain_trackers.rb

@@ -5,16 +5,6 @@ module BSV
     # Namespace for chain tracker implementations.
     module ChainTrackers
       autoload :WhatsOnChain, 'bsv/transaction/chain_trackers/whats_on_chain'
-      autoload :Chaintracks,  'bsv/transaction/chain_trackers/chaintracks'
-
-      # Return a default chain tracker backed by the Arcade/GorillaPool Chaintracks API.
-      #
-      # @param testnet [Boolean] use the testnet endpoint when true
-      # @param ** [Hash] forwarded to the underlying tracker (e.g. +api_key:+)
-      # @return [Chaintracks]
-      def self.default(testnet: false, **)
-        Chaintracks.default(testnet: testnet, **)
-      end
     end
   end
 end