bsv-sdk 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1ead96687ff2a6118fde4ab72a7dc0b11c7d82db8b4b883910120bcc0cee0dc
-  data.tar.gz: 5a089f6b80111ba4abf5472bfbd8067a028b35a73f90e504e2541376d0d00d55
+  metadata.gz: 27489947d80a203e32fad08b53cfee4edabca7df61f244dff2ca12c5fa45e261
+  data.tar.gz: d3bd5ead19a4fa67f4111e9bd3a203a1cad3c083ad4b8e174ee114b5b7fdb4bd
 SHA512:
-  metadata.gz: d05f8b3b8a584706323c631fb9ff005420c6d5cdc5081f76fbf6a73b15c12323b87d30f469e5fa186bfa30b51905ffe4bc0785b57bd77d72286ee3f8ce03dc1f
-  data.tar.gz: b892a8add5e5faaad6bc837ab26de879419cc457d909be4f5b1fb812fd4a69fb5356529689081dffe1195caffdb2e259da6a073ea1ce6ff2f0d08068c73a67f1
+  metadata.gz: 5ebdd5176602d584debb675d470dc31079cb16a29bb858c806123227efe03783c7c7f77eccf38174e254b7579fae9bad71d17c9e71791c21a694653647e15ad6
+  data.tar.gz: cedddebaec0eeb9c2fa037af4227ad7307492146c2b4dc18d3a7f4dfc7f3179c20428245424d0a8542db97bbad08831a334d7821f17fd3c05264d38289271552

data/CHANGELOG.md

@@ -5,6 +5,59 @@ All notable changes to the `bsv-sdk` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.15.0 — 2026-04-29
+
+### Added
+- Extracted secp256k1 elliptic curve operations to the standalone
+  `secp256k1-native` gem, with an optional native C extension providing
+  ~22x speedup for field, scalar, and Jacobian point operations (#648)
+- Native C extension scaffold with field arithmetic, scalar arithmetic,
+  and Jacobian point operations (#627, #628, #629, #630, #631)
+- Constant-time Montgomery ladder with branchless conditional swap for
+  scalar multiplication; `mul` is now constant-time by default, with
+  `mul_vt` available for variable-time use cases (#641, #653)
+- Wycheproof Bitcoin ECDSA test vectors (463 cases) with explicit
+  categorisation of high-S malleability cases as mathematically valid
+  but policy-rejected — documenting the layer separation between
+  ECDSA verification and Bitcoin's low-S enforcement (#652)
+- Wycheproof standard ECDSA test vectors (474 cases), RFC 6979
+  compliance suite, and secp256k1 field/scalar/point compliance
+  examples (#636, #637, #638)
+
+### Fixed
+- Carry overflow in schoolbook multiplication (L2) and branchless
+  borrow extraction in field reduction (#631)
+- Gemspec version floor, docstring, and variable name corrections
+  from PR review (#653)
+
+### Changed
+- Replaced `BN` hex intermediaries with direct binary construction
+  for improved performance (#622)
+- Binary byte comparison in `SignedMessage` verification (#624)
+
+## 0.14.0 — 2026-04-22
+
+### Added
+- `BSV::Network::WhatsOnChain` expanded with `current_height`,
+  `get_block_header(height)`, and `valid_root_for_height?(root, height)` —
+  a single WhatsOnChain instance now serves as a complete chain data source
+  (#596)
+- BEEF-based SPV verification conformance tests (#607)
+
+### Changed
+- `Transaction#verify` now raises `VerificationError` for all failure modes:
+  `:script_failure` (wraps `ScriptError` with cause chaining),
+  `:missing_source` (replaces `ArgumentError`), `:invalid_merkle_proof`,
+  `:insufficient_fee`, and `:output_overflow`. Code rescuing `ArgumentError`
+  or `ScriptError` from `verify` must switch to `VerificationError` (#608)
+- Removed dead code: `BSV::Wallet::Wallet` (superseded by bsv-wallet gem's
+  `Client`), `BSV::Messages` (unused re-export alias), and duplicate
+  `BSV::Wallet::InsufficientFundsError` (#594)
+
+### Fixed
+- WhatsOnChain `valid_root_for_height?` YARD doc now correctly documents
+  that 404 returns `false` rather than raising
+
 ## 0.13.0 — 2026-04-21
 
 ### Added

data/README.md

@@ -34,7 +34,9 @@ These are maintained under the BSV Blockchain organisation and backed by the Bit
 
 The BSV Blockchain Libraries Project aims to structure and maintain a middleware layer of the BSV Blockchain technology stack. By facilitating the development and maintenance of core libraries, it serves as an essential toolkit for developers looking to build on the BSV Blockchain.
 
-This Ruby SDK brings maximum compatibility with the official SDK family to the Ruby ecosystem. It was born from a practical need: building an attestation gem ([bsv-attest](https://rubygems.org/gems/bsv-attest)) required a complete, idiomatic Ruby implementation of BSV primitives, script handling, and transaction construction. Rather than wrapping FFI bindings or shelling out to other languages, the SDK implements everything in pure Ruby. Elliptic curve operations (secp256k1) use a native Ruby implementation ported from the TypeScript reference SDK; OpenSSL is used only for hashing, HMAC, and symmetric encryption.
+This Ruby SDK brings maximum compatibility with the official SDK family to the Ruby ecosystem. It was born from a practical need: building an attestation gem ([bsv-attest](https://rubygems.org/gems/bsv-attest)) required a complete, idiomatic Ruby implementation of BSV primitives, script handling, and transaction construction.
+
+Elliptic curve operations (secp256k1) are provided by the [`secp256k1-native`](https://github.com/sgbett/secp256k1-native) gem, which was originally part of this library and has been extracted as a standalone dependency. This is a custom implementation ported from the TypeScript reference SDK — it does not wrap `libsecp256k1`. It includes a pure Ruby implementation with an optional native C extension for constant-time field arithmetic and performance. OpenSSL is used only for hashing, HMAC, and symmetric encryption.
 
 <!-- TODO: Update bsv-attest link once gem documentation is published (see #48) -->
 
@@ -59,6 +61,16 @@ Or install directly:
 gem install bsv-sdk
 ```
 
+### Native C Extension (Recommended)
+
+The SDK depends on [`secp256k1-native`](https://github.com/sgbett/secp256k1-native) for elliptic curve operations. It works out of the box in pure Ruby, but compiling the optional C extension is strongly recommended — it provides constant-time field arithmetic, which protects against timing side-channel attacks on private key operations:
+
+```bash
+cd $(bundle show secp256k1-native) && bundle exec rake compile
+```
+
+This requires a C99 compiler with `__uint128_t` support (GCC or Clang on macOS/Linux). If compilation is not possible, the SDK falls back to pure Ruby automatically — but the pure Ruby path does not guarantee constant-time execution.
+
 ### Basic Usage
 
 Create and sign a P2PKH transaction:
@@ -101,7 +113,7 @@ puts tx.to_hex
 
 ## Features & Deliverables
 
-- **Cryptographic Primitives** — ECDSA signing with RFC 6979 deterministic nonces, Schnorr signatures, ECIES encryption/decryption, Bitcoin Signed Messages. Elliptic curve operations use a [pure Ruby secp256k1 implementation](docs/about/secp256k1.md) ported from the TypeScript reference SDK.
+- **Cryptographic Primitives** — ECDSA signing with RFC 6979 deterministic nonces, Schnorr signatures, ECIES encryption/decryption, Bitcoin Signed Messages. Elliptic curve operations are provided by the [`secp256k1-native`](https://github.com/sgbett/secp256k1-native) gem — a pure Ruby secp256k1 implementation with an optional C extension (~22× speedup).
 - **Key Management** — BIP-32 HD key derivation, BIP-39 mnemonic generation (12/24-word phrases), WIF import/export, Base58Check encoding/decoding.
 - **Script Layer** — Complete opcode set, script parsing and serialisation, type detection and predicates (`p2pkh?`, `p2pk?`, `p2sh?`, `multisig?`, `op_return?`), data extraction (pubkey hashes, script hashes, addresses), and a fluent builder API.
 - **Script Templates** — Ready-made locking and unlocking script generators for P2PKH, P2PK, P2MS (multisig), and OP_RETURN.

data/lib/bsv/auth/certificate.rb

@@ -176,7 +176,7 @@ module BSV
       def verify(verifier_wallet = nil)
         raise ArgumentError, 'certificate has no signature to verify' if @signature.nil? || @signature.empty?
 
-        verifier_wallet ||= BSV::Wallet::Client.new('anyone', storage: BSV::Wallet::Store::Memory.new)
+        verifier_wallet ||= BSV::Wallet::Client.new('anyone', storage: BSV::Wallet::Store::Memory.new, allow_memory_store: true)
         preimage  = to_binary(include_signature: false)
         sig_bytes = [@signature].pack('H*').unpack('C*')
 

data/lib/bsv/network/whats_on_chain.rb

@@ -5,8 +5,11 @@ module BSV
     # WhatsOnChain chain data provider for reading transactions and UTXOs
     # from the BSV network.
     #
-    # Any object responding to #fetch_utxos(address) and
-    # #fetch_transaction(txid) can serve as a chain data provider;
+    # Any object responding to #fetch_utxos(address),
+    # #fetch_transaction(txid), #current_height,
+    # #get_block_header(height), and optionally
+    # #valid_root_for_height?(root_hex, height) can serve as a chain
+    # data source;
     # this class implements that contract by delegating to
     # Protocols::WoCREST.
     #
@@ -62,6 +65,42 @@ module BSV
         BSV::Transaction::Transaction.from_hex(result.data)
       end
 
+      # Return the current blockchain height.
+      # @return [Integer]
+      # @raise [BSV::Network::ChainProviderError] on network or API error
+      def current_height
+        result = @protocol.call(:current_height)
+        raise_on_error(result)
+
+        result.data
+      end
+
+      # Fetch the block header for a given height.
+      # @param height [Integer] block height
+      # @return [Hash] parsed block header JSON
+      # @raise [BSV::Network::ChainProviderError] on network or API error
+      def get_block_header(height)
+        result = @protocol.call(:get_block_header, height)
+        raise_on_error(result)
+
+        result.data
+      end
+
+      # Verify that a merkle root is valid for the given block height.
+      # Returns +false+ when the block is not found (404); raises on other errors.
+      # @param root [String] expected merkle root as hex
+      # @param height [Integer] block height
+      # @return [Boolean]
+      # @raise [BSV::Network::ChainProviderError] on network or non-404 API error
+      def valid_root_for_height?(root, height)
+        result = @protocol.call(:valid_root, root, height)
+        return false if result.not_found?
+
+        raise_on_error(result)
+
+        result.data == true
+      end
+
       private
 
       # Translates a non-success Protocol result into a raised ChainProviderError.

data/lib/bsv/primitives/base58.rb

@@ -42,6 +42,7 @@ module BSV
         bytes.each_byte { |b| b.zero? ? leading_zeros += 1 : break }
 
         # Convert to big integer and repeatedly divide by 58
+        # C-backed hex conversion — 10x faster than pure-Ruby byte shifting; not a porting artefact.
         n = bytes.unpack1('H*').to_i(16)
         result = +''
         while n.positive?
@@ -78,7 +79,7 @@ module BSV
           n = (n * BASE) + digit
         end
 
-        # Convert integer to bytes
+        # Convert integer to bytes — C-backed hex round-trip is the fastest pure-Ruby integer→bytes path.
         hex = n.zero? ? '' : n.to_s(16)
         hex = "0#{hex}" if hex.length.odd?
         result = [hex].pack('H*')

data/lib/bsv/primitives/curve.rb

@@ -25,10 +25,11 @@ module BSV
 
       module_function
 
-      # Multiply the generator point by a scalar (variable-time, wNAF).
+      # Multiply the generator point by a scalar (constant-time).
       #
-      # Suitable for public scalars only (e.g. verify paths). For secret
-      # scalars use {multiply_generator_ct}.
+      # Uses the Montgomery ladder by default, matching OpenSSL convention.
+      # Safe for both secret and public scalars. For explicit variable-time
+      # multiplication of public scalars, use {multiply_generator_vt}.
       #
       # @param scalar_bn [OpenSSL::BN] the scalar multiplier
       # @return [OpenSSL::PKey::EC::Point] the resulting curve point
@@ -38,19 +39,31 @@ module BSV
 
       # Multiply the generator point by a secret scalar (constant-time).
       #
-      # Uses the Montgomery ladder to avoid timing side-channels on the
-      # scalar. Use for key generation and signing.
+      # Alias for {multiply_generator} — retained for backward compatibility
+      # and expressiveness.
       #
       # @param scalar_bn [OpenSSL::BN] the secret scalar multiplier
       # @return [OpenSSL::PKey::EC::Point] the resulting curve point
       def multiply_generator_ct(scalar_bn)
-        G.mul_ct(scalar_bn)
+        G.mul(scalar_bn)
       end
 
-      # Multiply an arbitrary curve point by a scalar (variable-time, wNAF).
+      # Multiply the generator point by a public scalar (variable-time, wNAF).
       #
-      # Suitable for public scalars only. For secret scalars use
-      # {multiply_point_ct}.
+      # Faster than {multiply_generator} but leaks timing information about
+      # the scalar. Use only for public scalars (e.g. signature verification).
+      #
+      # @param scalar_bn [OpenSSL::BN] the public scalar multiplier
+      # @return [OpenSSL::PKey::EC::Point] the resulting curve point
+      def multiply_generator_vt(scalar_bn)
+        G.mul_vt(scalar_bn)
+      end
+
+      # Multiply an arbitrary curve point by a scalar (constant-time).
+      #
+      # Uses the Montgomery ladder by default, matching OpenSSL convention.
+      # Safe for both secret and public scalars. For explicit variable-time
+      # multiplication of public scalars, use {multiply_point_vt}.
       #
       # @param point [OpenSSL::PKey::EC::Point] the point to multiply
       # @param scalar_bn [OpenSSL::BN] the scalar multiplier
@@ -61,14 +74,26 @@ module BSV
 
       # Multiply an arbitrary curve point by a secret scalar (constant-time).
       #
-      # Uses the Montgomery ladder to avoid timing side-channels on the
-      # scalar. Use for ECDH shared-secret derivation.
+      # Alias for {multiply_point} — retained for backward compatibility
+      # and expressiveness.
       #
       # @param point [OpenSSL::PKey::EC::Point] the base point
       # @param scalar_bn [OpenSSL::BN] the secret scalar multiplier
       # @return [OpenSSL::PKey::EC::Point] the resulting curve point
       def multiply_point_ct(point, scalar_bn)
-        point.mul_ct(scalar_bn)
+        point.mul(scalar_bn)
+      end
+
+      # Multiply an arbitrary curve point by a public scalar (variable-time, wNAF).
+      #
+      # Faster than {multiply_point} but leaks timing information about
+      # the scalar. Use only for public scalars (e.g. signature verification).
+      #
+      # @param point [OpenSSL::PKey::EC::Point] the point to multiply
+      # @param scalar_bn [OpenSSL::BN] the public scalar multiplier
+      # @return [OpenSSL::PKey::EC::Point] the resulting curve point
+      def multiply_point_vt(point, scalar_bn)
+        point.mul_vt(scalar_bn)
       end
 
       # Add two curve points together.

data/lib/bsv/primitives/ecdsa.rb

@@ -82,8 +82,8 @@ module BSV
         u1 = ((n - e) * r_inv) % n
         u2 = (s * r_inv) % n
 
-        p1 = Curve.multiply_generator(u1)
-        p2 = Curve.multiply_point(r_point, u2)
+        p1 = Curve.multiply_generator_vt(u1)
+        p2 = Curve.multiply_point_vt(r_point, u2)
         q = Curve.add_points(p1, p2)
 
         raise ArgumentError, 'recovered point is at infinity' if q.infinity?
@@ -112,8 +112,8 @@ module BSV
         u2 = (r * s_inv) % n
 
         # R' = u1*G + u2*Q
-        point1 = Curve.multiply_generator(u1)
-        point2 = Curve.multiply_point(public_key_point, u2)
+        point1 = Curve.multiply_generator_vt(u1)
+        point2 = Curve.multiply_point_vt(public_key_point, u2)
         result_point = Curve.add_points(point1, point2)
 
         return false if result_point.infinity?

data/lib/bsv/primitives/openssl_ec_shim.rb

@@ -66,6 +66,22 @@ class BSVShimECPoint
     pt
   end
 
+  # Scalar multiplication: self * scalar (constant-time, Montgomery ladder).
+  #
+  # Matches OpenSSL convention where +EC_POINT_mul+ is always constant-time.
+  # Safe for both secret and public scalars.
+  #
+  # Also supports the multi-scalar form: +mul(bns, points)+ computes
+  # <tt>bns[0]*self + bns[1]*points[0] + ...</tt>
+  # where +bns.length == points.length + 1+.
+  #
+  # @overload mul(scalar_bn)
+  #   @param scalar_bn [OpenSSL::BN, Integer] the scalar multiplier
+  # @overload mul(bns, points)
+  #   @param bns [Array<OpenSSL::BN>] scalars; must have +points.length + 1+ elements
+  #   @param points [Array<BSVShimECPoint>] additional points
+  #   @raise [NoMethodError] if +bns+ and +points+ lengths are mismatched
+  # @return [BSVShimECPoint]
   def mul(*args)
     if args.length == 1
       scalar = bn_to_int(args[0])
@@ -85,16 +101,27 @@ class BSVShimECPoint
     end
   end
 
-  # Constant-time scalar multiplication via the Montgomery ladder.
+  # Constant-time scalar multiplication (alias for {#mul}).
   #
-  # Delegates to {BSV::Primitives::Secp256k1::Point#mul_ct} to ensure
-  # secret-scalar paths execute in constant time.
+  # Retained for backward compatibility and expressiveness. Delegates
+  # to {#mul}, which is constant-time by default.
   #
-  # @param scalar_bn [OpenSSL::BN, Integer] the secret scalar
+  # @param scalar_bn [OpenSSL::BN, Integer] the scalar multiplier
   # @return [BSVShimECPoint]
   def mul_ct(scalar_bn)
+    mul(scalar_bn)
+  end
+
+  # Variable-time scalar multiplication (wNAF).
+  #
+  # Faster than {#mul} but leaks timing information about the scalar.
+  # Use only for public scalars (e.g. signature verification).
+  #
+  # @param scalar_bn [OpenSSL::BN, Integer] the public scalar multiplier
+  # @return [BSVShimECPoint]
+  def mul_vt(scalar_bn)
     scalar = bn_to_int(scalar_bn)
-    result = @secp_point.mul_ct(scalar)
+    result = @secp_point.mul_vt(scalar)
     self.class.from_secp_point(@group, result)
   end
 

data/lib/bsv/primitives/private_key.rb

@@ -165,7 +165,7 @@ module BSV
       def derive_child(public_key, invoice_number)
         shared = derive_shared_secret(public_key)
         hmac = Digest.hmac_sha256(shared.compressed, invoice_number.encode('UTF-8'))
-        hmac_bn = OpenSSL::BN.new(hmac.unpack1('H*'), 16)
+        hmac_bn = OpenSSL::BN.new(hmac, 2)
         PrivateKey.new(@bn.mod_add(hmac_bn, Curve::N))
       end
 
@@ -207,7 +207,7 @@ module BSV
           loop do
             counter_bytes = [i, attempts].pack('N*') + SecureRandom.random_bytes(32)
             h             = Digest.hmac_sha512(seed, counter_bytes)
-            candidate     = OpenSSL::BN.new(h.unpack1('H*'), 16) % PointInFiniteField::P
+            candidate     = OpenSSL::BN.new(h, 2) % PointInFiniteField::P
 
             attempts += 1
             raise ArgumentError, 'failed to generate unique x-coordinate after 5 attempts' if attempts > 5

data/lib/bsv/primitives/public_key.rb

@@ -132,7 +132,7 @@ module BSV
       def derive_child(private_key, invoice_number)
         shared = derive_shared_secret(private_key)
         hmac = Digest.hmac_sha256(shared.compressed, invoice_number.encode('UTF-8'))
-        hmac_bn = OpenSSL::BN.new(hmac.unpack1('H*'), 16)
+        hmac_bn = OpenSSL::BN.new(hmac, 2)
         hmac_point = Curve.multiply_generator_ct(hmac_bn)
         child_point = Curve.add_points(@point, hmac_point)
         PublicKey.new(child_point)

data/lib/bsv/primitives/schnorr.rb

@@ -97,15 +97,15 @@ module BSV
         e = compute_challenge(public_key_a, public_key_b, shared_secret, proof.s_prime, proof.r)
 
         # Equation 1: z·G == R + e·A
-        z_g = Curve.multiply_generator(proof.z)
-        e_a = Curve.multiply_point(public_key_a.point, e)
+        z_g = Curve.multiply_generator_vt(proof.z)
+        e_a = Curve.multiply_point_vt(public_key_a.point, e)
         r_plus_ea = Curve.add_points(proof.r.point, e_a)
 
         return false unless points_equal?(z_g, r_plus_ea)
 
         # Equation 2: z·B == S' + e·S
-        z_b = Curve.multiply_point(public_key_b.point, proof.z)
-        e_s = Curve.multiply_point(shared_secret.point, e)
+        z_b = Curve.multiply_point_vt(public_key_b.point, proof.z)
+        e_s = Curve.multiply_point_vt(shared_secret.point, e)
         sp_plus_es = Curve.add_points(proof.s_prime.point, e_s)
 
         points_equal?(z_b, sp_plus_es)