bsv-sdk 0.23.1 → 0.25.0

data/lib/bsv/storage/utils.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Storage
+    # Helpers for encoding and decoding UHRP (Unified Hash Resource Protocol) URLs.
+    #
+    # A UHRP URL is a Base58Check string with a two-byte `\xCE\x00` prefix prepended
+    # to the SHA-256 hash of the content. This makes each URL self-verifying and
+    # stable across storage providers.
+    #
+    # == URL normalisation
+    #
+    # `normalize_url` strips the `uhrp:` scheme (case-insensitive) and the optional
+    # `//` authority prefix, matching the TS SDK contract exactly. The `web+uhrp://`
+    # variant used by some browser extension manifests is *not* normalised here — that
+    # diverges from the TS reference (Python normalises it; we follow TS).
+    module Utils
+      # Two-byte UHRP version prefix: 0xCE 0x00.
+      UHRP_PREFIX = "\xCE\x00".b.freeze
+
+      module_function
+
+      # Encode a 32-byte binary SHA-256 hash as a UHRP URL.
+      #
+      # @param hash [String] 32-byte binary string (SHA-256 hash)
+      # @return [String] Base58Check-encoded UHRP URL
+      # @raise [ArgumentError] if hash is not exactly 32 bytes
+      def get_url_for_hash(hash)
+        raise ArgumentError, 'Hash length must be 32 bytes (sha256)' unless hash.bytesize == 32
+
+        BSV::Primitives::Base58.check_encode(hash.b, prefix: UHRP_PREFIX)
+      end
+
+      # Compute the SHA-256 hash of +data+ and encode it as a UHRP URL.
+      #
+      # @param data [String] binary file content
+      # @return [String] Base58Check-encoded UHRP URL
+      def get_url_for_file(data)
+        hash = OpenSSL::Digest::SHA256.digest(data.b)
+        get_url_for_hash(hash)
+      end
+
+      # Decode a UHRP URL and return the 32-byte binary SHA-256 hash.
+      #
+      # Accepts URLs with or without the `uhrp:` scheme and optional `//` authority.
+      #
+      # @param url [String] UHRP URL (with or without `uhrp:` prefix)
+      # @return [String] 32-byte binary SHA-256 hash
+      # @raise [ArgumentError] if the URL is not a String, empty, has a bad prefix, or has wrong length
+      # @raise [BSV::Primitives::Base58::ChecksumError] if the Base58Check checksum fails
+      def get_hash_from_url(url)
+        raise ArgumentError, 'URL must be a String' unless url.is_a?(String)
+        raise ArgumentError, 'URL must not be empty' if url.empty?
+
+        normalised = normalize_url(url)
+        result = BSV::Primitives::Base58.check_decode(normalised, prefix_length: 2)
+        raise ArgumentError, 'Bad prefix' unless result[:prefix] == UHRP_PREFIX
+        raise ArgumentError, 'Invalid length!' unless result[:data].bytesize == 32
+
+        result[:data]
+      end
+
+      # Strip the `uhrp:` scheme (case-insensitive) and optional `//` from a URL.
+      #
+      # Follows the TS SDK contract: only `uhrp:` and `uhrp://` are normalised.
+      # `web+uhrp://` is deliberately not stripped (TS does not strip it; Python does).
+      #
+      # @param url [String] URL to normalise
+      # @return [String] normalised URL
+      def normalize_url(url)
+        url = url.slice(5..) if url.downcase.start_with?('uhrp:')
+        url = url.slice(2..) if url.start_with?('//')
+        url
+      end
+
+      # Return +true+ if +url+ is a syntactically valid UHRP URL.
+      #
+      # @param url [String] URL to validate
+      # @return [Boolean]
+      def valid_url?(url)
+        get_hash_from_url(url)
+        true
+      rescue ArgumentError, BSV::Primitives::Base58::ChecksumError
+        false
+      end
+    end
+  end
+end

data/lib/bsv/storage.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BSV
+  # Storage module for UHRP (Unified Hash Resource Protocol) URL encoding,
+  # decoding, and validation helpers.
+  #
+  # UHRP enables content-addressed storage on BSV: a SHA-256 hash of a file
+  # is Base58Check-encoded with the `\xCE\x00` prefix to produce a stable,
+  # self-verifying URL.
+  module Storage
+    autoload :Utils,          'bsv/storage/utils'
+    autoload :DownloadResult, 'bsv/storage/downloader'
+    autoload :Downloader,     'bsv/storage/downloader'
+    autoload :DownloadError,  'bsv/storage/errors'
+  end
+end

data/lib/bsv/transaction/beef.rb

@@ -72,10 +72,10 @@ module BSV
 
       # A BEEF entry containing a raw transaction without a merkle proof.
       class RawTxEntry < BeefTx
-        # @return [Transaction] the transaction
+        # @return [Transaction::Tx] the transaction
         attr_reader :transaction
 
-        # @param transaction [Transaction] the transaction
+        # @param transaction [Transaction::Tx] the transaction
         # @raise [ArgumentError] if transaction is nil
         def initialize(transaction:)
           raise ArgumentError, 'RawTxEntry requires a transaction' if transaction.nil?
@@ -97,13 +97,13 @@ module BSV
 
       # A BEEF entry containing a raw transaction with an associated BUMP index.
       class ProvenTxEntry < BeefTx
-        # @return [Transaction] the transaction
+        # @return [Transaction::Tx] the transaction
         attr_reader :transaction
 
         # @return [Integer] index into the BEEF bumps array
         attr_reader :bump_index
 
-        # @param transaction [Transaction] the transaction
+        # @param transaction [Transaction::Tx] 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:)
@@ -188,7 +188,7 @@ module BSV
       # After parsing, input source transactions are wired automatically.
       #
       # @param data [String] raw BEEF binary
-      # @return [Beef] the parsed BEEF bundle
+      # @return [Transaction::Beef] the parsed BEEF bundle
       def self.from_binary(data)
         raise ArgumentError, "truncated BEEF: need at least 4 bytes for version, got #{data.bytesize}" if data.bytesize < 4
 
@@ -247,7 +247,7 @@ module BSV
       # Deserialise a BEEF bundle from a hex string.
       #
       # @param hex [String] hex-encoded BEEF data
-      # @return [Beef] the parsed BEEF bundle
+      # @return [Transaction::Beef] the parsed BEEF bundle
       def self.from_hex(hex)
         from_binary(BSV::Primitives::Hex.decode(hex, name: 'BEEF hex'))
       end
@@ -320,7 +320,7 @@ module BSV
       # Find a transaction in the bundle by its wire-order transaction ID.
       #
       # @param wtxid [String] 32-byte wire-order wtxid
-      # @return [Transaction, nil] the matching transaction, or nil
+      # @return [Transaction::Tx, nil] the matching transaction, or nil
       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" }
@@ -353,7 +353,7 @@ module BSV
       # Find a transaction with all source_transactions wired for signing.
       #
       # @param wtxid [String] 32-byte wire-order wtxid
-      # @return [Transaction, nil] the transaction with wired inputs, or nil
+      # @return [Transaction::Tx, nil] the transaction with wired inputs, or nil
       def find_transaction_for_signing(wtxid)
         BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
         tx = find_transaction(wtxid)
@@ -367,7 +367,7 @@ module BSV
       # and merkle paths) for atomic proof validation.
       #
       # @param wtxid [String] 32-byte wire-order wtxid
-      # @return [Transaction, nil] the transaction with full proof tree, or nil
+      # @return [Transaction::Tx, nil] the transaction with full proof tree, or nil
       def find_atomic_transaction(wtxid)
         BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
         tx = find_transaction(wtxid)
@@ -385,6 +385,161 @@ module BSV
         to_atomic_binary(subject_wtxid).unpack1('H*')
       end
 
+      # --- Supporting methods for multi-party BEEF exchange ---
+
+      # Add a TXID-only entry for +wtxid+ if no entry exists yet.
+      #
+      # If an entry already exists (in any format), the call is a no-op —
+      # TXID-only is the weakest format, so an existing stronger entry is kept.
+      #
+      # @param wtxid [String] 32-byte wire-order binary txid
+      # @return [BeefTx] the existing or newly added entry
+      def merge_txid_only(wtxid)
+        BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
+        existing = @transactions.find { |bt| bt.wtxid == wtxid }
+        return existing if existing
+
+        entry = TxidOnlyEntry.new(known_wtxid: wtxid)
+        @transactions << entry
+        entry
+      end
+
+      # Return a shallow copy of this Transaction::Beef.
+      #
+      # Both +@bumps+ and +@transactions+ arrays are duplicated (new arrays),
+      # but the +BeefTx+ and +MerklePath+ objects they contain are shared
+      # references. This mirrors the TS SDK's +clone+ contract: entries are
+      # effectively immutable once added to a bundle, so shallow semantics are
+      # correct. If a deeper copy is ever required, add a separate +deep_dup+
+      # rather than changing this method's contract.
+      #
+      # +@subject_wtxid+ (Atomic BEEF) and +@txs_not_valid+ (cyclic-graph
+      # metadata) are preserved on the copy.
+      #
+      # @return [Transaction::Beef] a new shallow copy
+      def clone
+        # Use super (Object#clone) rather than self.class.new so subclasses
+        # (e.g. Transaction::BeefParty) with different initialize signatures
+        # work correctly. Object#clone does a shallow ivar copy without
+        # invoking initialize; we then dup the two arrays so the copy's
+        # contents can mutate independently.
+        c = super
+        c.instance_variable_set(:@bumps, @bumps.dup)
+        c.instance_variable_set(:@transactions, @transactions.dup)
+        c.instance_variable_set(:@txs_not_valid, @txs_not_valid&.dup)
+        c
+      end
+
+      # Return a new Transaction::Beef with TXID-only entries removed for any
+      # wtxid in +known_wtxids+.
+      #
+      # RAW_TX and RAW_TX_AND_BUMP entries are always retained, even when their
+      # wtxid appears in +known_wtxids+. Only +TxidOnlyEntry+ records are
+      # candidates for removal (they carry no proof data the recipient needs).
+      #
+      # After dropping TXID-only entries, any BUMP that is no longer referenced
+      # by any remaining +ProvenTxEntry+ is removed, and all +bump_index+
+      # fields are renumbered to match the new bumps array (mirrors TS
+      # +trimKnownTxids+ at +Beef.ts:861-914+).
+      #
+      # Does not mutate +self+. Starts from a {#clone} so the caller's state
+      # is preserved.
+      #
+      # @param known_wtxids [Array<String>] binary wtxids the recipient already has
+      # @return [Transaction::Beef] a new bundle with the specified entries trimmed
+      def trim_known_wtxids(known_wtxids)
+        known_set = known_wtxids.to_set
+
+        trimmed = clone
+        trimmed.instance_variable_set(
+          :@transactions,
+          trimmed.transactions.reject { |bt| bt.is_a?(TxidOnlyEntry) && known_set.include?(bt.wtxid) }
+        )
+
+        # Find which bump indices are still referenced
+        referenced = Set.new
+        trimmed.transactions.each do |bt|
+          referenced.add(bt.bump_index) if bt.is_a?(ProvenTxEntry)
+        end
+
+        # If all bumps are still referenced, nothing more to do
+        return trimmed if referenced.size == trimmed.bumps.length
+
+        # Build old → new index map for surviving bumps
+        index_map = {}
+        new_idx = 0
+        trimmed.bumps.each_with_index do |_, old_idx|
+          if referenced.include?(old_idx)
+            index_map[old_idx] = new_idx
+            new_idx += 1
+          end
+        end
+
+        # Drop unreferenced bumps
+        trimmed.instance_variable_set(
+          :@bumps,
+          trimmed.bumps.each_with_index.filter_map { |bump, i| bump if referenced.include?(i) }
+        )
+
+        # Renumber bump_index on all ProvenTxEntry records
+        trimmed.instance_variable_set(
+          :@transactions,
+          trimmed.transactions.map do |bt|
+            next bt unless bt.is_a?(ProvenTxEntry)
+
+            new_bump_idx = index_map.fetch(bt.bump_index)
+            ProvenTxEntry.new(transaction: bt.transaction, bump_index: new_bump_idx).tap do |e|
+              e.transaction.merkle_path = trimmed.bumps[new_bump_idx]
+            end
+          end
+        )
+
+        trimmed
+      end
+
+      # Return the wtxids of transactions that are "valid" in this bundle.
+      #
+      # A transaction is valid when it either:
+      # - has a merkle proof (is a +ProvenTxEntry+), or
+      # - all of its inputs chain back to proven transactions within the bundle.
+      #
+      # TXID-only entries are excluded. Cyclic transactions (from
+      # +@txs_not_valid+) are also excluded.
+      #
+      # Used by {Transaction::BeefParty} to record which wtxids a party gains
+      # knowledge of after a {#merge_beef_from_party} call.
+      #
+      # @return [Array<String>] binary wire-order wtxids
+      def valid_wtxids
+        invalid = @txs_not_valid || Set.new
+        known   = Set.new
+
+        # Seed with proven entries (excluding any marked cyclic/unsortable)
+        @transactions.each do |bt|
+          known.add(bt.wtxid) if bt.is_a?(ProvenTxEntry) && !invalid.include?(bt.wtxid)
+        end
+
+        # Iteratively resolve unproven entries whose inputs are all known.
+        # Skip @txs_not_valid entries — by definition they can't be ordered
+        # for validation, so a counterparty receiving them can't validate either.
+        changed = true
+        while changed
+          changed = false
+          @transactions.each do |bt|
+            next if bt.is_a?(TxidOnlyEntry) || known.include?(bt.wtxid)
+            next if invalid.include?(bt.wtxid)
+            next unless bt.respond_to?(:transaction)
+
+            if bt.transaction.inputs.all? { |inp| known.include?(inp.prev_wtxid) }
+              known.add(bt.wtxid)
+              changed = true
+            end
+          end
+        end
+
+        known.to_a
+      end
+
       # --- Merge operations ---
 
       # Add or deduplicate a merkle path (BUMP) in this BEEF bundle.
@@ -440,7 +595,7 @@ module BSV
       # (same txid) are upgraded if a stronger format is now available (F5.7):
       # TXID_ONLY → RAW_TX or RAW_TX_AND_BUMP; RAW_TX → RAW_TX_AND_BUMP.
       #
-      # @param tx [Transaction] the transaction to merge
+      # @param tx [Transaction::Tx] the transaction to merge
       # @return [BeefTx] the (possibly existing or upgraded) BeefTx entry
       def merge_transaction(tx)
         wtxid = tx.wtxid
@@ -479,7 +634,7 @@ module BSV
       # @param bump_index [Integer, nil] optional BUMP index
       # @return [BeefTx] the new or upgraded BeefTx entry
       def merge_raw_tx(raw_bytes, bump_index: nil)
-        tx = Transaction.from_binary(raw_bytes)
+        tx = Tx.from_binary(raw_bytes)
 
         if bump_index
           unless bump_index.is_a?(Integer) && bump_index >= 0 && bump_index < @bumps.length
@@ -512,7 +667,7 @@ module BSV
       # BUMP indices are remapped during merge. New BeefTx instances are
       # constructed rather than sharing references with the source bundle (F5.9).
       #
-      # @param other [Beef] the BEEF bundle to merge from
+      # @param other [Transaction::Beef] the BEEF bundle to merge from
       # @return [self]
       # @raise [ArgumentError] if a transaction in +other+ has a +bump_index+
       #   that does not point to any BUMP in +other.bumps+ (i.e. the source
@@ -740,7 +895,7 @@ module BSV
             case format
             when FORMAT_TXID_ONLY
               # Wire stores txid in internal (little-endian / wire) byte order;
-              # store as-is in known_wtxid so it matches Transaction#wtxid.
+              # store as-is in known_wtxid so it matches Tx#wtxid.
               raise ArgumentError, 'truncated BEEF: not enough bytes for TXID_ONLY entry' if offset + 32 > data.bytesize
 
               known_wtxid = data.byteslice(offset, 32)
@@ -749,12 +904,12 @@ module BSV
             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)
+              tx, consumed = Tx.from_binary_with_offset(data, offset)
               offset += consumed
               tx.merkle_path = beef.bumps[bump_index] if bump_index < beef.bumps.length
               beef.transactions << ProvenTxEntry.new(transaction: tx, bump_index: bump_index)
             when FORMAT_RAW_TX
-              tx, consumed = Transaction.from_binary_with_offset(data, offset)
+              tx, consumed = Tx.from_binary_with_offset(data, offset)
               offset += consumed
               beef.transactions << RawTxEntry.new(transaction: tx)
             end
@@ -768,7 +923,7 @@ module BSV
           offset += vi_size
 
           num_txs.times do
-            tx, consumed = Transaction.from_binary_with_offset(data, offset)
+            tx, consumed = Tx.from_binary_with_offset(data, offset)
             offset += consumed
 
             has_bump = data.getbyte(offset)
@@ -800,8 +955,7 @@ module BSV
 
               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*')}"
+                "[Beef] wired input #{input.dtxid_hex}:#{input.prev_tx_out_index} -> source #{source.dtxid}"
               end
             end
 
@@ -821,7 +975,7 @@ module BSV
       #   RAW_TX    → RAW_TX_AND_BUMP (if bump now available)
       #
       # @param existing [BeefTx] the current entry in @transactions
-      # @param tx [Transaction, nil] the raw transaction (may be nil for TXID_ONLY → TXID_ONLY)
+      # @param tx [Transaction::Tx, nil] the raw transaction (may be nil for TXID_ONLY → TXID_ONLY)
       # @param bump_index [Integer, nil] a BUMP index already validated against @bumps
       # @return [BeefTx, nil] the upgraded entry, or nil when no upgrade is needed
       def upgrade_beef_tx(existing, tx, bump_index: nil)

data/lib/bsv/transaction/beef_party.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module BSV
+  module Transaction
+    # Transaction::Beef subclass that tracks per-party knowledge of wtxids.
+    #
+    # Used in multi-party BEEF exchange to avoid re-transmitting transaction
+    # data and proofs that a counterparty already possesses. Each party is
+    # identified by a caller-supplied string and associated with the set of
+    # wtxids it is known to hold.
+    #
+    # @example Two-party exchange
+    #   party = BSV::Transaction::BeefParty.new(['alice', 'bob'])
+    #   party.merge_beef_from_party('alice', alice_beef)
+    #   trimmed = party.trimmed_beef_for_party('bob')  # plain Transaction::Beef
+    class BeefParty < Beef
+      # @param initial_parties [Array<String>] optional initial party identifiers
+      # @raise [ArgumentError] if +initial_parties+ contains duplicates
+      #
+      # Defaults to BEEF_V2 (BRC-96) because TXID-only entries — which are
+      # central to BeefParty's purpose — are only valid in V2. Matches the TS
+      # SDK's +new Beef()+ default.
+      def initialize(initial_parties = [])
+        super(version: BEEF_V2)
+        @party_knowledge = {}
+        initial_parties.each { |p| add_party(p) }
+      end
+
+      # @param party_id [String]
+      # @return [Boolean] true if +party_id+ has been added
+      def party?(party_id)
+        @party_knowledge.key?(party_id)
+      end
+
+      # Add a new unique party identifier.
+      #
+      # @param party_id [String]
+      # @raise [ArgumentError] if +party_id+ is already known
+      def add_party(party_id)
+        raise ArgumentError, "duplicate party #{party_id}" if party?(party_id)
+
+        @party_knowledge[party_id] = Set.new
+      end
+
+      # Record additional wtxids as known to +party_id+.
+      #
+      # Auto-creates the party if it is not yet known (TS parity). Also
+      # merges a TXID-only entry into the underlying bundle for each wtxid.
+      #
+      # @param party_id [String] party identifier (auto-created if unknown)
+      # @param wtxids [Array<String>] 32-byte wire-order binary wtxids
+      # @raise [ArgumentError] if any element of +wtxids+ is not a valid wtxid
+      def add_known_wtxids_for_party(party_id, wtxids)
+        add_party(party_id) unless party?(party_id)
+        wtxids.each do |wtxid|
+          BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
+          @party_knowledge[party_id].add(wtxid)
+          merge_txid_only(wtxid)
+        end
+      end
+
+      # @param party_id [String]
+      # @return [Array<String>] 32-byte wire-order binary wtxids known to +party_id+
+      # @raise [ArgumentError] if +party_id+ is unknown
+      def known_wtxids_for_party(party_id)
+        raise ArgumentError, "unknown party #{party_id}" unless party?(party_id)
+
+        @party_knowledge[party_id].to_a
+      end
+
+      # Merge a Transaction::Beef received from +party_id+.
+      #
+      # Merges all transactions and BUMPs from +beef_or_binary+ into +self+,
+      # then records the valid wtxids of the merged bundle as known to
+      # +party_id+. Auto-creates the party if not yet known.
+      #
+      # @param party_id [String] party identifier
+      # @param beef_or_binary [Transaction::Beef, String] a Transaction::Beef
+      #   instance or raw binary BEEF bytes
+      def merge_beef_from_party(party_id, beef_or_binary)
+        beef = beef_or_binary.is_a?(Beef) ? beef_or_binary : Beef.from_binary(beef_or_binary)
+        # Capture the set of wtxids the party actually sent before merging.
+        beef_wtxids = beef.transactions.map(&:wtxid)
+        merge(beef)
+        # Record knowledge of any tx the party sent that is now provably valid
+        # against the merged state. This captures the cross-bundle case where
+        # an unproven tx in +beef+ becomes valid via inputs already proven in
+        # +self+ (and conversely doesn't record knowledge the party never sent).
+        known = valid_wtxids & beef_wtxids
+        add_known_wtxids_for_party(party_id, known)
+      end
+
+      # Return a new Transaction::Beef (not Transaction::BeefParty) with
+      # TXID-only entries that are known to +party_id+ removed.
+      #
+      # RAW_TX and RAW_TX_AND_BUMP entries are always retained even when the
+      # party knows the txid — those formats carry proof data. BUMP indices
+      # are renumbered if any unreferenced bumps are dropped.
+      #
+      # Does not mutate +self+.
+      #
+      # @param party_id [String]
+      # @return [Transaction::Beef] a new trimmed bundle (plain Beef, not BeefParty)
+      # @raise [ArgumentError] if +party_id+ is unknown
+      def trimmed_beef_for_party(party_id)
+        raise ArgumentError, "unknown party #{party_id}" unless party?(party_id)
+
+        known = @party_knowledge[party_id].to_a
+
+        # Build a plain Beef from our current state so trim_known_wtxids
+        # returns a Beef, not a BeefParty.
+        plain = Beef.new(version: @version, bumps: @bumps.dup, transactions: @transactions.dup)
+        plain.instance_variable_set(:@subject_wtxid, @subject_wtxid)
+        plain.instance_variable_set(:@txs_not_valid, @txs_not_valid&.dup)
+        plain.trim_known_wtxids(known)
+      end
+    end
+  end
+end

data/lib/bsv/transaction/chain_tracker.rb

@@ -4,7 +4,7 @@ module BSV
   module Transaction
     # Duck type for block header lookups used by the SDK's verify methods.
     #
-    # {Beef#verify}, {MerklePath#verify}, and {Transaction#verify} define
+    # {Beef#verify}, {MerklePath#verify}, and {Tx#verify} define
     # what a valid structure *is* — they walk trees, check proofs, and
     # compare roots. But they have no data source of their own. The
     # chain tracker is the data source: an object the consumer provides
@@ -56,7 +56,7 @@ module BSV
       # Return a default ChainTracker backed by the GorillaPool provider.
       #
       # @param testnet [Boolean] when true, uses the testnet provider
-      # @return [ChainTracker]
+      # @return [Transaction::ChainTracker]
       def self.default(testnet: false)
         new(BSV::Network::Providers::GorillaPool.default(testnet: testnet))
       end

data/lib/bsv/transaction/fee_model.rb

@@ -17,7 +17,7 @@ module BSV
     class FeeModel
       # Compute the fee for a transaction.
       #
-      # @param transaction [Transaction] the transaction to compute the fee for
+      # @param transaction [Transaction::Tx] the transaction to compute the fee for
       # @return [Integer] the fee in satoshis
       # @raise [NotImplementedError] if not overridden by a subclass
       def compute_fee(_transaction)

data/lib/bsv/transaction/fee_models/live_policy.rb

@@ -66,7 +66,7 @@ module BSV
 
         # Compute the fee for a transaction using the latest ARC rate.
         #
-        # @param transaction [Transaction] the transaction to compute the fee for
+        # @param transaction [Transaction::Tx] the transaction to compute the fee for
         # @return [Integer] the fee in satoshis
         def compute_fee(transaction)
           rate = current_rate

data/lib/bsv/transaction/fee_models/satoshis_per_kilobyte.rb

@@ -23,7 +23,7 @@ module BSV
 
         # Compute the fee for a transaction based on its estimated size.
         #
-        # @param transaction [Transaction] the transaction to compute the fee for
+        # @param transaction [Transaction::Tx] the transaction to compute the fee for
         # @return [Integer] the fee in satoshis
         def compute_fee(transaction)
           size = transaction.estimated_size

data/lib/bsv/transaction/merkle_path.rb

@@ -322,7 +322,7 @@ module BSV
       # logic is: reject when `current_height - block_height < 100` (immature).
       #
       # @param dtxid_hex [String] hex-encoded transaction ID (display order)
-      # @param chain_tracker [ChainTracker] chain tracker to verify the root against
+      # @param chain_tracker [Transaction::ChainTracker] chain tracker to verify the root against
       # @return [Boolean] true if the computed root matches the block at this height
       def verify(dtxid_hex, chain_tracker)
         BSV::Primitives::Hex.validate_dtxid_hex!(dtxid_hex, name: 'dtxid_hex')
@@ -450,7 +450,7 @@ module BSV
       # that the extracted path computes the same merkle root as the
       # source.
       #
-      # The primary use case is +Transaction#to_beef+: when a BUMP loaded
+      # The primary use case is +Tx#to_beef+: when a BUMP loaded
       # from a proof store carries +txid: true+ flags for transactions
       # that are not part of the current BEEF bundle, extracting only the
       # bundled txids strips the phantom flags (and the now-unneeded

data/lib/bsv/transaction/p2pkh.rb

@@ -24,7 +24,7 @@ module BSV
 
       # Generate the P2PKH unlocking script for the given input.
       #
-      # @param tx [Transaction] the transaction being signed
+      # @param tx [Transaction::Tx] the transaction being signed
       # @param input_index [Integer] the input index to sign
       # @return [Script::Script] the unlocking script (signature + pubkey)
       def sign(tx, input_index)

data/lib/bsv/transaction/transaction_input.rb

@@ -26,7 +26,7 @@ module BSV
       # @return [Script::Script, nil] locking script of the source output (needed for sighash)
       attr_accessor :source_locking_script
 
-      # @return [Transaction, nil] the full source transaction (for BEEF wiring)
+      # @return [Transaction::Tx, nil] the full source transaction (for BEEF wiring)
       attr_accessor :source_transaction
 
       # @return [UnlockingScriptTemplate, nil] template for deferred signing