bsv-sdk 0.16.0 → 0.18.0

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)

data/lib/bsv/transaction/transaction.rb

@@ -329,16 +329,20 @@ module BSV
         ancestors = collect_ancestors
 
         bump_index_by_height = build_beef_bumps(beef, ancestors)
+        BSV.logger&.debug do
+          proven = ancestors.count(&:merkle_path)
+          "[Transaction] BEEF: #{ancestors.length} ancestors, #{proven} proven " \
+            "across #{bump_index_by_height.length} block heights"
+        end
 
         ancestors.each do |tx|
           entry = if tx.merkle_path
-                    Beef::BeefTx.new(
-                      format: Beef::FORMAT_RAW_TX_AND_BUMP,
+                    Beef::ProvenTxEntry.new(
                       transaction: tx,
                       bump_index: bump_index_by_height.fetch(tx.merkle_path.block_height)
                     )
                   else
-                    Beef::BeefTx.new(format: Beef::FORMAT_RAW_TX, transaction: tx)
+                    Beef::RawTxEntry.new(transaction: tx)
                   end
           beef.transactions << entry
         end
@@ -357,11 +361,11 @@ module BSV
       # full ancestry wired, including late-bound BUMP attachment.
       #
       # For Atomic BEEFs (BRC-95), the subject transaction is identified by
-      # the embedded subject_txid field. For plain BEEFs, the last transaction
-      # with a raw tx entry is used as the subject.
+      # the embedded +subject_wtxid+ field. For plain BEEFs, the last
+      # transaction with a raw tx entry is used as the subject.
       #
       # Uses +find_atomic_transaction+ so that FORMAT_RAW_TX ancestors whose
-      # txid appears as a leaf in a separately-stored BUMP get their
+      # wtxid appears as a leaf in a separately-stored BUMP get their
       # +merkle_path+ wired correctly — a gap not covered by the initial
       # +wire_source_transactions+ pass in +Beef.from_binary+.
       #
@@ -370,11 +374,11 @@ module BSV
       #   or nil if the BEEF is empty or contains no raw transaction entries
       def self.from_beef(data)
         beef = Beef.from_binary(data)
-        subject_txid = beef.subject_txid ||
-                       beef.transactions.reverse.find(&:transaction)&.transaction&.txid
-        return nil unless subject_txid
+        subject_wtxid = beef.subject_wtxid ||
+                        beef.transactions.reverse.find { |bt| !bt.is_a?(Beef::TxidOnlyEntry) }&.wtxid
+        return nil unless subject_wtxid
 
-        beef.find_atomic_transaction(subject_txid)
+        beef.find_atomic_transaction(subject_wtxid)
       end
 
       # Parse a BEEF hex string and return the subject transaction.
@@ -388,24 +392,38 @@ module BSV
 
       # --- Transaction ID ---
 
-      # Compute the transaction ID (double-SHA-256 of the serialised tx, byte-reversed).
+      # Wire-order transaction ID (raw SHA-256d of the serialised tx).
       #
-      # Returns display byte order (reversed from the natural hash).
-      # Compare with {TransactionInput#prev_tx_id} which stores wire byte
-      # order (natural hash). Use +.reverse+ to convert between the two.
+      # Used by BEEF, BUMPs, and merkle paths, which all work in wire byte order
+      # to match {TransactionInput#prev_wtxid}.
       #
-      # @return [String] 32-byte transaction ID in display byte order
-      def txid
-        BSV::Primitives::Digest.sha256d(to_binary).reverse
+      # @return [String] 32-byte transaction ID in wire byte order
+      def wtxid
+        id = BSV::Primitives::Digest.sha256d(to_binary)
+        BSV.logger&.debug { "[Transaction] wtxid computed (dtxid=#{id.reverse.unpack1('H*')})" }
+        id
       end
 
       # The transaction ID as a hex string (display byte order).
       #
-      # @return [String] hex-encoded transaction ID
+      # @return [String] 64-char hex-encoded transaction ID (display order)
       def txid_hex
-        txid.unpack1('H*')
+        wtxid.reverse.unpack1('H*')
       end
 
+      # Display-order transaction ID as a hex string.
+      #
+      # Mirrors the wallet gem's +DisplayTxid+ pattern. +dtxid+ always returns
+      # a 64-char hex string suitable for JSON and UI boundaries.
+      #
+      # @return [String] hex-encoded transaction ID (display order)
+      alias dtxid txid_hex
+
+      # Display-order transaction ID as a hex string (alias for {#dtxid}).
+      #
+      # @return [String] hex-encoded transaction ID (display order)
+      alias dtxid_hex txid_hex
+
       # --- Sighash (BIP-143 with FORKID) ---
 
       # Build the BIP-143 sighash preimage for an input.
@@ -421,6 +439,29 @@ module BSV
         raise ArgumentError, 'only SIGHASH_FORKID types are supported' unless sighash_type & Sighash::FORK_ID != 0
 
         input = @inputs[input_index]
+        raise ArgumentError, "no input at index #{input_index}" if input.nil?
+
+        # Resolve source data from wired source_transaction when not explicitly set.
+        if input.source_transaction
+          source_output = input.source_transaction.outputs[input.prev_tx_out_index]
+          if source_output
+            input.source_satoshis       ||= source_output.satoshis
+            input.source_locking_script ||= source_output.locking_script
+          end
+        end
+
+        if input.source_satoshis.nil?
+          raise ArgumentError,
+                "input #{input_index} has nil source_satoshis — " \
+                'set it or wire source_transaction before computing sighash'
+        end
+
+        unless subscript || input.source_locking_script
+          raise ArgumentError,
+                "input #{input_index} has nil source_locking_script — " \
+                'set it or wire source_transaction before computing sighash'
+        end
+
         base_type = sighash_type & Sighash::MASK
         anyone = sighash_type.anybits?(Sighash::ANYONE_CAN_PAY)
 
@@ -456,6 +497,19 @@ module BSV
         # 10. sighash type (4 LE) — includes FORKID flag
         buf << [sighash_type].pack('V')
 
+        BSV.logger&.debug do
+          hp = buf.byteslice(4, 32).unpack1('H*')
+          hs = buf.byteslice(36, 32).unpack1('H*')
+          op = input.outpoint_binary.unpack1('H*')
+          sc = script_bytes.unpack1('H*')
+          ho = buf.byteslice(-40, 32).unpack1('H*')
+          "[Sighash] input=#{input_index} type=0x#{format('%02x', sighash_type)} " \
+            "version=#{@version} hashPrevouts=#{hp} hashSequence=#{hs} " \
+            "outpoint=#{op} scriptCode=#{sc[0, 40]}#{'...' if sc.length > 40} " \
+            "value=#{input.source_satoshis} seq=#{input.sequence} " \
+            "hashOutputs=#{ho} locktime=#{@lock_time}"
+        end
+
         buf
       end
 
@@ -466,7 +520,9 @@ module BSV
       # @param subscript [Script::Script, nil] override locking script for the input
       # @return [String] 32-byte sighash digest
       def sighash(input_index, sighash_type = Sighash::ALL_FORK_ID, subscript: nil)
-        BSV::Primitives::Digest.sha256d(sighash_preimage(input_index, sighash_type, subscript: subscript))
+        digest = BSV::Primitives::Digest.sha256d(sighash_preimage(input_index, sighash_type, subscript: subscript))
+        BSV.logger&.debug { "[Sighash] digest=#{digest.unpack1('H*')}" }
+        digest
       end
 
       # --- Signing ---
@@ -580,17 +636,17 @@ module BSV
 
         until queue.empty?
           tx = queue.shift
-          tx_id = tx.txid_hex
-          next if verified[tx_id]
+          wtxid = tx.wtxid
+          next if verified[wtxid]
 
           # Merkle path short-circuit: proven transaction needs no input verification
           if tx.merkle_path
-            unless tx.merkle_path.verify(tx_id, chain_tracker)
+            unless tx.merkle_path.verify(tx.txid_hex, chain_tracker)
               raise VerificationError.new(:invalid_merkle_proof,
-                                          "invalid merkle proof for transaction #{tx_id}")
+                                          "invalid merkle proof for transaction #{tx.txid_hex}")
             end
 
-            verified[tx_id] = true
+            verified[wtxid] = true
             next
           end
 
@@ -622,13 +678,13 @@ module BSV
 
             # Enqueue source transaction for verification if not yet verified
             source_tx = input.source_transaction
-            queue << source_tx if source_tx && !verified[source_tx.txid_hex]
+            queue << source_tx if source_tx && !verified[source_tx.wtxid]
           end
 
           # Output ≤ input check
           verify_output_constraint(tx)
 
-          verified[tx_id] = true
+          verified[wtxid] = true
         end
 
         true
@@ -777,19 +833,19 @@ module BSV
       end
 
       def verify_input_requirements(tx, input, index)
-        tx_id = tx.txid_hex
+        dtxid_hex = tx.txid_hex
         if input.unlocking_script.nil?
           raise VerificationError.new(:missing_source,
-                                      "input #{index} of transaction #{tx_id} has no unlocking script")
+                                      "input #{index} of transaction #{dtxid_hex} has no unlocking script")
         end
         if input.source_locking_script.nil?
           raise VerificationError.new(:missing_source,
-                                      "input #{index} of transaction #{tx_id} has no source locking script")
+                                      "input #{index} of transaction #{dtxid_hex} has no source locking script")
         end
         return unless input.source_satoshis.nil?
 
         raise VerificationError.new(:missing_source,
-                                    "input #{index} of transaction #{tx_id} has no source satoshis")
+                                    "input #{index} of transaction #{dtxid_hex} has no source satoshis")
       end
 
       def verify_fee(fee_model)
@@ -843,7 +899,7 @@ module BSV
 
       # Collect this transaction and all its ancestors in dependency order
       # (ancestors first, self last). Stops recursion at transactions with
-      # a merkle_path (proven leaves). Deduplicates by txid.
+      # a merkle_path (proven leaves). Deduplicates by wtxid (wire-order bytes).
       def collect_ancestors
         seen = {}
         result = []
@@ -852,18 +908,25 @@ module BSV
       end
 
       def collect_ancestors_recursive(tx, seen, result)
-        txid = tx.txid
-        return if seen.key?(txid)
+        wtxid = tx.wtxid
+        return if seen.key?(wtxid)
 
-        unless tx.merkle_path
-          tx.inputs.each do |input|
-            next unless input.source_transaction
+        if tx.merkle_path
+          BSV.logger&.debug do
+            "[Transaction] ancestor: #{tx.dtxid_hex} proven at height #{tx.merkle_path.block_height} (leaf stop)"
+          end
+        else
+          tx.inputs.each_with_index do |input, idx|
+            unless input.source_transaction
+              BSV.logger&.debug { "[Transaction] ancestor: #{tx.dtxid_hex} input #{idx} has no source_transaction (skipped)" }
+              next
+            end
 
             collect_ancestors_recursive(input.source_transaction, seen, result)
           end
         end
 
-        seen[txid] = true
+        seen[wtxid] = true
         result << tx
       end
 
@@ -886,8 +949,8 @@ module BSV
           merged = txs.first.merkle_path.dup
           txs.drop(1).each { |t| merged.combine(t.merkle_path) }
 
-          txid_hashes = txs.map { |t| t.txid.reverse }
-          clean = merged.extract(txid_hashes)
+          wtxid_hashes = txs.map(&:wtxid)
+          clean = merged.extract(wtxid_hashes)
 
           bump_index_by_height[height] = beef.bumps.length
           beef.bumps << clean

data/lib/bsv/transaction/transaction_input.rb

@@ -8,8 +8,8 @@ module BSV
     # output index (the "outpoint"), and provide an unlocking script to
     # satisfy the locking script conditions.
     class TransactionInput
-      # @return [String] 32-byte transaction ID of the output being spent (internal byte order)
-      attr_reader :prev_tx_id
+      # @return [String] 32-byte wire-order transaction ID of the output being spent
+      attr_reader :prev_wtxid
 
       # @return [Integer] index of the output within the previous transaction
       attr_reader :prev_tx_out_index
@@ -32,15 +32,17 @@ module BSV
       # @return [UnlockingScriptTemplate, nil] template for deferred signing
       attr_accessor :unlocking_script_template
 
-      # @param prev_tx_id [String] 32-byte transaction ID (internal byte order)
+      # @param prev_wtxid [String] 32-byte wire-order transaction ID
       # @param prev_tx_out_index [Integer] output index in the previous transaction
       # @param unlocking_script [Script::Script, nil] unlocking script (nil if unsigned)
       # @param sequence [Integer] sequence number
-      def initialize(prev_tx_id:, prev_tx_out_index:, unlocking_script: nil, sequence: 0xFFFFFFFF)
-        @prev_tx_id = prev_tx_id.b
+      def initialize(prev_wtxid:, prev_tx_out_index:, unlocking_script: nil, sequence: 0xFFFFFFFF)
+        BSV::Primitives::Hex.validate_wtxid!(prev_wtxid, name: 'prev_wtxid')
+        @prev_wtxid = prev_wtxid.b
         @prev_tx_out_index = prev_tx_out_index
         @unlocking_script = unlocking_script
         @sequence = sequence
+        BSV.logger&.debug { "[TransactionInput] prev_wtxid set: #{dtxid_hex}:#{@prev_tx_out_index}" }
       end
 
       # Serialise the input to its binary wire format.
@@ -48,7 +50,7 @@ module BSV
       # @return [String] binary input (outpoint + varint + script + sequence)
       def to_binary
         script_bytes = @unlocking_script ? @unlocking_script.to_binary : ''.b
-        @prev_tx_id +
+        @prev_wtxid +
           [@prev_tx_out_index].pack('V') +
           VarInt.encode(script_bytes.bytesize) +
           script_bytes +
@@ -66,7 +68,7 @@ module BSV
                 "truncated input: need 36 bytes for outpoint at offset #{offset}, got #{data.bytesize - offset}"
         end
 
-        prev_tx_id = data.byteslice(offset, 32)
+        prev_wtxid = data.byteslice(offset, 32)
         prev_tx_out_index = data.byteslice(offset + 32, 4).unpack1('V')
         offset += 36
 
@@ -90,7 +92,7 @@ module BSV
 
         total = 36 + vi_size + script_len + 4
         input = new(
-          prev_tx_id: prev_tx_id,
+          prev_wtxid: prev_wtxid,
           prev_tx_out_index: prev_tx_out_index,
           unlocking_script: unlocking_script,
           sequence: sequence
@@ -98,26 +100,29 @@ module BSV
         [input, total]
       end
 
-      # Convert a hex transaction ID to internal byte order (reversed).
+      # Convert a display-order hex transaction ID to wire-order bytes.
       #
       # @param hex [String] hex-encoded transaction ID (display order)
-      # @return [String] 32-byte transaction ID in internal byte order
-      def self.txid_from_hex(hex)
-        [hex].pack('H*').reverse
+      # @return [String] 32-byte transaction ID in wire byte order
+      def self.wtxid_from_hex(hex)
+        BSV::Primitives::Hex.validate_dtxid_hex!(hex, name: 'wtxid_from_hex input')
+        wtxid = [hex].pack('H*').reverse
+        BSV.logger&.debug { "[TransactionInput] wtxid_from_hex: #{hex} -> #{wtxid.bytesize}B wire-order" }
+        wtxid
       end
 
-      # Serialise the outpoint (prev_tx_id + output index) as binary.
+      # Serialise the outpoint (prev_wtxid + output index) as binary.
       #
       # @return [String] 36-byte outpoint
       def outpoint_binary
-        @prev_tx_id + [@prev_tx_out_index].pack('V')
+        @prev_wtxid + [@prev_tx_out_index].pack('V')
       end
 
-      # The previous transaction ID in hex (display order).
+      # The previous transaction ID in display-order hex.
       #
-      # @return [String] hex-encoded transaction ID
-      def txid_hex
-        @prev_tx_id.reverse.unpack1('H*')
+      # @return [String] hex-encoded transaction ID (display order)
+      def dtxid_hex
+        @prev_wtxid.reverse.unpack1('H*')
       end
     end
   end

data/lib/bsv/version.rb

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

data/lib/bsv/wallet/interface/brc100.rb

@@ -38,10 +38,12 @@ module BSV
         #   - :basket [String] optional basket name for UTXO tracking
         #   - :custom_instructions [String] application-specific context
         #   - :tags [Array<String>] output tags for filtering
-        # @return [Hash] :txid, :tx, :no_send_change, :send_with_results, :signable_transaction
+        # @return [Hash] BRC-100 spec-mandated keys: :txid (display-order hex), :tx, :no_send_change,
+        #   :send_with_results, :signable_transaction
         def create_action(description:, input_beef: nil, inputs: nil, outputs: nil,
                           lock_time: nil, version: nil, labels: nil,
                           sign_and_process: true, accept_delayed_broadcast: true,
+                          # BRC-100 spec-mandated parameter names — display-order hex txids
                           trust_self: nil, known_txids: nil, return_txid_only: false,
                           no_send: false, no_send_change: nil, send_with: nil,
                           randomize_outputs: true, originator: nil)
@@ -53,7 +55,8 @@ module BSV
         # @param spends [Hash{Integer => Hash}] input index => { unlocking_script:, sequence_number: }
         # @param reference [String] reference returned by {#create_action}
         def sign_action(spends:, reference:,
-                        accept_delayed_broadcast: true, return_txid_only: false,
+                        accept_delayed_broadcast: true,
+                        return_txid_only: false, # BRC-100 spec-mandated parameter name
                         no_send: false, send_with: nil, originator: nil)
           raise NotImplementedError
         end

data/lib/bsv/wallet/proto_wallet/key_deriver.rb

@@ -45,6 +45,7 @@ module BSV
           Validators.validate_protocol_id!(protocol_id)
           Validators.validate_key_id!(key_id)
           invoice = compute_invoice_number(protocol_id, key_id)
+          BSV.logger&.debug { "[KeyDeriver] derive_public_key: invoice=#{invoice.inspect} for_self=#{for_self}" }
           counterparty_pub = resolve_counterparty(counterparty)
 
           if for_self
@@ -64,6 +65,7 @@ module BSV
           Validators.validate_protocol_id!(protocol_id)
           Validators.validate_key_id!(key_id)
           invoice = compute_invoice_number(protocol_id, key_id)
+          BSV.logger&.debug { "[KeyDeriver] derive_private_key: invoice=#{invoice.inspect}" }
           counterparty_pub = resolve_counterparty(counterparty)
           @root_key.derive_child(counterparty_pub, invoice)
         end

data/lib/bsv/wallet/proto_wallet.rb

@@ -127,6 +127,7 @@ module BSV
                            counterparty: nil, privileged: false, privileged_reason: nil,
                            seek_permission: true, originator: nil)
         counterparty ||= 'anyone'
+        BSV.logger&.debug { "[ProtoWallet] create_signature: protocol=#{protocol_id} key_id=#{key_id.inspect} counterparty=#{counterparty}" }
         priv_key = @key_deriver.derive_private_key(protocol_id, key_id, counterparty)
 
         hash = if hash_to_directly_sign
@@ -156,6 +157,10 @@ module BSV
                            privileged: false, privileged_reason: nil,
                            seek_permission: true, originator: nil)
         counterparty ||= 'self'
+        BSV.logger&.debug do
+          "[ProtoWallet] verify_signature: protocol=#{protocol_id} key_id=#{key_id.inspect} " \
+            "counterparty=#{counterparty} for_self=#{for_self}"
+        end
 
         pub_key = @key_deriver.derive_public_key(
           protocol_id, key_id, counterparty, for_self: for_self
@@ -169,6 +174,7 @@ module BSV
 
         sig   = BSV::Primitives::Signature.from_der(bytes_to_string(signature))
         valid = pub_key.verify(hash, sig)
+        BSV.logger&.debug { "[ProtoWallet] verify_signature result=#{valid}" }
 
         raise InvalidSignatureError unless valid