@pbnjam/bandersnatch 0.7.2-rc0 → 0.7.2-rc2

package/.github/workflows/docs.yml

@@ -32,8 +32,6 @@ jobs:
       - name: Install dependencies
         run: |
           bun install
-          # Ensure TypeDoc can find all dependencies
-          bun install --frozen-lockfile || bun install
 
       - name: Generate documentation
         run: bun run docs

package/LICENSE

@@ -201,3 +201,6 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 
+
+
+

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@pbnjam/bandersnatch",
-  "version": "0.7.2-rc0",
+  "version": "0.7.2-rc2",
   "description": "Bandersnatch elliptic curve implementation",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Esscrypt/bandersnatch.git"
+    "url": "git+https://github.com/Esscrypt/bandersnatch.git"
   },
   "homepage": "https://github.com/Esscrypt/bandersnatch",
   "bugs": {
@@ -19,13 +19,13 @@
     "docs": "npx typedoc --out docs --entryPoints src/index.ts --entryPointStrategy expand --readme none --name '@pbnjam/bandersnatch' --includeVersion --tsconfig tsconfig.typedoc.json"
   },
   "dependencies": {
-    "@noble/curves": "^2.0.1",
-    "@noble/hashes": "^2.0.1"
+    "@noble/curves": "2.0.1",
+    "@noble/hashes": "2.0.1"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.1",
+    "@types/bun": "1.3.5",
     "@types/node": "^22.0.0",
-    "bun-types": "^1.3.1",
+    "bun-types": "1.3.5",
     "typescript": "5.9.3",
     "typedoc": "0.28.15"
   },

package/src/curve.ts

@@ -43,12 +43,12 @@ export const Bandersnatch = edwards(BANDERSNATCH_CURVE)
 
 /**
  * Bandersnatch curve operations using @noble/curves.
- * 
+ *
  * This class provides a high-level interface for working with points on the
  * Bandersnatch elliptic curve. It implements all standard elliptic curve operations
  * including point addition, scalar multiplication, and point compression/decompression
  * compatible with arkworks serialization format.
- * 
+ *
  * The Bandersnatch curve is a Twisted Edwards curve defined over the BLS12-381 scalar field,
  * designed for efficient cryptographic operations in the JAM protocol.
  */
@@ -92,22 +92,28 @@ export class BandersnatchCurve {
 
   /**
    * Decompresses arkworks-compatible point bytes to a Noble EdwardsPoint.
-   * 
+   *
    * This is the inverse operation of `pointToBytes`. It handles arkworks sign bit logic
    * to reconstruct the full point from compressed bytes. The method:
    * 1. Extracts the y-coordinate from the first 31 bytes (little-endian)
    * 2. Extracts the x-coordinate sign from bit 7 of the last byte
    * 3. Computes the x-coordinate from y using the curve equation
-   * 4. Validates the point is in the prime subgroup G
+   * 4. Optionally validates the point is in the prime subgroup G
    *
    * @param bytes - Compressed point bytes in arkworks format (32 bytes)
+   * @param validateSubgroup - Whether to validate point is in prime subgroup (default: true)
+   *                           Set to false for faster validation when only checking if bytes
+   *                           represent a valid curve point (e.g., for padding point replacement)
    * @returns Decompressed Noble EdwardsPoint
    * @throws {Error} If the byte array length is not 32
    * @throws {Error} If the y-coordinate exceeds the field modulus
    * @throws {Error} If the point is not on the curve (no square root exists)
-   * @throws {Error} If the point is not in the prime subgroup G
+   * @throws {Error} If validatePointOnCurve is true and point is not on the curve
    */
-  static bytesToPoint(bytes: Uint8Array): EdwardsPoint {
+  static bytesToPoint(
+    bytes: Uint8Array,
+    validatePointOnCurve = true,
+  ): EdwardsPoint {
     if (bytes.length !== 32) {
       throw new Error(
         `Invalid compressed point length: ${bytes.length}, expected 32`,
@@ -167,25 +173,27 @@ export class BandersnatchCurve {
     // Create Noble point from affine coordinates
     const point = Bandersnatch.fromAffine({ x: finalX, y })
 
-    // Validate point is in prime subgroup as required by bandersnatch-vrf-spec section 2.1:
+    // Optionally validate point is in prime subgroup as required by bandersnatch-vrf-spec section 2.1:
     // "This function MUST outputs 'INVALID' if the octet-string does not decode
     // to a point on the prime subgroup G"
     // A point is in the prime subgroup if and only if multiplying by the curve order
     // gives the identity point (infinity)
     // Since @noble/curves requires 1 <= scalar < curve.n, we use CURVE_ORDER - 1
     // and then add the point once more: point * CURVE_ORDER = point * (CURVE_ORDER - 1) + point
-    const curveOrderMinusOne = BANDERSNATCH_PARAMS.CURVE_ORDER - 1n
-    const pointTimesOrderMinusOne = this.scalarMultiply(
-      point,
-      curveOrderMinusOne,
-    )
-    const pointTimesOrder = this.add(pointTimesOrderMinusOne, point)
-    const isInPrimeSubgroup = pointTimesOrder.equals(Bandersnatch.ZERO)
-
-    if (!isInPrimeSubgroup) {
-      throw new Error(
-        'Point is not in prime subgroup: decoded point is not in G',
+    if (validatePointOnCurve) {
+      const curveOrderMinusOne = BANDERSNATCH_PARAMS.CURVE_ORDER - 1n
+      const pointTimesOrderMinusOne = this.scalarMultiply(
+        point,
+        curveOrderMinusOne,
       )
+      const pointTimesOrder = this.add(pointTimesOrderMinusOne, point)
+      const isInPrimeSubgroup = pointTimesOrder.equals(Bandersnatch.ZERO)
+
+      if (!isInPrimeSubgroup) {
+        throw new Error(
+          'Point is not in prime subgroup: decoded point is not in G',
+        )
+      }
     }
 
     return point
@@ -193,12 +201,12 @@ export class BandersnatchCurve {
 
   /**
    * Performs scalar multiplication on a curve point.
-   * 
+   *
    * Computes `scalar * point` on the Bandersnatch curve. Handles edge cases including:
    * - Scalar 0: returns the identity point (infinity)
    * - Negative scalars: negates the point and uses positive scalar
    * - Scalars >= curve order: reduces modulo curve order
-   * 
+   *
    * @param point - The curve point to multiply
    * @param scalar - The scalar multiplier (can be negative or >= curve order)
    * @returns The result of scalar multiplication: `scalar * point`
@@ -234,10 +242,10 @@ export class BandersnatchCurve {
 
   /**
    * Adds two curve points together.
-   * 
+   *
    * Performs point addition on the Bandersnatch curve: `P + Q`.
    * This operation is commutative: `add(P, Q) === add(Q, P)`.
-   * 
+   *
    * @param p1 - First curve point
    * @param p2 - Second curve point
    * @returns The sum of the two points: `p1 + p2`
@@ -249,10 +257,10 @@ export class BandersnatchCurve {
 
   /**
    * Doubles a curve point.
-   * 
+   *
    * Computes `2 * point` on the Bandersnatch curve. This is equivalent to
    * `add(point, point)` but is typically more efficient.
-   * 
+   *
    * @param point - The curve point to double
    * @returns The doubled point: `2 * point`
    * @throws {Error} If the point is invalid or not on the curve
@@ -263,10 +271,10 @@ export class BandersnatchCurve {
 
   /**
    * Negates a curve point.
-   * 
+   *
    * Computes the additive inverse of a point on the Bandersnatch curve.
    * The result satisfies: `add(point, negate(point)) === INFINITY`.
-   * 
+   *
    * @param point - The curve point to negate
    * @returns The negated point: `-point`
    * @throws {Error} If the point is invalid or not on the curve
@@ -277,10 +285,10 @@ export class BandersnatchCurve {
 
   /**
    * Checks if a point lies on the Bandersnatch curve.
-   * 
+   *
    * Validates that the point satisfies the Twisted Edwards curve equation:
    * `a*x^2 + y^2 = 1 + d*x^2*y^2` where `a = -5` and `d` is the curve parameter.
-   * 
+   *
    * @param point - The curve point to validate
    * @returns `true` if the point is on the curve, `false` otherwise
    */
@@ -290,10 +298,10 @@ export class BandersnatchCurve {
 
   /**
    * Gets the generator point (base point) of the Bandersnatch curve.
-   * 
+   *
    * The generator is a point on the curve that generates the prime subgroup G.
    * All points in the prime subgroup can be expressed as scalar multiples of the generator.
-   * 
+   *
    * @returns The generator point G
    */
   static get GENERATOR() {
@@ -302,10 +310,10 @@ export class BandersnatchCurve {
 
   /**
    * Gets the identity point (point at infinity) of the Bandersnatch curve.
-   * 
+   *
    * The identity point is the neutral element for point addition:
    * `add(point, INFINITY) === point` for any point on the curve.
-   * 
+   *
    * @returns The identity point (point at infinity)
    */
   static get INFINITY() {
@@ -314,11 +322,11 @@ export class BandersnatchCurve {
 
   /**
    * Converts a curve point to its byte representation.
-   * 
+   *
    * Serializes the point to bytes, typically used for challenge generation
    * in cryptographic protocols. The output format matches the point compression
    * format used by the curve implementation.
-   * 
+   *
    * @param point - The curve point to hash
    * @returns Byte representation of the point
    * @throws {Error} If the point is invalid
@@ -329,10 +337,10 @@ export class BandersnatchCurve {
 
   /**
    * Gets the order (cardinality) of the prime subgroup of the Bandersnatch curve.
-   * 
+   *
    * The curve order is the number of points in the prime subgroup G.
    * For any point P in G, `scalarMultiply(P, CURVE_ORDER) === INFINITY`.
-   * 
+   *
    * @returns The curve order as a bigint
    */
   static get CURVE_ORDER() {

package/src/index.ts

@@ -5,16 +5,16 @@
  * with all necessary operations for cryptographic applications.
  */
 
-// Export types
-export type { CurvePoint } from './types'
 // Export curve parameters
 export { BANDERSNATCH_PARAMS } from './config'
 // Elligator2 hash-to-curve is now available in bandersnatch-vrf package
 // Export curve implementations
 // Temporary alias for legacy compatibility
 export {
-  BandersnatchCurve,
   Bandersnatch,
+  BandersnatchCurve,
 } from './curve'
 // VRF functionality moved to bandersnatch-vrf package
-export * from './math'
+export * from './math'
+// Export types
+export type { CurvePoint } from './types'

package/src/math.ts

@@ -10,10 +10,10 @@ import {
 
 /**
  * Computes the non-negative modular reduction.
- * 
+ *
  * Returns `a mod m` where the result is always non-negative (0 <= result < m).
  * This handles negative inputs correctly by adding the modulus to negative results.
- * 
+ *
  * @param a - The value to reduce
  * @param m - The modulus
  * @returns Non-negative result of `a mod m`
@@ -25,10 +25,10 @@ export function mod(a: bigint, m: bigint): bigint {
 
 /**
  * Computes the modular inverse using the extended Euclidean algorithm.
- * 
+ *
  * Finds the value `x` such that `(a * x) mod m = 1`. The modular inverse exists
  * if and only if `gcd(a, m) = 1`.
- * 
+ *
  * @param a - The value to find the inverse of
  * @param m - The modulus
  * @returns The modular inverse of `a` modulo `m`
@@ -53,10 +53,10 @@ export function modInverse(a: bigint, m: bigint): bigint {
 
 /**
  * Computes the modular square root using the noble package FpSqrt.
- * 
+ *
  * Finds a value `x` such that `x^2 mod p = value`. The square root exists
  * if and only if `value` is a quadratic residue modulo `p`.
- * 
+ *
  * @param value - The value to find the square root of
  * @param p - The prime modulus
  * @param field - The field implementation from @noble/curves
@@ -81,11 +81,10 @@ export function modSqrt(
 }
 
 export function numberToBytesLittleEndian(value: bigint): Uint8Array {
-    const bytes = new Uint8Array(32)
-    const hex = value.toString(16).padStart(64, '0')
-    for (let i = 0; i < 32; i++) {
-      bytes[i] = Number.parseInt(hex.slice(62 - i * 2, 64 - i * 2), 16)
-    }
-    return bytes
+  const bytes = new Uint8Array(32)
+  const hex = value.toString(16).padStart(64, '0')
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = Number.parseInt(hex.slice(62 - i * 2, 64 - i * 2), 16)
   }
-  
+  return bytes
+}

package/src/types.ts

@@ -4,11 +4,11 @@
 
 /**
  * Represents a point on an elliptic curve.
- * 
+ *
  * This interface defines the structure for curve points used in Bandersnatch
  * curve operations. Points can be either finite points with (x, y) coordinates
  * or the point at infinity.
- * 
+ *
  * @interface CurvePoint
  */
 export interface CurvePoint {
@@ -19,4 +19,3 @@ export interface CurvePoint {
   /** Whether this point is the point at infinity (identity element) */
   isInfinity: boolean
 }
-