bsv-sdk 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a76170f9d5dcdfc76945c20c541b556a02f3fb5a7214a8d6f777eb589f048461
-  data.tar.gz: 57176276d41d430d654682dd22aef0f93bee9e2e3c57d4fb76d435dbd8c3e705
+  metadata.gz: 0c528b336af4735e247429423231a5c6a0dd681718e94d7a3d9598b65b75a6a0
+  data.tar.gz: 21efe7a43b3ba356953af1668cb35227d9c72bd3b17a1f08a54fac2f55f0d577
 SHA512:
-  metadata.gz: fb7257bda0b14c14ab55d8da3a19fdc27a8eca113cfeb857487079d4e0f042ebbaef184e81382d50aed7a9efd69dc4d2cb2d77594b6e1ae5f3f6d047c01d2ab9
-  data.tar.gz: 20f9e8fe53476ddd87900d1b58d00811da403703d5ae8cf6dc0f6d4a4836ab8a12e42ddce88c7323bd281e710770f4b7b6805cb842ab4f164c4b17559afa46e7
+  metadata.gz: 94b507d613413fbb96ab08f72d5db324ea33626f0f32af34f248b7d3133bd847aff1527de7ea1e68c1a1cbc1f5140f7654d4be99726348d85b852483ea00519a
+  data.tar.gz: 71c1fd8a86414cce69c1c4ec4fe1df52bab863c624ba70b806f37e2e016968eca9ac0244c42b0d52407c1817f56d9133403d3aec04a41bb39766776eb4b8c108

data/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.17.0 — 2026-05-02
+
+### Breaking Changes
+- Renamed `TransactionInput#prev_tx_id` to `#prev_wtxid` — all call sites must update (#678)
+- Renamed MerklePath parameters from `txid_hex` to `dtxid_hex` throughout (#681)
+
+### Added
+- `Transaction#wtxid` — wire-order transaction ID (raw SHA-256d bytes) (#673)
+- `Transaction#dtxid` / `#dtxid_hex` — display-order hex aliases (#680)
+- `TransactionInput#dtxid_hex` — display-order hex of the referenced transaction (#678)
+- `TransactionInput.wtxid_from_hex` — convert display-order hex to wire-order bytes (#678)
+- `Hex.validate_wtxid!` / `Hex.validate_dtxid_hex!` — runtime validation for wire/display txid formats (#685)
+- `Hex.validate_hash32!` — general-purpose 32-byte binary hash validator (#686)
+- `BSV.logger` — opt-in debug instrumentation with zero overhead when unused (#686)
+- Debug logging at txid conversions, sighash preimage, script interpreter, ARC broadcast, BEEF ancestry, and ProtoWallet key derivation (#686, #688)
+
+### Changed
+- All internal txid variables renamed to `wtxid` (wire-order) convention (#679)
+- BEEF internals enforce wire-order throughout — no byte-reversals inside the bundle (#675)
+- MerklePath `compute_root_hex` and `from_tsc` now validate hex input (#686)
+
+### Fixed
+- `BeefTx#dtxid` now returns hex string (was returning binary) (#677)
+- Certificate field naming aligned with BRC-52 convention (#677)
+
 ## 0.16.0 — 2026-05-01
 
 ### Breaking Changes

data/lib/bsv/auth/certificate.rb

@@ -81,6 +81,9 @@ module BSV
         buf << [@subject].pack('H*')
         buf << [@certifier].pack('H*')
 
+        # Certificate binary format: revocation outpoint txid stored in display byte
+        # order (matching TS and Go SDKs). Go encodes via WriteBytesReverse(wire_order),
+        # TS encodes via toArray(display_hex) — both produce identical display-order bytes.
         txid_hex, output_index_str = @revocation_outpoint.to_s.split('.', 2)
         buf << [txid_hex].pack('H*')
         buf << BSV::Transaction::VarInt.encode(output_index_str.to_i)
@@ -124,7 +127,8 @@ module BSV
         certifier_bytes = data.byteslice(pos, 33)
         pos += 33
 
-        txid_bytes = data.byteslice(pos, 32)
+        # Outpoint txid bytes — stored in display byte order (matching TS and Go SDKs).
+        outpoint_txid = data.byteslice(pos, 32)
         pos += 32
         output_index, vi_len = BSV::Transaction::VarInt.decode(data, pos)
         pos += vi_len
@@ -158,7 +162,7 @@ module BSV
           serial_number: Base64.strict_encode64(serial_bytes),
           subject: subject_bytes.unpack1('H*'),
           certifier: certifier_bytes.unpack1('H*'),
-          revocation_outpoint: "#{txid_bytes.unpack1('H*')}.#{output_index}",
+          revocation_outpoint: "#{outpoint_txid.unpack1('H*')}.#{output_index}",
           fields: fields,
           signature: signature
         )

data/lib/bsv/identity/client.rb

@@ -207,6 +207,7 @@ module BSV
         raise 'Revoke failed: no transaction found in BEEF' unless tx
         raise 'Revoke failed: outputIndex out of range' if output_idx >= tx.outputs.length
 
+        # Overlay API boundary: outpoint uses display-order hex txid as per overlay convention
         txid = tx.txid_hex
         outpoint = "#{txid}.#{output_idx}"
 

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

@@ -116,7 +116,7 @@ module BSV
           return Helpers.error_response("Broadcast failed: #{arc_result.message}") unless arc_result.success?
 
           result = {
-            txid: arc_result.data[:txid],
+            txid: arc_result.data[:txid], # MCP tool boundary: display-order hex from ARC response
             tx_status: arc_result.data[:tx_status],
             hex: tx.to_hex
           }
@@ -154,7 +154,7 @@ module BSV
           selected_utxos.each do |utxo|
             locking_script = p2pkh_lock_for(sender_address)
             input = BSV::Transaction::TransactionInput.new(
-              prev_tx_id: BSV::Transaction::TransactionInput.txid_from_hex(utxo.tx_hash),
+              prev_wtxid: BSV::Transaction::TransactionInput.wtxid_from_hex(utxo.tx_hash),
               prev_tx_out_index: utxo.tx_pos
             )
             input.source_satoshis = utxo.satoshis

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

@@ -25,7 +25,7 @@ module BSV
         # @return [Hash]
         def self.transaction_to_h(tx)
           {
-            txid: tx.txid_hex,
+            txid: tx.txid_hex, # MCP tool boundary: display-order hex for human consumption
             version: tx.version,
             lock_time: tx.lock_time,
             inputs: tx.inputs.each_with_index.map { |inp, i| input_to_h(inp, i) },
@@ -38,7 +38,7 @@ module BSV
         def self.input_to_h(input, _index)
           unlock_script = input.unlocking_script
           {
-            prev_txid: input.prev_tx_id.reverse.unpack1('H*'),
+            prev_txid: input.dtxid_hex,
             vout: input.prev_tx_out_index,
             script_hex: unlock_script ? unlock_script.to_hex : '',
             script_asm: unlock_script ? unlock_script.to_asm : '',

data/lib/bsv/network/broadcast_error.rb

@@ -3,6 +3,7 @@
 module BSV
   module Network
     class BroadcastError < StandardError
+      # ARC API boundary: display-order hex txid as returned by the ARC error response.
       attr_reader :status_code, :txid, :arc_status
 
       def initialize(message, status_code: nil, txid: nil, arc_status: nil)

data/lib/bsv/network/broadcast_response.rb

@@ -3,6 +3,7 @@
 module BSV
   module Network
     class BroadcastResponse
+      # ARC API boundary: display-order hex txid as returned by the ARC broadcast endpoint.
       attr_reader :txid, :tx_status, :message, :extra_info, :block_hash, :block_height, :timestamp, :competing_txs
 
       def initialize(attrs = {})

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

@@ -138,7 +138,8 @@ module BSV
         # lacks source_satoshis / source_locking_script.
         def ef_hex_with_fallback(tx)
           tx.to_ef_hex
-        rescue ArgumentError
+        rescue ArgumentError => e
+          BSV.logger&.debug { "[ARC] EF serialisation failed: #{e.message} — falling back to raw hex" }
           tx.to_hex
         end
 
@@ -269,7 +270,7 @@ module BSV
         # same field set as broadcast responses rather than the raw parsed JSON.
         # Also checks for rejection status and missing txid (malformed 2xx).
         #
-        # @param txid [String] the transaction ID to query
+        # @param txid [String] ARC API boundary: display-order hex transaction ID to query
         # @return [Result::Success, Result::Error, Result::NotFound]
         def call_get_tx_status(txid, **)
           response = default_call(:get_tx_status, txid)
@@ -306,7 +307,7 @@ module BSV
         # @return [Hash]
         def arc_data_from(body)
           {
-            txid: body['txid'],
+            txid: body['txid'], # ARC API boundary: display-order hex from the ARC JSON response
             tx_status: body['txStatus'],
             message: body['title'],
             extra_info: body['extraInfo'],

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

@@ -53,6 +53,7 @@ module BSV
           code = response.code.to_i
           body = parse_json_body(response.body)
 
+          # TAAL API boundary: display-order hex txid from the TAAL broadcast response
           return Result::Success.new(data: { txid: body['txid'] }) if already_known?(body) && body['txid']
 
           retryable = code == 429 || (500..599).cover?(code)

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

@@ -175,7 +175,7 @@ module BSV
         # The +script_hash:+ keyword is accepted for future fallback support
         # but not used in this implementation.
         #
-        # @param txid        [String]  transaction ID
+        # @param txid        [String]  WoC API boundary: display-order hex transaction ID
         # @param vout        [Integer] output index
         # @param script_hash [String, nil] ignored
         # @return [Result::Success<Boolean>, Result::Error, Result::NotFound]
@@ -242,6 +242,7 @@ module BSV
           return result unless result.success?
 
           # WoC returns plain-text txid — result.data is the raw body string
+          # WoC API boundary: display-order hex txid returned as plain text
           Result::Success.new(data: { txid: result.data.to_s.strip })
         end
 

data/lib/bsv/overlay/lookup_resolver.rb

@@ -334,6 +334,7 @@ module BSV
         beef_data    = output['beef'] || output[:beef]
         output_index = (output['outputIndex'] || output[:output_index] || 0).to_i
 
+        # Overlay API boundary: outpoint key uses display-order txid bytes (via Transaction#txid)
         txid =
           begin
             beef = parse_beef(beef_data)

data/lib/bsv/overlay/topic_broadcaster.rb

@@ -110,7 +110,7 @@ module BSV
 
         OverlayBroadcastResult.new(
           status: 'success',
-          txid: tx.txid_hex,
+          txid: tx.txid_hex, # Overlay API boundary: display-order hex txid for the broadcast result
           message: "Sent to #{successful.size} Overlay Service host(s)."
         )
       end

data/lib/bsv/overlay/types.rb

@@ -82,6 +82,7 @@ module BSV
       # @return [String] result status ('success' or 'error')
       attr_reader :status
 
+      # Overlay API boundary: display-order hex txid echoed from the broadcast response.
       # @return [String, nil] transaction identifier (present on success)
       attr_reader :txid
 

data/lib/bsv/primitives/hex.rb

@@ -72,6 +72,70 @@ module BSV
       def self.encode(bytes)
         bytes.unpack1('H*')
       end
+
+      # Validate that +value+ is a 32-byte wire-order transaction ID.
+      #
+      # @param value [String] expected 32-byte binary string
+      # @param name [String] label for the error message (e.g. +'prev_wtxid'+)
+      # @return [String] the input value (pass-through for chaining)
+      # @raise [ArgumentError] if +value+ is not a 32-byte binary string
+      def self.validate_wtxid!(value, name: 'wtxid')
+        unless value.is_a?(String) && value.bytesize == 32
+          hint = if value.is_a?(String) && value.bytesize == 64 && value.match?(HEX_RE)
+                   ' (looks like a hex txid — use wtxid_from_hex to convert)'
+                 else
+                   ''
+                 end
+          size = value.is_a?(String) ? "#{value.bytesize}-byte string" : value.class.to_s
+          raise ArgumentError,
+                "expected 32-byte wire-order wtxid for #{name}, got #{size}#{hint}"
+        end
+        value
+      end
+
+      # Validate that +value+ is a 32-byte binary hash.
+      #
+      # General-purpose validator for any 32-byte hash (merkle nodes, roots,
+      # etc.) — not specific to transaction IDs. For txid-specific validation
+      # use {.validate_wtxid!} or {.validate_dtxid_hex!} instead.
+      #
+      # @param value [String] expected 32-byte binary string
+      # @param name [String] label for the error message
+      # @return [String] the input value (pass-through for chaining)
+      # @raise [ArgumentError] if +value+ is not a 32-byte binary string
+      def self.validate_hash32!(value, name: 'hash')
+        unless value.is_a?(String) && value.bytesize == 32
+          hint = if value.is_a?(String) && value.bytesize == 64 && value.match?(HEX_RE)
+                   ' (looks like hex — decode it first)'
+                 else
+                   ''
+                 end
+          size = value.is_a?(String) ? "#{value.bytesize}-byte string" : value.class.to_s
+          raise ArgumentError,
+                "expected 32-byte hash for #{name}, got #{size}#{hint}"
+        end
+        value
+      end
+
+      # Validate that +value+ is a 64-character display-order hex transaction ID.
+      #
+      # @param value [String] expected 64-char hex string
+      # @param name [String] label for the error message (e.g. +'dtxid_hex'+)
+      # @return [String] the input value (pass-through for chaining)
+      # @raise [ArgumentError] if +value+ is not a 64-char hex string
+      def self.validate_dtxid_hex!(value, name: 'dtxid_hex')
+        unless value.is_a?(String) && value.length == 64 && value.match?(HEX_RE)
+          hint = if value.is_a?(String) && value.bytesize == 32 && !value.match?(HEX_RE)
+                   ' (looks like binary bytes — use dtxid_hex or unpack to convert)'
+                 else
+                   ''
+                 end
+          size = value.is_a?(String) ? "#{value.length}-char string" : value.class.to_s
+          raise ArgumentError,
+                "expected 64-char display-order hex for #{name}, got #{size}#{hint}"
+        end
+        value
+      end
     end
   end
 end

data/lib/bsv/registry/client.rb

@@ -155,6 +155,7 @@ module BSV
         verify_ownership(registered_definition)
 
         definition_type = registered_definition.definition_type
+        # Registry API boundary: outpoint uses display-order hex txid from RegisteredDefinition
         outpoint = "#{registered_definition.txid}.#{registered_definition.output_index}"
 
         create_result = @wallet.create_action(
@@ -415,7 +416,7 @@ module BSV
 
         RegisteredDefinition.new(
           definition_data: definition_data,
-          txid: tx.txid_hex,
+          txid: tx.txid_hex, # Registry API boundary: display-order hex txid
           output_index: output_idx,
           locking_script: locking_script.to_hex,
           beef: beef_raw,
@@ -434,6 +435,7 @@ module BSV
         outpoint_str = output[:outpoint] || output['outpoint']
         return nil unless outpoint_str
 
+        # Registry API boundary: outpoint string uses display-order hex txid by convention
         txid, output_idx_str = outpoint_str.split('.')
         output_idx = output_idx_str.to_i
 

data/lib/bsv/registry/types.rb

@@ -188,6 +188,7 @@ module BSV
       # @return [String] the definition type (see {DefinitionType})
       attr_reader :definition_type
 
+      # Registry API boundary: display-order hex txid from the outpoint string held in the registry token.
       # @return [String] transaction ID of the containing UTXO
       attr_reader :txid
 

data/lib/bsv/script/interpreter/interpreter.rb

@@ -89,10 +89,12 @@ module BSV
 
       def execute
         scripts = [@unlock_script, @lock_script]
+        script_names = %w[unlock_script lock_script]
 
         scripts.each_with_index do |script, script_idx|
           @current_script = script
           chunks = script.chunks
+          BSV.logger&.debug { "[Interpreter] === #{script_names[script_idx]} (#{chunks.length} chunks) ===" }
 
           chunks.each_with_index do |chunk, chunk_idx|
             @current_chunk_idx = chunk_idx
@@ -115,6 +117,7 @@ module BSV
         end
 
         check_final_stack
+        BSV.logger&.debug { "[Interpreter] final stack: #{@dstack.length} items -> success" }
         true
       end
 
@@ -156,6 +159,10 @@ module BSV
           return
         end
 
+        BSV.logger&.debug do
+          name = Opcodes.name_for(opcode) || format('0x%02x', opcode)
+          "[Interpreter]   #{name} (stack: #{@dstack.length})"
+        end
         dispatch_opcode(opcode, chunk)
       end
 

data/lib/bsv/script/interpreter/operations/crypto.rb

@@ -126,7 +126,13 @@ module BSV
 
             pubkey = BSV::Primitives::PublicKey.from_bytes(pubkey_bytes)
             hash = @tx.sighash(@input_index, sighash_type, subscript: sub_script)
-            pubkey.verify(hash, sig)
+            result = pubkey.verify(hash, sig)
+            BSV.logger&.debug do
+              pk_hex = pubkey_bytes.unpack1('H*')
+              "[Interpreter] CHECKSIG: sighash_type=0x#{format('%02x', sighash_type)} " \
+                "pubkey=#{pk_hex[0, 8]}...#{pk_hex[-4..]} result=#{result}"
+            end
+            result
           rescue ArgumentError
             false
           end