bsv-sdk 0.24.0 → 0.26.0

data/lib/bsv/transaction/tx.rb

@@ -9,6 +9,13 @@ module BSV
     # computation (with FORKID), signing, script verification, and fee
     # estimation.
     #
+    # @note Not thread-safe. Direct mutation of {#inputs} / {#outputs} arrays
+    #   (e.g. `tx.inputs << input`) bypasses the cache-invalidation contract
+    #   and may produce silently invalid sighashes. Use {#add_input} /
+    #   {#add_output} and the documented setter surface, or call
+    #   {#invalidate_caches} after direct mutation. See
+    #   {file:docs/reference/sighash-cache.md}.
+    #
     # @example Build, sign, and serialise a transaction
     #   tx = BSV::Transaction::Tx.new
     #   tx.add_input(input)
@@ -59,35 +66,151 @@ module BSV
 
       # Append a transaction input.
       #
-      # @param input [TransactionInput] the input to add
+      # Idempotent on re-add: calling +add_input(x)+ twice with the same input
+      # on the same +Transaction::Tx+ returns +self+ on the second call without
+      # appending a duplicate or invalidating caches. Raises +ArgumentError+
+      # if the input is already attached to a different +Transaction::Tx+.
+      #
+      # @param input [Transaction::TransactionInput] the input to add
       # @return [self] for chaining
+      # @raise [ArgumentError] if the input is already attached to a different
+      #   Tx instance. Sharing across Tx instances is anti-idiomatic;
+      #   construct a fresh instance per Tx. See
+      #   {file:docs/reference/sighash-cache.md#one-owner}.
       def add_input(input)
+        existing_owner = input.instance_variable_get(:@owning_tx)
+        if existing_owner
+          return self if existing_owner.equal?(self)
+
+          raise ArgumentError,
+                "TransactionInput #{input.dtxid_hex}:#{input.prev_tx_out_index} is already attached to a Tx"
+        end
+
+        input.instance_variable_set(:@owning_tx, self)
         @inputs << input
+        # Avoid the O(N+M) rebind walk inside invalidate_caches — the new
+        # input's backref was just set above and every existing input/output
+        # was rebound when it was originally added. clear_caches is O(1).
+        clear_caches
         self
       end
 
       # Append a transaction output.
       #
-      # @param output [TransactionOutput] the output to add
+      # Idempotent on re-add: calling +add_output(x)+ twice with the same output
+      # on the same +Transaction::Tx+ returns +self+ on the second call without
+      # appending a duplicate or invalidating caches. Raises +ArgumentError+
+      # if the output is already attached to a different +Transaction::Tx+.
+      #
+      # @param output [Transaction::TransactionOutput] the output to add
       # @return [self] for chaining
+      # @raise [ArgumentError] if the output is already attached to a different
+      #   Tx instance. Sharing across Tx instances is anti-idiomatic;
+      #   construct a fresh instance per Tx. See
+      #   {file:docs/reference/sighash-cache.md#one-owner}.
       def add_output(output)
+        existing_owner = output.instance_variable_get(:@owning_tx)
+        if existing_owner
+          return self if existing_owner.equal?(self)
+
+          asm_fragment = output.locking_script&.to_asm || '<nil locking_script>'
+          asm_fragment = "#{asm_fragment[0, 40]}..." if asm_fragment.length > 40
+          raise ArgumentError,
+                "TransactionOutput (#{asm_fragment}) is already attached to a Tx"
+        end
+
+        output.instance_variable_set(:@owning_tx, self)
         @outputs << output
+        # Avoid the O(N+M) rebind walk inside invalidate_caches — the new
+        # output's backref was just set above and every existing input/output
+        # was rebound when it was originally added. clear_caches is O(1).
+        clear_caches
+        self
+      end
+
+      # Invalidate all cached state on this transaction (sighash components,
+      # wire serialisation, etc.) AND restore the +@owning_tx+ backref on every
+      # current input and output. This is what makes the escape hatch complete:
+      # if a caller appended an input/output via direct array mutation
+      # (bypassing +add_input+ / +add_output+), the new struct's backref is nil
+      # and future +sequence=+ / +locking_script=+ / etc. setters would not
+      # bubble invalidation up. After +invalidate_caches+, the backref is
+      # rebound so subsequent setter mutations flow through correctly.
+      #
+      # Raises +ArgumentError+ if any input or output is already attached to a
+      # different +Transaction::Tx+ — matches the cross-Tx rebind contract of
+      # +add_input+ / +add_output+.
+      #
+      # @example After mutating the inputs array directly
+      #   tx.inputs << input             # bypasses the documented setter surface
+      #   tx.invalidate_caches           # clears all cache layers + rebinds @owning_tx
+      #   input.sequence = 42            # now invalidates correctly
+      #   tx.verify(...)                 # safe
+      #
+      # @note Rarely needed. Normal mutation through the documented setter
+      #   surface (input.sequence=, output.satoshis=, etc.) invalidates the
+      #   right cache slices automatically. This method is an escape hatch
+      #   for code that mutates @inputs / @outputs through unsupported paths.
+      #   See {file:docs/reference/sighash-cache.md#escape-hatch}.
+      #
+      # @return [self] for chaining
+      # @raise [ArgumentError] if any input or output is attached to a different
+      #   Tx instance
+      def invalidate_caches
+        rebind_owning_tx!
+        clear_caches
         self
       end
 
+      # Called by +#dup+ and +#clone+. Deep-dups +@inputs+ and +@outputs+ so that
+      # the copy and the original do not share mutable input/output state. Rebinds
+      # +@owning_tx+ on each copied struct to +self+ (the new transaction). Resets
+      # all cache ivars directly so the dup does not share mutable cache state
+      # (especially +@hash_outputs_single+, a Hash) with the original.
+      #
+      # This closes the hazard at +beef.rb:703,707+ where a shallow dup would leave
+      # the copied inputs/outputs pointing at the original transaction's cache.
+      #
+      # Note: we cannot delegate to +invalidate_caches+ here because that method
+      # calls +Hash#clear+ on +@hash_outputs_single+, which would mutate the
+      # shared Hash and evict the *original*'s per-index cache too. Direct
+      # +ivar = nil+ assignments on +self+ leave the original untouched.
+      def initialize_copy(other)
+        super
+        @inputs = @inputs.map do |i|
+          dup_input = i.dup
+          dup_input.instance_variable_set(:@owning_tx, self)
+          dup_input
+        end
+        @outputs = @outputs.map do |o|
+          dup_output = o.dup
+          dup_output.instance_variable_set(:@owning_tx, self)
+          dup_output
+        end
+        @to_binary = nil
+        @wtxid = nil
+        @hash_prevouts = nil
+        @hash_sequence = nil
+        @hash_outputs_all = nil
+        @hash_outputs_single = nil
+      end
+
       # --- Serialisation ---
 
       # Serialise the transaction to its binary wire format.
       #
-      # @return [String] raw transaction bytes
+      # @note Memoised; see {file:docs/reference/sighash-cache.md} for the invalidation contract.
+      # @return [String] raw transaction bytes (binary encoding, frozen)
       def to_binary
-        buf = [@version].pack('V')
-        buf << VarInt.encode(@inputs.length)
-        @inputs.each { |i| buf << i.to_binary }
-        buf << VarInt.encode(@outputs.length)
-        @outputs.each { |o| buf << o.to_binary }
-        buf << [@lock_time].pack('V')
-        buf
+        @to_binary ||= begin
+          buf = [@version].pack('V')
+          buf << VarInt.encode(@inputs.length)
+          @inputs.each { |i| buf << i.to_binary }
+          buf << VarInt.encode(@outputs.length)
+          @outputs.each { |o| buf << o.to_binary }
+          buf << [@lock_time].pack('V')
+          buf.b.freeze
+        end
       end
 
       # Serialise the transaction to a hex string.
@@ -144,7 +267,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 +305,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 +313,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 +373,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 +383,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 +493,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 +507,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'))
@@ -397,11 +520,14 @@ module BSV
       # Used by BEEF, BUMPs, and merkle paths, which all work in wire byte order
       # to match {TransactionInput#prev_wtxid}.
       #
+      # @note Memoised; see {file:docs/reference/sighash-cache.md} for the invalidation contract.
       # @return [String] 32-byte transaction ID in wire byte order
       def wtxid
-        id = BSV::Primitives::Digest.sha256d(to_binary)
-        BSV.logger&.debug { "[Tx] wtxid computed (dtxid=#{id.reverse.unpack1('H*')})" }
-        id
+        @wtxid ||= begin
+          id = BSV::Primitives::Digest.sha256d(to_binary)
+          BSV.logger&.debug { "[Tx] wtxid computed (dtxid=#{id.reverse.unpack1('H*')})" }
+          id.freeze
+        end
       end
 
       # The transaction ID as a hex string (display byte order).
@@ -621,25 +747,103 @@ module BSV
       # - +:output_overflow+ — Ruby raises; TS/Python return +false+; Go omits the check
       # - +:script_failure+ — Ruby raises; TS/Python return +false+; Go also propagates errors
       # - +:missing_source+ — Ruby raises; consistent with TS/Go/Python (all raise/error)
+      # - +verified:+ kwarg — Ruby-only; no equivalent seam exists in the TS, Go, or Python SDKs.
+      #   This is a novel Ruby-side extension: a bidirectional wtxid-dedup Hash that the caller
+      #   can seed (short-circuit ancestors already verified) and read after +verify+ returns
+      #   (populate a persistent verification cache). See {file:docs/reference/verify-kwarg.md}.
+      #   The reference SDKs repeat the full walk every time +verify+ is called.
       #
-      # @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
+      # @param verified [Hash{String => Boolean}, nil] bidirectional wtxid dedup Hash.
+      #   Keys are 32-byte wire-order binary wtxids (not hex). Values are presence-only —
+      #   the SDK writes +true+ for wtxids it walks and treats any truthy value as
+      #   "already verified". A +false+ value is treated as absent (does not short-circuit)
+      #   and will be overwritten with +true+ if the wtxid is subsequently walked.
+      #   Callers use this three ways:
+      #
+      #   - **Pre-seed** (short-circuit): pass a Hash pre-populated with wtxids you have
+      #     verified in an earlier session. Their subtrees are skipped.
+      #   - **Post-read** (accumulate): pass an empty Hash; after +verify+ returns, read the
+      #     keys to see which wtxids the SDK walked. Populates a persistent verification cache.
+      #   - **Bidirectional** (both): pass a Hash that seeds the walk AND collects the walked
+      #     wtxids in one call.
+      #
+      #   The Hash is mutated in place — the caller's object identity is preserved.
+      #   +nil+ (default) means "no seed, no post-read" — the SDK uses an internal Hash the
+      #   caller cannot access. Rejected at entry with +ArgumentError+: anything that is not
+      #   +nil+ or a mutable +Hash+; a frozen +Hash+; or a +Hash+ with a truthy +default+
+      #   value or any +default_proc+ (funds risk — missing keys would return truthy and
+      #   silently short-circuit verification).
       # @return [true] on successful verification
+      # @raise [ArgumentError] if +verified:+ is (a) not +nil+ or a +Hash+, (b) a frozen
+      #   +Hash+ (the SDK writes walked wtxids into it and cannot mutate a frozen one), or
+      #   (c) a +Hash+ with a truthy +default+ value or a +default_proc+ (missing keys
+      #   would return truthy and silently short-circuit verification — funds risk)
       # @raise [VerificationError] with code +:invalid_merkle_proof+ if a merkle proof is invalid
       # @raise [VerificationError] with code +:insufficient_fee+ if the fee is below the model's threshold
       # @raise [VerificationError] with code +:output_overflow+ if outputs exceed inputs
       # @raise [VerificationError] with code +:script_failure+ if script execution fails
       # @raise [VerificationError] with code +:missing_source+ if an input is missing required source data
-      def verify(chain_tracker:, fee_model: nil)
-        verified = {}
+      # @note Security (trust contract): the caller warrants that every wtxid present in
+      #   +verified:+ at method entry is fully verified — script AND chain-anchor (merkle proof)
+      #   AND any consensus-flag context. A seeded wtxid is treated as fully verified regardless
+      #   of what proof or script data it carries. The SDK does **not** re-run the merkle proof
+      #   for a seeded ancestor. If the caller's cache is stale or compromised, +verify+ will
+      #   return +true+ for ancestry that has not actually been verified. Cached wtxids are
+      #   pinned to the consensus flags under which they were originally verified — invalidate
+      #   the caller's cache when consensus flags change, on chain reorganisation, or on any
+      #   event that could invalidate a prior verification. Fee validation is not affected by
+      #   this set — the fee gate is a caller-passed policy, not a cached claim, and runs once
+      #   at the start of every +verify+ call when +fee_model+ is given.
+      # @note Concurrency: the SDK writes to +verified:+ in place without locking. Passing the
+      #   same Hash to concurrent +verify+ calls is a race — guard it externally, or give each
+      #   thread its own Hash and merge the results afterwards. The class-level
+      #   "Not thread-safe" note on {Tx} covers direct-mutation concerns; this is the
+      #   specific footgun that comes with the in-place-mutation contract of this kwarg.
+      # @example Pre-seed short-circuit
+      #   # wallet has already verified source_tx in a prior session
+      #   cache = { source_tx.wtxid => true }
+      #   tx.verify(chain_tracker: tracker, verified: cache)
+      # @example Post-read accumulate
+      #   walked = {}
+      #   tx.verify(chain_tracker: tracker, verified: walked)
+      #   walked.keys # => [subject_wtxid, ancestor1_wtxid, ...]
+      # @example Bidirectional round-trip
+      #   cache = load_persistent_verified_cache
+      #   tx.verify(chain_tracker: tracker, verified: cache)
+      #   save_persistent_verified_cache(cache) # includes newly-walked wtxids
+      # @since 0.11.0
+      def verify(chain_tracker:, fee_model: nil, verified: nil)
+        verified = normalise_verified(verified)
+        # Fee gate runs once at the start of every verify call. Fee is a caller-passed policy,
+        # not a cached script-validity claim — seeding the subject wtxid cannot silently disable it.
+        # verify_fee → total_input_satoshis raises ArgumentError when source data is missing;
+        # translate that to :missing_source VerificationError so callers see a consistent error
+        # taxonomy from #verify (all failure modes raise VerificationError, not ArgumentError).
+        if fee_model
+          begin
+            verify_fee(fee_model)
+          rescue ArgumentError => e
+            raise VerificationError.new(:missing_source,
+                                        "cannot compute fee: #{e.message}")
+          end
+        end
+
         queue = [self]
 
         until queue.empty?
           tx = queue.shift
           wtxid = tx.wtxid
-          next if verified[wtxid]
+          # Top-of-loop dedup covers both walked-during-this-call and caller-seeded wtxids.
+          # A seeded wtxid short-circuits everything — including the merkle proof — because
+          # the caller warrants full trust. See @note Security.
+          # fetch(k, false) bypasses any custom Hash default / default_proc — critical, because
+          # Hash.new(true)[missing_key] would return true and short-circuit verification silently
+          # (funds risk). normalise_verified also rejects such Hashes at entry, but this is
+          # defence in depth.
+          next if verified.fetch(wtxid, false)
 
-          # Merkle path short-circuit: proven transaction needs no input verification
           if tx.merkle_path
             unless tx.merkle_path.verify(tx.txid_hex, chain_tracker)
               raise VerificationError.new(:invalid_merkle_proof,
@@ -650,9 +854,6 @@ module BSV
             next
           end
 
-          # Fee validation (root transaction only)
-          verify_fee(fee_model) if tx.equal?(self) && fee_model
-
           # Verify each input
           tx.inputs.each_with_index do |input, index|
             # Populate source data from source_transaction when not already set.
@@ -676,9 +877,10 @@ module BSV
               )
             end
 
-            # Enqueue source transaction for verification if not yet verified
+            # Enqueue source transaction unless it's already dealt with (seeded or walked).
+            # fetch(k, false) bypasses any custom Hash default — see note above at top-of-loop dedup.
             source_tx = input.source_transaction
-            queue << source_tx if source_tx && !verified[source_tx.wtxid]
+            queue << source_tx if source_tx && !verified.fetch(source_tx.wtxid, false)
           end
 
           # Output ≤ input check
@@ -806,7 +1008,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)
@@ -832,6 +1034,44 @@ module BSV
               "input #{idx} source_transaction has no output at index #{input.prev_tx_out_index}"
       end
 
+      # Validate the +verified:+ kwarg for {#verify}.
+      #
+      # Returns the caller's Hash directly (no dup, no freeze) so the SDK can mutate it in place —
+      # the bidirectional contract from {#verify}. When +arg+ is +nil+, returns a fresh empty
+      # Hash that the caller has no reference to; that Hash is discarded when +verify+ returns.
+      #
+      # @param arg [Hash, nil]
+      # @return [Hash] the caller's Hash unchanged, or a fresh empty Hash if arg was nil
+      # @raise [ArgumentError] if +arg+ is neither +nil+ nor a Hash, a frozen Hash (the SDK writes
+      #   walked wtxids into it and cannot mutate a frozen Hash), or a Hash with a truthy default
+      #   value or a default_proc (missing keys would return truthy and silently short-circuit
+      #   verification for un-seeded wtxids — funds risk)
+      def normalise_verified(arg)
+        return {} if arg.nil?
+
+        unless arg.is_a?(Hash)
+          raise ArgumentError,
+                "verified: must be nil or Hash of wtxid => truthy entries (got #{arg.class})"
+        end
+
+        if arg.frozen?
+          raise ArgumentError,
+                'verified: Hash must be mutable — the SDK writes walked wtxids into it'
+        end
+
+        # A Hash with a truthy default or a default_proc could return a truthy value for missing
+        # keys, silently short-circuiting verification for un-seeded wtxids. The walk sites use
+        # `fetch(k, false)` as defence in depth, but reject at entry so the caller sees a clear
+        # error rather than an opaquely-behaving verify.
+        if arg.default_proc || arg.default
+          raise ArgumentError,
+                'verified: Hash must not have a truthy default or a default_proc — ' \
+                'missing keys must return falsy so verification cannot be silently skipped'
+        end
+
+        arg
+      end
+
       def verify_input_requirements(tx, input, index)
         dtxid_hex = tx.txid_hex
         if input.unlocking_script.nil?
@@ -866,37 +1106,59 @@ module BSV
                                     "outputs (#{output_total}) exceed inputs (#{input_total}) for transaction #{tx.txid_hex}")
       end
 
-      ZERO_HASH = "\x00".b * 32
+      ZERO_HASH = ("\x00".b * 32).freeze # rubocop:disable Style/RedundantFreeze
       private_constant :ZERO_HASH
 
+      # @note Memoised; see {file:docs/reference/sighash-cache.md} for the invalidation contract.
       def hash_prevouts(anyone_can_pay)
         return ZERO_HASH if anyone_can_pay
 
-        buf = @inputs.map(&:outpoint_binary).join
-        BSV::Primitives::Digest.sha256d(buf)
+        @hash_prevouts ||=
+          BSV::Primitives::Digest.sha256d(@inputs.map(&:outpoint_binary).join).freeze
       end
 
+      # @note Memoised; see {file:docs/reference/sighash-cache.md} for the invalidation contract.
       def hash_sequence(anyone_can_pay, base_type)
         return ZERO_HASH if anyone_can_pay || base_type == Sighash::SINGLE || base_type == Sighash::NONE
 
-        buf = @inputs.map { |i| [i.sequence].pack('V') }.join
-        BSV::Primitives::Digest.sha256d(buf)
+        @hash_sequence ||=
+          BSV::Primitives::Digest.sha256d(@inputs.map { |i| [i.sequence].pack('V') }.join).freeze
       end
 
+      # @note Memoised; see {file:docs/reference/sighash-cache.md} for the invalidation contract.
       def hash_outputs(base_type, input_index)
         case base_type
         when Sighash::NONE
           ZERO_HASH
         when Sighash::SINGLE
+          # NEVER cache the ZERO_HASH branch — after add_output, an idx that was
+          # out-of-range may move in-range; a cached ZERO_HASH would be stale.
           return ZERO_HASH if input_index >= @outputs.length
 
-          BSV::Primitives::Digest.sha256d(@outputs[input_index].to_binary)
+          hash_outputs_single(input_index)
         else # ALL (and any non-standard base type per BIP-143)
-          buf = @outputs.map(&:to_binary).join
-          BSV::Primitives::Digest.sha256d(buf)
+          hash_outputs_all
         end
       end
 
+      # Memoises the +hash_outputs+ ALL branch (sha256d of all outputs joined).
+      #
+      # @!visibility private
+      def hash_outputs_all
+        @hash_outputs_all ||= BSV::Primitives::Digest.sha256d(@outputs.map(&:to_binary).join).freeze
+      end
+
+      # Memoises +hash_outputs+ for the SIGHASH_SINGLE branch, keyed by input
+      # index. The Hash itself is the ivar; per-key lookup uses +Hash#[]= ||=+
+      # which does not trigger +Naming/MemoizedInstanceVariableName+.
+      #
+      # @!visibility private
+      def hash_outputs_single(input_index)
+        @hash_outputs_single ||= {}
+        @hash_outputs_single[input_index] ||=
+          BSV::Primitives::Digest.sha256d(@outputs[input_index].to_binary).freeze
+      end
+
       # 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 wtxid (wire-order bytes).
@@ -1066,6 +1328,75 @@ module BSV
         scale_factor = LOG10_RECIPROCAL_D_VALUES_1TO9[Random.rand(9)] # Array indexing starts at 0
         (min + (scale_factor * (max - min))).floor
       end
+
+      # Clears the +hash_sequence+ component-hash memo. Called by
+      # +TransactionInput#sequence=+ via the owning-Tx backref.
+      #
+      # @!visibility private
+      def invalidate_sequence_components_cache
+        @hash_sequence = nil
+      end
+
+      # Clears the +hash_outputs+ component-hash memos (both the ALL branch and
+      # the SIGHASH_SINGLE per-index cache). Called by
+      # +TransactionOutput#satoshis=+ and +TransactionOutput#locking_script=+
+      # via the owning-Tx backref.
+      #
+      # @!visibility private
+      def invalidate_outputs_components_cache
+        @hash_outputs_all = nil
+        @hash_outputs_single&.clear
+      end
+
+      # Clears the L2 wire-serialisation caches (+to_binary+ and +wtxid+).
+      # Called by per-struct setter bubbles and +invalidate_caches+.
+      #
+      # @!visibility private
+      def invalidate_wire_cache
+        @to_binary = nil
+        @wtxid = nil
+      end
+
+      # Clears every cache slice on this Tx without the +rebind_owning_tx!+
+      # walk. Called from +add_input+ / +add_output+ where the new struct's
+      # backref was just set inline and existing structs' backrefs were
+      # established when they were added — making the rebind walk redundant
+      # and reducing N-input construction from O(N²) to O(N).
+      #
+      # The public +invalidate_caches+ keeps the rebind walk because it is
+      # the documented escape hatch for direct array mutation, where the
+      # walk is required.
+      #
+      # @!visibility private
+      def clear_caches
+        @hash_prevouts = nil
+        invalidate_sequence_components_cache
+        invalidate_outputs_components_cache
+        invalidate_wire_cache
+      end
+
+      # Restore +@owning_tx+ on every current input and output. Called by
+      # +invalidate_caches+ so the escape hatch covers direct array mutation
+      # (e.g. +tx.inputs << input+ bypasses +add_input+ and leaves the new
+      # struct's backref nil — subsequent setter mutations would not bubble
+      # invalidation).
+      #
+      # Raises if any struct is currently attached to a *different* Tx —
+      # matches the +add_input+ / +add_output+ cross-Tx rebind contract.
+      #
+      # @!visibility private
+      def rebind_owning_tx!
+        (@inputs + @outputs).each do |struct|
+          existing_owner = struct.instance_variable_get(:@owning_tx)
+          if existing_owner && !existing_owner.equal?(self)
+            raise ArgumentError,
+                  "#{struct.class.name.split('::').last} is already attached to a different Tx; " \
+                  'invalidate_caches cannot rebind across transactions'
+          end
+
+          struct.instance_variable_set(:@owning_tx, self)
+        end
+      end
     end
   end
 end

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.26.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).