bsv-sdk 0.24.0 → 0.25.0

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 [Tx] the transaction
+        # @return [Transaction::Tx] the transaction
         attr_reader :transaction
 
-        # @param transaction [Tx] 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 [Tx] the transaction
+        # @return [Transaction::Tx] the transaction
         attr_reader :transaction
 
         # @return [Integer] index into the BEEF bumps array
         attr_reader :bump_index
 
-        # @param transaction [Tx] 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 [Tx, 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 [Tx, 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 [Tx, 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 [Tx] 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
@@ -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
@@ -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 [Tx, 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

@@ -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 [Tx] 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 [Tx] 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 [Tx] 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')

data/lib/bsv/transaction/p2pkh.rb

@@ -24,7 +24,7 @@ module BSV
 
       # Generate the P2PKH unlocking script for the given input.
       #
-      # @param tx [Tx] 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 [Tx, 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

data/lib/bsv/transaction/tx.rb

@@ -59,7 +59,7 @@ module BSV
 
       # Append a transaction input.
       #
-      # @param input [TransactionInput] the input to add
+      # @param input [Transaction::TransactionInput] the input to add
       # @return [self] for chaining
       def add_input(input)
         @inputs << input
@@ -68,7 +68,7 @@ module BSV
 
       # Append a transaction output.
       #
-      # @param output [TransactionOutput] the output to add
+      # @param output [Transaction::TransactionOutput] the output to add
       # @return [self] for chaining
       def add_output(output)
         @outputs << output
@@ -144,7 +144,7 @@ module BSV
       # Deserialise a transaction from binary data.
       #
       # @param data [String] raw binary transaction
-      # @return [Tx] the parsed transaction
+      # @return [Transaction::Tx] the parsed transaction
       def self.from_binary(data)
         raise ArgumentError, "truncated transaction: need at least 10 bytes, got #{data.bytesize}" if data.bytesize < 10
 
@@ -182,7 +182,7 @@ module BSV
       # Deserialise a transaction from a hex string.
       #
       # @param hex [String] hex-encoded transaction
-      # @return [Tx] the parsed transaction
+      # @return [Transaction::Tx] the parsed transaction
       def self.from_hex(hex)
         from_binary(BSV::Primitives::Hex.decode(hex, name: 'transaction hex'))
       end
@@ -190,7 +190,7 @@ module BSV
       # Deserialise a transaction from Extended Format (BRC-30) binary data.
       #
       # @param data [String] raw EF binary
-      # @return [Tx] the parsed transaction with source data on inputs
+      # @return [Transaction::Tx] the parsed transaction with source data on inputs
       # @raise [ArgumentError] if the EF marker is invalid
       def self.from_ef(data)
         raise ArgumentError, "truncated EF transaction: need at least 10 bytes, got #{data.bytesize}" if data.bytesize < 10
@@ -250,7 +250,7 @@ module BSV
       # Deserialise a transaction from an Extended Format hex string.
       #
       # @param hex [String] hex-encoded EF transaction
-      # @return [Tx] the parsed transaction with source data on inputs
+      # @return [Transaction::Tx] the parsed transaction with source data on inputs
       def self.from_ef_hex(hex)
         from_ef(BSV::Primitives::Hex.decode(hex, name: 'EF transaction hex'))
       end
@@ -260,7 +260,7 @@ module BSV
       #
       # @param data [String] binary data containing the transaction
       # @param offset [Integer] byte offset to start reading from
-      # @return [Array(Tx, Integer)] the transaction and bytes consumed
+      # @return [Array(Transaction::Tx, Integer)] the transaction and bytes consumed
       def self.from_binary_with_offset(data, offset = 0)
         if data.bytesize < offset + 10
           raise ArgumentError, "truncated transaction: need at least 10 bytes at offset #{offset}, got #{data.bytesize - offset}"
@@ -370,7 +370,7 @@ module BSV
       # +wire_source_transactions+ pass in +Beef.from_binary+.
       #
       # @param data [String] raw BEEF binary
-      # @return [Tx, nil] the subject transaction with ancestry wired,
+      # @return [Transaction::Tx, nil] the subject transaction with ancestry wired,
       #   or nil if the BEEF is empty or contains no raw transaction entries
       def self.from_beef(data)
         beef = Beef.from_binary(data)
@@ -384,7 +384,7 @@ module BSV
       # Parse a BEEF hex string and return the subject transaction.
       #
       # @param hex [String] hex-encoded BEEF
-      # @return [Tx, nil] the subject transaction with ancestry wired,
+      # @return [Transaction::Tx, nil] the subject transaction with ancestry wired,
       #   or nil if the BEEF is empty or contains no raw transaction entries
       def self.from_beef_hex(hex)
         from_beef(BSV::Primitives::Hex.decode(hex, name: 'BEEF hex'))
@@ -622,7 +622,7 @@ module BSV
       # - +:script_failure+ — Ruby raises; TS/Python return +false+; Go also propagates errors
       # - +:missing_source+ — Ruby raises; consistent with TS/Go/Python (all raise/error)
       #
-      # @param chain_tracker [ChainTracker] chain tracker for merkle root validation
+      # @param chain_tracker [Transaction::ChainTracker] chain tracker for merkle root validation
       # @param fee_model [FeeModel, nil] optional fee model to validate the root transaction's fee
       # @return [true] on successful verification
       # @raise [VerificationError] with code +:invalid_merkle_proof+ if a merkle proof is invalid
@@ -806,7 +806,7 @@ module BSV
       # is required. Otherwise, requires a wired +source_transaction+ and a
       # valid output at +prev_tx_out_index+.
       #
-      # @param input [TransactionInput]
+      # @param input [Transaction::TransactionInput]
       # @param idx [Integer] input index, used in error messages
       # @return [TransactionOutput, nil]
       def ef_source_output(input, idx)

data/lib/bsv/transaction/unlocking_script_template.rb

@@ -14,7 +14,7 @@ module BSV
     class UnlockingScriptTemplate
       # Generate the unlocking script for a transaction input.
       #
-      # @param _tx [Tx] 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 generated unlocking script
       # @raise [NotImplementedError] if not overridden by a subclass
@@ -24,7 +24,7 @@ module BSV
 
       # Estimate the unlocking script length in bytes (for fee estimation).
       #
-      # @param _tx [Tx] the transaction
+      # @param _tx [Transaction::Tx] the transaction
       # @param _input_index [Integer] the input index
       # @return [Integer] estimated script length in bytes
       # @raise [NotImplementedError] if not overridden by a subclass

data/lib/bsv/transaction.rb

@@ -19,6 +19,7 @@ module BSV
     autoload :ChainTracker,             'bsv/transaction/chain_tracker'
     autoload :ChainTrackers,            'bsv/transaction/chain_trackers'
     autoload :Beef,                     'bsv/transaction/beef'
+    autoload :BeefParty, 'bsv/transaction/beef_party'
     autoload :UnlockingScriptTemplate,  'bsv/transaction/unlocking_script_template'
     autoload :P2PKH,                    'bsv/transaction/p2pkh'
     autoload :Tx,                       'bsv/transaction/tx'

data/lib/bsv/version.rb

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

data/lib/bsv-sdk.rb

@@ -26,6 +26,8 @@ module BSV
   autoload :Identity,    'bsv/identity'
   autoload :Registry,    'bsv/registry'
   autoload :MCP,         'bsv/mcp'
+  autoload :Storage,     'bsv/storage'
+  autoload :KVStore,     'bsv/kv_store'
 
   # Wallet is loaded eagerly to avoid load-path shadowing when bsv-wallet is
   # also in the bundle (bsv-wallet/lib/bsv/wallet.rb would otherwise win).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -85,6 +85,11 @@ files:
 - lib/bsv/identity/constants.rb
 - lib/bsv/identity/identity_parser.rb
 - lib/bsv/identity/types.rb
+- lib/bsv/kv_store.rb
+- lib/bsv/kv_store/entry.rb
+- lib/bsv/kv_store/global.rb
+- lib/bsv/kv_store/interpreter.rb
+- lib/bsv/kv_store/token.rb
 - lib/bsv/mcp.rb
 - lib/bsv/mcp/config.rb
 - lib/bsv/mcp/server.rb
@@ -118,6 +123,7 @@ files:
 - lib/bsv/overlay/broadcast_facilitator.rb
 - lib/bsv/overlay/constants.rb
 - lib/bsv/overlay/errors.rb
+- lib/bsv/overlay/historian.rb
 - lib/bsv/overlay/host_reputation_tracker.rb
 - lib/bsv/overlay/lookup_facilitator.rb
 - lib/bsv/overlay/lookup_resolver.rb
@@ -152,6 +158,7 @@ files:
 - lib/bsv/registry/constants.rb
 - lib/bsv/registry/types.rb
 - lib/bsv/script.rb
+- lib/bsv/script/bip276.rb
 - lib/bsv/script/builder.rb
 - lib/bsv/script/chunk.rb
 - lib/bsv/script/interpreter/error.rb
@@ -169,8 +176,13 @@ files:
 - lib/bsv/script/push_drop_template.rb
 - lib/bsv/script/script.rb
 - lib/bsv/secp256k1_native.bundle
+- lib/bsv/storage.rb
+- lib/bsv/storage/downloader.rb
+- lib/bsv/storage/errors.rb
+- lib/bsv/storage/utils.rb
 - lib/bsv/transaction.rb
 - lib/bsv/transaction/beef.rb
+- lib/bsv/transaction/beef_party.rb
 - lib/bsv/transaction/chain_tracker.rb
 - lib/bsv/transaction/chain_trackers.rb
 - lib/bsv/transaction/chain_trackers/whats_on_chain.rb