bsv-sdk 0.16.0 → 0.17.0

data/lib/bsv/transaction/transaction.rb

@@ -329,6 +329,11 @@ 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
@@ -370,11 +375,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(&:transaction)&.transaction&.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,15 +393,26 @@ 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).
+      #
+      # 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 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
+
+      # Display-order transaction ID (reversed from the natural SHA-256d hash).
       #
-      # 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.
+      # This is the conventional human-readable representation used in block
+      # explorers, wallets, and all user-facing contexts.
       #
       # @return [String] 32-byte transaction ID in display byte order
       def txid
-        BSV::Primitives::Digest.sha256d(to_binary).reverse
+        wtxid.reverse
       end
 
       # The transaction ID as a hex string (display byte order).
@@ -406,6 +422,19 @@ module BSV
         txid.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.
@@ -456,6 +485,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 +508,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 +624,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 +666,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 +821,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 +887,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 +896,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 +937,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.17.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
 

data/lib/bsv-sdk.rb

@@ -3,6 +3,20 @@
 require_relative 'bsv/version'
 
 module BSV
+  class << self
+    # Optional logger for debug-level instrumentation of txid conversions,
+    # BEEF wiring, and merkle path operations.
+    #
+    # No logger is configured by default — zero overhead when unused.
+    # Consumers opt in via:
+    #
+    #   require 'logger'
+    #   BSV.logger = Logger.new($stdout).tap { |l| l.level = Logger::DEBUG }
+    #
+    # @return [Logger, nil]
+    attr_accessor :logger
+  end
+
   autoload :Primitives,  'bsv/primitives'
   autoload :Script,      'bsv/script'
   autoload :Transaction, 'bsv/transaction'

metadata

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