bsv-sdk 0.23.1 → 0.25.0

data/lib/bsv/overlay/historian.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module BSV
+  module Overlay
+    # Builds a chronological history (oldest → newest) of typed values by traversing
+    # a transaction's input ancestry and interpreting each output with a provided interpreter.
+    #
+    # The interpreter contract is: +interpreter.call(tx, output_index, ctx)+, returning the
+    # typed value or +nil+. Any callable responding to +:call+ is accepted (lambda, proc,
+    # method, or object).
+    #
+    # Traversal follows +input.source_transaction+ references recursively. Callers must
+    # supply transactions whose inputs have +source_transaction+ populated.
+    #
+    # == Cycle safety
+    #
+    # Each transaction is visited at most once, tracked by its +wtxid+ (wire-order binary).
+    #
+    # == Value semantics
+    #
+    # Only +nil+ is excluded. Falsy non-nil values (+false+, +""+, +0+) are valid history
+    # entries and are included in the result.
+    #
+    # == Caching
+    #
+    # An optional +history_cache+ (any +[]/[]=+ responder) caches complete history results.
+    # Cache keys have the form: <tt>"#{interpreter_version}|#{dtxid_hex}|#{ctx_key}"</tt>.
+    # Cached arrays are stored frozen; each retrieval returns a +dup+ to protect the cache.
+    #
+    # == Note
+    #
+    # The Ruby Historian is synchronous. There is no async/await semantics.
+    class Historian
+      # @param interpreter       [#call]     callable: +call(tx, output_index, ctx) → value|nil+
+      # @param debug             [Boolean]   enable debug logging via +BSV.logger+
+      # @param history_cache     [Hash, nil] optional cache store (+[]/[]=+ responder)
+      # @param interpreter_version [String]  version tag for cache key invalidation
+      # @param ctx_key_fn        [#call, nil] serialises context to a string cache key
+      def initialize(interpreter, debug: false, history_cache: nil, interpreter_version: 'v1', ctx_key_fn: nil)
+        @interpreter = interpreter
+        @debug = debug
+        @history_cache = history_cache
+        @interpreter_version = interpreter_version
+        @ctx_key_fn = ctx_key_fn
+      end
+
+      # Traverses input ancestry from +start_transaction+ and returns all interpreted
+      # values in chronological order (oldest first).
+      #
+      # @param start_transaction [Transaction::Tx]
+      # @param context           [Object, nil] forwarded verbatim to the interpreter
+      # @return [Array] interpreted values, oldest first
+      def build_history(start_transaction, context = nil)
+        if @history_cache
+          key = cache_key(start_transaction, context)
+          cached = @history_cache[key]
+          unless cached.nil?
+            BSV.logger&.debug { "[Historian] History cache hit: #{key}" } if @debug
+            return cached.dup
+          end
+        end
+
+        history = []
+        visited = {}
+
+        traverse(start_transaction, context, history, visited)
+
+        result = history.reverse
+
+        if @history_cache
+          key ||= cache_key(start_transaction, context)
+          @history_cache[key] = result.dup.freeze
+          BSV.logger&.debug { "[Historian] History cached: #{key}" } if @debug
+        end
+
+        result
+      end
+
+      private
+
+      def cache_key(tx, context)
+        ctx_key = @ctx_key_fn ? @ctx_key_fn.call(context) : context.to_s
+        "#{@interpreter_version}|#{tx.dtxid_hex}|#{ctx_key}"
+      end
+
+      def traverse(tx, context, history, visited)
+        id = tx.wtxid
+
+        if visited.key?(id)
+          BSV.logger&.debug { "[Historian] Skipping already visited transaction: #{tx.dtxid_hex}" } if @debug
+          return
+        end
+
+        visited[id] = true
+
+        BSV.logger&.debug { "[Historian] Processing transaction: #{tx.dtxid_hex}" } if @debug
+
+        tx.outputs.each_with_index do |_output, index|
+          value = @interpreter.call(tx, index, context)
+          unless value.nil?
+            history << value
+            BSV.logger&.debug { "[Historian] Added value to history: #{value.inspect}" } if @debug
+          end
+        rescue StandardError => e
+          BSV.logger&.debug { "[Historian] Failed to interpret output #{index}: #{e.message}" } if @debug
+        end
+
+        tx.inputs.each do |input|
+          if input.source_transaction
+            traverse(input.source_transaction, context, history, visited)
+          elsif @debug
+            BSV.logger&.debug { '[Historian] Input missing sourceTransaction, skipping' }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/overlay/topic_broadcaster.rb

@@ -74,7 +74,7 @@ module BSV
 
       # Broadcast a transaction to all interested overlay hosts.
       #
-      # @param tx [BSV::Transaction::Transaction] the transaction to broadcast
+      # @param tx [Transaction::Tx] the transaction to broadcast
       # @return [OverlayBroadcastResult]
       def broadcast(tx)
         beef = serialise_beef(tx)

data/lib/bsv/overlay/types.rb

@@ -108,6 +108,43 @@ module BSV
         @code = code
         @description = description
       end
+
+      # @return [Boolean] true when the broadcast reached at least one
+      #   competent host and satisfied any acknowledgement requirements.
+      def success?
+        @status == 'success'
+      end
+
+      # Raise the appropriate {OverlayError} subclass when {#success?} is
+      # false. Lets callers treat a broadcast failure as an exception rather
+      # than silently swallowing the result object — used by Identity and
+      # Registry clients which terminate on broadcast failure regardless.
+      #
+      # @return [self] when the result is a success (chainable)
+      # @raise [NoCompetentHostsError] for +ERR_NO_HOSTS_INTERESTED+
+      # @raise [AllHostsRejectedError] for +ERR_ALL_HOSTS_REJECTED+
+      # @raise [AcknowledgementError] for +ERR_REQUIRE_ACK_*_FAILED+
+      # @raise [OverlayError] for any other non-success status
+      def raise_if_error!
+        return self if success?
+
+        message = [@code, @description].compact.join(': ')
+        raise error_class_for_code, message
+      end
+
+      private
+
+      def error_class_for_code
+        case @code
+        when 'ERR_NO_HOSTS_INTERESTED' then NoCompetentHostsError
+        when 'ERR_ALL_HOSTS_REJECTED' then AllHostsRejectedError
+        when 'ERR_REQUIRE_ACK_FROM_ANY_HOST_FAILED',
+             'ERR_REQUIRE_ACK_FROM_ALL_HOSTS_FAILED',
+             'ERR_REQUIRE_ACK_FROM_SPECIFIC_HOSTS_FAILED'
+          AcknowledgementError
+        else OverlayError
+        end
+      end
     end
   end
 end

data/lib/bsv/overlay.rb

@@ -25,5 +25,6 @@ module BSV
     autoload :HTTPSBroadcastFacilitator,  'bsv/overlay/broadcast_facilitator'
     autoload :TopicBroadcaster,           'bsv/overlay/topic_broadcaster'
     autoload :SHIPBroadcaster,            'bsv/overlay/topic_broadcaster'
+    autoload :Historian,                  'bsv/overlay/historian'
   end
 end

data/lib/bsv/primitives/ecies.rb

@@ -147,15 +147,24 @@ module BSV
       # @param message [String] the plaintext message
       # @param public_key [PublicKey] the recipient's public key
       # @param private_key [PrivateKey, nil] optional ephemeral key (random if omitted)
+      # @param iv [String, nil] optional 16-byte ASCII-8BIT IV. When omitted a random IV is
+      #   generated via +SecureRandom+. Supply a fixed value only for deterministic test
+      #   vectors — **never use a fixed IV in production**.
       # @return [String] encrypted payload
-      def bitcore_encrypt(message, public_key, private_key: nil)
+      # @raise [ArgumentError] if +iv+ is supplied but is not exactly 16 bytes
+      def bitcore_encrypt(message, public_key, private_key: nil, iv: nil)
         message = message.b if message.encoding != Encoding::ASCII_8BIT
 
+        if iv
+          iv = iv.b if iv.encoding != Encoding::ASCII_8BIT
+          raise ArgumentError, 'iv must be exactly 16 bytes' unless iv.bytesize == 16
+        else
+          iv = SecureRandom.random_bytes(16)
+        end
+
         ephemeral = private_key || PrivateKey.generate
         key_e, key_m = derive_bitcore_keys(ephemeral, public_key)
 
-        iv = SecureRandom.random_bytes(16)
-
         cipher = OpenSSL::Cipher.new('aes-256-cbc')
         cipher.encrypt
         cipher.key = key_e

data/lib/bsv/registry/client.rb

@@ -50,7 +50,9 @@ module BSV
       # @param data [BasketDefinitionData, ProtocolDefinitionData, CertificateDefinitionData]
       #   structured definition data
       # @return [BSV::Overlay::OverlayBroadcastResult]
-      # @raise [RuntimeError] if the transaction cannot be created or broadcast
+      # @raise [RuntimeError] if the transaction cannot be created
+      # @raise [BSV::Overlay::OverlayError] (or a subclass) if the overlay broadcast fails —
+      #   see {BSV::Overlay::OverlayBroadcastResult#raise_if_error!} for the mapping
       def register_definition(definition_type, data)
         registry_operator = identity_key
         fields = build_pushdrop_fields(definition_type, data, registry_operator)
@@ -81,8 +83,8 @@ module BSV
 
         raise "Register failed: could not create #{definition_type} registration transaction" if create_result[:tx].nil?
 
-        tx = BSV::Transaction::Transaction.from_beef(normalise_beef(create_result[:tx]))
-        broadcaster_for(definition_type).broadcast(tx)
+        tx = BSV::Transaction::Tx.from_beef(normalise_beef(create_result[:tx]))
+        broadcaster_for(definition_type).broadcast(tx).raise_if_error!
       end
 
       # Resolves registry definitions of a given type using the overlay lookup service.
@@ -110,6 +112,48 @@ module BSV
         end
       end
 
+      # Resolves basket registry definitions.
+      #
+      # Thin wrapper around {#resolve} for cross-SDK parity with the Go SDK's
+      # +ResolveBasket+ method.
+      #
+      # @param query [Hash] optional filter criteria:
+      #   - +:basket_id+ [String] exact basket identifier
+      #   - +:name+ [String] human-readable basket name
+      #   - +:registry_operators+ [Array<String>] operator public key hexes
+      # @return [Array<RegisteredDefinition>] matching registered basket definitions
+      def resolve_basket(query = {})
+        resolve(DefinitionType::BASKET, query)
+      end
+
+      # Resolves protocol registry definitions.
+      #
+      # Thin wrapper around {#resolve} for cross-SDK parity with the Go SDK's
+      # +ResolveProtocol+ method.
+      #
+      # @param query [Hash] optional filter criteria:
+      #   - +:name+ [String] human-readable protocol name
+      #   - +:protocol_id+ [Array] BRC-43 two-element protocol ID, e.g. +[1, 'protomap']+
+      #   - +:registry_operators+ [Array<String>] operator public key hexes
+      # @return [Array<RegisteredDefinition>] matching registered protocol definitions
+      def resolve_protocol(query = {})
+        resolve(DefinitionType::PROTOCOL, query)
+      end
+
+      # Resolves certificate type registry definitions.
+      #
+      # Thin wrapper around {#resolve} for cross-SDK parity with the Go SDK's
+      # +ResolveCertificate+ method.
+      #
+      # @param query [Hash] optional filter criteria:
+      #   - +:type+ [String] Base64-encoded certificate type identifier
+      #   - +:name+ [String] human-readable certificate type name
+      #   - +:registry_operators+ [Array<String>] operator public key hexes
+      # @return [Array<RegisteredDefinition>] matching registered certificate type definitions
+      def resolve_certificate(query = {})
+        resolve(DefinitionType::CERTIFICATE, query)
+      end
+
       # Lists the registry operator's own published definitions for the given type.
       #
       # Queries the wallet for spendable outputs in the appropriate basket,
@@ -428,7 +472,7 @@ module BSV
       #
       # @param definition_type [String]
       # @param output [Hash] wallet output with :outpoint, :satoshis keys
-      # @param beef [BSV::Transaction::Beef] parsed BEEF
+      # @param beef [Transaction::Beef] parsed BEEF
       # @param beef_raw [String] raw BEEF bytes
       # @return [RegisteredDefinition, nil]
       def parse_own_output_to_registered_definition(definition_type, output, beef, beef_raw)
@@ -463,9 +507,12 @@ module BSV
       # @param definition_type [String]
       # @param create_result [Hash] result from wallet.create_action containing :signable_transaction
       # @return [BSV::Overlay::OverlayBroadcastResult]
+      # @raise [RuntimeError] if the transaction cannot be signed
+      # @raise [BSV::Overlay::OverlayError] (or a subclass) if the overlay broadcast fails —
+      #   see {BSV::Overlay::OverlayBroadcastResult#raise_if_error!} for the mapping
       def sign_and_broadcast(definition_type, create_result)
         signable   = create_result[:signable_transaction]
-        partial_tx = BSV::Transaction::Transaction.from_beef(normalise_beef(signable[:tx]))
+        partial_tx = BSV::Transaction::Tx.from_beef(normalise_beef(signable[:tx]))
 
         template = BSV::Script::PushDropTemplate.new(wallet: @wallet, originator: @originator)
         unlocker = template.unlock(
@@ -488,8 +535,8 @@ module BSV
 
         raise 'Revoke failed: could not sign transaction' if sign_result[:tx].nil?
 
-        signed_tx = BSV::Transaction::Transaction.from_beef(normalise_beef(sign_result[:tx]))
-        broadcaster_for(definition_type).broadcast(signed_tx)
+        signed_tx = BSV::Transaction::Tx.from_beef(normalise_beef(sign_result[:tx]))
+        broadcaster_for(definition_type).broadcast(signed_tx).raise_if_error!
       end
 
       # Verifies that the registered definition belongs to the current wallet.

data/lib/bsv/script/bip276.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'bsv/primitives/digest'
+
+module BSV
+  module Script
+    # BIP-276 text encoding for scripts and templates.
+    #
+    # Encodes and decodes typed bitcoin data using the scheme described in
+    # https://github.com/moneybutton/bips/blob/master/bip-0276.mediawiki
+    #
+    # Format: `<prefix>:<version-byte><network-byte><hex-payload><checksum>`
+    # where version and network are each one byte (two hex digits), and
+    # checksum is the first 4 bytes of double-SHA256 over the full preimage
+    # (the string up to and including the payload), hex-encoded.
+    #
+    # @note Field order is version-then-network, matching the BIP-276 spec
+    #   and the Go SDK reference. The Python SDK has these reversed — a known
+    #   py-sdk bug that is invisible at default v=1, n=1.
+    module BIP276
+      # Returned by {decode}; immutable value object.
+      Result = Data.define(:prefix, :version, :network, :data)
+
+      # Custom exception hierarchy.
+      class Error < StandardError; end
+      class InvalidFormat   < Error; end
+      class InvalidChecksum < Error; end
+
+      PREFIX_SCRIPT   = 'bitcoin-script'
+      PREFIX_TEMPLATE = 'bitcoin-template'
+      CURRENT_VERSION = 1
+      NETWORK_MAINNET = 1
+      NETWORK_TESTNET = 2
+
+      # Regex: prefix(:)(version 2 hex)(network 2 hex)(data hex*)(checksum 8 hex)
+      VALID_BIP276 = /\A(.+?):([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})([0-9A-Fa-f]*)([0-9A-Fa-f]{8})\z/
+
+      module_function
+
+      # Encode a binary payload as a BIP-276 string.
+      #
+      # @param data    [String]  binary payload (e.g. a {Script::Script}'s binary form)
+      # @param prefix  [String]  {PREFIX_SCRIPT} or {PREFIX_TEMPLATE} (or any custom prefix)
+      # @param version [Integer] 1..255 — {CURRENT_VERSION} by default
+      # @param network [Integer] 1..255 — {NETWORK_MAINNET} by default
+      # @return [String] BIP-276 encoded string
+      # @raise [ArgumentError] if version or network is out of the range 1..255
+      def encode(data, prefix: PREFIX_SCRIPT, network: NETWORK_MAINNET, version: CURRENT_VERSION)
+        raise ArgumentError, "version must be 1..255, got #{version}"  unless (1..255).cover?(version)
+        raise ArgumentError, "network must be 1..255, got #{network}"  unless (1..255).cover?(network)
+
+        preimage = build_preimage(prefix, version, network, data)
+        preimage + checksum(preimage)
+      end
+
+      # Decode a BIP-276 string.
+      #
+      # @param str [String] BIP-276 encoded string
+      # @return [Result] value object with +:prefix+, +:version+, +:network+, +:data+
+      # @raise [InvalidFormat]   if the string is structurally malformed
+      # @raise [InvalidChecksum] if the checksum does not match the payload
+      def decode(str)
+        match = VALID_BIP276.match(str)
+        raise InvalidFormat, 'not a valid BIP-276 string' unless match
+
+        prefix  = match[1]
+        version = match[2].to_i(16)
+        network = match[3].to_i(16)
+
+        raise InvalidFormat, 'data payload has odd number of hex digits' if match[4].length.odd?
+
+        data = [match[4]].pack('H*')
+
+        # Compute the checksum over the EXACT input bytes (everything except
+        # the trailing 8-hex-digit checksum) rather than rebuilding the
+        # preimage from parsed fields. Rebuilding via build_preimage would
+        # lowercase the payload hex, causing valid mixed-case input to fail.
+        preimage = str[0..-9]
+        expected = checksum(preimage)
+        raise InvalidChecksum, 'checksum mismatch' unless match[5].downcase == expected
+
+        Result.new(prefix: prefix, version: version, network: network, data: data)
+      end
+
+      # Encode a script payload using the {PREFIX_SCRIPT} prefix.
+      #
+      # @param (see encode)
+      # @return [String] BIP-276 encoded string with +bitcoin-script+ prefix
+      def encode_script(data, network: NETWORK_MAINNET, version: CURRENT_VERSION)
+        encode(data, prefix: PREFIX_SCRIPT, network: network, version: version)
+      end
+
+      # Encode a template payload using the {PREFIX_TEMPLATE} prefix.
+      #
+      # @param (see encode)
+      # @return [String] BIP-276 encoded string with +bitcoin-template+ prefix
+      def encode_template(data, network: NETWORK_MAINNET, version: CURRENT_VERSION)
+        encode(data, prefix: PREFIX_TEMPLATE, network: network, version: version)
+      end
+
+      # Decode a BIP-276 string that must have the {PREFIX_SCRIPT} prefix.
+      #
+      # @param str [String] BIP-276 encoded string
+      # @return [Result]
+      # @raise [InvalidFormat] if prefix is not +bitcoin-script+
+      # @raise [InvalidChecksum] if the checksum does not match
+      def decode_script(str)
+        result = decode(str)
+        raise InvalidFormat, "expected prefix '#{PREFIX_SCRIPT}', got '#{result.prefix}'" \
+          unless result.prefix == PREFIX_SCRIPT
+
+        result
+      end
+
+      # Decode a BIP-276 string that must have the {PREFIX_TEMPLATE} prefix.
+      #
+      # @param str [String] BIP-276 encoded string
+      # @return [Result]
+      # @raise [InvalidFormat] if prefix is not +bitcoin-template+
+      # @raise [InvalidChecksum] if the checksum does not match
+      def decode_template(str)
+        result = decode(str)
+        raise InvalidFormat, "expected prefix '#{PREFIX_TEMPLATE}', got '#{result.prefix}'" \
+          unless result.prefix == PREFIX_TEMPLATE
+
+        result
+      end
+
+      # @api private
+      def build_preimage(prefix, version, network, data)
+        format('%<prefix>s:%<version>02x%<network>02x%<payload>s',
+               prefix: prefix, version: version, network: network, payload: data.unpack1('H*'))
+      end
+      private_class_method :build_preimage
+
+      # @api private
+      def checksum(preimage)
+        BSV::Primitives::Digest.sha256d(preimage)[0, 4].unpack1('H*')
+      end
+      private_class_method :checksum
+    end
+  end
+end

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

@@ -70,7 +70,7 @@ module BSV
 
       # Verify a transaction input by evaluating its scripts.
       #
-      # @param tx [Transaction::Transaction] the transaction being verified
+      # @param tx [Transaction::Tx] the transaction being verified
       # @param input_index [Integer] the input index within the transaction
       # @param unlock_script [Script] the input's unlocking script
       # @param lock_script [Script] the previous output's locking script

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::Transaction] 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::Transaction] unused
+        # @param _tx [Transaction::Tx] unused
         # @param _input_index [Integer] unused
         # @return [Integer]
         def estimated_length(_tx, _input_index)

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 = OpenSSL::Digest::SHA256.digest(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