bsv-sdk 0.24.0 → 0.26.0

data/lib/bsv/primitives/digest.rb

@@ -9,33 +9,111 @@ module BSV
     # Thin wrappers around +OpenSSL::Digest+ and +OpenSSL::HMAC+ providing
     # the hash algorithms used throughout the BSV protocol: SHA-1, SHA-256,
     # double-SHA-256, SHA-512, RIPEMD-160, Hash160, HMAC, and PBKDF2.
+    #
+    # @note **Per-fibre cached OpenSSL contexts (via +Thread.current+)**
+    #
+    #   +sha256+, +sha256d+, +sha1+, and +sha512+ each cache one
+    #   +OpenSSL::Digest+ instance per fibre in +Thread.current+ under a
+    #   namespaced key (e.g. +:bsv_sdk_sha256_digest+).  Because MRI has no
+    #   fibres in this SDK's +lib/+ today, "per fibre" and "per thread" are
+    #   the same in practice — but the primitive is fibre-local, so the more
+    #   precise term is used throughout.  On every call the context is reset
+    #   with +OpenSSL::Digest#reset+, which calls +EVP_DigestInit_ex+ against
+    #   the +EVP_MD*+ already stored on the context.  This skips the
+    #   +EVP_get_digestbyname+ namemap lookup that
+    #   +OpenSSL::Digest::SHA256.new+ (or +.digest+) performs on every fresh
+    #   allocation.  The namemap cost is paid exactly once per fibre per
+    #   algorithm.
+    #
+    #   **Fibre-local semantics.**  +Thread.current[:key]+ is *fibre-local*
+    #   in MRI (documented since Ruby 2.0, verified on 3.3 / 3.4 / 4.0) — each
+    #   Fibre gets its own cached context.  This is stronger than the SDK
+    #   currently requires (no Fibres in +lib/+) and is correctly safe if
+    #   Fibres are introduced later.  The HLR body's "GVL makes it safe"
+    #   rationale is subtly wrong; the correct reason is fibre-local scope.
+    #
+    #   **Do not touch the cached instances externally.**  The keys
+    #   +:bsv_sdk_sha256_digest+, +:bsv_sdk_sha1_digest+, and
+    #   +:bsv_sdk_sha512_digest+ are technically reachable via +Thread.current+
+    #   but must never have +update+ called on them outside this module.
+    #   Calling +update+ out-of-band would corrupt the next call's input.
+    #
+    #   **User-visible invariants are unchanged:** return values are always
+    #   +ASCII-8BIT+ binary strings; identical inputs always produce identical
+    #   outputs; successive calls return distinct +String+ objects (output
+    #   buffers are never cached).
+    #
+    #   **Prefix convention.**  +:bsv_sdk_<algo>_digest+ is the SDK-wide
+    #   naming convention for any future +Thread.current+ usage in this
+    #   codebase — the prefix avoids collision with other libraries that may
+    #   also use +Thread.current+.
+    #
+    #   **FIPS.**  SHA-1, SHA-256, and SHA-512 remain FIPS-approved algorithms
+    #   under this pattern; the algorithm fetch happens once at +.new+, not per
+    #   call.
+    #
+    #   **CI matrix.**  Verified on MRI 3.3, 3.4, and 4.0.  JRuby and
+    #   TruffleRuby are not in the CI matrix — per-thread caching is correct on
+    #   true-parallel Rubies (each thread has independent +Thread.current+) but
+    #   unverified here.
+    #
+    #   **Why other SDKs do not do this.**  The TypeScript, Go, and Python SDKs
+    #   allocate fresh digest contexts per call because their OpenSSL bindings
+    #   cache the algorithm handle internally.  MRI's +openssl+ gem bridges
+    #   through +EVP_get_digestbyname+ on every allocation — we are patching
+    #   the Ruby binding overhead, not diverging from BSV protocol semantics.
+    #
+    #   **Out of scope with rationale:**
+    #   - +ripemd160+ — pure-Ruby implementation; no OpenSSL context.
+    #   - +hmac_sha256+ / +hmac_sha512+ — HMAC key changes per call.  A future
+    #     cache *must* key on wrapper-object identity (+object_id+), never on
+    #     key bytes — a key-bytes cache lookup would create a secret-dependent
+    #     side-channel via cache-hit timing.
+    #   - +pbkdf2_hmac_sha512+ — one-shot at BIP-39 seed derivation; not a
+    #     hot path.
     module Digest
       module_function
 
       # Compute SHA-1 digest.
       #
       # @param data [String] binary data to hash
-      # @return [String] 20-byte digest
+      # @return [String] 20-byte digest (ASCII-8BIT)
       def sha1(data)
-        OpenSSL::Digest::SHA1.digest(data)
+        d = Thread.current[:bsv_sdk_sha1_digest] ||= OpenSSL::Digest.new('SHA1')
+        d.reset
+        d.update(data)
+        d.digest
       end
 
       # Compute SHA-256 digest.
       #
       # @param data [String] binary data to hash
-      # @return [String] 32-byte digest
+      # @return [String] 32-byte digest (ASCII-8BIT)
       def sha256(data)
-        OpenSSL::Digest::SHA256.digest(data)
+        d = Thread.current[:bsv_sdk_sha256_digest] ||= OpenSSL::Digest.new('SHA256')
+        d.reset
+        d.update(data)
+        d.digest
       end
 
       # Compute double-SHA-256 (SHA-256d) digest.
       #
       # Used extensively in Bitcoin for transaction and block hashing.
+      # Inlines the two-round chain against the same cached SHA-256 context,
+      # saving one context allocation, one namemap lookup, one intermediate
+      # +String+, and one +module_function+ dispatch per call compared with
+      # the naive +sha256(sha256(data))+ decomposition.
       #
       # @param data [String] binary data to hash
-      # @return [String] 32-byte digest
+      # @return [String] 32-byte digest (ASCII-8BIT)
       def sha256d(data)
-        sha256(sha256(data))
+        d = Thread.current[:bsv_sdk_sha256_digest] ||= OpenSSL::Digest.new('SHA256')
+        d.reset
+        d.update(data)
+        first = d.digest
+        d.reset # defensive: some Ruby versions internally reset after #digest
+        d.update(first)
+        d.digest
       end
 
       alias hash256 sha256d
@@ -44,15 +122,23 @@ module BSV
       # Compute SHA-512 digest.
       #
       # @param data [String] binary data to hash
-      # @return [String] 64-byte digest
+      # @return [String] 64-byte digest (ASCII-8BIT)
       def sha512(data)
-        OpenSSL::Digest::SHA512.digest(data)
+        d = Thread.current[:bsv_sdk_sha512_digest] ||= OpenSSL::Digest.new('SHA512')
+        d.reset
+        d.update(data)
+        d.digest
       end
 
       # Compute RIPEMD-160 digest.
       #
+      # @note Uses the pure-Ruby {BSV::Primitives::Ripemd160} implementation —
+      #   no OpenSSL context is held or cached here.  RIPEMD-160 is not in
+      #   scope for the per-thread caching optimisation (different optimisation
+      #   track; not currently a hot path).
+      #
       # @param data [String] binary data to hash
-      # @return [String] 20-byte digest
+      # @return [String] 20-byte digest (ASCII-8BIT)
       def ripemd160(data)
         Ripemd160.digest(data)
       end
@@ -62,25 +148,32 @@ module BSV
       # Standard Bitcoin hash used for addresses and P2PKH script matching.
       #
       # @param data [String] binary data to hash
-      # @return [String] 20-byte digest
+      # @return [String] 20-byte digest (ASCII-8BIT)
       def hash160(data)
         ripemd160(sha256(data))
       end
 
       # Compute HMAC-SHA-256.
       #
+      # @note HMAC context reuse is deferred — the key changes per call, so a
+      #   future cache must key on wrapper-object identity (+object_id+), never
+      #   on key bytes, to avoid a secret-dependent side-channel via cache-hit
+      #   timing.
+      #
       # @param key [String] HMAC key
       # @param data [String] data to authenticate
-      # @return [String] 32-byte MAC
+      # @return [String] 32-byte MAC (ASCII-8BIT)
       def hmac_sha256(key, data)
         OpenSSL::HMAC.digest('SHA256', key, data)
       end
 
       # Compute HMAC-SHA-512.
       #
+      # @note HMAC context reuse is deferred — see +hmac_sha256+ note.
+      #
       # @param key [String] HMAC key
       # @param data [String] data to authenticate
-      # @return [String] 64-byte MAC
+      # @return [String] 64-byte MAC (ASCII-8BIT)
       def hmac_sha512(key, data)
         OpenSSL::HMAC.digest('SHA512', key, data)
       end
@@ -88,12 +181,13 @@ module BSV
       # Derive a key using PBKDF2-HMAC-SHA-512.
       #
       # Used by BIP-39 to convert mnemonic phrases into seeds.
+      # One-shot at key creation — not a hot path; no context reuse applied.
       #
       # @param password [String] the password (mnemonic phrase)
       # @param salt [String] the salt (+"mnemonic"+ + passphrase)
       # @param iterations [Integer] iteration count (default: 2048 per BIP-39)
       # @param key_length [Integer] desired output length in bytes (default: 64)
-      # @return [String] derived key bytes
+      # @return [String] derived key bytes (ASCII-8BIT)
       def pbkdf2_hmac_sha512(password, salt, iterations: 2048, key_length: 64)
         OpenSSL::PKCS5.pbkdf2_hmac(password, salt, iterations, key_length, 'sha512')
       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

@@ -112,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,
@@ -430,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)

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

@@ -52,6 +52,8 @@ module BSV
       STACK_MEMORY_EXCEEDED = :stack_memory_exceeded
       UNIMPLEMENTED_OPCODE = :unimplemented_opcode
       MISSING_TX_CONTEXT = :missing_tx_context
+      SIG_PUSHONLY = :sig_pushonly
+      CLEAN_STACK = :clean_stack
     end
   end
 end