bsv-sdk 0.16.0 → 0.17.0

data/lib/bsv/transaction/beef.rb

@@ -13,7 +13,7 @@ module BSV
     #
     # @example Parse a BEEF bundle and find a transaction
     #   beef = BSV::Transaction::Beef.from_hex(beef_hex)
-    #   tx = beef.find_transaction(txid_bytes)
+    #   tx = beef.find_transaction(wtxid)
     class Beef
       # @!group Version constants
 
@@ -44,37 +44,53 @@ module BSV
         # @return [Transaction, nil] the transaction (nil for TXID-only entries)
         attr_reader :transaction
 
-        # @return [String, nil] 32-byte txid for TXID-only entries
-        attr_reader :known_txid
+        # @return [String, nil] 32-byte wire-order wtxid for TXID-only entries
+        attr_reader :known_wtxid
 
         # @return [Integer, nil] index into the BEEF bumps array
         attr_reader :bump_index
 
         # @param format [Integer] format flag
         # @param transaction [Transaction, nil] the transaction
-        # @param known_txid [String, nil] 32-byte txid for TXID-only entries
+        # @param known_wtxid [String, nil] 32-byte wire-order wtxid for TXID-only entries
         # @param bump_index [Integer, nil] index into the bumps array
         # @raise [ArgumentError] if format is FORMAT_RAW_TX_AND_BUMP without a bump_index
-        def initialize(format:, transaction: nil, known_txid: nil, bump_index: nil)
+        def initialize(format:, transaction: nil, known_wtxid: nil, bump_index: nil)
           raise ArgumentError, 'FORMAT_RAW_TX_AND_BUMP requires a bump_index' if format == FORMAT_RAW_TX_AND_BUMP && bump_index.nil?
 
+          BSV::Primitives::Hex.validate_wtxid!(known_wtxid, name: 'known_wtxid') if known_wtxid
           @format = format
           @transaction = transaction
-          @known_txid = known_txid
+          @known_wtxid = known_wtxid
           @bump_index = bump_index
         end
 
-        # The transaction ID for this entry.
-        #
-        # @return [String, nil] 32-byte txid in display byte order
-        def txid
+        # Wire-order transaction ID.
+        # @return [String, nil] 32-byte wtxid
+        def wtxid
           case @format
           when FORMAT_TXID_ONLY
-            @known_txid
+            @known_wtxid
           else
-            @transaction&.txid
+            @transaction&.wtxid
           end
         end
+
+        # Display-order transaction ID as binary bytes.
+        # @return [String, nil] 32-byte display-order txid
+        def txid
+          wtxid&.reverse
+        end
+
+        # Display-order transaction ID as a hex string.
+        #
+        # +dtxid+ always returns a 64-char hex string suitable for JSON
+        # and UI boundaries.
+        #
+        # @return [String, nil] hex-encoded transaction ID (display order)
+        def dtxid
+          wtxid&.reverse&.unpack1('H*')
+        end
       end
 
       # @return [Integer] BEEF version constant
@@ -86,8 +102,21 @@ module BSV
       # @return [Array<BeefTx>] the transactions in dependency order
       attr_reader :transactions
 
-      # @return [String, nil] 32-byte subject txid (Atomic BEEF only)
-      attr_reader :subject_txid
+      # @return [String, nil] 32-byte wire-order subject txid (Atomic BEEF only)
+      attr_reader :subject_wtxid
+
+      # Display-order subject txid as binary bytes (Atomic BEEF only).
+      # @return [String, nil] 32-byte display-order txid, or nil
+      def subject_txid
+        @subject_wtxid&.reverse
+      end
+
+      # Display-order subject txid as a hex string (Atomic BEEF only).
+      #
+      # @return [String, nil] hex-encoded display-order txid, or nil
+      def subject_dtxid
+        @subject_wtxid&.reverse&.unpack1('H*')
+      end
 
       # @param version [Integer] BEEF version constant (default: BEEF_V1, matching to_binary's
       #   default for ARC compatibility; from_binary overwrites this with the parsed version)
@@ -97,7 +126,7 @@ module BSV
         @version = version
         @bumps = bumps
         @transactions = transactions
-        @subject_txid = nil
+        @subject_wtxid = nil
       end
 
       # --- Deserialisation ---
@@ -133,9 +162,9 @@ module BSV
             raise ArgumentError, "truncated Atomic BEEF: need 36 bytes at offset #{offset}, got #{remaining}"
           end
 
-          # Atomic BEEF stores the subject txid in internal byte order (little-endian
-          # hash order), matching JS and Go SDKs. Reverse to display order for internal use.
-          beef.instance_variable_set(:@subject_txid, data.byteslice(offset, 32).reverse)
+          # Atomic BEEF stores the subject txid in wire (internal / little-endian) byte order,
+          # matching JS and Go SDKs. Store as-is in @subject_wtxid (wire-order).
+          beef.instance_variable_set(:@subject_wtxid, data.byteslice(offset, 32))
           offset += 32
           inner_version = data.byteslice(offset, 4).unpack1('V')
           offset += 4
@@ -223,13 +252,13 @@ module BSV
 
       # Serialise as Atomic BEEF (BRC-95), wrapping V2 data with a subject txid.
       #
-      # @param subject_txid [String] 32-byte subject transaction ID
+      # @param subject_wtxid [String] 32-byte wire-order subject transaction ID
       # @return [String] raw Atomic BEEF binary
-      def to_atomic_binary(subject_txid)
+      def to_atomic_binary(subject_wtxid)
+        BSV::Primitives::Hex.validate_wtxid!(subject_wtxid, name: 'subject_wtxid')
         buf = [ATOMIC_BEEF].pack('V')
-        # Write subject txid in internal byte order (reverse of display order),
-        # matching JS and Go SDK conventions for Bitcoin binary formats.
-        buf << subject_txid.b.reverse
+        # subject_wtxid is already in wire (internal) byte order — write as-is.
+        buf << subject_wtxid.b
         # BRC-95: inner envelope is always V2
         buf << to_binary(version: BEEF_V2)
         buf
@@ -237,42 +266,45 @@ module BSV
 
       # --- Lookup ---
 
-      # Find a transaction in the bundle by its transaction ID.
+      # Find a transaction in the bundle by its wire-order transaction ID.
       #
-      # @param txid [String] 32-byte txid in display byte order
+      # @param wtxid [String] 32-byte wire-order wtxid
       # @return [Transaction, nil] the matching transaction, or nil
-      def find_transaction(txid)
+      def find_transaction(wtxid)
+        BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
+        BSV.logger&.debug { "[Beef] find_transaction: #{wtxid.reverse.unpack1('H*')} in #{@transactions.length} entries" }
         @transactions.each do |beef_tx|
-          return beef_tx.transaction if beef_tx.transaction&.txid == txid
+          return beef_tx.transaction if beef_tx.wtxid == wtxid
         end
         nil
       end
 
-      # Find the merkle path (BUMP) for a transaction by its txid.
+      # Find the merkle path (BUMP) for a transaction by its wire-order txid.
       #
       # First checks the transaction-table entries, then scans @bumps directly
-      # for a BUMP whose level-0 leaves contain the txid.
+      # for a BUMP whose level-0 leaves contain the wtxid.
       #
-      # @param txid [String] 32-byte txid in display byte order
+      # @param wtxid [String] 32-byte wire-order wtxid
       # @return [MerklePath, nil] the merkle path, or nil if not found
-      def find_bump(txid)
+      def find_bump(wtxid)
+        BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
         # Check transaction-table entries first (fast path)
-        bt = @transactions.find { |entry| entry.txid == txid && entry.format == FORMAT_RAW_TX_AND_BUMP }
+        bt = @transactions.find { |entry| entry.wtxid == wtxid && entry.format == FORMAT_RAW_TX_AND_BUMP }
         return bt.transaction&.merkle_path || (bt.bump_index && @bumps[bt.bump_index]) if bt
 
-        # F5.8: also scan @bumps directly for a path containing the txid leaf
-        txid_internal = txid.reverse
+        # F5.8: also scan @bumps directly for a path containing the wtxid leaf
         @bumps.find do |bump|
-          bump.path[0]&.any? { |leaf| leaf.hash == txid_internal }
+          bump.path[0]&.any? { |leaf| leaf.hash == wtxid }
         end
       end
 
       # Find a transaction with all source_transactions wired for signing.
       #
-      # @param txid [String] 32-byte txid in display byte order
+      # @param wtxid [String] 32-byte wire-order wtxid
       # @return [Transaction, nil] the transaction with wired inputs, or nil
-      def find_transaction_for_signing(txid)
-        tx = find_transaction(txid)
+      def find_transaction_for_signing(wtxid)
+        BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
+        tx = find_transaction(wtxid)
         return unless tx
 
         wire_inputs(tx)
@@ -282,10 +314,11 @@ module BSV
       # Find a transaction and recursively wire its ancestry (source transactions
       # and merkle paths) for atomic proof validation.
       #
-      # @param txid [String] 32-byte txid in display byte order
+      # @param wtxid [String] 32-byte wire-order wtxid
       # @return [Transaction, nil] the transaction with full proof tree, or nil
-      def find_atomic_transaction(txid)
-        tx = find_transaction(txid)
+      def find_atomic_transaction(wtxid)
+        BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
+        tx = find_transaction(wtxid)
         return unless tx
 
         wire_ancestry(tx)
@@ -294,10 +327,10 @@ module BSV
 
       # Serialise as Atomic BEEF (BRC-95) hex string.
       #
-      # @param subject_txid [String] 32-byte subject transaction ID
+      # @param subject_wtxid [String] 32-byte wire-order subject transaction ID
       # @return [String] hex-encoded Atomic BEEF
-      def to_atomic_hex(subject_txid)
-        to_atomic_binary(subject_txid).unpack1('H*')
+      def to_atomic_hex(subject_wtxid)
+        to_atomic_binary(subject_wtxid).unpack1('H*')
       end
 
       # --- Merge operations ---
@@ -339,7 +372,7 @@ module BSV
         level0_internal = level0_leaves.map(&:hash).compact.to_set
         @transactions.each_with_index do |bt, i|
           next unless bt.format == FORMAT_RAW_TX && bt.transaction
-          next unless level0_internal.include?(bt.transaction.txid.reverse)
+          next unless level0_internal.include?(bt.transaction.wtxid)
 
           bt.transaction.merkle_path ||= bump
           @transactions[i] = BeefTx.new(
@@ -362,10 +395,10 @@ module BSV
       # @param tx [Transaction] the transaction to merge
       # @return [BeefTx] the (possibly existing or upgraded) BeefTx entry
       def merge_transaction(tx)
-        txid = tx.txid
+        wtxid = tx.wtxid
 
         # Check for existing entry and upgrade if a stronger format is available
-        existing_idx = @transactions.index { |bt| bt.txid == txid }
+        existing_idx = @transactions.index { |bt| bt.wtxid == wtxid }
         if existing_idx
           existing = @transactions[existing_idx]
           upgraded = upgrade_beef_tx(existing, tx)
@@ -409,7 +442,7 @@ module BSV
           tx.merkle_path = @bumps[bump_index]
         end
 
-        existing_idx = @transactions.index { |bt| bt.txid == tx.txid }
+        existing_idx = @transactions.index { |bt| bt.wtxid == tx.wtxid }
         if existing_idx
           existing = @transactions[existing_idx]
           upgraded = upgrade_beef_tx(existing, tx, bump_index: bump_index)
@@ -448,11 +481,11 @@ module BSV
         other.transactions.each do |beef_tx|
           case beef_tx.format
           when FORMAT_TXID_ONLY
-            next if @transactions.any? { |bt| bt.txid == beef_tx.known_txid }
+            next if @transactions.any? { |bt| bt.wtxid == beef_tx.known_wtxid }
 
-            @transactions << BeefTx.new(format: FORMAT_TXID_ONLY, known_txid: beef_tx.known_txid)
+            @transactions << BeefTx.new(format: FORMAT_TXID_ONLY, known_wtxid: beef_tx.known_wtxid)
           else
-            next if @transactions.any? { |bt| bt.txid == beef_tx.txid }
+            next if @transactions.any? { |bt| bt.wtxid == beef_tx.wtxid }
 
             if beef_tx.format == FORMAT_RAW_TX_AND_BUMP && beef_tx.bump_index
               new_idx = bump_remap[beef_tx.bump_index]
@@ -482,13 +515,14 @@ module BSV
 
       # Convert a transaction entry to TXID-only format.
       #
-      # @param txid [String] 32-byte txid in display byte order
+      # @param wtxid [String] 32-byte wire-order wtxid
       # @return [BeefTx, nil] the converted entry, or nil if not found
-      def make_txid_only(txid)
-        idx = @transactions.index { |bt| bt.txid == txid }
+      def make_txid_only(wtxid)
+        BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
+        idx = @transactions.index { |bt| bt.wtxid == wtxid }
         return unless idx
 
-        @transactions[idx] = BeefTx.new(format: FORMAT_TXID_ONLY, known_txid: txid)
+        @transactions[idx] = BeefTx.new(format: FORMAT_TXID_ONLY, known_wtxid: wtxid)
       end
 
       # --- Validation ---
@@ -520,15 +554,15 @@ module BSV
 
           # The txid must appear as a leaf in the BUMP and compute a valid root
           begin
-            bump.compute_root(bt.transaction.txid.reverse)
+            bump.compute_root(bt.transaction.wtxid)
           rescue ArgumentError
             return false
           end
         end
 
-        known_txids = build_known_txids(allow_txid_only)
+        known_wtxids = build_known_wtxids(allow_txid_only)
 
-        pending = @transactions.select { |bt| bt.transaction && !known_txids.include?(bt.txid) }
+        pending = @transactions.select { |bt| bt.transaction && !known_wtxids.include?(bt.wtxid) }
 
         # Iteratively resolve: if all inputs of a tx are known, it becomes known
         changed = true
@@ -536,10 +570,10 @@ module BSV
           changed = false
           pending.reject! do |bt|
             all_inputs_known = bt.transaction.inputs.all? do |input|
-              known_txids.include?(input.prev_tx_id.reverse)
+              known_wtxids.include?(input.prev_wtxid)
             end
             if all_inputs_known
-              known_txids.add(bt.txid)
+              known_wtxids.add(bt.wtxid)
               changed = true
             end
             all_inputs_known
@@ -584,8 +618,8 @@ module BSV
       def sort_transactions!
         return self if @transactions.length <= 1
 
-        txid_index = {}
-        @transactions.each_with_index { |bt, i| txid_index[bt.txid] = i }
+        wtxid_index = {}
+        @transactions.each_with_index { |bt, i| wtxid_index[bt.wtxid] = i }
 
         # Build adjacency: for each tx, which other txs must come before it?
         in_degree = Array.new(@transactions.length, 0)
@@ -595,7 +629,7 @@ module BSV
           next unless bt.transaction
 
           bt.transaction.inputs.each do |input|
-            dep_idx = txid_index[input.prev_tx_id.reverse]
+            dep_idx = wtxid_index[input.prev_wtxid]
             next unless dep_idx
 
             dependents[dep_idx] << i
@@ -618,8 +652,8 @@ module BSV
 
         # F5.5: preserve unsortable (cyclic) transactions rather than silently dropping them
         if sorted.length < @transactions.length
-          sorted_set = sorted.to_set(&:txid)
-          @txs_not_valid = @transactions.reject { |bt| sorted_set.include?(bt.txid) }
+          sorted_set = sorted.to_set(&:wtxid)
+          @txs_not_valid = @transactions.reject { |bt| sorted_set.include?(bt.wtxid) }
         end
 
         @transactions = sorted
@@ -661,14 +695,13 @@ module BSV
 
             case format
             when FORMAT_TXID_ONLY
-              # Wire stores txid in internal (little-endian) byte order;
-              # reverse to display order so BeefTx#txid is consistent with
-              # Transaction#txid across all format types.
+              # Wire stores txid in internal (little-endian / wire) byte order;
+              # store as-is in known_wtxid so it matches Transaction#wtxid.
               raise ArgumentError, 'truncated BEEF: not enough bytes for TXID_ONLY entry' if offset + 32 > data.bytesize
 
-              known_txid = data.byteslice(offset, 32).reverse
+              known_wtxid = data.byteslice(offset, 32)
               offset += 32
-              beef.transactions << BeefTx.new(format: FORMAT_TXID_ONLY, known_txid: known_txid)
+              beef.transactions << BeefTx.new(format: FORMAT_TXID_ONLY, known_wtxid: known_wtxid)
             when FORMAT_RAW_TX_AND_BUMP
               bump_index, vi_size = VarInt.decode(data, offset)
               offset += vi_size
@@ -719,14 +752,20 @@ module BSV
           beef.transactions.each do |beef_tx|
             next unless beef_tx.transaction
 
-            # Wire inputs to ancestors already in the map (BEEF is dependency-ordered)
+            # Wire inputs to ancestors already in the map (BEEF is dependency-ordered).
+            # Both prev_wtxid and wtxid are wire-order — no conversion needed.
             beef_tx.transaction.inputs.each do |input|
-              # prev_tx_id is wire byte order; txid keys are display byte order (reversed)
-              source = tx_map[input.prev_tx_id.reverse]
-              input.source_transaction = source if source
+              source = tx_map[input.prev_wtxid]
+              next unless source
+
+              input.source_transaction = source
+              BSV.logger&.debug do
+                "[Beef] wired input #{input.prev_wtxid.reverse.unpack1('H*')}:#{input.prev_tx_out_index} " \
+                  "-> source #{source.wtxid.reverse.unpack1('H*')}"
+              end
             end
 
-            tx_map[beef_tx.transaction.txid] = beef_tx.transaction
+            tx_map[beef_tx.transaction.wtxid] = beef_tx.transaction
           end
         end
       end
@@ -768,15 +807,15 @@ module BSV
         # FORMAT_RAW_TX_AND_BUMP is already the strongest — no upgrade needed
       end
 
-      # Build a set of txids that are "known" (proven or txid-only).
-      def build_known_txids(allow_txid_only)
+      # Build a set of wire-order wtxids that are "known" (proven or txid-only).
+      def build_known_wtxids(allow_txid_only)
         known = Set.new
         @transactions.each do |bt|
           case bt.format
           when FORMAT_RAW_TX_AND_BUMP
-            known.add(bt.txid)
+            known.add(bt.wtxid)
           when FORMAT_TXID_ONLY
-            known.add(bt.txid) if allow_txid_only
+            known.add(bt.wtxid) if allow_txid_only
           end
         end
         known
@@ -787,7 +826,7 @@ module BSV
         tx.inputs.each do |input|
           next if input.source_transaction
 
-          source = find_transaction(input.prev_tx_id.reverse)
+          source = find_transaction(input.prev_wtxid)
           input.source_transaction = source if source
         end
       end
@@ -799,7 +838,7 @@ module BSV
           next unless input.source_transaction
 
           source = input.source_transaction
-          source.merkle_path ||= find_bump(source.txid)
+          source.merkle_path ||= find_bump(source.wtxid)
           wire_ancestry(source)
         end
       end
@@ -820,8 +859,8 @@ module BSV
         case beef_tx.format
         when FORMAT_TXID_ONLY
           buf << [FORMAT_TXID_ONLY].pack('C')
-          # Reverse display-order txid back to wire (internal) byte order.
-          buf << beef_tx.known_txid.reverse
+          # known_wtxid is already wire (internal) byte order.
+          buf << beef_tx.known_wtxid
         when FORMAT_RAW_TX_AND_BUMP
           buf << [FORMAT_RAW_TX_AND_BUMP].pack('C')
           buf << VarInt.encode(beef_tx.bump_index)

data/lib/bsv/transaction/merkle_path.rb

@@ -21,7 +21,8 @@ module BSV
       # @!attribute [r] hash
       #   @return [String, nil] 32-byte hash (nil when duplicate)
       # @!attribute [r] txid
-      #   @return [Boolean] whether this leaf is a transaction ID
+      #   @return [Boolean] BRC-74 flag — whether this leaf represents a transaction in
+      #     the merkle tree (the 0x02 bit in the BRC-74 serialisation). Not a txid value.
       # @!attribute [r] duplicate
       #   @return [Boolean] whether this leaf duplicates its sibling
       class PathElement
@@ -29,7 +30,9 @@ module BSV
 
         # @param offset [Integer] position index within the tree level
         # @param hash [String, nil] 32-byte hash (nil when duplicate)
-        # @param txid [Boolean] whether this leaf is a transaction ID
+        # @param txid [Boolean] BRC-74 flag — true when this leaf represents a transaction
+        #   in the tree (the 0x02 bit in the BRC-74 serialisation). This is NOT a txid
+        #   value; it is a boolean presence flag mandated by the BRC-74 specification.
         # @param duplicate [Boolean] whether this leaf duplicates its sibling
         def initialize(offset:, hash: nil, txid: false, duplicate: false)
           @offset = offset
@@ -147,25 +150,26 @@ module BSV
       # @example Convert a WoC TSC proof
       #   tsc = JSON.parse(woc_response).first
       #   mp = BSV::Transaction::MerklePath.from_tsc(
-      #     txid:         tsc['txOrId'],
+      #     dtxid_hex:    tsc['txOrId'],
       #     index:        tsc['index'],
       #     nodes:        tsc['nodes'],
       #     block_height: 612_251
       #   )
       #   mp.compute_root_hex(tsc['txOrId']) #=> the block's merkle root
       #
-      # @param txid [String] hex-encoded transaction ID in display byte order
+      # @param dtxid_hex [String] hex-encoded transaction ID in display byte order
       # @param index [Integer] the transaction's position in the block
       # @param nodes [Array<String>] sibling hashes leaf-to-root, each a 32-byte
       #   hex string in display byte order, or +"*"+ for a duplicate node
       # @param block_height [Integer] the block's height (TSC carries the block
       #   hash; the caller must look up the height separately)
       # @return [MerklePath] a BRC-74 merkle path equivalent to the TSC proof
-      def self.from_tsc(txid:, index:, nodes:, block_height:)
-        txid_bytes = [txid].pack('H*').reverse
+      def self.from_tsc(dtxid_hex:, index:, nodes:, block_height:)
+        BSV::Primitives::Hex.validate_dtxid_hex!(dtxid_hex, name: 'dtxid_hex')
+        wtxid = [dtxid_hex].pack('H*').reverse
 
         # Level 0 always contains the txid leaf.
-        level0 = [PathElement.new(offset: index, hash: txid_bytes, txid: true)]
+        level0 = [PathElement.new(offset: index, hash: wtxid, txid: true)]
 
         # A single-tx block has no siblings — the txid IS the merkle root.
         return new(block_height: block_height, path: [level0]) if nodes.empty?
@@ -193,6 +197,7 @@ module BSV
         if node == '*'
           PathElement.new(offset: offset, duplicate: true)
         else
+          BSV::Primitives::Hex.validate_dtxid_hex!(node, name: "TSC merkle node at offset #{offset}")
           PathElement.new(offset: offset, hash: [node].pack('H*').reverse)
         end
       end
@@ -240,17 +245,22 @@ module BSV
 
       # Recompute the merkle root from this path and a transaction ID.
       #
-      # @param txid [String, nil] 32-byte txid in internal byte order (auto-detected if nil)
-      # @return [String] 32-byte merkle root in internal byte order
-      # @raise [ArgumentError] if the txid is not found in the path
-      def compute_root(txid = nil)
-        txid ||= @path[0].find(&:hash)&.hash
-        return txid if @path.length == 1 && @path[0].length == 1
+      # @param wtxid [String, nil] 32-byte txid in wire byte order (auto-detected if nil)
+      # @return [String] 32-byte merkle root in wire byte order
+      # @raise [ArgumentError] if the wtxid is not found in the path
+      def compute_root(wtxid = nil)
+        wtxid ||= @path[0].find(&:hash)&.hash
+        BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid') if wtxid
+        BSV.logger&.debug do
+          dtxid = wtxid&.reverse&.unpack1('H*')
+          "[MerklePath] compute_root: dtxid=#{dtxid} block_height=#{@block_height} levels=#{@path.length}"
+        end
+        return wtxid if @path.length == 1 && @path[0].length == 1
 
         indexed = build_indexed_path
 
-        tx_leaf = @path[0].find { |l| l.hash == txid }
-        raise ArgumentError, 'the BUMP does not contain the txid' unless tx_leaf
+        tx_leaf = @path[0].find { |l| l.hash == wtxid }
+        raise ArgumentError, 'the BUMP does not contain the given wtxid' unless tx_leaf
 
         working = tx_leaf.hash
         index = tx_leaf.offset
@@ -289,11 +299,12 @@ module BSV
 
       # Recompute the merkle root and return it as a hex string.
       #
-      # @param txid_hex [String, nil] hex-encoded txid (display order)
+      # @param dtxid_hex [String, nil] hex-encoded txid (display order)
       # @return [String] hex-encoded merkle root (display order)
-      def compute_root_hex(txid_hex = nil)
-        txid = txid_hex ? [txid_hex].pack('H*').reverse : nil
-        compute_root(txid).reverse.unpack1('H*')
+      def compute_root_hex(dtxid_hex = nil)
+        BSV::Primitives::Hex.validate_dtxid_hex!(dtxid_hex, name: 'compute_root_hex dtxid_hex') if dtxid_hex
+        wtxid = dtxid_hex ? [dtxid_hex].pack('H*').reverse : nil
+        compute_root(wtxid).reverse.unpack1('H*')
       end
 
       # --- Verification ---
@@ -312,22 +323,27 @@ module BSV
       # and accepts immature ones — the opposite of the intended behaviour. The correct
       # logic is: reject when `current_height - block_height < 100` (immature).
       #
-      # @param txid_hex [String] hex-encoded transaction ID (display order)
+      # @param dtxid_hex [String] hex-encoded transaction ID (display order)
       # @param chain_tracker [ChainTracker] chain tracker to verify the root against
       # @return [Boolean] true if the computed root matches the block at this height
-      def verify(txid_hex, chain_tracker)
-        txid_bytes = [txid_hex].pack('H*').reverse
-        txid_leaf = @path[0].find { |l| l.hash == txid_bytes }
+      def verify(dtxid_hex, chain_tracker)
+        BSV::Primitives::Hex.validate_dtxid_hex!(dtxid_hex, name: 'dtxid_hex')
+        wtxid = [dtxid_hex].pack('H*').reverse
+        tx_leaf = @path[0].find { |l| l.hash == wtxid }
 
         # Offset 0 in a block's merkle tree is always the coinbase transaction —
         # a Bitcoin protocol invariant. Apply the 100-block maturity check.
-        if txid_leaf&.offset&.zero?
+        if tx_leaf&.offset&.zero?
           current = chain_tracker.current_height
           return false if current - @block_height < 100
         end
 
-        root_hex = compute_root_hex(txid_hex)
-        chain_tracker.valid_root_for_height?(root_hex, @block_height)
+        root_hex = compute_root_hex(dtxid_hex)
+        valid = chain_tracker.valid_root_for_height?(root_hex, @block_height)
+        BSV.logger&.debug do
+          "[MerklePath] verify: dtxid=#{dtxid_hex} height=#{@block_height} root=#{root_hex} valid=#{valid}"
+        end
+        valid
       end
 
       # --- Combine ---
@@ -445,24 +461,24 @@ module BSV
       #
       # Matches the TS SDK's +MerklePath.extract+ behaviour.
       #
-      # @param txid_hashes [Array<String>] 32-byte txids in internal byte
+      # @param wtxid_hashes [Array<String>] 32-byte txids in wire byte
       #   order (reverse of display order). To pass hex strings, use
-      #   +txid_hexes.map { |h| [h].pack('H*').reverse }+.
+      #   +dtxid_hexes.map { |h| [h].pack('H*').reverse }+.
       # @return [MerklePath] a new trimmed compound path proving only the
       #   requested txids
-      # @raise [ArgumentError] if +txid_hashes+ is empty, any requested
+      # @raise [ArgumentError] if +wtxid_hashes+ is empty, any requested
       #   txid is not present in the source path's level 0, or the
       #   extracted path's root does not match the source root
-      def extract(txid_hashes)
-        raise ArgumentError, 'at least one txid must be provided to extract' if txid_hashes.empty?
+      def extract(wtxid_hashes)
+        raise ArgumentError, 'at least one wtxid must be provided to extract' if wtxid_hashes.empty?
 
         original_root = compute_root
         indexed = build_indexed_path
 
         # Build a level-0 hash → offset lookup
-        txid_to_offset = {}
+        wtxid_to_offset = {}
         @path[0].each do |leaf|
-          txid_to_offset[leaf.hash] = leaf.offset if leaf.hash
+          wtxid_to_offset[leaf.hash] = leaf.offset if leaf.hash
         end
 
         max_offset = @path[0].map(&:offset).max || 0
@@ -470,15 +486,15 @@ module BSV
 
         needed = Array.new(tree_height) { {} }
 
-        txid_hashes.each do |txid|
-          tx_offset = txid_to_offset[txid]
+        wtxid_hashes.each do |wtxid_hash|
+          tx_offset = wtxid_to_offset[wtxid_hash]
           if tx_offset.nil?
             raise ArgumentError,
-                  "transaction ID #{txid.reverse.unpack1('H*')} not found in the Merkle Path"
+                  "wtxid #{wtxid_hash.reverse.unpack1('H*')} not found in the Merkle Path"
           end
 
-          # Level 0: the txid leaf itself + its tree sibling
-          needed[0][tx_offset] = PathElement.new(offset: tx_offset, hash: txid, txid: true)
+          # Level 0: the transaction leaf itself + its tree sibling
+          needed[0][tx_offset] = PathElement.new(offset: tx_offset, hash: wtxid_hash, txid: true)
           sib0_offset = tx_offset ^ 1
           unless needed[0].key?(sib0_offset)
             sib = offset_leaf(indexed, 0, sib0_offset)