@noble/curves 1.8.2 → 1.9.1

package/src/abstract/weierstrass.ts

@@ -7,9 +7,9 @@
  *
  * * a: formula param
  * * b: formula param
- * * Fp: finite Field over which we'll do calculations. Can be complex (Fp2, Fp12)
- * * n: Curve prime subgroup order, total count of valid points in the field
- * * Gx: Base point (x, y) aka generator point x coordinate
+ * * Fp: finite field of prime characteristic P; may be complex (Fp2). Arithmetics is done in field
+ * * n: order of prime subgroup a.k.a total amount of valid curve points
+ * * Gx: Base point (x, y) aka generator point. Gx = x coordinate
  * * Gy: ...y coordinate
  * * h: cofactor, usually 1. h*n = curve group order (n is only subgroup order)
  * * lowS: whether to enable (default) or disable "low-s" non-malleable signatures
@@ -40,25 +40,51 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 // prettier-ignore
 import {
-  type AffinePoint, type BasicCurve, type Group, type GroupConstructor,
   pippenger, validateBasic, wNAF,
+  type AffinePoint, type BasicCurve, type Group, type GroupConstructor
 } from './curve.ts';
 // prettier-ignore
 import {
-  Field, type IField, getMinHashLength, invert, mapHashToField, mod, validateField,
+  Field,
+  FpInvertBatch,
+  getMinHashLength, invert, mapHashToField, mod, validateField,
+  type IField
 } from './modular.ts';
 // prettier-ignore
 import {
-  type CHash, type Hex, type PrivKey,
   aInRange, abool,
   bitMask,
   bytesToHex, bytesToNumberBE, concatBytes, createHmacDrbg, ensureBytes, hexToBytes,
-  inRange, isBytes, memoized, numberToBytesBE, numberToHexUnpadded, validateObject
+  inRange, isBytes, memoized, numberToBytesBE, numberToHexUnpadded, validateObject,
+  type CHash, type Hex, type PrivKey
 } from './utils.ts';
 
 export type { AffinePoint };
 type HmacFnSync = (key: Uint8Array, ...messages: Uint8Array[]) => Uint8Array;
-type EndomorphismOpts = {
+/**
+ * When Weierstrass curve has `a=0`, it becomes Koblitz curve.
+ * Koblitz curves allow using **efficiently-computable GLV endomorphism ψ**.
+ * Endomorphism uses 2x less RAM, speeds up precomputation by 2x and ECDH / key recovery by 20%.
+ * For precomputed wNAF it trades off 1/2 init time & 1/3 ram for 20% perf hit.
+ *
+ * Endomorphism consists of beta, lambda and splitScalar:
+ *
+ * 1. GLV endomorphism ψ transforms a point: `P = (x, y) ↦ ψ(P) = (β·x mod p, y)`
+ * 2. GLV scalar decomposition transforms a scalar: `k ≡ k₁ + k₂·λ (mod n)`
+ * 3. Then these are combined: `k·P = k₁·P + k₂·ψ(P)`
+ * 4. Two 128-bit point-by-scalar multiplications + one point addition is faster than
+ *    one 256-bit multiplication.
+ *
+ * where
+ * * beta: β ∈ Fₚ with β³ = 1, β ≠ 1
+ * * lambda: λ ∈ Fₙ with λ³ = 1, λ ≠ 1
+ * * splitScalar decomposes k ↦ k₁, k₂, by using reduced basis vectors.
+ *   Gauss lattice reduction calculates them from initial basis vectors `(n, 0), (-λ, 0)`
+ *
+ * Check out `test/misc/endomorphism.js` and
+ * [gist](https://gist.github.com/paulmillr/eb670806793e84df628a7c434a873066).
+ */
+export type EndomorphismOpts = {
   beta: bigint;
   splitScalar: (k: bigint) => { k1neg: boolean; k1: bigint; k2neg: boolean; k2: bigint };
 };
@@ -70,7 +96,7 @@ export type BasicWCurve<T> = BasicCurve<T> & {
   // Optional params
   allowedPrivateKeyLengths?: readonly number[]; // for P521
   wrapPrivateKey?: boolean; // bls12-381 requires mod(n) instead of rejecting keys >= n
-  endo?: EndomorphismOpts; // Endomorphism options for Koblitz curves
+  endo?: EndomorphismOpts;
   // When a cofactor != 1, there can be an effective methods to:
   // 1. Determine whether a point is torsion-free
   isTorsionFree?: (c: ProjConstructor<T>, point: ProjPointType<T>) => boolean;
@@ -94,17 +120,16 @@ export interface ProjPointType<T> extends Group<ProjPointType<T>> {
   readonly pz: T;
   get x(): T;
   get y(): T;
-  multiply(scalar: bigint): ProjPointType<T>;
   toAffine(iz?: T): AffinePoint<T>;
-  isTorsionFree(): boolean;
-  clearCofactor(): ProjPointType<T>;
-  assertValidity(): void;
-  hasEvenY(): boolean;
-  toRawBytes(isCompressed?: boolean): Uint8Array;
   toHex(isCompressed?: boolean): string;
+  toRawBytes(isCompressed?: boolean): Uint8Array;
 
+  assertValidity(): void;
+  hasEvenY(): boolean;
   multiplyUnsafe(scalar: bigint): ProjPointType<T>;
   multiplyAndAddUnsafe(Q: ProjPointType<T>, a: bigint, b: bigint): ProjPointType<T> | undefined;
+  isTorsionFree(): boolean;
+  clearCofactor(): ProjPointType<T>;
   _setWindowSize(windowSize: number): void;
 }
 // Static methods for 3d XYZ points
@@ -136,26 +161,26 @@ function validatePointOpts<T>(curve: CurvePointsType<T>): CurvePointsTypeWithLen
       b: 'field',
     },
     {
+      allowInfinityPoint: 'boolean',
       allowedPrivateKeyLengths: 'array',
-      wrapPrivateKey: 'boolean',
-      isTorsionFree: 'function',
       clearCofactor: 'function',
-      allowInfinityPoint: 'boolean',
       fromBytes: 'function',
+      isTorsionFree: 'function',
       toBytes: 'function',
+      wrapPrivateKey: 'boolean',
     }
   );
   const { endo, Fp, a } = opts;
   if (endo) {
     if (!Fp.eql(a, Fp.ZERO)) {
-      throw new Error('invalid endomorphism, can only be defined for Koblitz curves that have a=0');
+      throw new Error('invalid endo: CURVE.a must be 0');
     }
     if (
       typeof endo !== 'object' ||
       typeof endo.beta !== 'bigint' ||
       typeof endo.splitScalar !== 'function'
     ) {
-      throw new Error('invalid endomorphism, expected beta: bigint and splitScalar: function');
+      throw new Error('invalid endo: expected "beta": bigint and "splitScalar": function');
     }
   }
   return Object.freeze({ ...opts } as const);
@@ -287,6 +312,10 @@ export const DER: IDER = {
   },
 };
 
+function numToSizedHex(num: bigint, size: number): string {
+  return bytesToHex(numberToBytesBE(num, size));
+}
+
 // Be friendly to bad ECMAScript parsers by not using bigint literals
 // prettier-ignore
 const _0n = BigInt(0), _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3), _4n = BigInt(4);
@@ -320,15 +349,25 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
   function weierstrassEquation(x: T): T {
     const { a, b } = CURVE;
     const x2 = Fp.sqr(x); // x * x
-    const x3 = Fp.mul(x2, x); // x2 * x
-    return Fp.add(Fp.add(x3, Fp.mul(x, a)), b); // x3 + a * x + b
+    const x3 = Fp.mul(x2, x); // x² * x
+    return Fp.add(Fp.add(x3, Fp.mul(x, a)), b); // x³ + a * x + b
   }
+
+  function isValidXY(x: T, y: T): boolean {
+    const left = Fp.sqr(y); // y²
+    const right = weierstrassEquation(x); // x³ + ax + b
+    return Fp.eql(left, right);
+  }
+
   // Validate whether the passed curve params are valid.
-  // We check if curve equation works for generator point.
-  // `assertValidity()` won't work: `isTorsionFree()` is not available at this point in bls12-381.
-  // ProjectivePoint class has not been initialized yet.
-  if (!Fp.eql(Fp.sqr(CURVE.Gy), weierstrassEquation(CURVE.Gx)))
-    throw new Error('bad generator point: equation left != right');
+  // Test 1: equation y² = x³ + ax + b should work for generator point.
+  if (!isValidXY(CURVE.Gx, CURVE.Gy)) throw new Error('bad curve params: generator point');
+
+  // Test 2: discriminant Δ part should be non-zero: 4a³ + 27b² != 0.
+  // Guarantees curve is genus-1, smooth (non-singular).
+  const _4a3 = Fp.mul(Fp.pow(CURVE.a, _3n), _4n);
+  const _27b2 = Fp.mul(Fp.sqr(CURVE.b), BigInt(27));
+  if (Fp.is0(Fp.add(_4a3, _27b2))) throw new Error('bad curve params: a or b');
 
   // Valid group elements reside in range 1..n-1
   function isWithinCurveOrder(num: bigint): boolean {
@@ -369,7 +408,7 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
 
   // Converts Projective point to affine (x, y) coordinates.
   // Can accept precomputed Z^-1 - for example, from invertBatch.
-  // (x, y, z) ∋ (x=x/z, y=y/z)
+  // (X, Y, Z) ∋ (x=X/Z, y=Y/Z)
   const toAffineMemo = memoized((p: Point, iz?: T): AffinePoint<T> => {
     const { px: x, py: y, pz: z } = p;
     // Fast-path for normalized points
@@ -399,28 +438,28 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
     const { x, y } = p.toAffine();
     // Check if x, y are valid field elements
     if (!Fp.isValid(x) || !Fp.isValid(y)) throw new Error('bad point: x or y not FE');
-    const left = Fp.sqr(y); // y²
-    const right = weierstrassEquation(x); // x³ + ax + b
-    if (!Fp.eql(left, right)) throw new Error('bad point: equation left != right');
+    if (!isValidXY(x, y)) throw new Error('bad point: equation left != right');
     if (!p.isTorsionFree()) throw new Error('bad point: not in prime-order subgroup');
     return true;
   });
 
   /**
-   * Projective Point works in 3d / projective (homogeneous) coordinates: (x, y, z) ∋ (x=x/z, y=y/z)
+   * Projective Point works in 3d / projective (homogeneous) coordinates: (X, Y, Z) ∋ (x=X/Z, y=Y/Z)
    * Default Point works in 2d / affine coordinates: (x, y)
    * We're doing calculations in projective, because its operations don't require costly inversion.
    */
   class Point implements ProjPointType<T> {
+    // base / generator point
     static readonly BASE = new Point(CURVE.Gx, CURVE.Gy, Fp.ONE);
-    static readonly ZERO = new Point(Fp.ZERO, Fp.ONE, Fp.ZERO);
+    // zero / infinity / identity point
+    static readonly ZERO = new Point(Fp.ZERO, Fp.ONE, Fp.ZERO); // 0, 1, 0
     readonly px: T;
     readonly py: T;
     readonly pz: T;
 
     constructor(px: T, py: T, pz: T) {
       if (px == null || !Fp.isValid(px)) throw new Error('x required');
-      if (py == null || !Fp.isValid(py)) throw new Error('y required');
+      if (py == null || !Fp.isValid(py) || Fp.is0(py)) throw new Error('y required');
       if (pz == null || !Fp.isValid(pz)) throw new Error('z required');
       this.px = px;
       this.py = py;
@@ -454,7 +493,10 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
      * Optimization: converts a list of projective points to a list of identical points with Z=1.
      */
     static normalizeZ(points: Point[]): Point[] {
-      const toInv = Fp.invertBatch(points.map((p) => p.pz));
+      const toInv = FpInvertBatch(
+        Fp,
+        points.map((p) => p.pz)
+      );
       return points.map((p, i) => p.toAffine(toInv[i])).map(Point.fromAffine);
     }
 
@@ -617,6 +659,7 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
     is0() {
       return this.equals(Point.ZERO);
     }
+
     private wNAF(n: bigint): { p: Point; f: Point } {
       return wnaf.wNAFCached(this, n, Point.normalizeZ);
     }
@@ -638,6 +681,7 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
         return wnaf.wNAFCachedUnsafe(this, sc, Point.normalizeZ);
 
       // Case c: endomorphism
+      /** See docs for {@link EndomorphismOpts} */
       let { k1neg, k1, k2neg, k2 } = endo.splitScalar(sc);
       let k1p = I;
       let k2p = I;
@@ -668,6 +712,7 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
       const { endo, n: N } = CURVE;
       aInRange('scalar', scalar, _1n, N);
       let point: Point, fake: Point; // Fake point is used to const-time mult
+      /** See docs for {@link EndomorphismOpts} */
       if (endo) {
         const { k1neg, k1, k2neg, k2 } = endo.splitScalar(scalar);
         let { p: k1p, f: f1p } = this.wNAF(k1);
@@ -732,9 +777,8 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
       return bytesToHex(this.toRawBytes(isCompressed));
     }
   }
-  const _bits = CURVE.nBitLength;
-  const wnaf = wNAF(Point, CURVE.endo ? Math.ceil(_bits / 2) : _bits);
-  // Validate if generator point is on curve
+  const { endo, nBitLength } = CURVE;
+  const wnaf = wNAF(Point, endo ? Math.ceil(nBitLength / 2) : nBitLength);
   return {
     CURVE,
     ProjectivePoint: Point as ProjConstructor<T>,
@@ -756,7 +800,6 @@ export interface SignatureType {
   recoverPublicKey(msgHash: Hex): ProjPointType<bigint>;
   toCompactRawBytes(): Uint8Array;
   toCompactHex(): string;
-  // DER-encoded
   toDERRawBytes(isCompressed?: boolean): Uint8Array;
   toDERHex(isCompressed?: boolean): string;
 }
@@ -827,7 +870,7 @@ export type CurveFn = {
  */
 export function weierstrass(curveDef: CurveType): CurveFn {
   const CURVE = validateOpts(curveDef) as ReturnType<typeof validateOpts>;
-  const { Fp, n: CURVE_ORDER } = CURVE;
+  const { Fp, n: CURVE_ORDER, nByteLength, nBitLength } = CURVE;
   const compressedLen = Fp.BYTES + 1; // e.g. 33 for 32
   const uncompressedLen = 2 * Fp.BYTES + 1; // e.g. 65 for 32
 
@@ -890,8 +933,6 @@ export function weierstrass(curveDef: CurveType): CurveFn {
       }
     },
   });
-  const numToNByteHex = (num: bigint): string =>
-    bytesToHex(numberToBytesBE(num, CURVE.nByteLength));
 
   function isBiggerThanHalfOrder(number: bigint) {
     const HALF = CURVE_ORDER >> _1n;
@@ -922,7 +963,7 @@ export function weierstrass(curveDef: CurveType): CurveFn {
 
     // pair (bytes of r, bytes of s)
     static fromCompact(hex: Hex) {
-      const l = CURVE.nByteLength;
+      const l = nByteLength;
       hex = ensureBytes('compactSignature', hex, l * 2);
       return new Signature(slcNum(hex, 0, l), slcNum(hex, l, 2 * l));
     }
@@ -951,7 +992,7 @@ export function weierstrass(curveDef: CurveType): CurveFn {
       const radj = rec === 2 || rec === 3 ? r + CURVE.n : r;
       if (radj >= Fp.ORDER) throw new Error('recovery id 2 or 3 invalid');
       const prefix = (rec & 1) === 0 ? '02' : '03';
-      const R = Point.fromHex(prefix + numToNByteHex(radj));
+      const R = Point.fromHex(prefix + numToSizedHex(radj, Fp.BYTES));
       const ir = invN(radj); // r^-1
       const u1 = modN(-h * ir); // -hr^-1
       const u2 = modN(s * ir); // sr^-1
@@ -975,7 +1016,7 @@ export function weierstrass(curveDef: CurveType): CurveFn {
       return hexToBytes(this.toDERHex());
     }
     toDERHex() {
-      return DER.hexFromSig({ r: this.r, s: this.s });
+      return DER.hexFromSig(this);
     }
 
     // padded bytes of r, then padded bytes of s
@@ -983,7 +1024,8 @@ export function weierstrass(curveDef: CurveType): CurveFn {
       return hexToBytes(this.toCompactHex());
     }
     toCompactHex() {
-      return numToNByteHex(this.r) + numToNByteHex(this.s);
+      const l = nByteLength;
+      return numToSizedHex(this.r, l) + numToSizedHex(this.s, l);
     }
   }
   type RecoveredSignature = Signature & { recovery: number };
@@ -1036,14 +1078,19 @@ export function weierstrass(curveDef: CurveType): CurveFn {
   /**
    * Quick and dirty check for item being public key. Does not validate hex, or being on-curve.
    */
-  function isProbPub(item: PrivKey | PubKey): boolean {
-    const arr = isBytes(item);
-    const str = typeof item === 'string';
-    const len = (arr || str) && (item as Hex).length;
-    if (arr) return len === compressedLen || len === uncompressedLen;
-    if (str) return len === 2 * compressedLen || len === 2 * uncompressedLen;
+  function isProbPub(item: PrivKey | PubKey): boolean | undefined {
+    if (typeof item === 'bigint') return false;
     if (item instanceof Point) return true;
-    return false;
+    const arr = ensureBytes('key', item);
+    const len = arr.length;
+    const fpl = Fp.BYTES;
+    const compLen = fpl + 1; // e.g. 33 for 32
+    const uncompLen = 2 * fpl + 1; // e.g. 65 for 32
+    if (CURVE.allowedPrivateKeyLengths || nByteLength === compLen) {
+      return undefined;
+    } else {
+      return len === compLen || len === uncompLen;
+    }
   }
 
   /**
@@ -1057,8 +1104,8 @@ export function weierstrass(curveDef: CurveType): CurveFn {
    * @returns shared public key
    */
   function getSharedSecret(privateA: PrivKey, publicB: Hex, isCompressed = true): Uint8Array {
-    if (isProbPub(privateA)) throw new Error('first arg must be private key');
-    if (!isProbPub(publicB)) throw new Error('second arg must be public key');
+    if (isProbPub(privateA) === true) throw new Error('first arg must be private key');
+    if (isProbPub(publicB) === false) throw new Error('second arg must be public key');
     const b = Point.fromHex(publicB); // check for being on-curve
     return b.multiply(normPrivateKeyToScalar(privateA)).toRawBytes(isCompressed);
   }
@@ -1070,12 +1117,12 @@ export function weierstrass(curveDef: CurveType): CurveFn {
   const bits2int =
     CURVE.bits2int ||
     function (bytes: Uint8Array): bigint {
-      // Our custom check "just in case"
+      // Our custom check "just in case", for protection against DoS
       if (bytes.length > 8192) throw new Error('input is too large');
       // For curves with nBitLength % 8 !== 0: bits2octets(bits2octets(m)) !== bits2octets(m)
       // for some cases, since bytes.length * 8 is not actual bitLength.
       const num = bytesToNumberBE(bytes); // check for == u8 done here
-      const delta = bytes.length * 8 - CURVE.nBitLength; // truncate to nBitLength leftmost bits
+      const delta = bytes.length * 8 - nBitLength; // truncate to nBitLength leftmost bits
       return delta > 0 ? num >> BigInt(delta) : num;
     };
   const bits2int_modN =
@@ -1084,14 +1131,14 @@ export function weierstrass(curveDef: CurveType): CurveFn {
       return modN(bits2int(bytes)); // can't use bytesToNumberBE here
     };
   // NOTE: pads output with zero as per spec
-  const ORDER_MASK = bitMask(CURVE.nBitLength);
+  const ORDER_MASK = bitMask(nBitLength);
   /**
    * Converts to bytes. Checks if num in `[0..ORDER_MASK-1]` e.g.: `[0..2^256-1]`.
    */
   function int2octets(num: bigint): Uint8Array {
-    aInRange('num < 2^' + CURVE.nBitLength, num, _0n, ORDER_MASK);
+    aInRange('num < 2^' + nBitLength, num, _0n, ORDER_MASK);
     // works with order, can have different size than numToField!
-    return numberToBytesBE(num, CURVE.nByteLength);
+    return numberToBytesBE(num, nByteLength);
   }
 
   // Steps A, D of RFC6979 3.2
@@ -1383,7 +1430,8 @@ export function mapToCurveSimpleSWU<T>(
     y = Fp.cmov(y, value, isValid); // 22.   y = CMOV(y, y1, is_gx1_square)
     const e1 = Fp.isOdd!(u) === Fp.isOdd!(y); // 23.  e1 = sgn0(u) == sgn0(y)
     y = Fp.cmov(Fp.neg(y), y, e1); // 24.   y = CMOV(-y, y, e1)
-    x = Fp.div(x, tv4); // 25.   x = x / tv4
+    const tv4_inv = FpInvertBatch(Fp, [tv4], true)[0];
+    x = Fp.mul(x, tv4_inv); // 25.   x = x / tv4
     return { x, y };
   };
 }

package/src/bls12-381.ts

@@ -28,12 +28,12 @@
  * 3. Curve security level is about 120 bits as per [Barbulescu-Duquesne 2017](https://hal.science/hal-01534101/file/main.pdf)
  * 4. Compatible with specs:
  *    [cfrg-pairing-friendly-curves-11](https://tools.ietf.org/html/draft-irtf-cfrg-pairing-friendly-curves-11),
- *    [cfrg-bls-signature-05](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-05),
+ *    [cfrg-bls-signature-05](https://www.rfc-editor.org/rfc/draft-irtf-cfrg-bls-signature-05),
  *    RFC 9380.
  *
  * ### Params
  * To verify curve parameters, see
- * [pairing-friendly-curves spec](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-pairing-friendly-curves-11).
+ * [pairing-friendly-curves spec](https://www.rfc-editor.org/rfc/draft-irtf-cfrg-pairing-friendly-curves-11).
  * Basic math is done over finite fields over p.
  * More complicated math is done over polynominal extension fields.
  * To simplify calculations in Fp12, we construct extension tower:
@@ -70,16 +70,16 @@ import {
   bytesToNumberBE,
   concatBytes as concatB,
   ensureBytes,
-  type Hex,
   numberToBytesBE,
+  type Hex,
 } from './abstract/utils.ts';
 // Types
 import { isogenyMap } from './abstract/hash-to-curve.ts';
 import type { Fp, Fp12, Fp2, Fp6 } from './abstract/tower.ts';
 import { psiFrobenius, tower12 } from './abstract/tower.ts';
 import {
-  type AffinePoint,
   mapToCurveSimpleSWU,
+  type AffinePoint,
   type ProjPointType,
 } from './abstract/weierstrass.ts';
 
@@ -337,8 +337,7 @@ const G1_SWU = mapToCurveSimpleSWU(Fp, {
   Z: Fp.create(BigInt(11)),
 });
 
-// Endomorphisms (for fast cofactor clearing)
-// Ψ(P) endomorphism
+// GLV endomorphism Ψ(P), for fast cofactor clearing
 const { G2psi, G2psi2 } = psiFrobenius(Fp, Fp2, Fp2.div(Fp2.ONE, Fp2.NONRESIDUE)); // 1/(u+1)
 
 // Default hash_to_field options are for hash to G2.
@@ -476,28 +475,15 @@ export const bls12_381: CurveFn = bls({
     // It returns false for shitty points.
     // https://eprint.iacr.org/2021/1130.pdf
     isTorsionFree: (c, point): boolean => {
-      // φ endomorphism
-      const cubicRootOfUnityModP = BigInt(
+      // GLV endomorphism ψ(P)
+      const beta = BigInt(
         '0x5f19672fdf76ce51ba69c6076a0f77eaddb3a93be6f89688de17d813620a00022e01fffffffefffe'
       );
-      const phi = new c(Fp.mul(point.px, cubicRootOfUnityModP), point.py, point.pz);
-
-      // todo: unroll
+      const phi = new c(Fp.mul(point.px, beta), point.py, point.pz);
+      // TODO: unroll
       const xP = point.multiplyUnsafe(BLS_X).negate(); // [x]P
       const u2P = xP.multiplyUnsafe(BLS_X); // [u2]P
       return u2P.equals(phi);
-
-      // https://eprint.iacr.org/2019/814.pdf
-      // (z² − 1)/3
-      // const c1 = BigInt('0x396c8c005555e1560000000055555555');
-      // const P = this;
-      // const S = P.sigma();
-      // const Q = S.double();
-      // const S2 = S.sigma();
-      // // [(z² − 1)/3](2σ(P) − P − σ²(P)) − σ²(P) = O
-      // const left = Q.subtract(P).subtract(S2).multiplyUnsafe(c1);
-      // const C = left.subtract(S2);
-      // return C.isZero();
     },
     // Clear cofactor of G1
     // https://eprint.iacr.org/2019/403
@@ -627,14 +613,12 @@ export const bls12_381: CurveFn = bls({
     // point.isTorsionFree() should return true for valid points
     // It returns false for shitty points.
     // https://eprint.iacr.org/2021/1130.pdf
+    // Older version: https://eprint.iacr.org/2019/814.pdf
     isTorsionFree: (c, P): boolean => {
       return P.multiplyUnsafe(BLS_X).negate().equals(G2psi(c, P)); // ψ(P) == [u](P)
-      // Older version: https://eprint.iacr.org/2019/814.pdf
-      // Ψ²(P) => Ψ³(P) => [z]Ψ³(P) where z = -x => [z]Ψ³(P) - Ψ²(P) + P == O
-      // return P.psi2().psi().mulNegX().subtract(psi2).add(P).isZero();
     },
     // Maps the point into the prime-order subgroup G2.
-    // clear_cofactor_bls12381_g2 from cfrg-hash-to-curve-11
+    // clear_cofactor_bls12381_g2 from RFC 9380.
     // https://eprint.iacr.org/2017/419.pdf
     // prettier-ignore
     clearCofactor: (c, P) => {

package/src/bn254.ts

@@ -13,6 +13,15 @@ There are huge compatibility issues in the ecosystem:
    https://github.com/scipr-lab/libff/blob/a44f482e18b8ac04d034c193bd9d7df7817ad73f/libff/algebra/curves/bn128/bn128_init.cpp#L166-L169
 3. halo2curves bn256 is also incompatible and returns different outputs
 
+We don't implement Point methods toHex / toRawBytes.
+To work around this limitation, has to initialize points on their own from BigInts.
+Reason it's not implemented is because [there is no standard](https://github.com/privacy-scaling-explorations/halo2curves/issues/109).
+Points of divergence:
+
+- Endianness: LE vs BE (byte-swapped)
+- Flags as first hex bits (similar to BLS) vs no-flags
+- Imaginary part last in G2 vs first (c0, c1 vs c1, c0)
+
 The goal of our implementation is to support "Ethereum" variant of the curve,
 because it at least has specs:
 
@@ -239,6 +248,7 @@ export const bn254: BLSCurveFn = bls({
  * bn254 weierstrass curve with ECDSA.
  * This is very rare and probably not used anywhere.
  * Instead, you should use G1 / G2, defined above.
+ * @deprecated
  */
 export const bn254_weierstrass: CurveFn = weierstrass({
   a: BigInt(0),

package/src/ed25519.ts

@@ -13,10 +13,11 @@ import { type CurveFn, type ExtPointType, twistedEdwards } from './abstract/edwa
 import {
   createHasher,
   expand_message_xmd,
+  type Hasher,
   type htfBasicOpts,
   type HTFMethod,
 } from './abstract/hash-to-curve.ts';
-import { Field, FpSqrtEven, isNegativeLE, mod, pow2 } from './abstract/modular.ts';
+import { Field, FpInvertBatch, FpSqrtEven, isNegativeLE, mod, pow2 } from './abstract/modular.ts';
 import { montgomery, type CurveFn as XCurveFn } from './abstract/montgomery.ts';
 import {
   bytesToHex,
@@ -178,10 +179,7 @@ export const ed25519ph: CurveFn = /* @__PURE__ */ (() =>
 export const x25519: XCurveFn = /* @__PURE__ */ (() =>
   montgomery({
     P: ED25519_P,
-    a: BigInt(486662),
-    montgomeryBits: 255, // n is 253 bits
-    nByteLength: 32,
-    Gu: BigInt(9),
+    type: 'x25519',
     powPminus2: (x: bigint): bigint => {
       const P = ED25519_P;
       // x^(p-2) aka x^(2^255-21)
@@ -289,12 +287,11 @@ function map_to_curve_elligator2_edwards25519(u: bigint) {
   xd = Fp.cmov(xd, Fp.ONE, e); //  10. xd = CMOV(xd, 1, e)
   yn = Fp.cmov(yn, Fp.ONE, e); //  11. yn = CMOV(yn, 1, e)
   yd = Fp.cmov(yd, Fp.ONE, e); //  12. yd = CMOV(yd, 1, e)
-
-  const inv = Fp.invertBatch([xd, yd]); // batch division
-  return { x: Fp.mul(xn, inv[0]), y: Fp.mul(yn, inv[1]) }; //  13. return (xn, xd, yn, yd)
+  const [xd_inv, yd_inv] = FpInvertBatch(Fp, [xd, yd], true); // batch division
+  return { x: Fp.mul(xn, xd_inv), y: Fp.mul(yn, yd_inv) }; //  13. return (xn, xd, yn, yd)
 }
 
-const htf = /* @__PURE__ */ (() =>
+export const ed25519_hasher: Hasher<bigint> = /* @__PURE__ */ (() =>
   createHasher(
     ed25519.ExtendedPoint,
     (scalars: bigint[]) => map_to_curve_elligator2_edwards25519(scalars[0]),
@@ -308,8 +305,9 @@ const htf = /* @__PURE__ */ (() =>
       hash: sha512,
     }
   ))();
-export const hashToCurve: HTFMethod<bigint> = /* @__PURE__ */ (() => htf.hashToCurve)();
-export const encodeToCurve: HTFMethod<bigint> = /* @__PURE__ */ (() => htf.encodeToCurve)();
+export const hashToCurve: HTFMethod<bigint> = /* @__PURE__ */ (() => ed25519_hasher.hashToCurve)();
+export const encodeToCurve: HTFMethod<bigint> = /* @__PURE__ */ (() =>
+  ed25519_hasher.encodeToCurve)();
 
 function aristp(other: unknown) {
   if (!(other instanceof RistPoint)) throw new Error('RistrettoPoint expected');
@@ -344,8 +342,11 @@ const bytes255ToNumberLE = (bytes: Uint8Array) =>
 
 type ExtendedPoint = ExtPointType;
 
-// Computes Elligator map for Ristretto
-// https://ristretto.group/formulas/elligator.html
+/**
+ * Computes Elligator map for Ristretto255.
+ * Described in [RFC9380](https://www.rfc-editor.org/rfc/rfc9380#appendix-B) and on
+ * the [website](https://ristretto.group/formulas/elligator.html).
+ */
 function calcElligatorRistrettoMap(r0: bigint): ExtendedPoint {
   const { d } = ed25519.CURVE;
   const P = ed25519.CURVE.Fp.ORDER;
@@ -373,7 +374,7 @@ function calcElligatorRistrettoMap(r0: bigint): ExtendedPoint {
  * a source of bugs for protocols like ring signatures. Ristretto was created to solve this.
  * Ristretto point operates in X:Y:Z:T extended coordinates like ExtendedPoint,
  * but it should work in its own namespace: do not combine those two.
- * https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-ristretto255-decaf448
+ * See [RFC9496](https://www.rfc-editor.org/rfc/rfc9496).
  */
 class RistPoint implements Group<RistPoint> {
   static BASE: RistPoint;
@@ -393,7 +394,8 @@ class RistPoint implements Group<RistPoint> {
    * Takes uniform output of 64-byte hash function like sha512 and converts it to `RistrettoPoint`.
    * The hash-to-group operation applies Elligator twice and adds the results.
    * **Note:** this is one-way map, there is no conversion from point to hash.
-   * https://ristretto.group/formulas/elligator.html
+   * Described in [RFC9380](https://www.rfc-editor.org/rfc/rfc9380#appendix-B) and on
+   * the [website](https://ristretto.group/formulas/elligator.html).
    * @param hex 64-byte output of a hash function
    */
   static hashToCurve(hex: Hex): RistPoint {
@@ -407,7 +409,7 @@ class RistPoint implements Group<RistPoint> {
 
   /**
    * Converts ristretto-encoded string to ristretto point.
-   * https://ristretto.group/formulas/decoding.html
+   * Described in [RFC9496](https://www.rfc-editor.org/rfc/rfc9496#name-decode).
    * @param hex Ristretto-encoded 32 bytes. Not every 32-byte string is valid ristretto encoding
    */
   static fromHex(hex: Hex): RistPoint {
@@ -444,7 +446,7 @@ class RistPoint implements Group<RistPoint> {
 
   /**
    * Encodes ristretto point to Uint8Array.
-   * https://ristretto.group/formulas/encoding.html
+   * Described in [RFC9496](https://www.rfc-editor.org/rfc/rfc9496#name-encode).
    */
   toRawBytes(): Uint8Array {
     let { ex: x, ey: y, ez: z, et: t } = this.ep;
@@ -482,7 +484,10 @@ class RistPoint implements Group<RistPoint> {
     return this.toHex();
   }
 
-  // Compare one point to another.
+  /**
+   * Compares two Ristretto points.
+   * Described in [RFC9496](https://www.rfc-editor.org/rfc/rfc9496#name-equals).
+   */
   equals(other: RistPoint): boolean {
     aristp(other);
     const { ex: X1, ey: Y1 } = this.ep;
@@ -520,13 +525,21 @@ class RistPoint implements Group<RistPoint> {
     return new RistPoint(this.ep.negate());
   }
 }
+
+/**
+ * Wrapper over Edwards Point for ristretto255 from
+ * [RFC9496](https://www.rfc-editor.org/rfc/rfc9496).
+ */
 export const RistrettoPoint: typeof RistPoint = /* @__PURE__ */ (() => {
   if (!RistPoint.BASE) RistPoint.BASE = new RistPoint(ed25519.ExtendedPoint.BASE);
   if (!RistPoint.ZERO) RistPoint.ZERO = new RistPoint(ed25519.ExtendedPoint.ZERO);
   return RistPoint;
 })();
 
-// Hashing to ristretto255. https://www.rfc-editor.org/rfc/rfc9380#appendix-B
+/**
+ * hash-to-curve for ristretto255.
+ * Described in [RFC9380](https://www.rfc-editor.org/rfc/rfc9380#appendix-B).
+ */
 export const hashToRistretto255 = (msg: Uint8Array, options: htfBasicOpts): RistPoint => {
   const d = options.DST;
   const DST = typeof d === 'string' ? utf8ToBytes(d) : d;