bsv-sdk 0.24.0 → 0.26.0

data/lib/bsv/transaction/transaction_input.rb

@@ -14,19 +14,42 @@ module BSV
       # @return [Integer] index of the output within the previous transaction
       attr_reader :prev_tx_out_index
 
-      # @return [Integer] sequence number (default: 0xFFFFFFFF)
-      attr_accessor :sequence
-
-      # @return [Script::Script, nil] the unlocking script (set after signing)
-      attr_accessor :unlocking_script
+      # @!attribute [rw] sequence
+      #   @return [Integer] sequence number (default: 0xFFFFFFFF)
+      #   @note Setting this invalidates the owning Tx's wire cache and the
+      #     hash_sequence component of the sighash cache. See
+      #     {file:docs/reference/sighash-cache.md}.
+      attr_reader :sequence
+
+      # @!attribute [rw] unlocking_script
+      #   @return [Script::Script, nil] the unlocking script (set after signing)
+      #   @note Setting this invalidates the owning Tx's wire cache only.
+      #     The unlocking script does not enter the BIP-143 preimage, so the
+      #     sighash component caches are not touched. See
+      #     {file:docs/reference/sighash-cache.md}.
+      attr_reader :unlocking_script
 
       # @return [Integer, nil] satoshi value of the source output (needed for sighash)
+      # @note Enters the BIP-143 preimage at step 6 but no current cache layer
+      #   memoises the per-input preimage, so no invalidator is required. If a
+      #   future change adds preimage or per-input digest memoisation, add a
+      #   setter override here that invalidates the relevant cache slice. See
+      #   {file:docs/reference/sighash-cache.md}.
       attr_accessor :source_satoshis
 
       # @return [Script::Script, nil] locking script of the source output (needed for sighash)
+      # @note Enters the BIP-143 preimage as scriptCode (step 5) when no
+      #   subscript override is supplied. Same caveat as {#source_satoshis}:
+      #   no current cache layer depends on this field, but a future preimage
+      #   cache would need a setter override here. See
+      #   {file:docs/reference/sighash-cache.md}.
       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)
+      # @note Source data is lazily resolved from this Tx during {Tx#verify}
+      #   and {Tx#sighash_preimage}. Mutation of this field after resolution
+      #   has occurred has no effect on caches because no current cache layer
+      #   depends on resolved source data.
       attr_accessor :source_transaction
 
       # @return [UnlockingScriptTemplate, nil] template for deferred signing
@@ -38,23 +61,60 @@ module BSV
       # @param sequence [Integer] sequence number
       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
+        # Defensively copy + freeze so external mutation of the caller's String
+        # cannot stale the cached outpoint_binary / to_binary.
+        @prev_wtxid = prev_wtxid.b.dup.freeze
         @prev_tx_out_index = prev_tx_out_index
         @unlocking_script = unlocking_script
         @sequence = sequence
+        @owning_tx = nil
         BSV.logger&.debug { "[TransactionInput] prev_wtxid set: #{dtxid_hex}:#{@prev_tx_out_index}" }
       end
 
+      # Called by +#dup+ and +#clone+. Clears the owning-Tx backref so that the
+      # cloned input does not belong to any transaction until it is explicitly
+      # added via +Tx#add_input+.
+      def initialize_copy(other)
+        super
+        @owning_tx = nil
+      end
+
+      # Sets the sequence number and invalidates the L1 binary memo and any
+      # owning-Tx slice caches that incorporate sequence (BIP-143 preimage
+      # and wire format).
+      #
+      # @param value [Integer] new sequence number
+      def sequence=(value)
+        @sequence = value
+        @to_binary = nil
+        @owning_tx&.send(:invalidate_sequence_components_cache)
+        @owning_tx&.send(:invalidate_wire_cache)
+      end
+
+      # Sets the unlocking script and invalidates the L1 binary memo and the
+      # owning-Tx wire cache. Unlocking script does not enter the BIP-143
+      # preimage, so the sequence/outputs components caches are not touched.
+      #
+      # @param value [Script::Script, nil] new unlocking script
+      def unlocking_script=(value)
+        @unlocking_script = value
+        @to_binary = nil
+        @owning_tx&.send(:invalidate_wire_cache)
+      end
+
       # Serialise the input to its binary wire format.
       #
+      # @note Memoised; see {file:docs/reference/sighash-cache.md} for the invalidation contract.
       # @return [String] binary input (outpoint + varint + script + sequence)
       def to_binary
-        script_bytes = @unlocking_script ? @unlocking_script.to_binary : ''.b
-        @prev_wtxid +
-          [@prev_tx_out_index].pack('V') +
-          VarInt.encode(script_bytes.bytesize) +
-          script_bytes +
-          [@sequence].pack('V')
+        @to_binary ||= begin
+          script_bytes = @unlocking_script ? @unlocking_script.to_binary : ''.b
+          (@prev_wtxid +
+            [@prev_tx_out_index].pack('V') +
+            VarInt.encode(script_bytes.bytesize) +
+            script_bytes +
+            [@sequence].pack('V')).freeze
+        end
       end
 
       # Deserialise a transaction input from binary data.
@@ -113,9 +173,13 @@ module BSV
 
       # Serialise the outpoint (prev_wtxid + output index) as binary.
       #
+      # Memoised: outpoint components are +attr_reader+ only so the value is
+      # immutable after construction. Returns a frozen binary string.
+      #
+      # @note Memoised; see {file:docs/reference/sighash-cache.md} for the invalidation contract.
       # @return [String] 36-byte outpoint
       def outpoint_binary
-        @prev_wtxid + [@prev_tx_out_index].pack('V')
+        @outpoint_binary ||= (@prev_wtxid + [@prev_tx_out_index].pack('V')).freeze
       end
 
       # The previous transaction ID in display-order hex.

data/lib/bsv/transaction/transaction_output.rb

@@ -8,11 +8,17 @@ module BSV
     # Outputs are consumed by transaction inputs that provide matching
     # unlocking scripts.
     class TransactionOutput
-      # @return [Integer] the output value in satoshis
-      attr_accessor :satoshis
+      # @!attribute [rw] satoshis
+      #   @return [Integer] the output value in satoshis
+      #   @note Setting this invalidates the owning Tx's outputs-components
+      #     and wire caches. See {file:docs/reference/sighash-cache.md}.
+      attr_reader :satoshis
 
-      # @return [Script::Script] the locking script (spending conditions)
-      attr_accessor :locking_script
+      # @!attribute [rw] locking_script
+      #   @return [Script::Script] the locking script (spending conditions)
+      #   @note Setting this invalidates the owning Tx's outputs-components
+      #     and wire caches. See {file:docs/reference/sighash-cache.md}.
+      attr_reader :locking_script
 
       # @return [Boolean] whether this output receives change
       attr_accessor :change
@@ -24,14 +30,48 @@ module BSV
         @satoshis = satoshis
         @locking_script = locking_script
         @change = change
+        @owning_tx = nil
+      end
+
+      # Called by +#dup+ and +#clone+. Clears the owning-Tx backref so that the
+      # cloned output does not belong to any transaction until it is explicitly
+      # added via +Tx#add_output+.
+      def initialize_copy(other)
+        super
+        @owning_tx = nil
+      end
+
+      # Sets the satoshi value and invalidates the L1 binary memo and the
+      # owning-Tx outputs-components and wire caches.
+      #
+      # @param value [Integer] new satoshi value
+      def satoshis=(value)
+        @satoshis = value
+        @to_binary = nil
+        @owning_tx&.send(:invalidate_outputs_components_cache)
+        @owning_tx&.send(:invalidate_wire_cache)
+      end
+
+      # Sets the locking script and invalidates the L1 binary memo and the
+      # owning-Tx outputs-components and wire caches.
+      #
+      # @param value [Script::Script] new locking script
+      def locking_script=(value)
+        @locking_script = value
+        @to_binary = nil
+        @owning_tx&.send(:invalidate_outputs_components_cache)
+        @owning_tx&.send(:invalidate_wire_cache)
       end
 
       # Serialise the output to its binary wire format.
       #
+      # @note Memoised; see {file:docs/reference/sighash-cache.md} for the invalidation contract.
       # @return [String] binary output (8-byte LE satoshis + varint + script)
       def to_binary
-        script_bytes = @locking_script.to_binary
-        [satoshis].pack('Q<') + VarInt.encode(script_bytes.bytesize) + script_bytes
+        @to_binary ||= begin
+          script_bytes = @locking_script.to_binary
+          ([@satoshis].pack('Q<') + VarInt.encode(script_bytes.bytesize) + script_bytes).freeze
+        end
       end
 
       # Deserialise a transaction output from binary data.