@noble/curves 2.0.0-beta.1 → 2.0.0-beta.3

package/src/abstract/weierstrass.ts

@@ -28,7 +28,6 @@
 import { hmac as nobleHmac } from '@noble/hashes/hmac.js';
 import { ahash } from '@noble/hashes/utils.js';
 import {
-  _validateObject,
   abool,
   abytes,
   aInRange,
@@ -42,12 +41,14 @@ import {
   isBytes,
   memoized,
   numberToHexUnpadded,
+  validateObject,
   randomBytes as wcRandomBytes,
   type CHash,
   type Signer,
 } from '../utils.ts';
 import {
-  _createCurveFields,
+  createCurveFields,
+  createKeygen,
   mulEndoUnsafe,
   negateCt,
   normalizeZ,
@@ -66,7 +67,6 @@ import {
 } from './modular.ts';
 
 export type { AffinePoint };
-export type HmacFnSync = (key: Uint8Array, ...messages: Uint8Array[]) => Uint8Array;
 
 type EndoBasis = [[bigint, bigint], [bigint, bigint]];
 /**
@@ -129,26 +129,71 @@ export function _splitEndoScalar(k: bigint, basis: EndoBasis, n: bigint): Scalar
   return { k1neg, k1, k2neg, k2 };
 }
 
-export type ECDSASigFormat = 'compact' | 'recovered' | 'der';
+/**
+ * Option to enable hedged signatures with improved security.
+ *
+ * * Randomly generated k is bad, because broken CSPRNG would leak private keys.
+ * * Deterministic k (RFC6979) is better; but is suspectible to fault attacks.
+ *
+ * We allow using technique described in RFC6979 3.6: additional k', a.k.a. adding randomness
+ * to deterministic sig. If CSPRNG is broken & randomness is weak, it would STILL be as secure
+ * as ordinary sig without ExtraEntropy.
+ *
+ * * `true` means "fetch data, from CSPRNG, incorporate it into k generation"
+ * * `false` means "disable extra entropy, use purely deterministic k"
+ * * `Uint8Array` passed means "incorporate following data into k generation"
+ *
+ * https://paulmillr.com/posts/deterministic-signatures/
+ */
+export type ECDSAExtraEntropy = boolean | Uint8Array;
+/**
+ * - `compact` is the default format
+ * - `recovered` is the same as compact, but with an extra byte indicating recovery byte
+ * - `der` is ASN.1 DER encoding
+ */
+export type ECDSASignatureFormat = 'compact' | 'recovered' | 'der';
+/**
+ * - `prehash`: (default: true) indicates whether to do sha256(message).
+ *   When a custom hash is used, it must be set to `false`.
+ */
 export type ECDSARecoverOpts = {
   prehash?: boolean;
 };
+/**
+ * - `prehash`: (default: true) indicates whether to do sha256(message).
+ *   When a custom hash is used, it must be set to `false`.
+ * - `lowS`: (default: true) prohibits signatures which have (sig.s >= CURVE.n/2n).
+ *   Compatible with BTC/ETH. Setting `lowS: false` allows to create malleable signatures,
+ *   which is default openssl behavior.
+ *   Non-malleable signatures can still be successfully verified in openssl.
+ * - `format`: (default: 'compact') 'compact' or 'recovered' with recovery byte
+ */
 export type ECDSAVerifyOpts = {
   prehash?: boolean;
   lowS?: boolean;
-  format?: ECDSASigFormat;
+  format?: ECDSASignatureFormat;
 };
+/**
+ * - `prehash`: (default: true) indicates whether to do sha256(message).
+ *   When a custom hash is used, it must be set to `false`.
+ * - `lowS`: (default: true) prohibits signatures which have (sig.s >= CURVE.n/2n).
+ *   Compatible with BTC/ETH. Setting `lowS: false` allows to create malleable signatures,
+ *   which is default openssl behavior.
+ *   Non-malleable signatures can still be successfully verified in openssl.
+ * - `format`: (default: 'compact') 'compact' or 'recovered' with recovery byte
+ * - `extraEntropy`: (default: false) creates sigs with increased security, see {@link ECDSAExtraEntropy}
+ */
 export type ECDSASignOpts = {
   prehash?: boolean;
   lowS?: boolean;
-  format?: ECDSASigFormat;
-  extraEntropy?: Uint8Array | boolean;
+  format?: ECDSASignatureFormat;
+  extraEntropy?: ECDSAExtraEntropy;
 };
 
-function validateSigFormat(format: string): ECDSASigFormat {
+function validateSigFormat(format: string): ECDSASignatureFormat {
   if (!['compact', 'recovered', 'der'].includes(format))
     throw new Error('Signature format must be "compact", "recovered", or "der"');
-  return format as ECDSASigFormat;
+  return format as ECDSASignatureFormat;
 }
 
 function validateSigOpts<T extends ECDSASignOpts, D extends Required<ECDSASignOpts>>(
@@ -214,7 +259,6 @@ export type WeierstrassOpts<T> = Readonly<{
 // When a cofactor != 1, there can be an effective methods to:
 // 1. Determine whether a point is torsion-free
 // 2. Clear torsion component
-// wrapPrivateKey: bls12-381 requires mod(n) instead of rejecting keys >= n
 export type WeierstrassExtraOpts<T> = Partial<{
   Fp: IField<T>;
   Fn: IField<bigint>;
@@ -240,7 +284,7 @@ export type WeierstrassExtraOpts<T> = Partial<{
  */
 export type ECDSAOpts = Partial<{
   lowS: boolean;
-  hmac: HmacFnSync;
+  hmac: (key: Uint8Array, message: Uint8Array) => Uint8Array;
   randomBytes: (bytesLength?: number) => Uint8Array;
   bits2int: (bytes: Uint8Array) => bigint;
   bits2int_modN: (bytes: Uint8Array) => bigint;
@@ -407,29 +451,31 @@ const _0n = BigInt(0), _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3), _4n =
 /**
  * Creates weierstrass Point constructor, based on specified curve options.
  *
+ * See {@link WeierstrassOpts}.
+ *
  * @example
 ```js
 const opts = {
-  p: BigInt('0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff'),
-  n: BigInt('0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551'),
-  h: BigInt(1),
-  a: BigInt('0xffffffff00000001000000000000000000000000fffffffffffffffffffffffc'),
-  b: BigInt('0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604b'),
-  Gx: BigInt('0x6b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c296'),
-  Gy: BigInt('0x4fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5'),
+  p: 0xfffffffffffffffffffffffffffffffeffffac73n,
+  n: 0x100000000000000000001b8fa16dfab9aca16b6b3n,
+  h: 1n,
+  a: 0n,
+  b: 7n,
+  Gx: 0x3b4c382ce37aa192a4019e763036f4f5dd4d7ebbn,
+  Gy: 0x938cf935318fdced6bc28286531733c3f03c4feen,
 };
-const p256_Point = weierstrass(opts);
+const secp160k1_Point = weierstrass(opts);
 ```
  */
 export function weierstrass<T>(
   params: WeierstrassOpts<T>,
   extraOpts: WeierstrassExtraOpts<T> = {}
 ): WeierstrassPointCons<T> {
-  const validated = _createCurveFields('weierstrass', params, extraOpts);
+  const validated = createCurveFields('weierstrass', params, extraOpts);
   const { Fp, Fn } = validated;
   let CURVE = validated.CURVE as WeierstrassOpts<T>;
   const { h: cofactor, n: CURVE_ORDER } = CURVE;
-  _validateObject(
+  validateObject(
     extraOpts,
     {},
     {
@@ -439,7 +485,6 @@ export function weierstrass<T>(
       fromBytes: 'function',
       toBytes: 'function',
       endo: 'object',
-      wrapPrivateKey: 'boolean',
     }
   );
 
@@ -493,9 +538,9 @@ export function weierstrass<T>(
         throw new Error('bad point: is not on curve, sqrt error' + err);
       }
       assertCompressionIsSupported();
-      const isYOdd = Fp.isOdd!(y); // (y & _1n) === _1n;
-      const isHeadOdd = (head & 1) === 1; // ECDSA-specific
-      if (isHeadOdd !== isYOdd) y = Fp.neg(y);
+      const evenY = Fp.isOdd!(y);
+      const evenH = (head & 1) === 1; // ECDSA-specific
+      if (evenH !== evenY) y = Fp.neg(y);
       return { x, y };
     } else if (length === uncomp && head === 0x04) {
       // TODO: more checks
@@ -544,7 +589,7 @@ export function weierstrass<T>(
   }
 
   function aprjpoint(other: unknown) {
-    if (!(other instanceof Point)) throw new Error('ProjectivePoint expected');
+    if (!(other instanceof Point)) throw new Error('Weierstrass Point expected');
   }
 
   function splitEndoScalarN(k: bigint) {
@@ -844,9 +889,11 @@ export function weierstrass<T>(
       const { endo } = extraOpts;
       const p = this as Point;
       if (!Fn.isValid(sc)) throw new Error('invalid scalar: out of range'); // 0 is valid
-      if (sc === _0n || p.is0()) return Point.ZERO;
-      if (sc === _1n) return p; // fast-path
-      if (wnaf.hasCache(this)) return this.multiply(sc);
+      if (sc === _0n || p.is0()) return Point.ZERO; // 0
+      if (sc === _1n) return p; // 1
+      if (wnaf.hasCache(this)) return this.multiply(sc); // precomputes
+      // We don't have method for double scalar multiplication (aP + bQ):
+      // Even with using Strauss-Shamir trick, it's 35% slower than naïve mul+add.
       if (endo) {
         const { k1neg, k1, k2neg, k2 } = splitEndoScalarN(sc);
         const { p1, p2 } = mulEndoUnsafe(Point, p, k1, k2); // 30% faster vs wnaf.unsafe
@@ -856,11 +903,6 @@ export function weierstrass<T>(
       }
     }
 
-    multiplyAndAddUnsafe(Q: Point, a: bigint, b: bigint): Point | undefined {
-      const sum = this.multiplyUnsafe(a).add(Q.multiplyUnsafe(b));
-      return sum.is0() ? undefined : sum;
-    }
-
     /**
      * Converts Projective point to affine (x, y) coordinates.
      * @param invertedZ Z^-1 (inverted zero) - optional, precomputation is useful for invertBatch
@@ -919,14 +961,15 @@ export interface ECDSASignature {
   readonly recovery?: number;
   addRecoveryBit(recovery: number): ECDSASignature & { readonly recovery: number };
   hasHighS(): boolean;
+  recoverPublicKey(messageHash: Uint8Array): WeierstrassPoint<bigint>;
   toBytes(format?: string): Uint8Array;
   toHex(format?: string): string;
 }
 /** Methods of ECDSA signature constructor. */
 export type ECDSASignatureCons = {
   new (r: bigint, s: bigint, recovery?: number): ECDSASignature;
-  fromBytes(bytes: Uint8Array, format?: ECDSASigFormat): ECDSASignature;
-  fromHex(hex: string, format?: ECDSASigFormat): ECDSASignature;
+  fromBytes(bytes: Uint8Array, format?: ECDSASignatureFormat): ECDSASignature;
+  fromHex(hex: string, format?: ECDSASignatureFormat): ECDSASignature;
 };
 
 // Points start with byte 0x02 when y is even; otherwise 0x03
@@ -1127,11 +1170,6 @@ export function ecdh(
     return Point.BASE.multiply(Fn.fromBytes(secretKey)).toBytes(isCompressed);
   }
 
-  function keygen(seed?: Uint8Array) {
-    const secretKey = randomSecretKey(seed);
-    return { secretKey, publicKey: getPublicKey(secretKey) };
-  }
-
   /**
    * Quick and dirty check for item being public key. Does not validate hex, or being on-curve.
    */
@@ -1168,17 +1206,17 @@ export function ecdh(
     isValidPublicKey,
     randomSecretKey,
   };
+  const keygen = createKeygen(randomSecretKey, getPublicKey);
 
   return Object.freeze({ getPublicKey, getSharedSecret, keygen, Point, utils, lengths });
 }
 
 /**
  * Creates ECDSA signing interface for given elliptic curve `Point` and `hash` function.
- * We need `hash` for 2 features:
- * 1. Message prehash-ing. NOT used if `sign` / `verify` are called with `prehash: false`
- * 2. k generation in `sign`, using HMAC-drbg(hash)
  *
- * ECDSAOpts are only rarely needed.
+ * @param Point created using {@link weierstrass} function
+ * @param hash used for 1) message prehash-ing 2) k generation in `sign`, using hmac_drbg(hash)
+ * @param ecdsaOpts rarely needed, see {@link ECDSAOpts}
  *
  * @example
  * ```js
@@ -1194,7 +1232,7 @@ export function ecdsa(
   ecdsaOpts: ECDSAOpts = {}
 ): ECDSA {
   ahash(hash);
-  _validateObject(
+  validateObject(
     ecdsaOpts,
     {},
     {
@@ -1207,9 +1245,7 @@ export function ecdsa(
   );
   ecdsaOpts = Object.assign({}, ecdsaOpts);
   const randomBytes = ecdsaOpts.randomBytes || wcRandomBytes;
-  const hmac: HmacFnSync =
-    ecdsaOpts.hmac ||
-    (((key, ...msgs) => nobleHmac(hash, key, concatBytes(...msgs))) satisfies HmacFnSync);
+  const hmac = ecdsaOpts.hmac || ((key, msg) => nobleHmac(hash, key, msg));
 
   const { Fp, Fn } = Point;
   const { ORDER: CURVE_ORDER, BITS: fnBits } = Fn;
@@ -1217,9 +1253,10 @@ export function ecdsa(
   const defaultSigOpts: Required<ECDSASignOpts> = {
     prehash: true,
     lowS: typeof ecdsaOpts.lowS === 'boolean' ? ecdsaOpts.lowS : true,
-    format: 'compact' as ECDSASigFormat,
+    format: 'compact' as ECDSASignatureFormat,
     extraEntropy: false,
   };
+  const hasLargeCofactor = CURVE_ORDER * _2n < Fp.ORDER; // Won't CURVE().h > 2n be more effective?
 
   function isBiggerThanHalfOrder(number: bigint) {
     const HALF = CURVE_ORDER >> _1n;
@@ -1230,7 +1267,19 @@ export function ecdsa(
       throw new Error(`invalid signature ${title}: out of range 1..Point.Fn.ORDER`);
     return num;
   }
-  function validateSigLength(bytes: Uint8Array, format: ECDSASigFormat) {
+  function assertSmallCofactor(): void {
+    // ECDSA recovery is hard for cofactor > 1 curves.
+    // In sign, `r = q.x mod n`, and here we recover q.x from r.
+    // While recovering q.x >= n, we need to add r+n for cofactor=1 curves.
+    // However, for cofactor>1, r+n may not get q.x:
+    // r+n*i would need to be done instead where i is unknown.
+    // To easily get i, we either need to:
+    // a. increase amount of valid recid values (4, 5...); OR
+    // b. prohibit non-prime-order signatures (recid > 1).
+    if (hasLargeCofactor)
+      throw new Error('"recovered" sig type is not supported for cofactor >2 curves');
+  }
+  function validateSigLength(bytes: Uint8Array, format: ECDSASignatureFormat) {
     validateSigFormat(format);
     const size = lengths.signature!;
     const sizer = format === 'compact' ? size : format === 'recovered' ? size + 1 : undefined;
@@ -1248,11 +1297,18 @@ export function ecdsa(
     constructor(r: bigint, s: bigint, recovery?: number) {
       this.r = validateRS('r', r); // r in [1..N-1];
       this.s = validateRS('s', s); // s in [1..N-1];
-      if (recovery != null) this.recovery = recovery;
+      if (recovery != null) {
+        assertSmallCofactor();
+        if (![0, 1, 2, 3].includes(recovery)) throw new Error('invalid recovery id');
+        this.recovery = recovery;
+      }
       Object.freeze(this);
     }
 
-    static fromBytes(bytes: Uint8Array, format: ECDSASigFormat = defaultSigOpts.format): Signature {
+    static fromBytes(
+      bytes: Uint8Array,
+      format: ECDSASignatureFormat = defaultSigOpts.format
+    ): Signature {
       validateSigLength(bytes, format);
       let recid: number | undefined;
       if (format === 'der') {
@@ -1270,41 +1326,34 @@ export function ecdsa(
       return new Signature(Fn.fromBytes(r), Fn.fromBytes(s), recid);
     }
 
-    static fromHex(hex: string, format?: ECDSASigFormat) {
+    static fromHex(hex: string, format?: ECDSASignatureFormat) {
       return this.fromBytes(hexToBytes(hex), format);
     }
 
+    private assertRecovery(): number {
+      const { recovery } = this;
+      if (recovery == null) throw new Error('invalid recovery id: must be present');
+      return recovery;
+    }
+
     addRecoveryBit(recovery: number): RecoveredSignature {
       return new Signature(this.r, this.s, recovery) as RecoveredSignature;
     }
 
     recoverPublicKey(messageHash: Uint8Array): WeierstrassPoint<bigint> {
-      const FIELD_ORDER = Fp.ORDER;
-      const { r, s, recovery: rec } = this;
-      if (rec == null || ![0, 1, 2, 3].includes(rec)) throw new Error('recovery id invalid');
-
-      // ECDSA recovery is hard for cofactor > 1 curves.
-      // In sign, `r = q.x mod n`, and here we recover q.x from r.
-      // While recovering q.x >= n, we need to add r+n for cofactor=1 curves.
-      // However, for cofactor>1, r+n may not get q.x:
-      // r+n*i would need to be done instead where i is unknown.
-      // To easily get i, we either need to:
-      // a. increase amount of valid recid values (4, 5...); OR
-      // b. prohibit non-prime-order signatures (recid > 1).
-      const hasCofactor = CURVE_ORDER * _2n < FIELD_ORDER;
-      if (hasCofactor && rec > 1) throw new Error('recovery id is ambiguous for h>1 curve');
-
-      const radj = rec === 2 || rec === 3 ? r + CURVE_ORDER : r;
-      if (!Fp.isValid(radj)) throw new Error('recovery id 2 or 3 invalid');
+      const { r, s } = this;
+      const recovery = this.assertRecovery();
+      const radj = recovery === 2 || recovery === 3 ? r + CURVE_ORDER : r;
+      if (!Fp.isValid(radj)) throw new Error('invalid recovery id: sig.r+curve.n != R.x');
       const x = Fp.toBytes(radj);
-      const R = Point.fromBytes(concatBytes(pprefix((rec & 1) === 0), x));
+      const R = Point.fromBytes(concatBytes(pprefix((recovery & 1) === 0), x));
       const ir = Fn.inv(radj); // r^-1
       const h = bits2int_modN(abytes(messageHash, undefined, 'msgHash')); // Truncate hash
       const u1 = Fn.create(-h * ir); // -hr^-1
       const u2 = Fn.create(s * ir); // sr^-1
       // (sr^-1)R-(hr^-1)G = -(hr^-1)G + (sr^-1). unsafe is fine: there is no private data.
       const Q = Point.BASE.multiplyUnsafe(u1).add(R.multiplyUnsafe(u2));
-      if (Q.is0()) throw new Error('point at infinify');
+      if (Q.is0()) throw new Error('invalid recovery: point at infinify');
       Q.assertValidity();
       return Q;
     }
@@ -1314,19 +1363,20 @@ export function ecdsa(
       return isBiggerThanHalfOrder(this.s);
     }
 
-    toBytes(format: ECDSASigFormat = defaultSigOpts.format) {
+    toBytes(format: ECDSASignatureFormat = defaultSigOpts.format) {
       validateSigFormat(format);
       if (format === 'der') return hexToBytes(DER.hexFromSig(this));
-      const r = Fn.toBytes(this.r);
-      const s = Fn.toBytes(this.s);
+      const { r, s } = this;
+      const rb = Fn.toBytes(r);
+      const sb = Fn.toBytes(s);
       if (format === 'recovered') {
-        if (this.recovery == null) throw new Error('recovery bit must be present');
-        return concatBytes(Uint8Array.of(this.recovery), r, s);
+        assertSmallCofactor();
+        return concatBytes(Uint8Array.of(this.assertRecovery()), rb, sb);
       }
-      return concatBytes(r, s);
+      return concatBytes(rb, sb);
     }
 
-    toHex(format?: ECDSASigFormat) {
+    toHex(format?: ECDSASignatureFormat) {
       return bytesToHex(this.toBytes(format));
     }
   }
@@ -1374,14 +1424,14 @@ export function ecdsa(
    * Warning: we cannot assume here that message has same amount of bytes as curve order,
    * this will be invalid at least for P521. Also it can be bigger for P224 + SHA256.
    */
-  function prepSig(message: Uint8Array, privateKey: Uint8Array, opts: ECDSASignOpts) {
+  function prepSig(message: Uint8Array, secretKey: Uint8Array, opts: ECDSASignOpts) {
     const { lowS, prehash, extraEntropy } = validateSigOpts(opts, defaultSigOpts);
     message = validateMsgAndHash(message, prehash); // RFC6979 3.2 A: h1 = H(m)
     // We can't later call bits2octets, since nested bits2int is broken for curves
     // with fnBits % 8 !== 0. Because of that, we unwrap it here as int2octets call.
     // const bits2octets = (bits) => int2octets(bits2int_modN(bits))
     const h1int = bits2int_modN(message);
-    const d = Fn.fromBytes(privateKey); // validate secret key, convert to bigint
+    const d = Fn.fromBytes(secretKey); // validate secret key, convert to bigint
     if (!Fn.isValidNot0(d)) throw new Error('invalid private key');
     const seedArgs = [int2octets(d), int2octets(h1int)];
     // extraEntropy. RFC6979 3.6: additional k' (optional).
@@ -1401,7 +1451,7 @@ export function ecdsa(
     // Can use scalar blinding b^-1(bm + bdr) where b ∈ [1,q−1] according to
     // https://tches.iacr.org/index.php/TCHES/article/view/7337/6509. We've decided against it:
     // a) dependency on CSPRNG b) 15% slowdown c) doesn't really help since bigints are not CT
-    function k2sig(kBytes: Uint8Array): RecoveredSignature | undefined {
+    function k2sig(kBytes: Uint8Array): Signature | undefined {
       // RFC 6979 Section 3.2, step 3: k = bits2int(T)
       // Important: all mod() calls here must be done over N
       const k = bits2int(kBytes); // Cannot use fields methods, since it is group element
@@ -1410,15 +1460,15 @@ export function ecdsa(
       const q = Point.BASE.multiply(k).toAffine(); // q = k⋅G
       const r = Fn.create(q.x); // r = q.x mod n
       if (r === _0n) return;
-      const s = Fn.create(ik * Fn.create(m + r * d)); // Not using blinding here, see comment above
+      const s = Fn.create(ik * Fn.create(m + r * d)); // s = k^-1(m + rd) mod n
       if (s === _0n) return;
-      let recovery = (q.x === r ? 0 : 2) | Number(q.y & _1n); // recovery bit (2 or 3, when q.x > n)
+      let recovery = (q.x === r ? 0 : 2) | Number(q.y & _1n); // recovery bit (2 or 3 when q.x>n)
       let normS = s;
       if (lowS && isBiggerThanHalfOrder(s)) {
-        normS = Fn.neg(s); // if lowS was passed, ensure s is always
-        recovery ^= 1; // // in the bottom half of N
+        normS = Fn.neg(s); // if lowS was passed, ensure s is always in the bottom half of N
+        recovery ^= 1;
       }
-      return new Signature(r, normS, recovery) as RecoveredSignature; // use normS, not s
+      return new Signature(r, normS, hasLargeCofactor ? undefined : recovery);
     }
     return { seed, k2sig };
   }
@@ -1436,7 +1486,7 @@ export function ecdsa(
    */
   function sign(message: Uint8Array, secretKey: Uint8Array, opts: ECDSASignOpts = {}): Uint8Array {
     const { seed, k2sig } = prepSig(message, secretKey, opts); // Steps A, D of RFC6979 3.2.
-    const drbg = createHmacDrbg<RecoveredSignature>(hash.outputLen, Fn.BYTES, hmac);
+    const drbg = createHmacDrbg<Signature>(hash.outputLen, Fn.BYTES, hmac);
     const sig = drbg(seed, k2sig); // Steps B, C, D, E, F, G
     return sig.toBytes(opts.format);
   }

package/src/bls12-381.ts

@@ -149,6 +149,7 @@ const bls12_381_CURVE_G1: WeierstrassOpts<bigint> = {
 
 // CURVE FIELDS
 // r = z⁴ − z² + 1; CURVE.n from other curves
+/** bls12-381 Fr (Fn) field. Note: does mod() on fromBytes, due to modFromBytes option. */
 export const bls12_381_Fr: IField<bigint> = Field(bls12_381_CURVE_G1.n, {
   modFromBytes: true,
 });
@@ -570,30 +571,18 @@ const bls12_hasher_opts = {
   hasherOpts: hasher_opts,
   hasherOptsG1: { ...hasher_opts, m: 1, DST: 'BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_' },
   hasherOptsG2: { ...hasher_opts },
-};
+} as const;
 
 const bls12_params = {
   ateLoopSize: BLS_X, // The BLS parameter x for BLS12-381
   xNegative: true,
   twistType: 'multiplicative' as const,
   randomBytes: randomBytes,
-  // https://datatracker.ietf.org/doc/html/rfc9380#name-clearing-the-cofactor
-  // https://datatracker.ietf.org/doc/html/rfc9380#name-cofactor-clearing-for-bls12
-  // G2hEff: BigInt(
-  //   '0xbc69f08f2ee75b3584c6a0ea91b352888e2a8e9145ad7689986ff031508ffe1329c2f178731db956d82bf015d1212b02ec0ec69d7477c1ae954cbc06689f6a359894c0adebbf6b4e8020005aaa95551'
-  // ),
 };
 
 /**
- * bls12-381 pairing-friendly curve.
- * @example
- * import { bls12_381 as bls } from '@noble/curves/bls12-381';
- * // G1 keys, G2 signatures
- * const privateKey = '67d53f170b908cabb9eb326c3c337762d59289a8fec79f7bc9254b584b73265c';
- * const message = '64726e3da8';
- * const publicKey = bls.getPublicKey(privateKey);
- * const signature = bls.sign(message, privateKey);
- * const isValid = bls.verify(signature, message, publicKey);
+ * bls12-381 pairing-friendly curve construction.
+ * Provides both longSignatures and shortSignatures.
  */
 export const bls12_381: BlsCurvePairWithSignatures = bls(
   fields,

package/src/bn254.ts

@@ -35,7 +35,7 @@ because it at least has specs:
     - https://github.com/arkworks-rs/curves/blob/master/bn254/src/lib.rs
 - Python implementations use different towers and produce different Fp12 outputs:
     - https://github.com/ethereum/py_pairing
-    - https://github.com/ethereum/execution-specs/blob/master/src/ethereum/crypto/alt_bn128.py
+    - https://github.com/ethereum/py_ecc/tree/main/py_ecc/bn128
 - Points are encoded differently in different implementations
 
 ### Params
@@ -56,9 +56,9 @@ Ate loop size: 6x+2
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 import {
   blsBasic,
-  type BLSCurvePair,
-  type PostPrecomputeFn,
-  type PostPrecomputePointAddFn,
+  type BlsCurvePair,
+  type BlsPostPrecomputeFn,
+  type BlsPostPrecomputePointAddFn,
 } from './abstract/bls.ts';
 import { Field, type IField } from './abstract/modular.ts';
 import type { Fp, Fp12, Fp2, Fp6 } from './abstract/tower.ts';
@@ -121,13 +121,13 @@ const { Fp, Fp2, Fp6, Fp12 } = tower12({
 // END OF CURVE FIELDS
 const { G2psi, psi } = psiFrobenius(Fp, Fp2, Fp2.NONRESIDUE);
 
-export const _postPrecompute: PostPrecomputeFn = (
+export const _postPrecompute: BlsPostPrecomputeFn = (
   Rx: Fp2,
   Ry: Fp2,
   Rz: Fp2,
   Qx: Fp2,
   Qy: Fp2,
-  pointAdd: PostPrecomputePointAddFn
+  pointAdd: BlsPostPrecomputePointAddFn
 ) => {
   const q = psi(Qx, Qy);
   ({ Rx, Ry, Rz } = pointAdd(Rx, Ry, Rz, q[0], q[1]));
@@ -216,4 +216,4 @@ const bn254_params = {
  * Contains G1 / G2 operations and pairings.
  */
 // bn254_hasher
-export const bn254: BLSCurvePair = blsBasic(fields, bn254_G1, bn254_G2, bn254_params);
+export const bn254: BlsCurvePair = blsBasic(fields, bn254_G1, bn254_G2, bn254_params);