bsv-sdk 0.25.0 → 0.26.0

data/lib/bsv/script/interpreter/operations/flow_control.rb

@@ -42,12 +42,21 @@ module BSV
             @else_stack.push(false)
           end
 
-          # OP_ELSE: toggle conditional branch (only one ELSE per IF after genesis)
+          # OP_ELSE: toggle the current conditional branch.
+          #
+          # Multi-ELSE handling matches the TS SDK (Spend.ts OP_ELSE case):
+          # - In relaxed mode (no explicit flags), each ELSE toggles the branch —
+          #   any number of ELSEs per IF is valid. This is the script-021 case.
+          # - With explicit post-genesis flags, only one ELSE per IF is permitted;
+          #   a second ELSE raises UNBALANCED_CONDITIONAL. Vectors such as
+          #   node.script.bitcoin-sv.0731 and teranode.0057 enforce this.
           def op_else
             raise ScriptError.new(ScriptErrorCode::UNBALANCED_CONDITIONAL, 'OP_ELSE without matching OP_IF') if @cond_stack.empty?
 
-            # After genesis: only one ELSE per IF
-            raise ScriptError.new(ScriptErrorCode::UNBALANCED_CONDITIONAL, 'duplicate OP_ELSE') if @else_stack.pop
+            already_seen_else = @else_stack.pop
+            if already_seen_else && explicit_flags? && after_genesis?
+              raise ScriptError.new(ScriptErrorCode::UNBALANCED_CONDITIONAL, 'duplicate OP_ELSE')
+            end
 
             case @cond_stack.last
             when :true  then @cond_stack[-1] = :false
@@ -97,20 +106,23 @@ module BSV
 
           # OP_VER: push 4-byte little-endian transaction version onto the stack.
           #
-          # Requires a transaction context (@tx must not be nil). Raises
-          # MISSING_TX_CONTEXT when called from Interpreter.evaluate (no-tx path).
+          # Resolves the version from +@tx.version+ (when verifying a
+          # transaction) or from the +tx_version:+ parameter passed to
+          # +Interpreter.evaluate+. Raises MISSING_TX_CONTEXT only if neither
+          # is available.
           #
           # The version is always encoded as exactly 4 bytes (LE uint32), never as
           # a ScriptNumber. Version 1 → 01000000, version 2 → 02000000.
           def op_ver
-            if @tx.nil?
+            bytes = tx_version_bytes
+            if bytes.nil?
               raise ScriptError.new(
                 ScriptErrorCode::MISSING_TX_CONTEXT,
                 'OP_VER requires transaction context'
               )
             end
 
-            @dstack.push_bytes(tx_version_bytes)
+            @dstack.push_bytes(bytes)
           end
 
           # OP_VERIF: version-conditional branch — executes like OP_IF but compares
@@ -166,20 +178,25 @@ module BSV
           end
 
           # Returns the transaction version as a 4-byte little-endian binary
-          # string. Used by OP_VER, OP_VERIF, and OP_VERNOTIF.
+          # string, or +nil+ if no version is available. Used by OP_VER,
+          # OP_VERIF, and OP_VERNOTIF. Prefers +@tx.version+ when verifying a
+          # transaction; falls back to the +tx_version:+ argument used by
+          # evaluate-without-tx (e.g. conformance corpus runs).
           def tx_version_bytes
-            [@tx.version].pack('V')
+            v = @tx&.version || @tx_version
+            v.nil? ? nil : [v].pack('V')
           end
 
           # Compares raw bytes against the current transaction version.
           # Returns false if:
           # - +data+ is not exactly 4 bytes
-          # - @tx is nil (no transaction context)
-          # - the bytes do not match the 4-byte LE encoding of @tx.version
+          # - no version is available (neither @tx nor @tx_version set)
+          # - the bytes do not match the 4-byte LE encoding of the version
           def tx_version_matches?(data)
-            return false if @tx.nil? || data.bytesize != 4
+            return false if data.bytesize != 4
 
-            data == tx_version_bytes
+            bytes = tx_version_bytes
+            !bytes.nil? && data == bytes
           end
         end
       end

data/lib/bsv/script/script.rb

@@ -22,12 +22,20 @@ module BSV
     #   script.p2pkh? #=> true
     #   script.to_asm #=> "OP_DUP OP_HASH160 ... OP_EQUALVERIFY OP_CHECKSIG"
     class Script
-      # @return [String] the raw script bytes
+      # @return [String] the raw script bytes (frozen, binary encoding)
+      # @note Scripts are protocol-level immutable; the underlying bytes are
+      #   defensively copied + frozen on construction. Downstream callers
+      #   that need to build a script incrementally must compose bytes
+      #   into a new String and pass it to a fresh +Script.new+.
       attr_reader :bytes
 
       # @param bytes [String] raw script bytes (default: empty)
       def initialize(bytes = ''.b)
-        @bytes = bytes.b
+        # Defensive copy + freeze: scripts are immutable in the protocol; freezing
+        # @bytes prevents external in-place mutation from staling caches that
+        # depend on the script's serialisation (see
+        # docs/reference/sighash-cache.md).
+        @bytes = bytes.b.dup.freeze
         @chunks = nil
       end
 
@@ -460,6 +468,17 @@ module BSV
           b.getbyte(22) == Opcodes::OP_EQUAL
       end
 
+      # Whether the script consists entirely of push-data operations.
+      #
+      # A script is push-only iff every chunk's opcode is at most +OP_16+
+      # (0x60). Used by the script interpreter to enforce the +SIGPUSHONLY+
+      # verification flag on unlock scripts.
+      #
+      # @return [Boolean]
+      def push_only?
+        chunks.all? { |chunk| chunk.opcode <= Opcodes::OP_16 }
+      end
+
       # Whether this is an OP_RETURN data carrier script.
       #
       # Matches both +OP_RETURN ...+ and +OP_FALSE OP_RETURN ...+ forms.

data/lib/bsv/storage/downloader.rb

@@ -145,7 +145,7 @@ module BSV
         body = response.body.to_s
         return nil if body.empty?
 
-        actual_hash = OpenSSL::Digest::SHA256.digest(body)
+        actual_hash = BSV::Primitives::Digest.sha256(body)
         return nil unless actual_hash == expected_hash
 
         DownloadResult.new(data: body, mime_type: response['Content-Type'])

data/lib/bsv/storage/utils.rb

@@ -38,7 +38,7 @@ module BSV
       # @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)
+        hash = BSV::Primitives::Digest.sha256(data.b)
         get_url_for_hash(hash)
       end
 

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 [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.