bsv-sdk 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4532a163439721455da80290d8b02342e597a01bb1e00b259d13343f8f9bd592
-  data.tar.gz: b7cfda4a8084b96c28f34afb6829fcba9f5be0dabb01fca536147bfe2c66bad8
+  metadata.gz: 27489947d80a203e32fad08b53cfee4edabca7df61f244dff2ca12c5fa45e261
+  data.tar.gz: d3bd5ead19a4fa67f4111e9bd3a203a1cad3c083ad4b8e174ee114b5b7fdb4bd
 SHA512:
-  metadata.gz: ed0b97db3cec8503eba509f232a463d8566373b34ccaf5fe7cd130a72e712cde17b083b4ce94ef64fa84786d6e6aec8965423ca6b8a7471ada70ebd522956e2a
-  data.tar.gz: 0747a93bef059a8eccf0f504e703d20ddc875f8c562db8f01d3af4050bf7562deb262eb4494db4d98b78665f91274ed77754fa76e99254b8592b7e0f1526aa13
+  metadata.gz: 5ebdd5176602d584debb675d470dc31079cb16a29bb858c806123227efe03783c7c7f77eccf38174e254b7579fae9bad71d17c9e71791c21a694653647e15ad6
+  data.tar.gz: cedddebaec0eeb9c2fa037af4227ad7307492146c2b4dc18d3a7f4dfc7f3179c20428245424d0a8542db97bbad08831a334d7821f17fd3c05264d38289271552

data/CHANGELOG.md

@@ -5,6 +5,36 @@ 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

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

data/lib/bsv/primitives/secp256k1.rb

@@ -1,602 +1,11 @@
 # frozen_string_literal: true
 
-# Single-letter parameter names (k, p, q, x, y, z, etc.) match standard
-# elliptic-curve mathematical notation and the BSV TypeScript reference SDK
-# this module is ported from. The whole-module length cop is disabled because
-# the curve implementation (field arithmetic + Jacobian point ops + wNAF
-# scalar multiplication + Point class) intentionally lives in one module to
-# keep the secp256k1 surface coherent.
-# rubocop:disable Naming/MethodParameterName, Metrics/ModuleLength
+require 'secp256k1'
 
 module BSV
   module Primitives
-    # Pure Ruby secp256k1 elliptic curve implementation.
-    #
-    # Provides field arithmetic, point operations with Jacobian coordinates,
-    # and windowed-NAF scalar multiplication. Ported from the BSV TypeScript
-    # SDK reference implementation.
-    #
-    # All field operations work on plain Ruby +Integer+ values (arbitrary
-    # precision, C-backed in MRI). No external gems required.
-    module Secp256k1
-      # The secp256k1 field prime: p = 2^256 - 2^32 - 977
-      P = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F
-
-      # The curve order (number of points on the curve).
-      N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
-
-      # Half the curve order, used for low-S normalisation (BIP-62).
-      HALF_N = N >> 1
-
-      # Generator point x-coordinate.
-      GX = 0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798
-
-      # Generator point y-coordinate.
-      GY = 0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8
-
-      # (P + 1) / 4 — used for modular square root since P ≡ 3 (mod 4).
-      P_PLUS1_DIV4 = (P + 1) >> 2
-
-      # 256-bit mask for fast reduction.
-      MASK_256 = (1 << 256) - 1
-
-      module_function
-
-      # -------------------------------------------------------------------
-      # Byte conversion helpers
-      # -------------------------------------------------------------------
-
-      # Convert a big-endian binary string to an Integer.
-      #
-      # @param bytes [String] binary string (ASCII-8BIT)
-      # @return [Integer]
-      def bytes_to_int(bytes)
-        bytes.unpack1('H*').to_i(16)
-      end
-
-      # Convert an Integer to a fixed-length big-endian binary string.
-      #
-      # @param n [Integer] the integer to convert
-      # @param length [Integer] desired byte length (default 32)
-      # @return [String] binary string (ASCII-8BIT)
-      def int_to_bytes(n, length = 32)
-        raise ArgumentError, 'negative integer' if n.negative?
-
-        hex = n.to_s(16)
-        hex = "0#{hex}" if hex.length.odd?
-        raise ArgumentError, "integer too large for #{length} bytes" if hex.length > length * 2
-
-        hex = hex.rjust(length * 2, '0')
-        [hex].pack('H*')
-      end
-
-      # -------------------------------------------------------------------
-      # Field arithmetic (mod P)
-      # -------------------------------------------------------------------
-
-      # Fast reduction modulo the secp256k1 prime.
-      #
-      # Exploits the structure P = 2^256 - 2^32 - 977 to avoid generic
-      # modular division. Two folding passes plus a conditional subtraction.
-      #
-      # @param x [Integer] non-negative integer
-      # @return [Integer] x mod P, in range [0, P)
-      def fred(x)
-        # First fold
-        hi = x >> 256
-        x = (x & MASK_256) + (hi << 32) + (hi * 977)
-
-        # Second fold (hi <= 2^32 + 977, so one more pass suffices)
-        hi = x >> 256
-        x = (x & MASK_256) + (hi << 32) + (hi * 977)
-
-        # Final conditional subtraction
-        x >= P ? x - P : x
-      end
-
-      # Modular multiplication in the field.
-      def fmul(a, b)
-        fred(a * b)
-      end
-
-      # Modular squaring in the field.
-      def fsqr(a)
-        fred(a * a)
-      end
-
-      # Modular addition in the field.
-      def fadd(a, b)
-        fred(a + b)
-      end
-
-      # Modular subtraction in the field.
-      def fsub(a, b)
-        a >= b ? a - b : P - (b - a)
-      end
-
-      # Modular negation in the field.
-      def fneg(a)
-        a.zero? ? 0 : P - a
-      end
-
-      # Modular multiplicative inverse in the field (Fermat's little theorem).
-      #
-      # @param a [Integer] value to invert (must be non-zero mod P)
-      # @return [Integer] a^(P-2) mod P
-      # @raise [ArgumentError] if a is zero mod P
-      def finv(a)
-        raise ArgumentError, 'field inverse is undefined for zero' if (a % P).zero?
-
-        a.pow(P - 2, P)
-      end
-
-      # Modular square root in the field.
-      #
-      # Uses the identity sqrt(a) = a^((P+1)/4) mod P, valid because
-      # P ≡ 3 (mod 4). Returns +nil+ if +a+ is not a quadratic residue.
-      #
-      # @param a [Integer]
-      # @return [Integer, nil] the square root, or nil if none exists
-      def fsqrt(a)
-        r = a.pow(P_PLUS1_DIV4, P)
-        fsqr(r) == (a % P) ? r : nil
-      end
-
-      # -------------------------------------------------------------------
-      # Scalar arithmetic (mod N)
-      # -------------------------------------------------------------------
-
-      # Reduce modulo the curve order.
-      def scalar_mod(a)
-        r = a % N
-        r += N if r.negative?
-        r
-      end
-
-      # Scalar multiplicative inverse (Fermat).
-      #
-      # @raise [ArgumentError] if a is zero mod N
-      def scalar_inv(a)
-        raise ArgumentError, 'scalar inverse is undefined for zero' if (a % N).zero?
-
-        a.pow(N - 2, N)
-      end
-
-      # Scalar multiplication mod N.
-      def scalar_mul(a, b)
-        (a * b) % N
-      end
-
-      # Scalar addition mod N.
-      def scalar_add(a, b)
-        (a + b) % N
-      end
-
-      # -------------------------------------------------------------------
-      # Jacobian point operations (internal)
-      #
-      # Points are represented as [X, Y, Z] arrays of Integers.
-      # The point at infinity is [0, 1, 0].
-      # -------------------------------------------------------------------
-
-      # @!visibility private
-      JP_INFINITY = [0, 1, 0].freeze
-
-      # Double a Jacobian point.
-      #
-      # Formula from hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-0.html
-      # (a=0 for secp256k1).
-      #
-      # @param p [Array(Integer, Integer, Integer)] Jacobian point [X, Y, Z]
-      # @return [Array(Integer, Integer, Integer)]
-      def jp_double(p)
-        x1, y1, z1 = p
-        return JP_INFINITY if y1.zero?
-
-        y1sq = fsqr(y1)
-        s = fmul(4, fmul(x1, y1sq))
-        m = fmul(3, fsqr(x1)) # a=0 for secp256k1
-        x3 = fsub(fsqr(m), fmul(2, s))
-        y3 = fsub(fmul(m, fsub(s, x3)), fmul(8, fsqr(y1sq)))
-        z3 = fmul(2, fmul(y1, z1))
-        [x3, y3, z3]
-      end
-
-      # Add two Jacobian points.
-      #
-      # @param p [Array] first Jacobian point
-      # @param q [Array] second Jacobian point
-      # @return [Array] resulting Jacobian point
-      def jp_add(p, q)
-        _px, _py, pz = p
-        _qx, _qy, qz = q
-        return q if pz.zero?
-        return p if qz.zero?
-
-        z1z1 = fsqr(pz)
-        z2z2 = fsqr(qz)
-        u1 = fmul(p[0], z2z2)
-        u2 = fmul(q[0], z1z1)
-        s1 = fmul(p[1], fmul(z2z2, qz))
-        s2 = fmul(q[1], fmul(z1z1, pz))
-
-        h = fsub(u2, u1)
-        r = fsub(s2, s1)
-
-        if h.zero?
-          return r.zero? ? jp_double(p) : JP_INFINITY
-        end
-
-        hh = fsqr(h)
-        hhh = fmul(h, hh)
-        v = fmul(u1, hh)
-
-        x3 = fsub(fsub(fsqr(r), hhh), fmul(2, v))
-        y3 = fsub(fmul(r, fsub(v, x3)), fmul(s1, hhh))
-        z3 = fmul(h, fmul(pz, qz))
-        [x3, y3, z3]
-      end
-
-      # Convert a Jacobian point to affine coordinates.
-      #
-      # @param jp [Array(Integer, Integer, Integer)]
-      # @return [Array(Integer, Integer)] affine [x, y], or nil for infinity
-      def jp_to_affine(jp)
-        _x, _y, z = jp
-        return nil if z.zero?
-
-        zinv = finv(z)
-        zinv2 = fsqr(zinv)
-        x = fmul(jp[0], zinv2)
-        y = fmul(jp[1], fmul(zinv2, zinv))
-        [x, y]
-      end
-
-      # -------------------------------------------------------------------
-      # Windowed-NAF scalar multiplication (variable-time, public scalars)
-      # -------------------------------------------------------------------
-
-      # @!visibility private
-      # Maximum number of entries kept in the wNAF precomputation cache.
-      # Bounds memory usage for long-running processes (e.g. servers).
-      WNAF_CACHE_MAX = 512
-
-      # @!visibility private
-      # Cache for precomputed wNAF tables, keyed by "window:x:y".
-      # Evicts oldest entry when the LRU limit is reached.
-      WNAF_TABLE_CACHE = {} # rubocop:disable Style/MutableConstant
-
-      # @!visibility private
-      # Multiply a point by a scalar using windowed-NAF.
-      #
-      # Variable-time algorithm — suitable only for public scalars (e.g.
-      # signature verification). Secret-scalar paths MUST use
-      # {scalar_multiply_ct} instead.
-      #
-      # Internal method — use {Point#mul} or {Point#mul_ct} instead.
-      # Exposed as a module function only so the nested Point class can
-      # call it; not part of the public API.
-      #
-      # @param k [Integer] the scalar (must be in [1, N))
-      # @param px [Integer] affine x-coordinate of the base point
-      # @param py [Integer] affine y-coordinate of the base point
-      # @param window [Integer] wNAF window size (default 5)
-      # @return [Array(Integer, Integer, Integer)] result as Jacobian point
-      def scalar_multiply_wnaf(k, px, py, window = 5)
-        return JP_INFINITY if k.zero?
-
-        cache_key = "#{window}:#{px.to_s(16)}:#{py.to_s(16)}"
-        tbl = WNAF_TABLE_CACHE[cache_key]
-
-        if tbl.nil?
-          # Evict the oldest entry when the cache is full (simple LRU).
-          WNAF_TABLE_CACHE.delete(WNAF_TABLE_CACHE.keys.first) if WNAF_TABLE_CACHE.size >= WNAF_CACHE_MAX
-
-          tbl_size = 1 << (window - 1) # e.g. w=5 -> 16 entries
-          tbl = Array.new(tbl_size)
-          tbl[0] = [px, py, 1]
-          two_p = jp_double(tbl[0])
-          1.upto(tbl_size - 1) do |i|
-            tbl[i] = jp_add(tbl[i - 1], two_p)
-          end
-          WNAF_TABLE_CACHE[cache_key] = tbl
-        end
-
-        # Build wNAF representation
-        w_big = 1 << window
-        w_half = w_big >> 1
-        wnaf = []
-        k_tmp = k
-        while k_tmp.positive?
-          if k_tmp.odd?
-            z = k_tmp & (w_big - 1)
-            z -= w_big if z > w_half
-            wnaf << z
-            k_tmp -= z
-          else
-            wnaf << 0
-          end
-          k_tmp >>= 1
-        end
-
-        # Accumulate from MSB to LSB
-        q = JP_INFINITY
-        (wnaf.length - 1).downto(0) do |i|
-          q = jp_double(q)
-          di = wnaf[i]
-          next if di.zero?
-
-          idx = di.abs >> 1
-          addend = di.positive? ? tbl[idx] : jp_neg(tbl[idx])
-          q = jp_add(q, addend)
-        end
-        q
-      end
-
-      # -------------------------------------------------------------------
-      # Montgomery ladder scalar multiplication (constant-time, secret scalars)
-      # -------------------------------------------------------------------
-
-      # @!visibility private
-      # Multiply a point by a scalar using the Montgomery ladder.
-      #
-      # Executes a fixed number of iterations (256) with one +jp_double+
-      # and one +jp_add+ per iteration regardless of the scalar value.
-      # Use this for ALL secret-scalar paths (key generation, signing,
-      # ECDH, BIP-32 derivation).
-      #
-      # *Best-effort constant-time in interpreted Ruby.* The branch on
-      # +bit+ selects which register receives each operation, and both
-      # operations always execute. However, Ruby's interpreter, GC, and
-      # the early-return branches in +jp_add+/+jp_double+ (for infinity
-      # edge cases) mean true constant-time execution is not achievable
-      # without native code. This matches the ts-sdk's TypeScript
-      # implementation, which has the same structural properties. For
-      # production deployments requiring side-channel resistance beyond
-      # what an interpreted language can offer, use a native secp256k1
-      # library (e.g. libsecp256k1 via FFI).
-      #
-      # Internal method — use {Point#mul_ct} instead. Not part of the
-      # public API.
-      #
-      # @param k [Integer] secret scalar (must be in [1, N))
-      # @param px [Integer] affine x-coordinate of the base point
-      # @param py [Integer] affine y-coordinate of the base point
-      # @return [Array(Integer, Integer, Integer)] result as Jacobian point
-      def scalar_multiply_ct(k, px, py)
-        return JP_INFINITY if k.zero?
-
-        # r0 accumulates the result; r1 = r0 + base_point at all times.
-        r0 = JP_INFINITY
-        r1 = [px, py, 1]
-
-        256.times do |i|
-          bit = (k >> (255 - i)) & 1
-          if bit.zero?
-            r1 = jp_add(r0, r1)
-            r0 = jp_double(r0)
-          else
-            r0 = jp_add(r0, r1)
-            r1 = jp_double(r1)
-          end
-        end
-
-        r0
-      end
-
-      # Negate a Jacobian point.
-      def jp_neg(p)
-        return p if p[2].zero?
-
-        [p[0], fneg(p[1]), p[2]]
-      end
-
-      # -------------------------------------------------------------------
-      # Point class
-      # -------------------------------------------------------------------
-
-      # An elliptic curve point on secp256k1.
-      #
-      # Stores affine coordinates (x, y) or represents the point at infinity.
-      # Scalar multiplication uses Jacobian coordinates internally with
-      # windowed-NAF for performance.
-      class Point
-        # @return [Integer, nil] x-coordinate (nil for infinity)
-        attr_reader :x
-
-        # @return [Integer, nil] y-coordinate (nil for infinity)
-        attr_reader :y
-
-        # @param x [Integer, nil] x-coordinate (nil for infinity)
-        # @param y [Integer, nil] y-coordinate (nil for infinity)
-        def initialize(x, y)
-          @x = x
-          @y = y
-        end
-
-        # The point at infinity (additive identity).
-        #
-        # @return [Point]
-        def self.infinity
-          new(nil, nil)
-        end
-
-        # The generator point G.
-        #
-        # @return [Point]
-        def self.generator
-          @generator ||= new(GX, GY)
-        end
-
-        # Deserialise a point from compressed (33 bytes) or uncompressed
-        # (65 bytes) SEC1 encoding.
-        #
-        # @param bytes [String] binary string
-        # @return [Point]
-        # @raise [ArgumentError] if the encoding is invalid or the point
-        #   is not on the curve
-        def self.from_bytes(bytes)
-          bytes = bytes.b if bytes.encoding != Encoding::BINARY
-          prefix = bytes.getbyte(0)
-
-          case prefix
-          when 0x04 # Uncompressed
-            raise ArgumentError, 'invalid uncompressed point length' unless bytes.length == 65
-
-            x = Secp256k1.bytes_to_int(bytes[1, 32])
-            y = Secp256k1.bytes_to_int(bytes[33, 32])
-            raise ArgumentError, 'x coordinate out of field range' if x >= P
-            raise ArgumentError, 'y coordinate out of field range' if y >= P
-
-            pt = new(x, y)
-            raise ArgumentError, 'point is not on the curve' unless pt.on_curve?
-
-            pt
-          when 0x02, 0x03 # Compressed
-            raise ArgumentError, 'invalid compressed point length' unless bytes.length == 33
-
-            x = Secp256k1.bytes_to_int(bytes[1, 32])
-            raise ArgumentError, 'x coordinate out of field range' if x >= P
-
-            y_squared = Secp256k1.fadd(Secp256k1.fmul(Secp256k1.fsqr(x), x), 7)
-            y = Secp256k1.fsqrt(y_squared)
-            raise ArgumentError, 'invalid point: x not on curve' if y.nil?
-
-            # Ensure y-parity matches prefix
-            y = Secp256k1.fneg(y) if (y.odd? ? 0x03 : 0x02) != prefix
-
-            new(x, y)
-          else
-            raise ArgumentError, "unknown point prefix: 0x#{prefix.to_s(16).rjust(2, '0')}"
-          end
-        end
-
-        # Whether this is the point at infinity.
-        #
-        # @return [Boolean]
-        def infinity?
-          @x.nil?
-        end
-
-        # Whether this point lies on the secp256k1 curve (y² = x³ + 7).
-        #
-        # @return [Boolean]
-        def on_curve?
-          return true if infinity?
-
-          lhs = Secp256k1.fsqr(@y)
-          rhs = Secp256k1.fadd(Secp256k1.fmul(Secp256k1.fsqr(@x), @x), 7)
-          lhs == rhs
-        end
-
-        # Serialise the point in SEC1 format.
-        #
-        # @param format [:compressed, :uncompressed]
-        # @return [String] binary string (33 or 65 bytes)
-        # @raise [RuntimeError] if the point is at infinity
-        def to_octet_string(format = :compressed)
-          raise 'cannot serialise point at infinity' if infinity?
-
-          case format
-          when :compressed
-            prefix = @y.odd? ? "\x03".b : "\x02".b
-            prefix + Secp256k1.int_to_bytes(@x, 32)
-          when :uncompressed
-            "\x04".b + Secp256k1.int_to_bytes(@x, 32) + Secp256k1.int_to_bytes(@y, 32)
-          else
-            raise ArgumentError, "unknown format: #{format}"
-          end
-        end
-
-        # Scalar multiplication: self * scalar (variable-time, wNAF).
-        #
-        # Suitable for public scalars only (e.g. signature verification).
-        # For secret-scalar paths use {#mul_ct}.
-        #
-        # @param scalar [Integer] the scalar multiplier
-        # @return [Point] the resulting point
-        def mul(scalar)
-          return self.class.infinity if scalar.zero? || infinity?
-
-          scalar %= N
-          return self.class.infinity if scalar.zero?
-
-          jp = Secp256k1.scalar_multiply_wnaf(scalar, @x, @y)
-          affine = Secp256k1.jp_to_affine(jp)
-          return self.class.infinity if affine.nil?
-
-          self.class.new(affine[0], affine[1])
-        end
-
-        # Constant-time scalar multiplication: self * scalar (Montgomery ladder).
-        #
-        # Processes all 256 bits unconditionally so execution time does not
-        # depend on the scalar value. Use this for secret-scalar paths:
-        # key generation, signing, and ECDH shared-secret derivation.
-        #
-        # @param scalar [Integer] the secret scalar multiplier
-        # @return [Point] the resulting point
-        def mul_ct(scalar)
-          return self.class.infinity if scalar.zero? || infinity?
-
-          scalar %= N
-          return self.class.infinity if scalar.zero?
-
-          jp = Secp256k1.scalar_multiply_ct(scalar, @x, @y)
-          affine = Secp256k1.jp_to_affine(jp)
-          return self.class.infinity if affine.nil?
-
-          self.class.new(affine[0], affine[1])
-        end
-
-        # Point addition: self + other.
-        #
-        # @param other [Point]
-        # @return [Point]
-        def add(other)
-          return other if infinity?
-          return self if other.infinity?
-
-          jp1 = [@x, @y, 1]
-          jp2 = [other.x, other.y, 1]
-          jp_result = Secp256k1.jp_add(jp1, jp2)
-          affine = Secp256k1.jp_to_affine(jp_result)
-          return self.class.infinity if affine.nil?
-
-          self.class.new(affine[0], affine[1])
-        end
-
-        # Point negation: -self.
-        #
-        # @return [Point]
-        def negate
-          return self if infinity?
-
-          self.class.new(@x, Secp256k1.fneg(@y))
-        end
-
-        # Equality comparison.
-        #
-        # @param other [Point]
-        # @return [Boolean]
-        def ==(other)
-          return false unless other.is_a?(Point)
-
-          if infinity? && other.infinity?
-            true
-          elsif infinity? || other.infinity?
-            false
-          else
-            @x == other.x && @y == other.y
-          end
-        end
-        alias eql? ==
-
-        def hash
-          infinity? ? 0 : [@x, @y].hash
-        end
-      end
-    end
+    # Backwards-compatibility alias: BSV::Primitives::Secp256k1 → ::Secp256k1
+    # This mapping will be removed in the next major version.
+    Secp256k1 = ::Secp256k1
   end
 end
-# rubocop:enable Naming/MethodParameterName, Metrics/ModuleLength

data/lib/bsv/primitives/signature.rb

@@ -59,7 +59,9 @@ module BSV
 
         # Parse S
         s_offset = 4 + r_len
+        raise ArgumentError, 'truncated: missing S tag' if s_offset >= bytes.length
         raise ArgumentError, 'invalid integer tag for S' unless bytes[s_offset] == 0x02
+        raise ArgumentError, 'truncated: missing S length' if s_offset + 1 >= bytes.length
 
         s_len = bytes[s_offset + 1]
         raise ArgumentError, 'S length overflows' if s_offset + 2 + s_len > bytes.length

data/lib/bsv/primitives/signed_message.rb

@@ -73,17 +73,18 @@ module BSV
         else
           # Specific recipient
           verifier_pub_bytes = sig.byteslice(37, 33)
-          verifier_pub_hex = verifier_pub_bytes.unpack1('H*')
 
           if recipient.nil?
             raise ArgumentError,
-                  "this signature can only be verified with knowledge of a specific private key. The associated public key is: #{verifier_pub_hex}"
+                  'this signature can only be verified with knowledge of a specific private key. ' \
+                  "The associated public key is: #{verifier_pub_bytes.unpack1('H*')}"
           end
 
-          recipient_pub_hex = recipient.public_key.compressed.unpack1('H*')
-          if verifier_pub_hex != recipient_pub_hex
+          recipient_pub_bytes = recipient.public_key.compressed
+          if verifier_pub_bytes != recipient_pub_bytes
             raise ArgumentError,
-                  "the recipient public key is #{recipient_pub_hex} but the signature requires the recipient to have public key #{verifier_pub_hex}"
+                  "the recipient public key is #{recipient_pub_bytes.unpack1('H*')} " \
+                  "but the signature requires the recipient to have public key #{verifier_pub_bytes.unpack1('H*')}"
           end
 
           key_id_offset = 70

data/lib/bsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BSV
-  VERSION = '0.14.0'
+  VERSION = '0.15.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: secp256k1-native
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.16'
 description: A Ruby library for interacting with the BSV Blockchain — keys, scripts,
   transactions, and more.
 executables:
@@ -142,6 +156,7 @@ files:
 - lib/bsv/script/opcodes.rb
 - lib/bsv/script/push_drop_template.rb
 - lib/bsv/script/script.rb
+- lib/bsv/secp256k1_native.bundle
 - lib/bsv/transaction.rb
 - lib/bsv/transaction/beef.rb
 - lib/bsv/transaction/chain_tracker.rb