bsv-sdk 0.24.0 → 0.25.0

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

data/lib/bsv/storage/utils.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Storage
+    # Helpers for encoding and decoding UHRP (Unified Hash Resource Protocol) URLs.
+    #
+    # A UHRP URL is a Base58Check string with a two-byte `\xCE\x00` prefix prepended
+    # to the SHA-256 hash of the content. This makes each URL self-verifying and
+    # stable across storage providers.
+    #
+    # == URL normalisation
+    #
+    # `normalize_url` strips the `uhrp:` scheme (case-insensitive) and the optional
+    # `//` authority prefix, matching the TS SDK contract exactly. The `web+uhrp://`
+    # variant used by some browser extension manifests is *not* normalised here — that
+    # diverges from the TS reference (Python normalises it; we follow TS).
+    module Utils
+      # Two-byte UHRP version prefix: 0xCE 0x00.
+      UHRP_PREFIX = "\xCE\x00".b.freeze
+
+      module_function
+
+      # Encode a 32-byte binary SHA-256 hash as a UHRP URL.
+      #
+      # @param hash [String] 32-byte binary string (SHA-256 hash)
+      # @return [String] Base58Check-encoded UHRP URL
+      # @raise [ArgumentError] if hash is not exactly 32 bytes
+      def get_url_for_hash(hash)
+        raise ArgumentError, 'Hash length must be 32 bytes (sha256)' unless hash.bytesize == 32
+
+        BSV::Primitives::Base58.check_encode(hash.b, prefix: UHRP_PREFIX)
+      end
+
+      # Compute the SHA-256 hash of +data+ and encode it as a UHRP URL.
+      #
+      # @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)
+        get_url_for_hash(hash)
+      end
+
+      # Decode a UHRP URL and return the 32-byte binary SHA-256 hash.
+      #
+      # Accepts URLs with or without the `uhrp:` scheme and optional `//` authority.
+      #
+      # @param url [String] UHRP URL (with or without `uhrp:` prefix)
+      # @return [String] 32-byte binary SHA-256 hash
+      # @raise [ArgumentError] if the URL is not a String, empty, has a bad prefix, or has wrong length
+      # @raise [BSV::Primitives::Base58::ChecksumError] if the Base58Check checksum fails
+      def get_hash_from_url(url)
+        raise ArgumentError, 'URL must be a String' unless url.is_a?(String)
+        raise ArgumentError, 'URL must not be empty' if url.empty?
+
+        normalised = normalize_url(url)
+        result = BSV::Primitives::Base58.check_decode(normalised, prefix_length: 2)
+        raise ArgumentError, 'Bad prefix' unless result[:prefix] == UHRP_PREFIX
+        raise ArgumentError, 'Invalid length!' unless result[:data].bytesize == 32
+
+        result[:data]
+      end
+
+      # Strip the `uhrp:` scheme (case-insensitive) and optional `//` from a URL.
+      #
+      # Follows the TS SDK contract: only `uhrp:` and `uhrp://` are normalised.
+      # `web+uhrp://` is deliberately not stripped (TS does not strip it; Python does).
+      #
+      # @param url [String] URL to normalise
+      # @return [String] normalised URL
+      def normalize_url(url)
+        url = url.slice(5..) if url.downcase.start_with?('uhrp:')
+        url = url.slice(2..) if url.start_with?('//')
+        url
+      end
+
+      # Return +true+ if +url+ is a syntactically valid UHRP URL.
+      #
+      # @param url [String] URL to validate
+      # @return [Boolean]
+      def valid_url?(url)
+        get_hash_from_url(url)
+        true
+      rescue ArgumentError, BSV::Primitives::Base58::ChecksumError
+        false
+      end
+    end
+  end
+end

data/lib/bsv/storage.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BSV
+  # Storage module for UHRP (Unified Hash Resource Protocol) URL encoding,
+  # decoding, and validation helpers.
+  #
+  # UHRP enables content-addressed storage on BSV: a SHA-256 hash of a file
+  # is Base58Check-encoded with the `\xCE\x00` prefix to produce a stable,
+  # self-verifying URL.
+  module Storage
+    autoload :Utils,          'bsv/storage/utils'
+    autoload :DownloadResult, 'bsv/storage/downloader'
+    autoload :Downloader,     'bsv/storage/downloader'
+    autoload :DownloadError,  'bsv/storage/errors'
+  end
+end