secp256k1-native 0.15.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3721e2220de6d65f6bda10fe26a47bd2eaa248ba5d645caf70a0e40901720268
+  data.tar.gz: e07a7c79de6e4055581fd4a009dd48c375f7deb722bd2a18f5b99e9c444341ef
+SHA512:
+  metadata.gz: a5b109ef38d0589630ac73eab3ff5b910e2592926fe949aea7c12c4b9285dc94242ebfb449075276666806c659c32e7366cd61e3f43bb3bbd6a12d848ec12330
+  data.tar.gz: 4298a51739c11a6a5d01231fcf9274f1bfcdd7a93518b2920c255b8361f10bdf25c5e0c85e2c080a11380c55f4382b6980cc7a90d0eaab6f2f06b518c64da91f

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [0.15.0] - 2026-04-27
+
+### Added
+
+- Pure-Ruby secp256k1 field, scalar, and point arithmetic
+- Native C extension for accelerated operations (~22× speedup)
+- Montgomery ladder with constant-time branchless cswap
+- wNAF scalar multiplication
+- Comprehensive test suite (303 examples):
+  - Wycheproof ECDSA vectors
+  - Field, scalar, and Jacobian compliance vectors
+  - Pure-Ruby vs native cross-validation

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Simon Bettison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+# secp256k1-native
+
+Pure native C secp256k1 implementation for Ruby (no libsecp256k1 dependency).
+
+Provides secp256k1 elliptic curve cryptography for Ruby — field arithmetic, scalar operations, Jacobian point arithmetic, and constant-time scalar multiplication — via an optional native C extension. The gem ships a pure-Ruby base layer that works out of the box on any Ruby 2.7+ platform, with the C extension as an optional accelerator (~22× speedup) that is silently skipped when unavailable.
+
+Used by the [bsv-ruby-sdk](https://github.com/sgbett/bsv-ruby-sdk) and suitable for any Ruby project requiring secp256k1 operations.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'secp256k1-native'
+```
+
+Or install directly:
+
+```bash
+gem install secp256k1-native
+```
+
+The gem installs and works without the native extension. To build the extension for maximum performance:
+
+```bash
+gem install secp256k1-native -- --with-extension
+# or from source:
+bundle exec rake compile
+```
+
+## Usage
+
+```ruby
+require 'secp256k1'
+
+# Generator point
+g = Secp256k1::Point.generator
+
+# Scalar multiplication (variable-time, for public scalars)
+scalar = 0xdeadbeef
+point = g.mul(scalar)
+puts point.x.to_s(16)
+
+# Constant-time scalar multiplication (for secret scalars)
+secret = 0xcafebabe
+pubkey = g.mul_ct(secret)
+
+# SEC1 encoding / decoding
+compressed = pubkey.to_octet_string(:compressed)    # 33 bytes
+uncompressed = pubkey.to_octet_string(:uncompressed) # 65 bytes
+decoded = Secp256k1::Point.from_bytes(compressed)
+
+# Field arithmetic
+a = Secp256k1::P - 1
+b = Secp256k1.fmul(a, a)      # modular multiplication
+c = Secp256k1.fadd(a, b)      # modular addition
+d = Secp256k1.finv(a)         # modular inverse (Fermat)
+
+# Scalar arithmetic (mod N)
+k = Secp256k1.scalar_inv(42)  # scalar inverse
+```
+
+## Architecture
+
+```
+secp256k1-native
+├── lib/secp256k1.rb           # Pure-Ruby module: field, scalar, point ops, wNAF, Montgomery ladder
+├── lib/secp256k1/version.rb
+└── ext/secp256k1_native/      # Optional C extension: accelerates field, scalar, Jacobian ops
+```
+
+### Pure-Ruby base layer
+
+`Secp256k1` is a pure Ruby module providing:
+
+- **Field arithmetic** over the secp256k1 prime (modular multiplication, squaring, inversion, square root)
+- **Scalar arithmetic** modulo the curve order N
+- **Jacobian point operations** (addition, doubling, negation) using projective coordinates for performance
+- **Windowed-NAF scalar multiplication** (window size 5) with precomputed table caching — variable-time, suitable for public scalars
+- **Montgomery ladder scalar multiplication** — constant-time at the algorithm level, suitable for secret scalars
+- **SEC 1 encoding** — compressed (33-byte) and uncompressed (65-byte) point serialisation
+
+### Native C extension (optional)
+
+`Secp256k1Native` is an optional C extension that replaces hot-path field, scalar, and Jacobian point operations with fixed-width C implementations. When compiled, `secp256k1.rb` automatically delegates to the extension at load time.
+
+The extension accelerates:
+
+- All field arithmetic (`fmul`, `fsqr`, `fadd`, `fsub`, `fneg`, `finv`, `fsqrt`, `fred`)
+- All scalar arithmetic (`scalar_mul`, `scalar_add`, `scalar_inv`, `scalar_mod`)
+- Jacobian point operations (`jp_double`, `jp_add`, `jp_neg`)
+- Montgomery ladder (`scalar_multiply_ct`) — fully branchless cswap in C
+
+The wNAF loop and ECDSA/Schnorr logic remain in Ruby, calling native primitives per step.
+
+### Performance
+
+| Mode | Operations/sec (scalar multiplication) |
+|---|---|
+| Pure Ruby | ~100 |
+| Native C extension | ~2,277 |
+
+The extension provides approximately 22× speedup for scalar multiplication — the dominant cost in signing, public key derivation, and Schnorr proof generation.
+
+## Building the native extension
+
+Requirements:
+
+- C99 compiler with `__uint128_t` support (GCC or Clang on macOS and Linux)
+- Ruby development headers (included with RVM builds)
+- **Not supported** on MSVC (Windows) — falls back to pure Ruby automatically
+
+```bash
+bundle exec rake compile
+```
+
+The compiled bundle is placed at `lib/secp256k1_native.bundle` (macOS) or `lib/secp256k1_native.so` (Linux).
+
+`extconf.rb` checks for `__uint128_t` availability at configure time. If the type is absent, a no-op Makefile is generated and the extension is silently skipped. At runtime, `secp256k1.rb` wraps the `require` in a `rescue LoadError` — if the bundle is absent, the pure-Ruby implementation is used without any error.
+
+## Running tests
+
+```bash
+bundle exec rspec
+```
+
+The test suite has 303 examples covering:
+
+- Wycheproof ECDSA compliance vectors
+- Field, scalar, and Jacobian compliance vectors
+- Pure-Ruby vs native cross-validation (ensures both implementations agree on every operation)
+
+## Ruby version compatibility
+
+Ruby 2.7 and above. No Ruby 3.0+ features are used.
+
+## Licence
+
+MIT License. See [LICENSE](LICENSE).

data/ext/secp256k1_native/extconf.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+
+# Check for __uint128_t support — required for efficient 256-bit arithmetic.
+# If unavailable (e.g. MSVC), create a dummy Makefile that builds nothing so
+# the gem still installs cleanly and falls back to pure-Ruby arithmetic.
+unless have_type('__uint128_t')
+  File.write('Makefile', <<~MAKEFILE)
+    all:
+    \t@echo "Skipping native extension: __uint128_t not available"
+    install:
+    clean:
+  MAKEFILE
+  return
+end
+
+$CFLAGS += ' -O2 -Wall -std=c99'
+
+# Auto-detect all .c files in this directory so additional source files
+# (field.c, scalar.c, jacobian.c) are compiled automatically in later tasks.
+$srcs = Dir.glob("#{$srcdir}/*.c").map { |f| File.basename(f) }
+
+create_makefile('secp256k1_native')