bsv-sdk 0.24.0 → 0.26.0

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

@@ -53,18 +53,74 @@ module BSV
       # stack overflow from deeply nested conditionals.
       MAX_CONDITIONAL_DEPTH = 256
 
+      # Opcodes that require Chronicle to execute. With explicit flags but
+      # without UTXO_AFTER_CHRONICLE, executing any of these raises
+      # DISABLED_OPCODE. OP_VER / OP_VERIF / OP_VERNOTIF are included because
+      # pre-Chronicle they're either reserved (OP_VER) or behave as a
+      # conditional-only NOP in non-executing branches — execution itself is
+      # disabled. Mirrors TS Spend.ts (lines ~694-709) and Go IsDisabled.
+      CHRONICLE_ONLY_OPCODES = [
+        Opcodes::OP_2MUL, Opcodes::OP_2DIV,
+        Opcodes::OP_VER, Opcodes::OP_VERIF, Opcodes::OP_VERNOTIF
+      ].freeze
+
+      # The two version-conditional opcodes — extracted to module-level
+      # constants so the interpreter hot path (every conditional dispatch /
+      # every executed chunk) doesn't allocate a fresh Array per call.
+      VER_CONDITIONAL_OPCODES = [Opcodes::OP_VERIF, Opcodes::OP_VERNOTIF].freeze
+
+      # Recognised verification flag names. Catches typos (a misspelled
+      # +SIGPUSHONLLY+ would otherwise silently disable enforcement) and forces
+      # any new flag to be declared here before use. The set is the union of
+      # flags appearing in the canonical conformance corpus and the Bitcoin
+      # Core +script_tests.json+ fixture, plus the witness/taproot family that
+      # downstream callers filter out before reaching the interpreter.
+      KNOWN_FLAGS = Set[
+        'CHECKLOCKTIMEVERIFY', 'CHECKSEQUENCEVERIFY',
+        'CLEANSTACK', 'DERSIG', 'DISCOURAGE_UPGRADABLE_NOPS',
+        'DISCOURAGE_UPGRADABLE_WITNESS_PROGRAM',
+        'GENESIS', 'LOW_S',
+        'MINIMALDATA', 'MINIMALIF',
+        'NULLDUMMY', 'NULLFAIL',
+        'P2SH', 'SIGHASH_FORKID', 'SIGPUSHONLY', 'STRICTENC',
+        'TAPROOT',
+        'UTXO_AFTER_CHRONICLE', 'UTXO_AFTER_GENESIS',
+        'WITNESS'
+      ].freeze
+
       # Evaluate unlock + lock scripts without transaction context.
       #
       # Signature operations will always fail (no sighash available).
       #
+      # @example Relaxed mode (post-Chronicle defaults, no malleability checks)
+      #   Interpreter.evaluate(unlock, lock)                  # flags defaults to nil
+      #
+      # @example Explicit flag set
+      #   Interpreter.evaluate(unlock, lock, flags: %w[UTXO_AFTER_GENESIS CLEANSTACK])
+      #
+      # @example Explicit-but-empty (pre-Genesis, pre-Chronicle, strict)
+      #   Interpreter.evaluate(unlock, lock, flags: [])       # NOT the same as nil
+      #
       # @param unlock_script [Script] the unlocking script
       # @param lock_script [Script] the locking script
+      # @param flags [Array<String>, Set<String>, nil] explicit verification flags
+      #   (e.g. +SIGPUSHONLY+, +CLEANSTACK+, +UTXO_AFTER_CHRONICLE+). +nil+
+      #   selects relaxed (post-Chronicle) mode where malleability checks are
+      #   off; an empty +[]+ array is explicit-but-empty (pre-Genesis,
+      #   pre-Chronicle strict mode). Each flag string must appear in
+      #   {KNOWN_FLAGS} — unknown names raise +ArgumentError+.
+      # @param tx_version [Integer, nil] transaction version made available to
+      #   +OP_VER+/+OP_VERIF+/+OP_VERNOTIF+ when no transaction is supplied
       # @return [Boolean] +true+ if execution succeeds
       # @raise [ScriptError] if script execution fails
-      def self.evaluate(unlock_script, lock_script)
+      # @raise [ArgumentError] if +flags+ contains an unknown name or
+      #   +tx_version+ is not a valid uint32
+      def self.evaluate(unlock_script, lock_script, flags: nil, tx_version: nil)
         new(
           unlock_script: unlock_script,
-          lock_script: lock_script
+          lock_script: lock_script,
+          flags: flags,
+          tx_version: tx_version
         ).execute
       end
 
@@ -75,19 +131,28 @@ module BSV
       # @param unlock_script [Script] the input's unlocking script
       # @param lock_script [Script] the previous output's locking script
       # @param satoshis [Integer] the value of the previous output in satoshis
+      # @param flags [Array<String>, Set<String>, nil] explicit verification flags
+      #   (see {.evaluate}). Production callers (e.g. +Tx#verify_input+) do not
+      #   pass +flags+, so mainnet transaction validation always runs in
+      #   relaxed mode; the parameter exists for conformance-corpus and
+      #   regression-vector runners that need to drive specific flag combinations.
       # @return [Boolean] +true+ if verification succeeds
       # @raise [ScriptError] if script execution fails
-      def self.verify(tx:, input_index:, unlock_script:, lock_script:, satoshis:)
+      # @raise [ArgumentError] if +flags+ contains an unknown name
+      def self.verify(tx:, input_index:, unlock_script:, lock_script:, satoshis:, flags: nil)
         new(
           unlock_script: unlock_script,
           lock_script: lock_script,
           tx: tx,
           input_index: input_index,
-          satoshis: satoshis
+          satoshis: satoshis,
+          flags: flags
         ).execute
       end
 
       def execute
+        enforce_sig_pushonly
+
         scripts = [@unlock_script, @lock_script]
         script_names = %w[unlock_script lock_script]
 
@@ -123,12 +188,15 @@ module BSV
 
       private
 
-      def initialize(unlock_script:, lock_script:, tx: nil, input_index: nil, satoshis: nil)
+      def initialize(unlock_script:, lock_script:, tx: nil, input_index: nil, satoshis: nil,
+                     flags: nil, tx_version: nil)
         @unlock_script = unlock_script
         @lock_script = lock_script
         @tx = tx
         @input_index = input_index
         @satoshis = satoshis
+        @flags = normalise_flags(flags)
+        @tx_version = validate_tx_version(tx_version)
 
         @dstack = Stack.new
         @astack = Stack.new
@@ -141,24 +209,137 @@ module BSV
         @current_chunk_idx = 0
       end
 
+      # Normalises the +flags:+ kwarg into a frozen Set of recognised names.
+      # +nil+ stays +nil+ (relaxed mode); any iterable is coerced to a Set of
+      # strings, dropping +nil+ / empty entries silently (so callers can pass
+      # +flags_csv.split(',')+ without trimming). Unknown flag names raise
+      # +ArgumentError+ — typos in consensus-affecting flag strings would
+      # otherwise silently disable the corresponding rule.
+      def normalise_flags(flags)
+        return nil if flags.nil?
+
+        normalised = Set.new
+        flags.each do |raw|
+          next if raw.nil?
+
+          name = raw.to_s.strip
+          next if name.empty?
+
+          unless KNOWN_FLAGS.include?(name)
+            raise ArgumentError,
+                  "unknown verification flag: #{raw.inspect} (add to KNOWN_FLAGS if intentional)"
+          end
+
+          normalised << name
+        end
+        normalised.freeze
+      end
+
+      # Ensures the +tx_version:+ kwarg is a valid uint32. Returns +nil+ for nil
+      # input. Raises +ArgumentError+ for negative values, values > 2^32-1, or
+      # non-Integer inputs — these would otherwise silently coerce inside
+      # +Array#pack('V')+ (negative wraps to 0xFFFFFFFF, oversized wraps mod
+      # 2^32), masking caller bugs.
+      def validate_tx_version(version)
+        return nil if version.nil?
+        return version if version.is_a?(Integer) && version >= 0 && version <= 0xFFFFFFFF
+
+        raise ArgumentError, "tx_version must be a uint32 (0..0xFFFFFFFF), got #{version.inspect}"
+      end
+
+      # Whether explicit verification flags were supplied.
+      # In their absence the interpreter behaves as if Chronicle is active and
+      # the unlock-script malleability flags are off (matches the TS SDK's
+      # +isRelaxed+ default — see Spend.ts).
+      def explicit_flags?
+        !@flags.nil?
+      end
+
+      def flag?(name)
+        explicit_flags? && @flags.include?(name)
+      end
+
+      # Whether post-Chronicle semantics apply (OP_2MUL/2DIV enabled,
+      # OP_VER/OP_VERIF/OP_VERNOTIF interpret +tx_version+).
+      def chronicle?
+        return flag?('UTXO_AFTER_CHRONICLE') if explicit_flags?
+
+        true
+      end
+
+      # Whether post-Genesis rules apply. With explicit flags this requires one
+      # of the genesis-era flags; without, the interpreter is always post-Genesis.
+      def after_genesis?
+        return flag?('GENESIS') || flag?('UTXO_AFTER_GENESIS') || flag?('UTXO_AFTER_CHRONICLE') if explicit_flags?
+
+        true
+      end
+
+      def enforce_sig_pushonly?
+        return flag?('SIGPUSHONLY') if explicit_flags?
+
+        false
+      end
+
+      def enforce_sig_pushonly
+        return unless enforce_sig_pushonly?
+        return if @unlock_script.push_only?
+
+        raise ScriptError.new(
+          ScriptErrorCode::SIG_PUSHONLY,
+          'unlock script must contain only push-data operations'
+        )
+      end
+
+      def enforce_clean_stack?
+        return flag?('CLEANSTACK') if explicit_flags?
+
+        false
+      end
+
+      def enforce_clean_stack
+        return unless enforce_clean_stack?
+        return if @dstack.length == 1
+
+        raise ScriptError.new(
+          ScriptErrorCode::CLEAN_STACK,
+          "CLEANSTACK requires exactly one stack item at end (found #{@dstack.length})"
+        )
+      end
+
       def execute_opcode(chunk)
         opcode = chunk.opcode
 
+        # Pre-Chronicle, pre-Genesis mode (explicit non-genesis flags) treats
+        # OP_VER / OP_VERIF / OP_VERNOTIF as universally illegal — they raise
+        # even in a non-executing branch. Mirrors TS Spend.ts line ~700.
+        enforce_pre_genesis_ver_gate(opcode)
+
         # After OP_RETURN inside a conditional: only process flow control opcodes
         # and OP_RETURN itself (which may terminate at top level once conditionals
         # are balanced), matching Go SDK's branchExecuting semantics.
         if @after_op_return
-          dispatch_opcode(opcode, chunk) if conditional_opcode?(opcode) || opcode == Opcodes::OP_RETURN
+          if conditional_opcode?(opcode) || opcode == Opcodes::OP_RETURN
+            return if skipped_ver_conditional?(opcode)
+
+            dispatch_opcode(opcode, chunk)
+          end
           return
         end
 
         # In non-executing branch: only dispatch conditional opcodes (for nesting tracking).
         # All other opcodes are skipped.
         unless branch_executing?
-          dispatch_opcode(opcode, chunk) if conditional_opcode?(opcode)
+          if conditional_opcode?(opcode)
+            return if skipped_ver_conditional?(opcode)
+
+            dispatch_opcode(opcode, chunk)
+          end
           return
         end
 
+        enforce_chronicle_gate(opcode)
+
         BSV.logger&.debug do
           name = Opcodes.name_for(opcode) || format('0x%02x', opcode)
           "[Interpreter]   #{name} (stack: #{@dstack.length})"
@@ -166,6 +347,41 @@ module BSV
         dispatch_opcode(opcode, chunk)
       end
 
+      def enforce_chronicle_gate(opcode)
+        return unless CHRONICLE_ONLY_OPCODES.include?(opcode)
+        return if chronicle?
+
+        raise ScriptError.new(
+          ScriptErrorCode::DISABLED_OPCODE,
+          "#{Opcodes.name_for(opcode) || format('0x%02x', opcode)} is disabled outside Chronicle"
+        )
+      end
+
+      # OP_VERIF / OP_VERNOTIF in a non-executing branch are conditional opcodes
+      # post-Chronicle (push to cond_stack, like OP_IF in a non-executing branch),
+      # but a complete NOP pre-Chronicle post-genesis — they neither push nor
+      # consume. This matches TS Spend.ts (line ~710) and Go opcodeVerConditional.
+      def skipped_ver_conditional?(opcode)
+        return false unless VER_CONDITIONAL_OPCODES.include?(opcode)
+
+        !chronicle? && after_genesis?
+      end
+
+      # Pre-Genesis VERIF / VERNOTIF are unconditionally illegal (even in
+      # non-executing branches — they enter the dispatcher as conditional opcodes).
+      # OP_VER pre-Genesis is illegal only when executing; in a non-executing
+      # branch it's skipped silently. Mirrors the Bitcoin Core script test
+      # rule "VER non-functional (ok if not executed); VERIF illegal everywhere".
+      def enforce_pre_genesis_ver_gate(opcode)
+        return unless VER_CONDITIONAL_OPCODES.include?(opcode)
+        return unless explicit_flags? && !after_genesis?
+
+        raise ScriptError.new(
+          ScriptErrorCode::DISABLED_OPCODE,
+          "#{Opcodes.name_for(opcode) || format('0x%02x', opcode)} is illegal pre-Genesis"
+        )
+      end
+
       def dispatch_opcode(opcode, chunk)
         case opcode
         # --- Data push ---
@@ -295,9 +511,12 @@ module BSV
       end
 
       # Verify final stack state: must have at least one truthy element on top.
+      # When the CLEANSTACK flag is set, additionally requires exactly one item.
       def check_final_stack
         raise ScriptError.new(ScriptErrorCode::EMPTY_STACK, 'stack empty at end of script execution') if @dstack.empty?
 
+        enforce_clean_stack
+
         return if @dstack.pop_bool
 
         raise ScriptError.new(ScriptErrorCode::EVAL_FALSE, 'false stack entry at end of script execution')

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/push_drop_template.rb

@@ -93,7 +93,7 @@ module BSV
         # the wallet's derived key, then returns a P2PKH unlock wrapped in a
         # PushDrop unlock (which is a pass-through).
         #
-        # @param tx [BSV::Transaction::Tx] the spending transaction
+        # @param tx [Transaction::Tx] the spending transaction
         # @param input_index [Integer] which input to sign
         # @return [BSV::Script::Script] the unlocking script
         def sign(tx, input_index)
@@ -125,7 +125,7 @@ module BSV
 
         # Estimated byte length of the unlocking script.
         #
-        # @param _tx [BSV::Transaction::Tx] unused
+        # @param _tx [Transaction::Tx] unused
         # @param _input_index [Integer] unused
         # @return [Integer]
         def estimated_length(_tx, _input_index)

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/script.rb

@@ -18,5 +18,6 @@ module BSV
     autoload :Stack,             'bsv/script/interpreter/stack'
 
     autoload :PushDropTemplate, 'bsv/script/push_drop_template'
+    autoload :BIP276,           'bsv/script/bip276'
   end
 end

data/lib/bsv/storage/downloader.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+module BSV
+  module Storage
+    # Result returned by {Downloader#download}.
+    DownloadResult = Data.define(:data, :mime_type)
+
+    # Downloads UHRP-addressed content from distributed storage hosts.
+    #
+    # Resolution: queries the +ls_uhrp+ lookup service via a {BSV::Overlay::LookupResolver},
+    # decodes each PushDrop output to extract the host URL (field[2]) and expiry timestamp
+    # (field[3], varint). Expired entries are silently dropped.
+    #
+    # Download: fetches each resolved URL in turn. Any HTTP 4xx/5xx, empty body, or
+    # network exception is treated as a failed host and the next URL is tried. This
+    # matches the TS SDK contract — no special treatment of 401/402/403.
+    #
+    # HTTP redirects are not followed (Net::HTTP default). This is intentional in v1.
+    #
+    # Download URLs are taken directly from the overlay; no private-IP filter is applied
+    # here. (The LookupResolver applies SSRF filtering to SLAP-discovered *infrastructure*
+    # hosts — content URLs are end-user data and are not subject to the same filter.)
+    class Downloader
+      # @param network_preset   [Symbol]                         :mainnet, :testnet, or :local
+      # @param lookup_resolver  [BSV::Overlay::LookupResolver]   injectable resolver (nil = default)
+      # @param http_client      [#call, nil]                     injectable HTTP client for testing.
+      #   Must respond to +.call(url_string)+ and return an object exposing +#code+ (Integer),
+      #   +#body+ (binary String), and +#[](header_name)+ for header access.
+      #   Default: a thin {Net::HTTP.get_response} wrapper.
+      # @param timeout          [Integer]                        per-request timeout in seconds
+      def initialize(network_preset: :mainnet, lookup_resolver: nil, http_client: nil, timeout: 30)
+        @lookup_resolver = lookup_resolver || BSV::Overlay::LookupResolver.new(network_preset: network_preset)
+        @http_client     = http_client
+        @timeout         = timeout
+      end
+
+      # Resolve a UHRP URL to a list of HTTP(S) download URLs.
+      #
+      # Queries the +ls_uhrp+ lookup service, decodes each PushDrop output,
+      # drops expired entries, and returns the remaining URLs.
+      #
+      # @param uhrp_url [String] UHRP URL (with or without +uhrp://+ prefix)
+      # @return [Array<String>] resolved HTTP(S) download URLs
+      # @raise [BSV::Storage::DownloadError] if the lookup answer is not an output-list
+      def resolve(uhrp_url)
+        question = BSV::Overlay::LookupQuestion.new(
+          service: 'ls_uhrp',
+          query: { 'uhrpUrl' => BSV::Storage::Utils.normalize_url(uhrp_url) }
+        )
+        answer = @lookup_resolver.query(question)
+        raise DownloadError, 'Lookup answer must be an output list' unless answer.type == 'output-list'
+
+        current_time = Time.now.to_i
+        urls = []
+
+        answer.outputs.each do |output|
+          url = decode_output_url(output, current_time)
+          urls << url if url
+        end
+
+        urls
+      end
+
+      # Download the content addressed by +uhrp_url+.
+      #
+      # Validates the URL, resolves it to a list of hosts, then attempts each
+      # host in order. Verifies the SHA-256 hash of the downloaded body against
+      # the hash embedded in the UHRP URL. Returns on the first successful match.
+      #
+      # @param uhrp_url [String] UHRP URL
+      # @return [BSV::Storage::DownloadResult] downloaded data and MIME type
+      # @raise [ArgumentError] if the URL is not a valid UHRP URL
+      # @raise [BSV::Storage::DownloadError] if no host yields content matching the hash
+      def download(uhrp_url)
+        raise ArgumentError, 'Invalid parameter UHRP url' unless BSV::Storage::Utils.valid_url?(uhrp_url)
+
+        urls = resolve(uhrp_url)
+        raise DownloadError, 'No one currently hosts this file!' if urls.empty?
+
+        expected_hash = BSV::Storage::Utils.get_hash_from_url(uhrp_url)
+
+        urls.each do |url|
+          result = attempt_download(url, expected_hash)
+          return result if result
+        end
+
+        raise DownloadError, "Unable to download content from #{uhrp_url}"
+      end
+
+      private
+
+      def decode_output_url(output, current_time)
+        beef_data    = output['beef'] || output[:beef]
+        output_index = (output['outputIndex'] || output[:output_index] || 0).to_i
+        return nil if beef_data.nil?
+        return nil if output_index.negative?
+
+        beef   = parse_beef(beef_data)
+        return nil unless beef
+
+        beef_tx = beef.transactions.last
+        return nil if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
+
+        txout = beef_tx.transaction.outputs[output_index]
+        return nil unless txout
+
+        fields = txout.locking_script.pushdrop_fields
+        return nil if fields.nil? || fields.length < 4
+
+        expiry, = BSV::Transaction::VarInt.decode(fields[3])
+        return nil if expiry < current_time
+
+        url = fields[2].force_encoding('UTF-8')
+        return nil unless url.valid_encoding?
+
+        url
+      rescue StandardError
+        nil
+      end
+
+      def parse_beef(beef_data)
+        case beef_data
+        when String
+          BSV::Transaction::Beef.from_binary(beef_data)
+        when Array
+          BSV::Transaction::Beef.from_binary(beef_data.pack('C*'))
+        end
+      rescue StandardError
+        nil
+      end
+
+      def attempt_download(url, expected_hash)
+        response = fetch(url)
+        return nil if response.nil?
+
+        code = response.code.to_i
+        # 3xx is treated as a failed host: redirects are intentionally not followed in v1,
+        # so a 302 body is never the content we want.
+        return nil if code >= 300
+
+        body = response.body.to_s
+        return nil if body.empty?
+
+        actual_hash = BSV::Primitives::Digest.sha256(body)
+        return nil unless actual_hash == expected_hash
+
+        DownloadResult.new(data: body, mime_type: response['Content-Type'])
+      rescue StandardError
+        nil
+      end
+
+      def fetch(url)
+        if @http_client
+          @http_client.call(url)
+        else
+          uri = URI(url)
+          Net::HTTP.start(
+            uri.hostname,
+            uri.port,
+            use_ssl: uri.scheme == 'https',
+            open_timeout: @timeout,
+            read_timeout: @timeout
+          ) { |http| http.request(Net::HTTP::Get.new(uri)) }
+        end
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/bsv/storage/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module BSV
+  module Storage
+    # Raised when a UHRP file cannot be downloaded from any available host.
+    class DownloadError < StandardError; end
+  end
+end