bsv-sdk 0.16.0 → 0.18.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
 
@@ -36,44 +36,119 @@ module BSV
 
       # @!endgroup
 
-      # A single entry in a BEEF bundle, wrapping a transaction with its format metadata.
+      # Abstract base class for a single entry in a BEEF bundle.
+      #
+      # Subclasses represent the three wire formats:
+      # - {RawTxEntry}    — raw transaction without a merkle proof
+      # - {ProvenTxEntry} — raw transaction with an associated BUMP index
+      # - {TxidOnlyEntry} — transaction ID only (no raw data)
+      #
+      # @abstract Subclass and implement {#wtxid} and {#format_flag}.
       class BeefTx
-        # @return [Integer] format flag (FORMAT_RAW_TX, FORMAT_RAW_TX_AND_BUMP, or FORMAT_TXID_ONLY)
-        attr_reader :format
+        def initialize; end
+
+        # Wire-order transaction ID.
+        # @return [String, nil] 32-byte wtxid
+        # @abstract
+        def wtxid
+          raise NotImplementedError, "#{self.class}#wtxid is not implemented"
+        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
+
+        # Wire-protocol format integer for serialisation.
+        # @return [Integer]
+        # @abstract
+        def format_flag
+          raise NotImplementedError, "#{self.class}#format_flag is not implemented"
+        end
+      end
 
-        # @return [Transaction, nil] the transaction (nil for TXID-only entries)
+      # A BEEF entry containing a raw transaction without a merkle proof.
+      class RawTxEntry < BeefTx
+        # @return [Transaction] the transaction
         attr_reader :transaction
 
-        # @return [String, nil] 32-byte txid for TXID-only entries
-        attr_reader :known_txid
+        # @param transaction [Transaction] the transaction
+        # @raise [ArgumentError] if transaction is nil
+        def initialize(transaction:)
+          raise ArgumentError, 'RawTxEntry requires a transaction' if transaction.nil?
+
+          super()
+          @transaction = transaction
+        end
+
+        # @return [String] wire-order wtxid delegated to the transaction
+        def wtxid
+          @transaction.wtxid
+        end
+
+        # @return [Integer] FORMAT_RAW_TX wire-protocol flag
+        def format_flag
+          FORMAT_RAW_TX
+        end
+      end
+
+      # A BEEF entry containing a raw transaction with an associated BUMP index.
+      class ProvenTxEntry < BeefTx
+        # @return [Transaction] the transaction
+        attr_reader :transaction
 
-        # @return [Integer, nil] index into the BEEF bumps array
+        # @return [Integer] 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 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)
-          raise ArgumentError, 'FORMAT_RAW_TX_AND_BUMP requires a bump_index' if format == FORMAT_RAW_TX_AND_BUMP && bump_index.nil?
+        # @param transaction [Transaction] the transaction
+        # @param bump_index [Integer] index into the bumps array
+        # @raise [ArgumentError] if transaction or bump_index is nil
+        def initialize(transaction:, bump_index:)
+          raise ArgumentError, 'ProvenTxEntry requires a transaction' if transaction.nil?
+          raise ArgumentError, 'ProvenTxEntry requires a bump_index' if bump_index.nil?
 
-          @format = format
+          super()
           @transaction = transaction
-          @known_txid = known_txid
           @bump_index = bump_index
         end
 
-        # The transaction ID for this entry.
-        #
-        # @return [String, nil] 32-byte txid in display byte order
-        def txid
-          case @format
-          when FORMAT_TXID_ONLY
-            @known_txid
-          else
-            @transaction&.txid
-          end
+        # @return [String] wire-order wtxid delegated to the transaction
+        def wtxid
+          @transaction.wtxid
+        end
+
+        # @return [Integer] FORMAT_RAW_TX_AND_BUMP wire-protocol flag
+        def format_flag
+          FORMAT_RAW_TX_AND_BUMP
+        end
+      end
+
+      # A BEEF entry containing only a transaction ID (no raw data).
+      class TxidOnlyEntry < BeefTx
+        # @return [String] 32-byte wire-order wtxid
+        attr_reader :known_wtxid
+
+        # @param known_wtxid [String] 32-byte wire-order wtxid
+        # @raise [ArgumentError] if known_wtxid is invalid
+        def initialize(known_wtxid:)
+          BSV::Primitives::Hex.validate_wtxid!(known_wtxid, name: 'known_wtxid')
+          super()
+          @known_wtxid = known_wtxid
+        end
+
+        # @return [String] the stored wire-order wtxid
+        def wtxid
+          @known_wtxid
+        end
+
+        # @return [Integer] FORMAT_TXID_ONLY wire-protocol flag
+        def format_flag
+          FORMAT_TXID_ONLY
         end
       end
 
@@ -86,8 +161,15 @@ 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 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 +179,7 @@ module BSV
         @version = version
         @bumps = bumps
         @transactions = transactions
-        @subject_txid = nil
+        @subject_wtxid = nil
       end
 
       # --- Deserialisation ---
@@ -133,9 +215,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
@@ -185,7 +267,7 @@ module BSV
       #   any FORMAT_TXID_ONLY entries (V1 / BRC-62 has no TXID-only format;
       #   pass +version: BEEF_V2+ to serialise such bundles)
       def to_binary(version: BEEF_V1)
-        if version == BEEF_V1 && @transactions.any? { |bt| bt.format == FORMAT_TXID_ONLY }
+        if version == BEEF_V1 && @transactions.any?(TxidOnlyEntry)
           raise ArgumentError,
                 'BEEF V1 (BRC-62) does not support FORMAT_TXID_ONLY entries; pass version: BEEF_V2 to serialise this bundle'
         end
@@ -223,13 +305,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 +319,46 @@ 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
+          next if beef_tx.is_a?(TxidOnlyEntry)
+          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 }
-        return bt.transaction&.merkle_path || (bt.bump_index && @bumps[bt.bump_index]) if bt
+        bt = @transactions.find { |entry| entry.wtxid == wtxid && entry.is_a?(ProvenTxEntry) }
+        return bt.transaction.merkle_path || @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 +368,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 +381,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 ---
@@ -338,15 +425,11 @@ module BSV
         level0_leaves = bump.path[0] || []
         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 bt.is_a?(RawTxEntry)
+          next unless level0_internal.include?(bt.wtxid)
 
           bt.transaction.merkle_path ||= bump
-          @transactions[i] = BeefTx.new(
-            format: FORMAT_RAW_TX_AND_BUMP,
-            transaction: bt.transaction,
-            bump_index: idx
-          )
+          @transactions[i] = ProvenTxEntry.new(transaction: bt.transaction, bump_index: idx)
         end
 
         idx
@@ -362,10 +445,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)
@@ -381,9 +464,9 @@ module BSV
         # Merge this transaction's BUMP if it has one
         entry = if tx.merkle_path
                   bump_idx = merge_bump(tx.merkle_path)
-                  BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_idx)
+                  ProvenTxEntry.new(transaction: tx, bump_index: bump_idx)
                 else
-                  BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+                  RawTxEntry.new(transaction: tx)
                 end
         @transactions << entry
         entry
@@ -409,7 +492,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)
@@ -418,9 +501,9 @@ module BSV
         end
 
         entry = if bump_index
-                  BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_index)
+                  ProvenTxEntry.new(transaction: tx, bump_index: bump_index)
                 else
-                  BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+                  RawTxEntry.new(transaction: tx)
                 end
         @transactions << entry
         entry
@@ -446,15 +529,15 @@ module BSV
         # Merge transactions with remapped BUMP indices, constructing new
         # BeefTx instances rather than sharing source references (F5.9).
         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 }
+          case beef_tx
+          when TxidOnlyEntry
+            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 << TxidOnlyEntry.new(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
+            if beef_tx.is_a?(ProvenTxEntry) && beef_tx.bump_index
               new_idx = bump_remap[beef_tx.bump_index]
               if new_idx.nil?
                 raise ArgumentError,
@@ -466,13 +549,9 @@ module BSV
               # so mutations to the merged bundle don't affect the source.
               tx = beef_tx.transaction.dup
               tx.merkle_path = @bumps[new_idx]
-              @transactions << BeefTx.new(
-                format: FORMAT_RAW_TX_AND_BUMP,
-                transaction: tx,
-                bump_index: new_idx
-              )
+              @transactions << ProvenTxEntry.new(transaction: tx, bump_index: new_idx)
             else
-              @transactions << BeefTx.new(format: FORMAT_RAW_TX, transaction: beef_tx.transaction.dup)
+              @transactions << RawTxEntry.new(transaction: beef_tx.transaction.dup)
             end
           end
         end
@@ -482,13 +561,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] = TxidOnlyEntry.new(known_wtxid: wtxid)
       end
 
       # --- Validation ---
@@ -507,28 +587,28 @@ module BSV
       # @return [Boolean] true if structurally valid
       def valid?(allow_txid_only: false)
         # TXID-only entries are invalid unless explicitly allowed
-        has_txid_only = @transactions.any? { |bt| bt.format == FORMAT_TXID_ONLY }
+        has_txid_only = @transactions.any?(TxidOnlyEntry)
         return false if has_txid_only && !allow_txid_only
 
         # F5.4: verify BUMP linkage and computed root for each proven transaction
         @transactions.each do |bt|
-          next unless bt.format == FORMAT_RAW_TX_AND_BUMP
+          next unless bt.is_a?(ProvenTxEntry)
 
           # Must have a BUMP
-          bump = bt.transaction&.merkle_path || (bt.bump_index && @bumps[bt.bump_index])
+          bump = bt.transaction.merkle_path || @bumps[bt.bump_index]
           return false unless bump
 
           # 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.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.reject { |bt| bt.is_a?(TxidOnlyEntry) || known_wtxids.include?(bt.wtxid) }
 
         # Iteratively resolve: if all inputs of a tx are known, it becomes known
         changed = true
@@ -536,10 +616,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,18 +664,18 @@ 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)
         dependents = Array.new(@transactions.length) { [] }
 
         @transactions.each_with_index do |bt, i|
-          next unless bt.transaction
+          next if bt.is_a?(TxidOnlyEntry)
 
           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 +698,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,27 +741,24 @@ 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 << TxidOnlyEntry.new(known_wtxid: known_wtxid)
             when FORMAT_RAW_TX_AND_BUMP
               bump_index, vi_size = VarInt.decode(data, offset)
               offset += vi_size
               tx, consumed = Transaction.from_binary_with_offset(data, offset)
               offset += consumed
               tx.merkle_path = beef.bumps[bump_index] if bump_index < beef.bumps.length
-              beef.transactions << BeefTx.new(
-                format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_index
-              )
+              beef.transactions << ProvenTxEntry.new(transaction: tx, bump_index: bump_index)
             when FORMAT_RAW_TX
               tx, consumed = Transaction.from_binary_with_offset(data, offset)
               offset += consumed
-              beef.transactions << BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+              beef.transactions << RawTxEntry.new(transaction: tx)
             end
           end
 
@@ -700,14 +777,12 @@ module BSV
             offset += 1
 
             if has_bump.zero?
-              beef.transactions << BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+              beef.transactions << RawTxEntry.new(transaction: tx)
             else
               bump_index, vi_size = VarInt.decode(data, offset)
               offset += vi_size
               tx.merkle_path = beef.bumps[bump_index] if bump_index < beef.bumps.length
-              beef.transactions << BeefTx.new(
-                format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_index
-              )
+              beef.transactions << ProvenTxEntry.new(transaction: tx, bump_index: bump_index)
             end
           end
 
@@ -717,16 +792,22 @@ module BSV
         def wire_source_transactions(beef)
           tx_map = {}
           beef.transactions.each do |beef_tx|
-            next unless beef_tx.transaction
+            next if beef_tx.is_a?(TxidOnlyEntry)
 
-            # 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.wtxid] = beef_tx.transaction
           end
         end
       end
@@ -751,33 +832,28 @@ module BSV
         effective_bump_idx = bump_index
         effective_bump_idx = merge_bump(tx.merkle_path) if effective_bump_idx.nil? && tx&.merkle_path
 
-        case existing.format
-        when FORMAT_TXID_ONLY
+        case existing
+        when TxidOnlyEntry
           if effective_bump_idx
-            BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: effective_bump_idx)
+            ProvenTxEntry.new(transaction: tx, bump_index: effective_bump_idx)
           elsif tx
-            BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+            RawTxEntry.new(transaction: tx)
           end
-        when FORMAT_RAW_TX
+        when RawTxEntry
           if effective_bump_idx
             tx_to_use = tx || existing.transaction
             tx_to_use.merkle_path ||= @bumps[effective_bump_idx]
-            BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx_to_use, bump_index: effective_bump_idx)
+            ProvenTxEntry.new(transaction: tx_to_use, bump_index: effective_bump_idx)
           end
         end
-        # FORMAT_RAW_TX_AND_BUMP is already the strongest — no upgrade needed
+        # ProvenTxEntry 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)
-          when FORMAT_TXID_ONLY
-            known.add(bt.txid) if allow_txid_only
-          end
+          known.add(bt.wtxid) if bt.is_a?(ProvenTxEntry) || (bt.is_a?(TxidOnlyEntry) && allow_txid_only)
         end
         known
       end
@@ -787,7 +863,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 +875,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
@@ -807,7 +883,7 @@ module BSV
       # V1 (BRC-62): raw_tx + has_bump(byte) [+ bump_index(varint)]
       def write_v1_tx(buf, beef_tx)
         buf << beef_tx.transaction.to_binary
-        if beef_tx.format == FORMAT_RAW_TX_AND_BUMP
+        if beef_tx.is_a?(ProvenTxEntry)
           buf << [1].pack('C')
           buf << VarInt.encode(beef_tx.bump_index)
         else
@@ -817,12 +893,12 @@ module BSV
 
       # V2 (BRC-96): format_byte [+ bump_index(varint)] + raw_tx
       def write_v2_tx(buf, beef_tx)
-        case beef_tx.format
-        when FORMAT_TXID_ONLY
+        case beef_tx
+        when TxidOnlyEntry
           buf << [FORMAT_TXID_ONLY].pack('C')
-          # Reverse display-order txid back to wire (internal) byte order.
-          buf << beef_tx.known_txid.reverse
-        when FORMAT_RAW_TX_AND_BUMP
+          # known_wtxid is already wire (internal) byte order.
+          buf << beef_tx.known_wtxid
+        when ProvenTxEntry
           buf << [FORMAT_RAW_TX_AND_BUMP].pack('C')
           buf << VarInt.encode(beef_tx.bump_index)
           buf << beef_tx.transaction.to_binary