bsv-sdk 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d666b0e5af3155dbe92f4298f5448a5792275848f6e3c08fcc1bbfa09d9a20bd
-  data.tar.gz: c4f3beba29031b049afe90a967b5d982ee473cea57ee077c09ba9c263385c067
+  metadata.gz: 5545794c00575e8bb9ce8ad04e6e156c435a9ed984e43a99db86e85d9d9648cb
+  data.tar.gz: 197daaa1e748ee650192920494a610d9f5aac6dcc43038eceb73c17991ba67f0
 SHA512:
-  metadata.gz: ce7d22f5b2267f44909e871e15c619af28e0055db71f84a5fc7529c70c7c030d0314f466d328a2154c476530a6485b19588e09a96ce7ae3f406f29cfd6ec8569
-  data.tar.gz: 46cfee8000801ffd398d659b6174b9ac48cc2e4fc098c93e367634f06cfc9d9c659211ef51c452fd7c83262121e8923c6ab7240588fe01782c3002a6fa4f8075
+  metadata.gz: 4382cc39a0c07227ba143554943fe66dedb9deaf5b7275ab82731417c4b9150fcfce27dd689b456db374cfdc7d6d4bd7c58238c00219b928332f6b19e0c24041
+  data.tar.gz: c6549c97011519d2d0ad8b4856df12fcc72311ff1a9800ec19b9e0d97d10355322f3216fb3c52a4c10b11bad3196b8ec01dd901a10e219d9cce3fd6ecd4a5770

data/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.23.0 — 2026-06-03
+
+### Changed (breaking)
+- **Canonical block-header response shape across protocols.** `Protocols::JungleBus`,
+  `Protocols::Chaintracks`, and `Protocols::WoCREST` now emit the merkle root as
+  `'merkle_root'` (lowercase snake_case) in their `:get_block_header` and
+  `:get_block_headers` responses, replacing the upstream-specific names
+  (`'merkleroot'` for JungleBus/WoCREST, `'merkleRoot'` for Chaintracks). Consumers
+  reading the raw field directly from `provider.call(:get_block_header).data` must
+  migrate to the canonical key. Wire protocols stay honest about other fields;
+  only the merkle-root key is renamed. No shim. (#791)
+- `WoCREST#:valid_root` now reads the normalised `merkle_root` key internally
+  (no behaviour change — same comparison output).
+- `BSV::Transaction::ChainTracker#valid_root_for_height?` reads
+  `result.data['merkle_root']` directly; the previous private
+  `normalise_merkle_root` helper is removed. Subclass-override pattern unchanged.
+
+### Note
+- This is the "Pattern A" normalisation from #791 — push cosmetic field-name
+  divergence down into the wire-protocol classes where the data is semantically
+  identical across upstreams. Pattern B (broadcast / get_tx_status with
+  structurally divergent shapes) stays at the consumer layer and is not part of
+  this release.
+
 ## 0.22.0 — 2026-05-30
 
 ### Added

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

@@ -21,7 +21,7 @@ module BSV
       #   result.data  # => 800000
       #
       #   result = ct.call(:get_block_header, 800_000)
-      #   result.data  # => { 'hash' => '...', 'height' => 800000, 'merkleRoot' => '...' }
+      #   result.data  # => { 'hash' => '...', 'height' => 800000, 'merkle_root' => '...' }
       #
       # @note No public Chaintracks instance is hosted by major providers — GorillaPool
       #   serves chain data via JungleBus instead. For general chain-tracking against
@@ -40,6 +40,26 @@ module BSV
         def initialize(base_url:, api_key: nil, auth: nil, http_client: nil)
           super
         end
+
+        private
+
+        # Block-header escape hatch: normalises Chaintracks's +merkleRoot+ field
+        # to the canonical +merkle_root+ key. See issue #791 for the cross-protocol
+        # rationale.
+        def call_get_block_header(*, **)
+          response = default_call(:get_block_header, *, **)
+          return response unless response.http_success?
+
+          response.with(data: normalize_block_header(response.data))
+        end
+
+        def normalize_block_header(data)
+          return data unless data.is_a?(Hash) && data.key?('merkleRoot')
+
+          data = data.dup
+          data['merkle_root'] = data.delete('merkleRoot')
+          data
+        end
       end
     end
   end

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

@@ -52,6 +52,34 @@ module BSV
         def initialize(base_url:, api_key: nil, auth: nil, http_client: nil)
           super
         end
+
+        private
+
+        # Block-header escape hatch: normalises JungleBus's +merkleroot+ field
+        # to the canonical +merkle_root+ key. See issue #791 for the cross-protocol
+        # rationale.
+        def call_get_block_header(*, **)
+          response = default_call(:get_block_header, *, **)
+          return response unless response.http_success?
+
+          response.with(data: normalize_block_header(response.data))
+        end
+
+        def call_get_block_headers(*, **)
+          response = default_call(:get_block_headers, *, **)
+          return response unless response.http_success?
+          return response unless response.data.is_a?(Array)
+
+          response.with(data: response.data.map { |h| normalize_block_header(h) })
+        end
+
+        def normalize_block_header(data)
+          return data unless data.is_a?(Hash) && data.key?('merkleroot')
+
+          data = data.dup
+          data['merkle_root'] = data.delete('merkleroot')
+          data
+        end
       end
     end
   end

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

@@ -373,9 +373,36 @@ module BSV
           result = default_call(:valid_root, height)
           return result unless result.http_success?
 
-          actual = result.data['merkleroot']
+          data = normalize_block_header(result.data)
+          actual = data['merkle_root']
           result.with(data: actual.to_s.downcase == root.to_s.downcase)
         end
+
+        # Block-header escape hatch: normalises WoCREST's +merkleroot+ field
+        # to the canonical +merkle_root+ key. See issue #791 for the cross-protocol
+        # rationale.
+        def call_get_block_header(*, **)
+          response = default_call(:get_block_header, *, **)
+          return response unless response.http_success?
+
+          response.with(data: normalize_block_header(response.data))
+        end
+
+        def call_get_block_headers(*, **)
+          response = default_call(:get_block_headers, *, **)
+          return response unless response.http_success?
+          return response unless response.data.is_a?(Array)
+
+          response.with(data: response.data.map { |h| normalize_block_header(h) })
+        end
+
+        def normalize_block_header(data)
+          return data unless data.is_a?(Hash) && data.key?('merkleroot')
+
+          data = data.dup
+          data['merkle_root'] = data.delete('merkleroot')
+          data
+        end
       end
     end
   end

data/lib/bsv/transaction/chain_tracker.rb

@@ -70,8 +70,11 @@ module BSV
       # 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+.
+      # on 404 (block not found). Relies on the wire-protocol classes that expose
+      # +:get_block_header+ (+Protocols::JungleBus+, +Protocols::Chaintracks+,
+      # +Protocols::WoCREST+) to emit the canonical +merkle_root+ key — see
+      # issue #791 for the Pattern A normalisation that absorbed the previous
+      # field-name shim.
       #
       # @param root [String] merkle root as a hex string
       # @param height [Integer] block height
@@ -85,7 +88,7 @@ module BSV
         return false if result.http_not_found?
         raise result.error_message.to_s unless result.http_success?
 
-        actual = normalise_merkle_root(result.data)
+        actual = result.data.is_a?(Hash) ? result.data['merkle_root'] : nil
         return false unless actual
 
         actual.casecmp(root).zero?
@@ -106,17 +109,6 @@ module BSV
 
         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
 end

data/lib/bsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BSV
-  VERSION = '0.22.0'
+  VERSION = '0.23.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.23.0
 platform: ruby
 authors:
 - Simon Bettison